PEP 582: Updates sysconfig scheme requirement (#3014)

pep-0582.rst

@@ -97,15 +97,20 @@ works. For example, ``__pypackages__`` will be ignored if the ``-P`` option or
 the ``PYTHONSAFEPATH`` environment variable is set.
 
 In order to be recognised, the ``__pypackages__`` directory must be laid out
-according to the "prefix" scheme in the sysconfig module. Specifically, either
+according to a new ``localpackages`` scheme in the sysconfig module.
-or both of the ``purelib`` and ``platlib`` directories must be present, using
+Specifically, both of the ``purelib`` and ``platlib`` directories must be
-the following code to determine the locations of those directories::
+present, using the following code to determine the locations of those
+directories::
 
-    scheme = sysconfig.get_preferred_scheme("prefix")
+    scheme = "localpackages"
     purelib = sysconfig.get_path("purelib", scheme, vars={"base": "__pypackages__", "platbase": "__pypackages__"})
     platlib = sysconfig.get_path("platlib", scheme, vars={"base": "__pypackages__", "platbase": "__pypackages__"})
 
-These two locations will be added to ``sys.path``, other directories or files in the ``__pypackages__`` directory will be silently ignored.
+These two locations will be added to ``sys.path``, other directories or
+files in the ``__pypackages__`` directory will be silently ignored. The
+paths will be based on Python versions.
+
+.. note:: There is a possible option of having a separate new API, it is documented at `issue #3013 <https://github.com/python/peps/issues/3013>`_.
 
 
 Example
@@ -170,7 +175,7 @@ working directory is used.
 
 In another example scenario, a trainer of a Python class can say "Today we are
 going to learn how to use Twisted! To start, please checkout our example
-project, go to that directory, and then run ``python3 -m pip install twisted``."
+project, go to that directory, and then run a given command to install Twisted."
 
 That will install Twisted into a directory separate from ``python3``. There's no
 need to discuss virtual environments, global versus user installs, etc. as the
@@ -266,21 +271,10 @@ As the intended use of the feature is to install 3rd party libraries in the new
 directory, it is important that tools, particularly installers, understand how to
 manage ``__pypackages__``.
 
-To minimise transition costs, the PEP proposes a layout for the
+It is hoped that tools will introduce a dedicated "pypackages" installation
-``__pypackages__`` directory that is compatible with pip's ``--prefix`` option,
+mode that *is* guaranteed to match the expected layout in all cases. However,
-in the most common cases, so that in the absence of any dedicated mechanism,
+the question of how best to support the ``__pypackages__`` layout is ultimately
-``pip install --prefix __pypackages__`` should work. However, this is
+left to individual tool maintainers to consider and decide on.
-considered a transitional measure only, and there is no guarantee that in
-exceptional cases where a distributor has customised things or pip has
-special-case handling, ``pip install --prefix`` might not work and installation
-will need to be handled manually.
-
-In the longer term, it is hoped that tools will introduce a dedicated
-"pypackages" installation mode that *is* guaranteed to match the expected
-layout in all cases, removing the need for interim approaches like
-``--prefix``. However, the question of how best to support the
-``__pypackages__`` layout is ultimately left to individual tool maintainers to
-consider and decide on.
 
 Tools that locate packages without actually running Python code (IDEs, linters,
 type checkers, etc.) would need updating to recognise ``__pypackages__``. In the