From 82b1902bcd074bf31230ee583c606617b74f8942 Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Thu, 16 Apr 2026 10:34:26 -0700 Subject: [PATCH] Improve the guidelines for usage and build tools --- peps/pep-0829.rst | 39 ++++++++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 15 deletions(-) diff --git a/peps/pep-0829.rst b/peps/pep-0829.rst index 4bba5dcdde6..8e0904e94e2 100644 --- a/peps/pep-0829.rst +++ b/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 ``.pth`` and ``.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 ``.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 ``.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 -``.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 + ``.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 ``.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 + ``.pth`` to use the following form: -After the deprecation period, remove all ``import`` lines from your -``.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 ``.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 + ``.pth`` file. + +Non-normatively, build tools may want to emit a warning if a package includes +both a ``.pth`` file and a ``.start`` file where the former +includes ``import`` lines that don't match lines in the latter. Reference Implementation