Python core developer Barry Warsaw has officially introduced a draft proposal to integrate two new functions, public() and private(), into the language’s built-in namespace. Designated as PEP 844, this Standards Track proposal aims to modernize how Python modules declare their public interfaces, addressing a decade-long ergonomic deficiency in the management of the all global variable. If accepted, the change is targeted for implementation in Python 3.16, marking a significant shift in the language’s approach to API documentation and visibility.
The proposal seeks to solve the "Don’t Repeat Yourself" (DRY) violation inherent in Python’s current mechanism for defining public APIs. Currently, Python developers use the all list—usually placed at the top of a module—to specify which names should be exported during a wildcard import (from module import *). However, this list often exists far from the actual definitions of the classes and functions it contains, leading to synchronization errors, stale entries, and increased maintenance overhead.
The Evolution of API Visibility in Python
The concept of visibility in Python has historically relied on a mixture of naming conventions and the all variable. Since the early days of the language, the use of a leading underscore (e.g., _private_func) has served as a signal to both the interpreter and the developer that a name is intended for internal use. While effective for simple scripts, this convention often proves insufficient for large-scale library maintenance.
As codebases grow, the disconnect between an object’s definition and its declaration in all becomes a liability. PEP 844 argues that by the time a developer reaches the end of a 1,000-line module, they may have forgotten to add a new class to the all list at the top of the file. Conversely, when a function is deleted, the corresponding string literal in all is frequently left behind, resulting in an AttributeError when a user attempts a wildcard import.
To mitigate these issues, Warsaw’s proposal leverages a pattern established by the third-party atpublic package, which has been in active use within the Python ecosystem since 2016. By moving the declaration of visibility to the point of definition using decorators, the proposal ensures that an object’s public status is declared exactly once.
Technical Specifications and Functional Forms
PEP 844 introduces three primary ways to utilize the new built-ins, ensuring that all types of module-level bindings—from functions to constants—are covered.
The Decorator Form
The most common application of the proposal involves using @public or @private as decorators for classes and functions. When a function is decorated with @public, the function’s name is automatically appended to the module’s all list. If all does not yet exist, the function creates it as a list.
@public
def calculate_metrics():
passIn this scenario, the name ‘calculate_metrics’ is added to all at the moment the module is initialized. This eliminates the need for the developer to manually manage a separate list of strings.
The Single Argument Form
For names that are bound through other means, such as imports from other modules, the proposal provides a functional call form. This allows developers to re-export names cleanly.
from .internal_utils import helper_func
public(helper_func)This form is particularly useful for "hub" modules that collect various internal components and present them as a unified public API. The proposal specifies that the name appended to all is the name the object is bound to in the calling module, rather than the name it was originally defined with.
The Keyword Argument Form
Because constants (such as integers or strings) and instances cannot be decorated, PEP 844 introduces a keyword argument form. This form binds the value to the module’s globals and simultaneously adds the name to all.
public(MAX_RETRIES=5, TIMEOUT=30)This specific form is designed to be the "ultimate DRY" solution for configuration values and global settings, ensuring that the variable name is written only once in the source code.
Historical Chronology and Development Timeline
The path to PEP 844 has been defined by a decade of experimentation and several competing proposals.
- 2016: Barry Warsaw releases the
atpublicpackage on PyPI. It gains traction among library maintainers who seek a more ergonomic way to manage all. - 2021–2025: Various discussions occur within the Python Core Development team regarding "Export" syntax. PEP 842 and PEP 843 are drafted to explore new keywords like
export. - August 5, 2026: Barry Warsaw officially creates PEP 844, proposing the inclusion of
atpublic‘s logic into the Python built-ins to avoid the need for third-party dependencies. - August 11, 2026: The proposal is posted to the Python Discourse for community feedback.
- September 21, 2026: Version 8.0.1 of the
atpublicpackage is released, aligning its semantics with the PEP 844 specification. - September 22, 2026: PEP 844 is revised to include stricter requirements, such as requiring all to be a list rather than a tuple.
Comparative Analysis: Built-ins vs. New Syntax
One of the most debated aspects of PEP 844 is its relationship to the now-withdrawn PEP 842 and the active PEP 843. PEP 842 had proposed a new export keyword, which would have required changes to the Python grammar.
Warsaw argues that a built-in function is a "cheaper" and more flexible alternative to new syntax. While a new keyword like export is permanent and cannot be easily back-ported to older versions of Python via shims, a built-in function like public() can be easily emulated in older environments. Furthermore, adding to the built-in namespace does not require a change to the Python parser, reducing the complexity of the implementation.
However, the proposal acknowledges a significant trade-off regarding static analysis. Tools like Mypy, Pyright, and various Linters are designed to recognize standard assignment patterns. A function call that binds a variable (like the keyword form of public()) is invisible to many current static analyzers. Warsaw contends that this is a "one-time, bounded cost" for tool maintainers, who already provide special-case support for other namespace-altering callables like namedtuple() and dataclass().
Performance Considerations and Implementation
A recurring concern in the Python community is the impact of any change on "import time"—the time it takes for the interpreter to load a module. Because decorators and function calls execute at runtime during the import process, there is a theoretical overhead compared to static list assignments.
To address this, PEP 844 suggests a C implementation within the CPython core. By implementing public() and private() in C, the interpreter can bypass much of the overhead associated with Python-level function calls and frame introspection. Warsaw notes that previous versions of the atpublic library used a C extension to achieve significant speedups, but this was eventually dropped to simplify third-party distribution. As a built-in, this performance advantage would be restored without the packaging burden.
Industry Impact and Community Reaction
The reaction from the Python community has been cautiously optimistic, with a focus on how this will change the "teaching" of Python. For decades, the leading underscore and all have been staples of intermediate Python education. If PEP 844 is adopted, the "standard" way to write a module will shift toward the use of decorators.
Library maintainers, particularly those managing large frameworks like Django or SQLAlchemy, stand to benefit the most. These projects often have complex internal structures where names are imported and re-exported across multiple sub-packages. The ability to use public(Object) immediately following an import statement would significantly clarify the intended API surface for contributors.
There is also a documentation benefit. When a developer reads code decorated with @private, the intent is unmistakable. It signals that the developer explicitly considered the visibility of the function and decided against making it public. This is seen as a superior alternative to leaving a function undecorated, which leaves future maintainers guessing whether the omission from all was intentional or an oversight.
Broader Implications for the Python Ecosystem
The introduction of public() and private() represents a move toward more "declarative" programming in Python. By embedding metadata (visibility) directly into the definition of objects, Python is following a trend seen in languages like Java (with access modifiers) and Rust (with the pub keyword), albeit in a way that remains uniquely "Pythonic" and dynamic.
If the PEP is accepted, it may pave the way for future runtime enforcement. While PEP 844 currently treats these functions as documentation and synchronization tools, future versions of Python could theoretically use the data generated by public() to issue warnings when private names are accessed from outside a module. However, the current draft explicitly avoids such enforcement to maintain backward compatibility and the language’s "consenting adults" philosophy.
As the discussion continues on the Python Discourse, the core development team will need to weigh the benefits of improved ergonomics against the slight increase in the complexity of the built-in namespace. With the target set for Python 3.16, the community has ample time to refine the specification and ensure that this 20-year-old "DRY" problem is finally laid to rest.
