PEP 843 – Export Statement for DRY Re-exports | peps.python.org

The Python development community is currently evaluating a transformative proposal that seeks to resolve a long-standing redundancy in the language’s module system. Authored by Neil Girdhar and sponsored by Peter Bierma, the draft proposal—formally introduced in August 2026—suggests the implementation of a new export keyword. This addition is designed to bridge the gap between a library’s internal implementation layout and its public-facing API, effectively automating the management of the __all__ attribute which has historically required manual, error-prone maintenance.

The Evolution of the Hub-and-Internals Pattern

For decades, Python library maintainers have utilized a "hub-and-internals" architecture. In this design, a large library organizes its code into a complex tree of submodules and private directories, which is convenient for development and maintenance. However, to provide a user-friendly experience, these libraries typically present a "flattened" public layout. For example, a user might import a class directly from the top-level package (from library import Tool) rather than navigating the deep internal structure (from library._internal.core.utils import Tool).

To achieve this flattening today, developers must employ one of two suboptimal methods. The first involves the "Double-Write Problem," where every exported name is written twice: once in an import statement and once as a string within the __all__ list. This violates the "Don’t Repeat Yourself" (DRY) principle, a core tenet of software engineering which states that every piece of knowledge must have a single, unambiguous representation within a system. When a library grows to include hundreds of functions and classes, keeping these two lists in sync becomes a significant maintenance burden.

The second method is the "reflexive-alias idiom," written as from module import name as name. While this signal tells type checkers that an import is an intentional re-export, it often appears as a typo or redundant code to human readers and can be inadvertently removed by automated code formatters that mistake it for an unused import.

Technical Specification of the Export Statement

The proposed export keyword acts as a "soft keyword," meaning it only carries special significance in the specific context of a from ... export statement, thereby preserving backward compatibility with existing codebases that might use "export" as a variable name.

Under the new specification, the statement from ._internal.core export PublicAPI would perform two simultaneous actions at runtime. First, it binds the name PublicAPI in the current module’s namespace, just as a standard import would. Second, it automatically appends the string "PublicAPI" to the module’s __all__ attribute. If __all__ does not exist, the machinery initializes it as a list.

The proposal also includes support for aliases and wildcard exports. A developer could write from ._internal.widgets export Widget as PublicWidget, which would bind the name under the alias and add "PublicWidget" to the export list. Furthermore, the wildcard form from ._internal.core export * would import all public names from the internal module and extend the current module’s __all__ list with those names in a single operation. This is particularly useful for "hub" modules that serve as the primary entry point for a package.

Chronology of the Proposal and Community Discussion

The journey of the export statement began on August 5, 2026, with the initial draft of the proposal. It was born out of discussions surrounding PEP 842, a broader proposal that attempted to introduce more rigid module exports and runtime access warnings. While PEP 842 faced criticism for its complexity and the potential performance overhead of enforcing "private" access at runtime, Girdhar’s proposal takes a more surgical approach, focusing specifically on the ergonomics of re-exporting names.

Following the initial posting, the proposal moved to the Python Discourse forums on August 21, 2026, where it underwent rigorous peer review. Key contributors to the discussion included prominent members of the Python steering committee and maintainers of major libraries. The timeline for implementation is currently set for Python 3.16, allowing the community ample time to refine the grammar changes and ensure that static analysis tools, such as Ruff and Mypy, can adapt to the new syntax.

Supporting Data: The Scale of the Redundancy Problem

To justify the need for a new keyword, the proposal points to several high-profile projects in the Python ecosystem. Libraries such as NumPy, pandas, Polars, FastAPI, and Typer are cited as primary examples of the "Double-Write" struggle.

In the case of pandas and Polars, the __init__.py files often contain hundreds of lines where names are imported from internal submodules and then meticulously listed again in a massive __all__ array. For instance, the pandas __init__.py has historically featured a wall of imports exceeding 300 lines. The proposal argues that this manual synchronization is not just a nuisance but a source of bugs. If a developer adds a new feature but forgets to update __all__, the feature remains invisible to wildcard imports and documentation generators. Conversely, if a name is removed from the import list but remains in __all__, it can lead to AttributeError at runtime when users attempt to access the ghost reference.

Integration with Lazy Imports

One of the most innovative aspects of the proposal is its synergy with PEP 810, which introduces explicit lazy imports. In modern high-performance computing and data science, the time it takes to import a library (the "time-to-first-plot") is a critical metric. Large libraries like NumPy often use complex __getattr__ hacks to defer loading submodules until they are actually needed.

The new export keyword is designed to work seamlessly with the lazy keyword. A statement such as lazy from ._internal.core export PublicAPI would immediately add "PublicAPI" to the __all__ list—ensuring that dir(library) and IDE auto-completion work correctly—while deferring the actual loading of the _internal.core module until the PublicAPI object is accessed. This would allow library authors to replace hundreds of lines of brittle __getattr__ logic with a few clean, declarative statements.

Analysis of Broader Implications and Industry Reactions

The introduction of export represents a shift in Python’s philosophy toward more declarative API design. By making the public layout of a package explicit and easy to maintain, the proposal is expected to improve the quality of documentation and the reliability of third-party tools.

Initial reactions from the developer community have been largely positive, though some purists argue against the proliferation of new keywords. However, the consensus among library maintainers appears to be that the reduction in "boilerplate" code outweighs the cost of learning a new syntax.

"The current way we handle re-exports is a relic of an era when Python packages were much smaller," noted one contributor during the Discourse debate. "As we move toward a world where Python is the backbone of massive AI and data engineering pipelines, the language needs built-in mechanisms to manage these complex interfaces without relying on hacks."

From a static analysis perspective, the proposal is a significant win. Modern IDEs like VS Code and PyCharm rely on __all__ to determine which names to suggest to users. By automating the population of this list, the export statement ensures that the IDE’s view of the library is always in sync with the actual code, reducing the "false positive" unused import warnings that currently plague developers using the as name idiom.

Comparison with Alternative Approaches

During the development of the proposal, several alternative ideas were rejected. One such idea was a @public decorator, similar to the one found in the third-party atpublic package. While decorators work well for functions and classes defined within the same module, they cannot easily be applied to imported names. Since the primary problem exists in "hub" modules that do not define their own functions, a decorator-based solution was deemed insufficient.

Another rejected idea was the implementation of "runtime enforcement," where Python would raise an error if a user tried to access a name not listed in __all__. The author of the current proposal intentionally excluded this feature to avoid the "adversarial framing" and performance penalties associated with policing private access. Instead, the proposal relies on existing conventions—such as the underscore prefix—to signal privacy, while using export to simplify the declaration of the public boundary.

Future Outlook and Conclusion

As Python 3.16 approaches its development milestones, the export statement stands as one of the most anticipated features for library authors. By solving the DRY violation inherent in the current module system, the proposal promises to make the Python ecosystem more robust and easier to navigate.

The proposal concludes by emphasizing that while direct __all__ manipulation will remain available for dynamic use cases—such as plugins discovered at runtime—the export statement will become the standard for the vast majority of static re-exports. This evolution reflects a maturing language that continues to prioritize developer experience and code clarity, ensuring that Python remains the preferred tool for building complex, multi-layered software systems. Given the strong support from maintainers of the ecosystem’s most critical libraries, the export keyword is likely to define the next era of Pythonic API design.