Edits based on PR feedback

Author: warsaw

peps/pep-0844.rst

@@ -14,10 +14,10 @@ Abstract
 
 This PEP proposes adding two new builtin functions, ``public()`` and ``private()``, which document
 the public interface of a module by keeping its ``__all__`` synchronized with the names actually
-defined in that module.  Both are used as decorators (``@public`` and ``@private``) on class and
-function definitions, so that a name's visibility is declared exactly once, at the point where the
-name is defined.  ``public()`` additionally has a function call form for names that cannot be
-decorated, such as constants.
+defined to be public in that module.  Both are used as decorators (``@public`` and ``@private``) on
+class and function definitions, so that a name's visibility is declared exactly once, at the point
+where the name is defined.  ``public()`` additionally has a function call form for names that cannot
+be decorated, such as constants.
 
 For example:
 
@@ -49,11 +49,11 @@ This PEP is an adjunct to :pep:`842` and PEP 843; see `Relationship to PEP 842 a
 Motivation
 ==========
 
-The module global variable :attr:`~module.__all__` is the mechanism Python currently
-defines for declaring a module's public names.  However, ``__all__`` suffers from a well known
-problem: it is typically defined as a separate list often far from the objects whose names are
-contained in it.  An object defined at one point in the file is repeated as a string literal in an
-``__all__`` list somewhere else, usually at the top of the file.
+The module global variable :attr:`~module.__all__` is the mechanism Python currently defines for
+declaring a module's public names.  However, ``__all__`` suffers from a well-known problem: it is
+typically defined as a separate list often far from the objects whose names are contained in it.  An
+object defined at one point in the file is repeated as a string literal in an ``__all__`` list
+somewhere else, usually at the top of the file.
 
 Nothing keeps the two in sync, leading to these problems:
 
@@ -83,9 +83,9 @@ enough, and useful enough, to be spelled without a third-party dependency.  Thus
 ``__all__`` already defines the public API
 ------------------------------------------
 
-It is sometimes said that Python has no way to express which names in a module are public and which
-are private, and that ``__all__`` is merely a convention governing ``from spam import *``. However,
-the :ref:`language reference <import>` explicitly says:
+It is sometimes said that Python has no way to express which names in a module are public and
+which are private, and that ``__all__`` is merely a convention governing ``from spam import *``.
+However, the :ref:`language reference <import>` explicitly says:
 
    The *public names* defined by a module are determined by checking
    the module's namespace for a variable named ``__all__``; if defined,
@@ -133,6 +133,14 @@ Specification
 
 Two new builtins are added: ``public()`` and ``private()``.
 
+This PEP concerns module-level visibility only.  ``public()`` and ``private()`` declare which of a
+module's global names make up its public interface, and they do so by maintaining ``__all__``, which
+is defined for modules and nothing else.  Visibility in any other scope is explicitly excluded:
+class attributes and methods, names local to a function, and names bound in nested scopes are all
+untouched by this proposal.  Python has no ``__all__`` equivalent for those scopes, and this PEP
+does not propose one.  Whether a method is part of a class's public interface remains, as today, a
+matter of naming convention and documentation.
+
 ``public()``
 ------------
 
@@ -217,17 +225,23 @@ author's intent; ``@public`` is what makes that intent observable.
 .. note::
 
    ``private()`` does *not* support a function call form, as no valid use case for it has been
-   identified or requested by users of the ``atpublic`` module.  See `Open Issues`_ for
-   further discussion.
+   identified or requested by users of the ``atpublic`` package.  See `Open Issues`_ for further
+   discussion.
 
 
 Restrictions
 ------------
 
-Note that because ``@public`` is primarily used to keep the ``__all__`` module global in sync, only
-module-level objects may be decorated.  Decorating a method inside a class body is not supported,
+Because ``@public`` and ``@private`` exist to keep the ``__all__`` module global in sync, only
+module-level objects may be declared.  Decorating a method inside a class body is not supported,
 since ``__all__`` documents module contents, not class contents.
 
+Neither function inspects the scope it is called from, so this misuse is not currently diagnosed.
+A decorator applied to a method appends the method's name to the enclosing *module's* ``__all__``,
+and a function call form used in a class body binds its keywords in the module globals rather than
+in the class body.  Neither outcome is likely to be what the author intended.  Whether these cases
+should raise an exception instead is an `Open Issues`_ question.
+
 Because ``__all__`` must be mutable for these functions to append to it, a module that assigns
 ``__all__`` itself must assign a list.  A module that wants an immutable ``__all__`` can freeze it
 after the last declaration with ``__all__ = tuple(__all__)``.
@@ -288,9 +302,9 @@ explicitly.  Given:
 ``SEVEN`` is bound in the module's globals by a function that reaches into its caller's frame.
 Nothing about that binding is visible in the syntax tree.  A type checker, linter, or language
 server reading the source sees a bare function call and no assignment, and will therefore report
-``SEVEN`` as undefined at every use site.  A soft keyword like ``export SEVEN = 7`` (such as
-proposed by :pep:`842`) has no such problem, because syntax is by construction visible to anything
-that parses the file.  This, and not the DRY objection raised in :pep:`842`, is the real cost of
+``SEVEN`` as undefined at every use site.  A soft keyword like ``export SEVEN = 7``, as proposed by
+:pep:`842`, has no such problem, because syntax is by construction visible to anything that parses
+the file.  This, and not the DRY objection raised in :pep:`842`, is the real cost of
 choosing a builtin over a keyword.
 
 This could easily be alleviated by future modifications to linting tools, so that they explicitly
@@ -322,8 +336,8 @@ Here the binding is a plain assignment, visible to every tool that parses Python
 transition aid rather than the recommended spelling, and it should not be needed for long.
 
 The conclusion is that the data and type alias use cases, which are the places a decorator
-genuinely cannot be utilized, do not require new syntax at all.  They require a function call that
-tools can learn to read, alleviating the need for a dedicated, new ``export`` keyword.
+genuinely cannot be utilized, do not require new syntax at all.  A function call that tools can
+recognize serves just as well, without the need for a new, dedicated ``export`` keyword.
 
 
 .. _pep-844-urgency:
@@ -369,7 +383,7 @@ pressing, but because the cheaper alternative stops being available once the exp
 
 .. _pep-844-performance:
 
-Import time performance
+Import-time performance
 -----------------------
 
 When this idea was informally floated with core developers some years ago, before either :pep:`842`
@@ -522,7 +536,7 @@ module" that pulls names out of private submodules must currently write each nam
 
 ``Widget`` is named once to import it, and twice more to export it.  That's a big violation of DRY!
 Hand-maintaining ``__all__`` would name it only twice, so for re-exports specifically, ``public()``
-is not merely unhelpful, it is a step backwards.
+is not merely unhelpful, but a step backwards.
 
 The decorator form of ``@public`` is unavailable here because there is nothing to decorate, and the
 function call form of ``public()`` requires naming the binding explicitly.  This is exactly the gap
@@ -663,18 +677,18 @@ Leaving ``atpublic`` on PyPI is the status quo option.  Users who want to opt in
 functionality can simply add that library as a dependency and import the functions (or use the
 ``pip install atpublic[install]`` extra to populate builtins).
 
-However, if this *is* a problem worth solving now, then leaving this in a third-party module on PyPI
-doesn't serve our users adequately.  The need to include a dependency and an explicit import may
-be just enough of a hurdle (albeit small) to stop widespread use of it.  Adding it to builtins gives
-this pattern a promotional endorsement that will gain in popularity.
+However, if this *is* a problem worth solving now, then leaving this in a third-party package on
+PyPI doesn't serve our users adequately.  The need to include a dependency and an explicit import
+may be just enough of a hurdle (albeit small) to stop widespread use of it.  Adding it to builtins
+endorses the pattern in a way that should broaden its adoption.
 
 
 A new standard library module instead of builtins
 -------------------------------------------------
 
 This would eliminate the third-party dependency problem, but still leaves the explicit import
 usability cost.  In addition, there's no obvious place to add it to the stdlib *other than* in
-builtins.  Two functions likely isn't worth the cost of a new top-level module.  Besides, since
+builtins.  Two functions likely aren't worth the cost of a new top-level module.  Besides, since
 ``__all__`` is in a sense built into Python, these functions should be built in too.
 
 
@@ -690,13 +704,17 @@ Open Issues
   visibility ergonomics.
 * Should ``private()`` support a function call form, for symmetry?  ``atpublic`` does not provide
   one and no need for it has ever been demonstrated or requested.
+* Should ``public()`` and ``private()`` diagnose being called outside module scope?  Neither
+  inspects its calling scope today, so ``@public`` on a method silently adds the method's name to
+  the module's ``__all__``.  Raising an exception would be friendlier, at the cost of a scope check
+  on every call, which bears on :ref:`pep-844-performance`.
 * Should the standard library itself adopt these decorators, and if so on what schedule?  This
   question is entangled with :ref:`pep-844-performance` and should be settled with startup
   measurements in hand.  Also, as with all new capabilities (such as lazy imports), Python's policy
   is generally not to wholesale update the stdlib to embrace the new functionality.  These new
   functions can be utilized opportunistically in modules where the most benefit can be gained, or
   when a module undergoes substantial rewrite.
-* Import time benchmarks for a C implementation are outstanding.
+* Import-time benchmarks for a C implementation are outstanding.
 
 
 Acknowledgements