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 _______________________________________
-
Brett Cannon -
Cheryl Sabella
-
Inada Naoki
-
miss-islington
-
Peter Bittner
-
Vinay Keerthi