The document on PYTHONHOME might be wrong?

From the Doc here, it says: the standard libraries are searched in prefix/lib/pythonversion and exec_prefix/lib/pythonversion.
However, the doc on sys.exec_prefix says “shared library modules are installed in exec_prefix/lib/pythonX.Y/lib-dynload”.
Namely, exec_prefix/lib/pythonversion will not be searched for library which conflicts the thing on PYTHONHOME.

Indeed, I tested removing prefix while keeping exec_prefix by setting PYTHONHOME, then the standard library cannot be loaded.
For example PYTHONHOME="/path_not_exit:/usr" /usr/bin/python3.8 does not start python as standard library is missing while PYTHONHOME="/usr:/path_not_exist" /usr/bin/python3.8 works well.

Besides, the doc under PYTHONHOME about prefix might also be wrong.
From the prefix doc(I cannot put more links, it is under doc of sys), the prefix affects paths as described in the installation-paths (under doc of sysconfig) section.
To my understanding, prefix + installation scheme determines eight paths currently. Among these paths, stdlib is where python search for the standard library (instead of /prefix/lib/pythonversion.

The docs you ref are for posix systems, but the lib-dynlib is a windows only folder.

Maybe what you are pointing out is that the docs need to clarify posix vs. Windows use of PYTHONHOME?

I don’t think the doc is for Windows. It also talk about /usr/local in the same paragraph.

Besides, on a Ubuntu machine, if you print out the sys.path, it contains the .../lib-dynload folder.

It definitely looks like the docs are incomplete and probably out of date. Maybe @steve.dower can help sort through what they should be? IIRC he recently rewrote a lot of code related to module search paths in Python (see Modules/getpath.py in the repo).

I’m on Windows 10, and it doesn’t have lib-dynload.

I guess in Windows it is DLLs

I rewrote without changing any of the semantics (intentionally), so I don’t necessarily understand the design. But getpath.py ought to be more readable than the old implementation if you want to figure out what the exact semantics are.

This seems to be another minor issue where none of the parties close to the code have the time to do the necessary analysis. Maybe someone reading this would like to try their hand at submitting an issue that explains how this actually works on various platforms and then a PR that fixes the docs?

Possibly @FFY00 would be interested? He’s been nominated as a maintainer for sysconfig, which is practically the same thing as path initialization.

Thank you for the ping. I think the relevant bits here are that the stdlib and platstdlib directories are added to sys.path, and these are the directories that should be referred here in the documentation.

The values may change overtime, leading to the documentation to become outdated, which is what appears to have happened here.

I would like to document the default installation scheme values in the sysconfig docs, which would let users know what values they can expect and how those values are calculated, making it clear how PYTHONHOME affects things, etc.

We can document that, and then point the other docs to it. What do you think?

Side-note: Interestingly enough, only Posix and Darwin use the lib-dynload directory, Windows does not use it in the platstdlib path :rofl:

1 Like

Looking forward to your PR!