PEP 829: Improve the guidelines for usage and build tools (#4918)

Improve the guidelines for usage and build tools

Author: warsaw

peps/pep-0829.rst

@@ -338,25 +338,34 @@ How to Teach This
 
 The :mod:`site` module documentation will be updated to describe the operation
 and best practices for ``<name>.pth`` and ``<name>.start`` files.  The
-following guidelines for package authors will be included:
+following migration guidelines for package authors will be included:
 
-If your package currently ships a ``<name>.pth`` file, analyze whether you are
-using it for ``sys.path`` extension or start up code execution.  You can keep
-all the ``sys.path`` extension lines unchanged.
+* If your package currently ships a ``<name>.pth`` file, analyze whether you
+  are using it for ``sys.path`` extension or start up code execution.  You can
+  keep all the ``sys.path`` extension lines unchanged.
 
-If you are using the code execution of ``import`` lines feature, create a
-callable (taking zero arguments) within an importable module inside your
-package.  Name these as ``pkg.mod:callable`` entry points in a matching
-``<name>.start`` file.
+* If you are using the code execution of ``import`` lines feature, create a
+  callable (taking zero arguments) within an importable module inside your
+  package.  Name these as ``pkg.mod:callable`` entry points in a matching
+  ``<name>.start`` file.
 
-During the deprecation period, if your package has to straddle older Pythons
-that don't support this PEP and newer Pythons that do, leave the ``import``
-lines in your ``<name>.pth`` file for now.  Older, non-supporting Pythons will
-execute the ``import`` lines, and newer, supporting Pythons will ignore these
-and use the entry points instead.
+* If your package has to straddle older Pythons that don't support this PEP
+  and newer Pythons that do, change the ``import`` lines in your
+  ``<name>.pth`` to use the following form:
 
-After the deprecation period, remove all ``import`` lines from your
-``<name>.pth`` file.
+  ``import pkg.mod; pkg.mod.callable()``
+
+  This way, older Pythons will execute these ``import`` lines, and newer
+  Pythons will ignore them, using the ``<name>.start`` file instead.  In both
+  cases the same code is effectively used, so while there's *some*
+  duplication, it is minimal.
+
+* After your straddling period, remove all ``import`` lines from your
+  ``<name>.pth`` file.
+
+Non-normatively, build tools may want to emit a warning if a package includes
+both a ``<name>.pth`` file and a ``<name>.start`` file where the former
+includes ``import`` lines that don't match lines in the latter.
 
 
 Reference Implementation