Last bit of polish

Author: warsaw

peps/pep-0829.rst

@@ -47,8 +47,8 @@ support two functions:
   ``import\\t``) are executed immediately by passing the source string
   to ``exec()``.
 
-While there are valid use cases for each feature, the ``import`` lines
-support are the most problematic because:
+While there are valid use cases for both, the ``import`` line feature is the
+most problematic because:
 
 * Code execution is a side effect of the implementation.  Lines that
   start with ``import`` can be extended by separating multiple
@@ -77,49 +77,61 @@ This PEP proposes the following:
   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.
+* A new file format called ``<name>.start`` is 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
   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.
+  support this PEP and earlier versions which do not.  In this case, warnings
+  about ``import`` lines are *not* printed.
 
   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
+  matching ``<name>.start`` file, the processing of the former is unchanged,
+  although a warning about ``import`` lines is issued.  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.
 
   See the :ref:`teach` section for specific migration guidelines.
 
+.. _dash-S: https://docs.python.org/3/using/cmdline.html#cmdoption-S
+
+Both ``<name>.pth`` and ``<name>.start`` files are processed by the
+``site.py`` module, just like current ``.pth`` files.  This means that
+`disabling site.py processing <dash-S_>`__ with ``-S`` disables processing of
+both files.
+
 ``site.py`` start up code is divided into these explicit phases:
 
 #. Find the ``<name>.pth`` files (see :ref:`discovery` for additional details)
    and sort them in alphabetical order by filename.
 
-#. Parse the ``<name>.pth`` files in sorted order, keeping a global sorted
-   list of all path extensions, ignoring duplicates.
+#. Parse the ``<name>.pth`` files in sorted order, keeping a global list of
+   all path extensions, preserving order file-by-file and then by entry
+   appearance. Duplicates are ignored.
 
 #. *Future extension:* apply a :ref:`global policy filter <future>` on the
-   sorted list of path extensions.
+   list of path extensions.
 
-#. Append path extensions in sorted order to ``sys.path``.
+#. Append path extensions to ``sys.path`` in the global preserved order.
 
 #. List all ``<name>.start`` files (see :ref:`discovery` for additional
    details) and sort them in alphabetical order by filename.
 
-#. Parse the ``<name>.start`` files in sorted order, keeping a global sorted
-   list of all entry points, ignoring duplicates.
+#. Parse the ``<name>.start`` files in sorted order, keeping a global list of
+   all entry points, preserving order file-by-file and then by entry
+   appearance.  Duplicates are :ref:`not ignored <duplicate-eps>`.
 
 #. *Future extension:* apply a :ref:`global policy filter <future>` on the
