PEP 829: A few more updates

peps/pep-0829.rst

@@ -419,6 +419,35 @@ Open Issues
   to effectively ``W(.W)*:(W(.W)*)``, namely, rejecting the older, non-colon
   form, and making the callable after the colon required.
 
+* ``site.addpackage()`` is an undocumented function that processes a single
+  ``.pth`` file.  It is not listed in ``site.__all__``, not covered in
+  `Doc/library/site.rst
+  <https://github.com/python/cpython/blob/main/Doc/library/site.rst>`_, and
+  has no stability guarantees.  A GitHub code search found roughly half a
+  dozen third-party projects calling it directly, mostly with the pattern
+  ``site.addpackage(dir, "apps.pth", set())`` — all of which can be replaced
+  by ``site.addsitedir(dir)``.
+
+  During the work on the reference implementation, ``addpackage()`` becomes a
+  thin wrapper around the new internal pipeline for processing ``.pth`` and
+  ``.start`` files.  Maintaining it as a separate functions adds complexity
+  for no documented use case.  This function should be deprecated, with the
+  suggestion that users migrate to ``addsitedir()`` instead, a documented
+  public API.
+
+* The PEP currently recommends a three year deprecation period on the
+  *processing* of ``import`` lines in ``.pth`` files.  Packages can straddle
+  without warnings because the presence of a matching ``.start`` file
+  disables warnings for ``import`` lines in ``.pth`` files *during the
+  deprecation period*.  However, as currently written, warnings will be
+  re-enabled at the end of the deprecation period, so at that point there
+  isn't a way to straddle without warnings.
+
+  The preferred solution is to simply hide all warnings for ``import`` lines
+  in ``.pth`` files behind the ``-v`` (verbose) flag, either for a full 5 year
+  period (keeping the 3 year *processing* deprecation timeline), or
+  indefinitely.
+
 * Should future ``-X`` options provide fine-grained control over error
   reporting or entry point execution?
 
@@ -437,6 +466,9 @@ Change History
   when ``-v`` (verbose) is given.
 * Clarify that ``import`` lines in ``<name>.pth`` files where there is a
   matching ``<name>.start`` file are ignored.
+* Added some :ref:`open issues <open-issues>` around ``site.addpackage()``
+  deprecation, and extending the suppression of ``import`` line warnings in
+  ``.pth`` files unless ``-v`` is given, for an additional two years.
 
 `13-Apr-2026 <https://discuss.python.org/t/pep-829-structured-startup-configuration-files/106789/69>`__