PEP 829: Accepted

peps/pep-0829.rst

@@ -2,14 +2,15 @@ PEP: 829
 Title: Package Startup Configuration Files
 Author: Barry Warsaw <barry@python.org>
 Discussions-To: https://discuss.python.org/t/pep-829-structured-startup-configuration-via-site-toml-files/106789
-Status: Draft
+Status: Accepted
 Type: Standards Track
 Created: 31-Mar-2026
 Python-Version: 3.15
 Post-History:
     `01-Apr-2026 <https://discuss.python.org/t/pep-829-structured-startup-configuration-files/106789>`__,
     `13-Apr-2026 <https://discuss.python.org/t/pep-829-structured-startup-configuration-files/106789/69>`__,
     `15-Apr-2026 <https://discuss.python.org/t/pep-829-structured-startup-configuration-files/106789/99>`__
+Resolution: `24-Apr-2026 <https://discuss.python.org/t/pep-829-structured-startup-configuration-files/106789/112>`__
 
 
 Abstract
@@ -21,18 +22,25 @@ Previously controlled through legacy ``.pth`` files parsed and executed by the
 ``sys.path`` and execute package initialization code before control is passed
 to the first line of user code.
 
-``.pth`` files in their historical form have a `long history
-<https://github.com/python/cpython/issues/78125>`_ of proposed removal,
-primarily because of the obtuse nature of the arbitrary code execution
-feature.  Recent `supply chain attacks
-<https://securitylabs.datadoghq.com/articles/litellm-compromised-pypi-teampcp-supply-chain-campaign/>`_
-have used arbitrary code execution in ``.pth`` files as an attack vector.
+This PEP proposes:
 
-This PEP doesn't completely close this vector, but it does propose an
-important and useful improvement, by narrowing the attack surface and enabling
-a future policy mechanism for controlling which packages are allowed or
-prevented from extending the path and executing start up code.  See
-:ref:`security` for additional discussion.
+* Replacing ``import`` lines in ``.pth`` files with entry point specifications
+  (i.e. ``pkg.mod:callable``) in ``.start`` files.
+* The presence of a matching ``.start`` file disables ``import`` line
+  processing in the matched ``.pth`` file.
+* The ``sys.path`` extension functionality of ``.pth`` files is retained.
+
+Support for ``import`` lines in ``.pth`` files will be gradually removed:
+
+* For the first three years (expected to be Python 3.15, 3.16, and 3.17)
+  ``import`` line processing in ``.pth`` files will remain, *except* in the
+  presence of a matching ``.start`` file.
+
+* For the next two years (expected to be Python 3.18 and 3.19), ``import``
+  lines in ``.pth`` files will be silently ignored.
+
+* Afterwards (expected to be Python 3.20 and higher), a warning will be
+  produced for the existence of ``import`` lines in ``.pth`` files.
 
 
 Motivation
@@ -316,20 +324,21 @@ utilize the ``import`` line arbitrary code execution feature of current
 importable module inside the package, and then name this callable in an entry
 point specification inside a ``<name>.start`` file.
 
+
 .. _security:
 
 Security Implications
 =====================
 
-This PEP improves the security posture of interpreter startup.
+This PEP makes it easier to audit code execution paths during interpreter startup.
 
-* The removal of arbitrary code execution by :func:`exec` with entry point
-  execution, which is more constrained and auditable.
-
-* Splitting ``sys.path`` extensioni from code execution into two separate
+* Splitting ``sys.path`` extension from code execution into two separate
   files means that you can tell by listing the files in the site-dir, exactly
   where arbitrary code execution occurs.
 
+* The removal of arbitrary code execution by :func:`exec` with entry point
+  execution, which is more constrained and auditable.
+
 * Python's import system is used to access and run the entry points, so the
   standard audit hooks (:pep:`578`) can provide monitoring.
 
@@ -339,10 +348,10 @@ This PEP improves the security posture of interpreter startup.
 * The ``package.module:callable`` syntax limits execution to callables within
   importable modules.
 
-The overall attack surface is not eliminated -- a malicious package can still
-cause arbitrary code execution via entry points, but the mechanism proposed in
-this PEP is more structured, auditable, and amenable to future policy
-controls.
+The overall pre-start code execution attack surface is not eliminated by this
+PEP.  A malicious package can still cause arbitrary code execution via entry
+points, but the mechanism proposed in this PEP is more structured, auditable,
+and amenable to future policy controls.
 
 
 .. _teach: