Add _pth breadcrumb to sys.path documentation

[TravelerHauptman]

BPO	31582
Nosy	@pfmoore, @tjguk, @ericsnowcurrently, @zware, @zooba, @RusselWebber
PRs	bpo-31582: Created a new section describing sys.path initialization #31082

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2017-09-26.04:47:19.983>
labels = ['3.11', 'type-feature', 'OS-windows', 'docs']
title = 'Add _pth breadcrumb to sys.path documentation'
updated_at = <Date 2022-03-23.17:29:54.697>
user = 'https://bugs.python.org/TravelerHauptman'

bugs.python.org fields:

activity = <Date 2022-03-23.17:29:54.697>
actor = 'steve.dower'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'Windows']
creation = <Date 2017-09-26.04:47:19.983>
creator = 'Traveler Hauptman'
dependencies = []
files = []
hgrepos = []
issue_num = 31582
keywords = ['patch']
message_count = 7.0
messages = ['303000', '303358', '410996', '411883', '411942', '411980', '415887']
nosy_count = 8.0
nosy_names = ['paul.moore', 'tim.golden', 'docs@python', 'eric.snow', 'zach.ware', 'steve.dower', 'Traveler Hauptman', 'RusselWebber']
pr_nums = ['31082']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue31582'
versions = ['Python 3.11']

[TravelerHauptman]

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.

[zooba]

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 :) )

[zooba]

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/getpath.py changes (which I hinted to in my previous comment from 5 years ago ;) ).

[RusselWebber]

I am happy to take a look at improving the documentation. I see the new getpath.py 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 getpath.py?

[zooba]

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 getpath.py, 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.

[RusselWebber]

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.

[zooba]

New changeset c62b944 by Russel Webber in branch 'main':
bpo-31582: Created a new documentation section describing sys.path initialization (GH-31082)
c62b944