Updates based on Brett's feedback

Author: warsaw

peps/pep-0829.rst

@@ -70,53 +70,62 @@ Specification
 
 This PEP proposes the following:
 
-* Keep the ``.pth`` file format, but deprecate ``import`` line
-  processing for three years, after which such lines will be
-  disallowed.
+* Keep the ``<name>.pth`` file format, but deprecate ``import`` line
+  processing for three years, after which such lines will be disallowed.
+
+* Keep the current ``sys.path`` extension feature of ``<name>.pth`` files
+  unchanged.  Specifically, absolute paths are used verbatim while relative
+  paths are anchored at the directory in which the ``.pth`` file is located.
+
+* A new file format called ``<name>.start`` files are added which names entry
+  points conforming to the "colon-form" of :func:`pkgutil.resolve_name`
+  arguments.
 
 * During the deprecation period, the presence of a ``<name>.start`` file
   matching a ``<name>.pth`` file disables the execution of ``import`` lines in
-  favor of entry points.  This provides a migration path straddling Python
-  versions which support this PEP and earlier versions which do not.  See the
-  :ref:`teach` section for specific migration guidelines.
+  the ``<name>.pth`` file in favor of entry points from the ``<name>.start``
+  file.  This provides a migration path straddling Python versions which
+  support this PEP and earlier versions which do not.
 
-* Keep the current ``sys.path`` extension feature of ``.pth`` files
-  unchanged.  Specifically, absolute paths are used verbatim while
-  relative paths are anchored at the directory in which the ``.pth``
-  file is located.
+  During the deprecation period, for any ``<name>.pth`` file without a
+  matching ``<name>.start`` file, the processing of the former is unchanged (a
+  warning about ``import`` lines may be printed).  After the deprecation
+  period ``import`` lines in ``<name>.pth`` files are ignored and a warning is
+  issued, regardless of whether there is a matching ``<name>.start`` file or
+  not.
 
-* A new file format called ``.start`` files are added which names entry points
-  conforming to the "colon-form" of :func:`pkgutil.resolve_name` arguments.
+  See the :ref:`teach` section for specific migration guidelines.
 
 ``site.py`` start up code is divided into these explicit phases:
 
-#. List all ``.pth`` files and sort in alphabetical order by filename.
+#. Find the ``<name>.pth`` files (see :ref:`discovery` for additional details)
+   and sort them in alphabetical order by filename.
 
-#. Parse ``.pth`` files in sorted order, keeping a global sorted list of all
-   path extensions, de-duplicating entries (first one wins).  Record the
-   ``.pth`` file the extension is found in (data structure TBD but documented).
+#. Parse the ``<name>.pth`` files in sorted order, keeping a global sorted
+   list of all path extensions, ignoring duplicates.
 
-#. *Future extension:* apply :ref:`global policy filter <future>` on sorted
-   list of path extensions.
+#. *Future extension:* apply a :ref:`global policy filter <future>` on the
+   sorted list of path extensions.
 
 #. Append path extensions in sorted order to ``sys.path``.
 
-#. List all ``.start`` files and sort in alphabetical order by filename.
+#. List all ``<name>.start`` files (see :ref:`discovery` for additional
+   details) and sort them in alphabetical order by filename.
 
-#. Parse ``.start`` files in sorted order, keeping a global sorted list of all
-   entry points, de-duplicating entries (first one wins).  Record the
-   ``.start`` file the entry point is found in (data structure TBD but
-   documented).
+#. Parse the ``<name>.start`` files in sorted order, keeping a global sorted
+   list of all entry points, ignoring duplicates.
 
-#. *Future extension:* :ref:`apply global policy filter <future>` on sorted
-   list of entry points.
+#. *Future extension:* apply a :ref:`global policy filter <future>` on the
+   sorted list of entry points.
 
 #. For each entry point, use :func:`pkgutil.resolve_name` to resolve the entry
    point into a callable.  Call the entry point with no arguments.
 
-For both ``.pth`` files and ``.start`` files, comment lines (i.e. lines
-beginning with ``#`` as the first non-whitespace character) and blank lines
-are ignored.  Any other parsing error causes the line to be ignored.
+In both ``<name>.pth`` files and ``<name>.start`` files, comment lines
+(i.e. lines beginning with ``#`` as the first non-whitespace character) and
+blank lines are ignored.  Any other parsing error causes the line to be
+ignored.
+
 
 .. _ep-syntax:
 
@@ -136,6 +145,8 @@ requires that the callable be specified.  See the :ref:`open issues
 <open-issues>` for further discussion.
 
 
+.. _discovery:
+
 File Naming and Discovery
 -------------------------
 
@@ -151,9 +162,9 @@ File Naming and Discovery
   ``<name>.pth`` files are found today.  The ``<name>.pth`` location stays the
   same.
 
-* The discovery rules for ``<name>.site.toml`` files is the same as
-  ``<name>.pth`` files today.  File names that start with a single ``.``
-  (e.g. ``.start``) and files with OS-level hidden attributes (``UF_HIDDEN``,
+* The discovery rules for ``<name>.start`` files is the same as ``<name>.pth``
+  files today.  File names that start with a single ``.`` (e.g. ``.start``)
+  and files with OS-level hidden attributes (``UF_HIDDEN``,
   ``FILE_ATTRIBUTE_HIDDEN``) are excluded.
 
 
@@ -378,9 +389,9 @@ Change History
 
 XX-XXX-2026
 
-* An evolution of the ``.pth`` file format and the addition of the ``.start``
-  file for entry point specification is proposed instead of the ``site.toml``
-  file from the previous draft.
+* An evolution of the ``<name>.pth`` file format and the addition of the
+  ``<name>.start`` file for entry point specification is proposed instead of
+  the ``<name>.site.toml`` file from the previous draft.
 
 
 Acknowledgments