Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add _pth breadcrumb to sys.path documentation #75763

Closed
TravelerHauptman mannequin opened this issue Sep 26, 2017 · 7 comments
Closed

Add _pth breadcrumb to sys.path documentation #75763

TravelerHauptman mannequin opened this issue Sep 26, 2017 · 7 comments
Labels
3.11 docs Documentation in the Doc dir OS-windows type-feature A feature request or enhancement

Comments

@TravelerHauptman
Copy link
Mannequin

TravelerHauptman mannequin commented Sep 26, 2017

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
    Copy link
    Mannequin Author

    TravelerHauptman mannequin commented Sep 26, 2017

    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.

    @TravelerHauptman TravelerHauptman mannequin added docs Documentation in the Doc dir type-feature A feature request or enhancement labels Sep 26, 2017
    @zooba
    Copy link
    Member

    zooba commented Sep 29, 2017

    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 zooba added the 3.7 label Sep 29, 2017
    @zooba
    Copy link
    Member

    zooba commented Jan 20, 2022

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

    @zooba zooba added 3.11 and removed 3.7 labels Jan 20, 2022
    @RusselWebber
    Copy link
    Mannequin

    RusselWebber mannequin commented Jan 27, 2022

    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
    Copy link
    Member

    zooba commented Jan 27, 2022

    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
    Copy link
    Mannequin

    RusselWebber mannequin commented Jan 28, 2022

    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
    Copy link
    Member

    zooba commented Mar 23, 2022

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

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    @slateny slateny closed this as completed May 14, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees
    No one assigned
    Labels
    3.11 docs Documentation in the Doc dir OS-windows type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    3 participants
    @merwok @zooba @slateny