Text of peps.python.org › pep-0844 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 844 – public and private builtins | peps.python.org

PEP 844 – public and private builtins PEP 844 – public and private builtins Author : Barry Warsaw <barry at python.org> Discussions-To : Discourse thread Status : Draft Type : Standards Track Created : 05-Aug-2026 Python-Version : 3.16 Post-History : 11-Aug-2026 , 22-Sep-2026 Table of Contents Abstract Motivation __all__ already defines the public API Specification public() private() Restrictions Rationale Why builtins?

Why decorators? Why private() ? Static analysis of the function call forms Is this urgent? Import-time performance Relationship to PEP 842 and PEP 843 Two problems, not one Why __all__ and not __export__ Why PEP 843 is a good companion Backwards Compatibility Security Implications How to Teach This Reference Implementation Rejected Ideas New export syntax instead of decorators Add a new __export__ variable Accept an __all__ that is not a list Leave it on PyPI A new standard library module instead of builtins Open Issues Acknowledgements Footnotes Change History Copyright 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 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. Both additionally have a single argument call form for names that are bound by other means (such as from ... import statements), and public() has a keyword argument form for names that cannot be decorated, such as constants. For example: # spam.py from strings import Bass @public class Public : ... @private class Private : ... public ( Bass ) public ( TEMPO = 120 ) >>> import spam >>> spam . __all__ ['Public', 'Bass', 'TEMPO'] The proposed semantics are those of the third-party atpublic package, which has provided this functionality since 2016.

This PEP is an adjunct to PEP 843 , and to the withdrawn PEP 842 ; see Relationship to PEP 842 and PEP 843 . Motivation The module global variable __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: Names get added to the module but never added to __all__ . Names get removed from or renamed in the module but not in __all__ , so from spam import * raises AttributeError . It’s easy to typo a name (or leave out a list item delimiting comma) in __all__ . Drift is only detectable in one direction. A linter can flag a name in __all__ that doesn’t exist as an object in the module, but no tool can flag a public name missing from __all__ , because nothing in the source says that name was meant to be public.

Readers of the code must scroll to a different part of the file (or a different screen) to answer “is this name public?” The convention of prefixing private names with an underscore addresses a related but different problem, and PEP 842 describes at length why prefixing is not by itself a sufficient answer . The pattern proposed here – declaring visibility at the definition site with a decorator – is not new or speculative.

The atpublic package on PyPI has implemented it for a decade, and it is already depended on by a number of projects. What this PEP proposes is that the pattern is common enough, and useful enough, to be spelled without a third-party dependency. Thus it proposes to add atpublic ’s public() and private() functions to the builtins. __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 language reference explicitly says: The public names defined by a module are determined by checking the module’s namespace for a variable named __all__ ; if defined, it must be a sequence of strings which are names defined or imported by that module. […] The names given in __all__ are all considered public and are required to exist. If __all__ is not defined, the set of public names includes all names found in the module’s namespace which do not begin with an underscore character ( '_' ). __all__ should contain the entire public API.

It is intended to avoid accidentally exporting items that are not part of the API (such as library modules which were imported and used within the module). This PEP explicitly adopts the definition of “public” in the Python Language Reference. Following from this: The concept already exists and is normative. “Public name” is a term the language reference defines, and it defines it in terms of __all__ . This is specification text, not folklore.

Python is not missing a way to say what is public; it has one, and it is documented. Exhaustiveness is already the contract. “ __all__ should contain the entire public API” is unambiguous. A module whose __all__ lists only part of its public surface is not exercising some alternative reading – it is out of conformance with what the reference says __all__ means. The imported-module problem is already in scope. The reference names it outright: __all__ exists in part to avoid “accidentally exporting items that are not part of the API (such as library modules which were imported and used within the module).” A module that declares __all__ accurately and imports argparse does not leak the name argparse as part of its public API, with or without renaming the import to _argparse .

The gap, then, is not semantic but ergonomic. Python already specifies what it means for a name to be public, and already recommends that __all__ say so exhaustively, while providing no convenient way to keep that promise as a module evolves. It asks authors to maintain a list of string literals by hand, in a different part of the file from the definitions, which is subject to being quite error prone. This PEP supplies the missing ergonomics.

It does not redefine what it means to be “public”, or introduce a second notion of visibility, or change what __all__ already means. It doesn’t try to redefine what it means for a name to be exported. It does however make the documented contract easy enough to actually honor. 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() public() has three call forms.

The decorator form ( @public ) is the most common use. Decorator form. When called with a single positional argument that has a __name__ attribute (such as a function or a class), public() appends that object’s __name__ to the __all__ of the module in which public() is called, and returns the object unchanged: @public def tune (): ... @public class Cello : ... # __all__ == ['tune', 'Cello'] Note that the bare decorator is used; Python’s semantics are to implicitly pass the object it decorates as the first argument to the decorator function.

Single argument form. The same call written without the @ appends to __all__ a name that is already bound in t

The rest of this page is on the live site.