ReleaseBytes
python Python PEPs ·

PEP 844 proposes `public()` and `private()` builtins for improved Python module APIs

engineer
announcement

Python Enhancement Proposal 844 (PEP 844) introduces `public()` and `private()` builtins for Python 3.16, designed to synchronize a module's `__all__` with explicitly declared public and private names. These new functions, primarily used as decorators, address long-standing ergonomic issues with `__all__` by declaring name visibility at the point of definition. The proposal aims to formalize a pattern already proven by the `atpublic` third-party package. This change will affect Python developers managing module APIs, especially for libraries, by making it easier to maintain accurate public interface declarations.

  • →Introducing PEP 844 for Public/Private Builtins
  • →Addressing `__all__` Synchronization Challenges
  • →Specification of `public()` and `private()` Builtins
Notes (3) ›
  • Introducing PEP 844 for Public/Private Builtins

    PEP 844 proposes adding `public()` and `private()` built-in functions to Python 3.16. These functions, typically used as decorators, will automatically keep a module's `__all__` synchronized with names explicitly designated as public or private.

  • Addressing `__all__` Synchronization Challenges

    The proposal tackles common problems with `__all__`, such as names being added to modules but not `__all__`, or names being removed without `__all__` being updated. It aims to improve the ergonomics of declaring a module's public interface, acknowledging that Python's language reference already defines `__all__` as normative for public API declaration.

  • Specification of `public()` and `private()` Builtins

    `public()` can be used as a decorator for functions and classes, or as a function call for constants, appending names to `__all__`. `private()` is exclusively a decorator, signaling that a name is not part of the module's public interface and ensuring it is not in `__all__`. Both functions affect only module-level visibility and create `__all__` if it does not already exist.

Read the original announcement →

https://peps.python.org/pep-0844/

Related releases