PEP 582: Tweek sysconfig and path details, and add some minor clarifications

[FFY00]

@kushaldas I have a couple changes here, mostly related to sysconfig. Could you have a look?

Changes:

• Rename the sysconfig scheme from localpackages to local_packages
  • It now follows the naming scheme, where words are separated by an underscore
• Clarify that the scheme local_packages is only required to provide the purelib and platlib paths
  • I still plan to provide the other paths, to keep backwards compatibility, if we don't have a new sysconfig by the time PEP 582 is released
• Remove __pypackages__ directory from the base/platbase definitions
  • IMO it should be part of the scheme, eg.

    ...
    'local_packages_posix': {
        'stdlib': '{installed_base}/{platlibdir}/python{py_version_short}',
        'platstdlib': '{installed_platbase}/{platlibdir}/python{py_version_short}',
        'include': '{installed_base}/include/python{py_version_short}{abiflags}',
        'platinclude': '{installed_platbase}/include/python{py_version_short}{abiflags}',
        'purelib': '{base}/__pypackages__/{py_version_short}/site-packages',
        'platlib': '{platbase}/__pypackages__/{py_version_short}/site-packages',
        'scripts': '{base}/__pypackages__/bin',
        'data': '{base}/__pypackages__/data',
    },
    ...
    

• Change the layout to __pypackages__/3.10/site-packages
  • There's no need for all that clutter in the path here, we are not installing on the system, we are installing language-specific directory
• Clarify that the subdirectory paths on Windows do not need to be different ("will be different" > "can be different")
• Specify that we will expand the local packages paths to an absolute path before adding them to sys.path
  • If we let them be relative, os.chdir will change the location of the __pypackages__, bypassing the mechanisms described in the security considerations section
• Clarify why we are offering an alternative option for the sysconfig API
  • This gives a bit more context to the reader, which IMO makes it a bit easier to follow
• Update link of the sysconfig API proposal to Kushal's fork, where it was moved to
• Clarify that when we say that the __pypackages__ in the current directory will be ignored when running a script, that we mean when running a script from a different path
  • Running a script in the current path will still pick up __pypackages__ from the current directory

---

📚 Documentation preview 📚: https://pep-previews--3036.org.readthedocs.build/

[CAM-Gerlach]

A handful of editorial comments

[CAM-Gerlach]

While you're at it, would be good to either link sysconfig to the canonical current docs:

Suggested change

	according to a new ``local_packages`` scheme in the sysconfig module. The scheme
	according to a new ``local_packages`` scheme in the :mod:`sysconfig` module. The scheme

or at least mark it as a literal, like you do elsewhere:

Suggested change

	according to a new ``local_packages`` scheme in the sysconfig module. The scheme
	according to a new ``local_packages`` scheme in the ``sysconfig`` module. The scheme

[CAM-Gerlach]

Suggested change

	An absolute version of these two locations will be added to ``sys.path``, other
	An absolute version of these two locations will be added to ``sys.path``; other

Fix grammar error (comma splice)

[CAM-Gerlach]

Maybe I'm just dumb, but what does "based on Python versions" mean here, specifically? This seems rather vague for a specification.

[CAM-Gerlach]

Suggested change

	`sysconfig` having to provide other scheme paths. It is documented in
	``sysconfig`` having to provide other scheme paths. It is documented in

Fix reST syntax mistake (that sphinx-lint would catch, but that check wasn't enabled for some reason).

[CAM-Gerlach]

Suggested change

	systems - on Windows the subdirectories can be different.
	systems --- on Windows the subdirectories can be different.

Minor typographical nit, but should be an em dash rather than a hyphen here

[CAM-Gerlach]

Suggested change

	::
	.. code-block:: text

Add the appropriate lexer name for non-Python code (or should this be treated as pseudo-shell?

[FFY00]

Thanks for the review CAM! I just kept the current formatting, but am happy to go over the whole document and fix this everywhere if Kushal doesn't have any issue with that.

[CAM-Gerlach]

Just to make sure we're on the same page, the first review comment (the formatting suggestion) was really just a tip/hint to let you know what was possible if you or @kushaldas want rather than requesting a specific change—that's totally up to you, of course, and you shouldn't feel pressured to go back and change it everywhere unless @kushaldas wants. The rest all fix syntax problems, grammar errors, and other minor issues as well as pointing out one added part I found unclear.

As a standard reminder, N.B., the other suggestions can be batch-applied with Files changed -> Add to batch -> Commit. Thanks!

[hugovk]

@FFY00 I don't have permission to push to this branch, but you can try this to resolve the conflict:

git checkout 582-sysconfig-minor-tweaks
git fetch upstream
git merge upstream/main
git push

[ambv]

Since the PEP has been rejected since, and Filipe is busy, I'm closing this.

[FFY00]

Thanks. I should have done it earlier when the PEP was rejected.