This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Add _pth breadcrumb to sys.path documentation
Type: enhancement Stage: patch review
Components: Documentation, Windows Versions: Python 3.11
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: RusselWebber, Traveler Hauptman, docs@python, eric.snow, paul.moore, steve.dower, tim.golden, zach.ware
Priority: normal Keywords: patch

Created on 2017-09-26 04:47 by Traveler Hauptman, last changed 2022-04-11 14:58 by admin.

Pull Requests
URL Status Linked Edit
PR 31082 merged RusselWebber, 2022-02-02 17:21
Messages (7)
msg303000 - (view) Author: Traveler Hauptman (Traveler Hauptman) Date: 2017-09-26 04:47
Python on windows (winpython) was not adding PYTHONPATH to sys.path as documented and I could not understand why.

It took a lot of time, web searches, and finally a tour through the code to find out about _pth; which is well documented but difficult to find out about if you don't know about it beforehand.

Please improve the sys.path documentation to say that it depends on either PYTHONPATH or the *._pth file. Better yet, link to the actual sys.path heuristics.
msg303358 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2017-09-29 21:19
Sounds like a good idea.

I hope that sys.path initialization is documented as well for POSIX as it is for Windows, as that will make this a simple "for X, click here; for Y, click here" patch. Otherwise, someone will need to figure out exactly what rules are followed so they can be documented.

(Hey Eric - when we get that Python initialization script, we can have one set of rules for inferring sys.path on all platforms in easy-to-read Python code :) )
msg410996 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2022-01-20 00:25
Need to make this happen, and it probably needs to be me (though I'm happy to review a contribution).

We now handle ._pth files on all platforms as part of the Modules/ changes (which I hinted to in my previous comment from 5 years ago ;) ).
msg411883 - (view) Author: Russel Webber (RusselWebber) * Date: 2022-01-27 14:34
I am happy to take a look at improving the documentation. I see the new has very extensive commenting. Should I simply mention ._pth files as in the original issue from 5 years ago, or are you looking for documentation of how sys.path is initialised based on the comments in
msg411942 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2022-01-27 23:46
I think we need somewhere in the documentation to explain how the initial import path is calculated, in terms useful for an end user (rather than what's in, which is for developers).

Right now, I'm not sure there's a good place for it. There's a Windows-specific page with some detail, but we probably need something more generic. Probably it belongs under Doc/using/cmdline.rst (the environment variables section there is tempting, but I expect those would be updated to point to an easier to follow explanation. We'd also point to it from sys.path.

Without adding the new section, there isn't really anywhere sensible to mention it.
msg411980 - (view) Author: Russel Webber (RusselWebber) * Date: 2022-01-28 08:44
I agree wholeheartedly, an explantation of sys.path initialisation would be very helpful. I've seen too many hacks in end user Python code due to misunderstandings around sys.path initialisation and the available ways to customise sys.path. I'll work on this, try to write an easy to follow explanantion and see where the other documentation needs to be amended to point to a new section.
msg415887 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2022-03-23 17:29
New changeset c62b944dfc98911a5050389fa6ac753e283fee1f by Russel Webber in branch 'main':
bpo-31582: Created a new documentation section describing sys.path initialization (GH-31082)
Date User Action Args
2022-04-11 14:58:52adminsetgithub: 75763
2022-03-23 17:29:54steve.dowersetmessages: + msg415887
2022-02-02 17:21:59RusselWebbersetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request29265
2022-01-28 08:44:50RusselWebbersetmessages: + msg411980
2022-01-27 23:46:09steve.dowersetmessages: + msg411942
2022-01-27 14:34:19RusselWebbersetnosy: + RusselWebber
messages: + msg411883
2022-01-20 00:25:06steve.dowersetmessages: + msg410996
versions: + Python 3.11, - Python 3.6, Python 3.7
2017-09-29 21:19:25steve.dowersetversions: + Python 3.6, Python 3.7
nosy: + eric.snow

messages: + msg303358

stage: needs patch
2017-09-29 16:22:01eric.araujosetnosy: + paul.moore, tim.golden, zach.ware, steve.dower
components: + Windows
2017-09-26 04:47:20Traveler Hauptmancreate