[issue31582] Add _pth breadcrumb to sys.path documentation

[Steve Dower]

Steve Dower  added the comment:


New changeset c62b944dfc98911a5050389fa6ac753e283fee1f by Russel Webber in 
branch 'main':
bpo-31582: Created a new documentation section describing sys.path 
initialization (GH-31082)
https://github.com/python/cpython/commit/c62b944dfc98911a5050389fa6ac753e283fee1f


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue31582] Add _pth breadcrumb to sys.path documentation

[Russel Webber]

Change by Russel Webber :


--
keywords: +patch
pull_requests: +29265
stage: needs patch -> patch review
pull_request: https://github.com/python/cpython/pull/31082

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue31582] Add _pth breadcrumb to sys.path documentation

[Russel Webber]

Russel Webber  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue31582] Add _pth breadcrumb to sys.path documentation

[Steve Dower]

Steve Dower  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue31582] Add _pth breadcrumb to sys.path documentation

[Russel Webber]

Russel Webber  added the comment:

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?

--
nosy: +RusselWebber

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue31582] Add _pth breadcrumb to sys.path documentation

[Steve Dower]

Steve Dower  added the comment:

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 ;) ).

--
versions: +Python 3.11 -Python 3.6, Python 3.7

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue31582] Add _pth breadcrumb to sys.path documentation

[Steve Dower]

Steve Dower  added the comment:

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

--
nosy: +eric.snow
stage:  -> needs patch
versions: +Python 3.6, Python 3.7

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue31582] Add _pth breadcrumb to sys.path documentation

[Éric Araujo]

Change by Éric Araujo :


--
components: +Windows
nosy: +paul.moore, steve.dower, tim.golden, zach.ware

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue31582] Add _pth breadcrumb to sys.path documentation

[Traveler Hauptman]

New submission from Traveler Hauptman:

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.

--
assignee: docs@python
components: Documentation
messages: 303000
nosy: Traveler Hauptman, docs@python
priority: normal
severity: normal
status: open
title: Add _pth breadcrumb to sys.path documentation
type: enhancement

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com