bpo-38623: Add note about site module (site-packages) #16974
Conversation
Seriously, the StackOverflow question is already solved for quite some time. This is about improving the Python documentation in a way that would make it unnecessary for people to look for a solution in the Internet. I'd be open for suggestions to find an even better place for this type of information, or a better way of explaining the facts. You may have noticed that on StackOverflow the answer is much more elaborated and enriched with hands-on tips. Not sure if the tutorial would be a good place for that; I wanted to keep it concise. |
|
Is this PR okay to be merged? Anything I may improve or change? |
|
Can we merge this enhancement? Please let me know if there's anything missing for it to get merged. |
|
Can I help somehow to bring this PR to the the next stage, the "core review" mentioned above? |
|
The tutorial would now contain the word "site-packages", which can attract organic search traffic. The contributed text contains a link to the |
| @@ -191,7 +191,8 @@ named :file:`spam.py` in a list of directories given by the variable | |||
| file is specified). | |||
| * :envvar:`PYTHONPATH` (a list of directory names, with the same syntax as the | |||
| shell variable :envvar:`PATH`). | |||
| * The installation-dependent default. | |||
| * The installation-dependent default (by convention including a | |||
| ``site-packages`` directory, handled by the :mod:`site` module). | |||
There was a problem hiding this comment.
I feel this is just a noise for tutorial readers.
We don't introduce even standard library (it is introduced in 6.2). So we shouldn't mention about what is in the "installation-dependent default" in this chapter. It should be just "some other directories" for the readers here.
If you really want to document site-packages, I think Python Setup and Usage or Installing Python Modules is better place.
There was a problem hiding this comment.
It's not clear to the reader what "handled" means here. What would a reader of the tutorial do with the site module?
There was a problem hiding this comment.
Would "taken care of [by ...]" be better, maybe? This is mainly a referral to the first paragraph of the site module documentation, which says:
This module is automatically imported during initialization.
The tutorial reader, which may be someone having landed here by organic search traffic (i.e. not necessarily a Python novice), may get a hint on what "installation-dependent default[s]" are (via "site-packages") and where to read more about it (via the link to the site module documentation).
There was a problem hiding this comment.
I guess i don't understand why any reader needs to know what module placed site-packages into the import path? Just because someone might land on this page through a search doesn't mean we should add every fact to it. The tutorial should first and foremost be useful to read by beginners. This addition seems like a confusing addition.
|
Closing and re-opening to re-trigger CI. |
|
GH-28536 is a backport of this pull request to the 3.10 branch. |
|
GH-28537 is a backport of this pull request to the 3.9 branch. |
(cherry picked from commit 55b45bf) Co-authored-by: Peter Bittner <django@bittner.it>
(cherry picked from commit 55b45bf) Co-authored-by: Peter Bittner <django@bittner.it>
Adds a information about "site-packages" in a concise way.
Background
A popular question on StackOverflow is, "How do I find the location of my Python site-packages directory?"
While this may hint at a deeper problem that needs to be solved, a user suggested the accepted answer to be added to Python's official documentation.
https://bugs.python.org/issue38623