[issue38623] Python documentation should mention how to find site-packages
New submission from Peter Bittner <peter.bittner@gmx.net>: A popular question on StackOverflow is, "How do I find the location of my Python site-packages directory?" [1] While this may hint at a deeper problem that needs to be solved, a user suggested [2] the accepted answer to be added to Python's official documentation. The most appropriate place I could find to add related information is ``Doc/tutorial/modules.rst``. [1] https://stackoverflow.com/questions/122327/how-do-i-find-the-location-of-my-... [2] https://stackoverflow.com/questions/122327/how-do-i-find-the-location-of-my-... ---------- assignee: docs@python components: Documentation messages: 355599 nosy: bittner, docs@python priority: normal severity: normal status: open title: Python documentation should mention how to find site-packages type: enhancement versions: Python 2.7, Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38623> _______________________________________
Change by Peter Bittner <peter.bittner@gmx.net>: ---------- keywords: +patch pull_requests: +16500 stage: -> patch review pull_request: https://github.com/python/cpython/pull/16974 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38623> _______________________________________
Change by Cheryl Sabella <cheryl.sabella@gmail.com>: ---------- nosy: +brett.cannon versions: -Python 2.7, Python 3.5, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38623> _______________________________________
Vinay Keerthi <ktvkvinaykeerthi+python@gmail.com> added the comment: Just chiming in my opinion, the site-packages directory is also dependent on venv, correct? So would explaining where it is at a global install level be much use? Or do you mean explaining where site-packages is even for a venv? I could take this up, if some agrees that jr needs doing. ---------- nosy: +stonecharioteer _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38623> _______________________________________
Inada Naoki <songofacandy@gmail.com> added the comment: There is a document about it in Doc/library/site.rst already. I'm not sure this should be documented in the tutorial. ---------- nosy: +inada.naoki _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38623> _______________________________________
Change by Inada Naoki <songofacandy@gmail.com>: ---------- pull_requests: +17278 pull_request: https://github.com/python/cpython/pull/17858 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38623> _______________________________________
Peter Bittner <peter.bittner@gmx.net> added the comment: There is a specific question this change attempts to answer: "Where is the module I imported located in the file system?" I suspect this comes up a lot because developers want to inspect or mess with installed modules, add debug output and the like, to understand some of their development issues better. The site module documentation explains the details.[3] The paragraph the change adds links to that documentation. That should be sufficient (for a tutorial); other technical details probably fit well in the document being linked to. [3] https://docs.python.org/3/library/site.html#site.getusersitepackages I tried to keep it concise, adding value with a quick glance over the `site` module features that relate to the module paths topic. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38623> _______________________________________
Inada Naoki <songofacandy@gmail.com> added the comment:
There is a specific question this change attempts to answer: "Where is the module I imported located in the file system?"
So `print(the_module.__file__)` is better answer. (or `pip list -v` if the module is third party package installed via pip). `python -m site` doesn't tell you where the imported module came from.
[3] https://docs.python.org/3/library/site.html#site.getusersitepackages
After merging PR 17858, you can use :ref:`site-commandline` for cross reference. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38623> _______________________________________
Brett Cannon <brett@python.org> added the comment: I agree with Inada-san that pointing out how to get the file path on a module is a better solution then explaining directory layouts which are borderline implementation details. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38623> _______________________________________
Inada Naoki <songofacandy@gmail.com> added the comment: New changeset ca94677a6216e2d41b04574986ce49d31a0b329c by Inada Naoki in branch 'master': bpo-38623: Doc: Add section for site module CLI. (GH-17858) https://github.com/python/cpython/commit/ca94677a6216e2d41b04574986ce49d31a0... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38623> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +17300 pull_request: https://github.com/python/cpython/pull/17890 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38623> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +17301 pull_request: https://github.com/python/cpython/pull/17891 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38623> _______________________________________
miss-islington <mariatta.wijaya+miss-islington@gmail.com> added the comment: New changeset 72995c5cdd7ad4af6252bbe129e8fc63f5006130 by Miss Islington (bot) in branch '3.7': bpo-38623: Doc: Add section for site module CLI. (GH-17858) https://github.com/python/cpython/commit/72995c5cdd7ad4af6252bbe129e8fc63f50... ---------- nosy: +miss-islington _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38623> _______________________________________
miss-islington <mariatta.wijaya+miss-islington@gmail.com> added the comment: New changeset a6b37589a05c63abec122d3a00785641a3bcd85a by Miss Islington (bot) in branch '3.8': bpo-38623: Doc: Add section for site module CLI. (GH-17858) https://github.com/python/cpython/commit/a6b37589a05c63abec122d3a00785641a3b... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38623> _______________________________________
Inada Naoki <songofacandy@gmail.com> added the comment: It is tempting that putting some paragraphs to the tutorial when you think "this should be documented!" but there is no good place in the library reference. HOWTOs is the document for advanced topics. But it doesn't cover wide area yet. There is no topic about module search path or site-packages. Since the tutorial covers a wide area, including module, it is very tempting to add many random notes about module. But please remember that the primary reader is people new to Python. (I learned Python 2.4 by the tutorial!) The reader has learned Python syntax and basic types in chapters 1~5 and now learning how to split a Python program into multiple files. So please don't try to answer the question in Stackoverflow in the tutorial, unless it is worth enough for the reader. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38623> _______________________________________
Peter Bittner <peter.bittner@gmx.net> added the comment: Python learners deserve to know about "site-packages" and (optionally) "dist-packages". This is a "random note", it's an explanation that is missing in the tutorial. - Site-packages "is the target directory of manually built Python packages", does someone explain.[4] - It is the "expected convention for locally installed packages", explains Greg Ward in "Installing Python Modules".[5] - Their location is only a subset of `sys.path`, as visible from the Python code in the `site` module.[6] The tutorial currently mentions its special role only briefly [7], saying:
* The installation-dependent default.
We should explain that part. I'll give it a shot replacing my earlier proposal. [4] https://stackoverflow.com/questions/31384639/what-is-pythons-site-packages-d... [5] https://docs.python.org/3.8/install/#modifying-python-s-search-path [6] https://github.com/python/cpython/blob/master/Lib/site.py#L319-L344 [7] https://docs.python.org/3.8/tutorial/modules.html?highlight=installation-dep... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38623> _______________________________________
Inada Naoki <songofacandy@gmail.com> added the comment:
The tutorial currently mentions its special role only briefly [7], saying:
* The installation-dependent default.
We should explain that part. I'll give it a shot replacing my earlier proposal.
I don't think so. At there, the tutorial doesn't explain about even standard library. We shouldn't explain about it there. It should be explained much later in the tutorial, or document other than the tutorial. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38623> _______________________________________
Brett Cannon <brett@python.org> added the comment: I think "Python learners deserve to know about "site-packages" and (optionally) "dist-packages" " is a bit strong of a statement. I don't think the tutorial covers how to install third-party package which is what goes into site-packages, so I don't know what benefit they will garner from having that covered in the tutorial to teach the basics of Python. In an intermediate tutorial I can totally understand the explanation along with using e.g. pip, but for a tutorial like this I still think it's unnecessary. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38623> _______________________________________
participants (6)
-
Brett Cannon -
Cheryl Sabella
-
Inada Naoki
-
miss-islington
-
Peter Bittner
-
Vinay Keerthi