-   sorted list of entry points.
+   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 each entry point in preserved order, use :func:`pkgutil.resolve_name`
+   to resolve the entry point into a callable.  Call the entry point with no
+   arguments and any return value is discarded.  The resolved object is not
+   tested for callability before it is called (and thus any ``TypeError`` that
+   might result is reported).
 
 In both ``<name>.pth`` files and ``<name>.start`` files, comment lines
 (i.e. lines beginning with ``#`` as the first non-whitespace character) and
@@ -162,34 +174,32 @@ File Naming and Discovery
   ``<name>.pth`` files are found today.  The ``<name>.pth`` location stays the
   same.
 
-* 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``,
+* The discovery rules for ``<name>.start`` files are the same as with
+  ``<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.
 
 
 Error Handling
 --------------
 
-Errors are handled differently depending on the phase:
+During parsing, errors are generally skipped and only reported when ``-v``
+(verbose) flag is given to Python.  Unlike with ``.pth`` files currently,
+processing does *not* abort for the entire file when an error is encountered.
+
+#. If a ``<name>.pth`` or ``<name>.start`` file cannot be opened or read, it
+   is skipped and processing continues to the next file.
 
-Phase 1: Reading and Parsing
-    If a ``<name>.pth`` or ``<name>.start`` file cannot be opened or read, it
-    is skipped and processing continues to the next file.  Errors are reported
-    only when ``-v`` (verbose) is given.
+#. Invalid entry point specifications are skipped.
 
-Phase 2: Execution
-    Invalid or nonexistent file system paths are ignored, with errors printed
-    to ``sys.stderr``.  Processing continues to the next path entry.
+During execution, errors are printed to ``sys.stderr`` and processing
+continues.
 
-    Invalid entry point specifications are skipped.  Exceptions during
-    execution of the entry point are printed to ``sys.stderr``.  Processing
-    continues to the next entry point.
+#. Any ``sys.path`` extension directory pointing to an invalid or nonexistent
+   path is ignored and processing continues to the next path entry.
 
-Because of the 2-phase interpretation of ``<name>.pth`` and ``<name>.start``
-files, continued evaluation of paths and entry points is a deliberate
-improvement over current ``.pth`` behavior, which aborts processing the
-remainder of a file on the first error.
+#. Exceptions during execution of the entry point are printed and processing
+   continues to the next entry point.
 
 
 .. _future:
@@ -246,8 +256,24 @@ for both ``sys.path`` extension and entry point invocation gives us a chance
 (:ref:`in the future <future>`) to design and implement global policies for
 explicitly controlling which path extensions and entry points are allowed (and
 by implication, deemed safe), without resorting to the heavy hammer of
-`disabling site.py processing completely
-<https://docs.python.org/3/using/cmdline.html#cmdoption-S>`_.
+`disabling site.py processing <dash-S_>`__ completely.
+
+All valid ``sys.path`` extensions in all ``<name>.pth`` files found are
+processed *before* any entry points in ``<name>.start`` files are called.
+This is to ensure that all ``sys.path`` modifications required to import entry
+point modules are applied first.
+
+.. _duplicate-eps:
+
+Entry points are *not* de-duplicated, regardless of whether they're defined
+multiple times in the same ``<name>.start`` file or across more than one
+``<name>.start`` file.  This means that if an entry point appears more than
+once it will get called more than once.  Unlike with the de-duplication of
+``sys.path`` entries (where the appearance of a directory path later on
+``sys.path`` than its duplicate has no effect), users could -- however
+unlikely -- actually want multiple invocations of their entry points.  This
+also avoids the complexity of defining de-duplicating entry point semantics
+across independently-authored ``<name>.start`` files.
 
 
 Backwards Compatibility
@@ -282,7 +308,7 @@ This PEP improves the security posture of interpreter startup.
   importable modules.
 
 The overall attack surface is not eliminated -- a malicious package can still
-cause arbitrary code execution viaentry points, but the mechanism proposed in
+cause arbitrary code execution via entry points, but the mechanism proposed in
 this PEP is more structured, auditable, and amenable to future policy
 controls.
 
@@ -294,7 +320,7 @@ 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 include:
+following 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
@@ -363,9 +389,9 @@ Open Issues
 * As described in the :ref:`entry point syntax <ep-syntax>` section, this PEP
   proposes to use a narrow definition of the acceptable object reference
   syntax implemented by :func:`pkgutil.resolve_name`, i.e. specifically
-  requiring the ``pkg.mod:callable`` syntax.  This is because a) we don't want
-  to encourage code execution by direct import side-effect (i.e. functionality
-  at module scope level).
+  requiring the ``pkg.mod:callable`` syntax.  This is because we don't want to
+  encourage code execution by direct import side-effect (i.e. functionality at
+  module scope level).
 
   Assuming this restriction is acceptable, how this is implemented is an open
   question.  ``site.py`` could enforce it directly, but then that sort of
@@ -403,12 +429,6 @@ to its current form.  Thanks also go to Emma Smith and Brett Cannon for their
 feedback and encouragement.
 
 
-Footnotes
-=========
-
-None
-
-
 Copyright
 =========