PEP 842 – Module Exports

PEP 842 – Module Exports | peps.python.org

Following system colour scheme

Selected dark colour scheme

Selected light colour scheme

Author: Peter Bierma Discussions-To: Discourse thread Status: Draft Type: Standards Track Created: 25-Jul-2026 Python-Version: 3.16 Post-History: 24-Jul-2026, 31-Jul-2026

Table of Contents Abstract

Motivation Module-level names need privacy

Prefixed names aren’t necessarily a great solution It’s not always clear where names need prefixing

Prefixed names are not a universal rule

We want to be nice to users, not shrug them away Library consumers use runtime introspection for documentation

__all__ is only a convention

Specification __export__ rules Object requirements

Item requirements

Module attribute access Dunder names

Module __getattr__ functions

__dir__ behavior User-defined module __dir__ functions

Implicit __all__ definitions

Semantic implementation

Rationale __export__ is not an access modifier

Backwards Compatibility

Security Implications

How to Teach This

Reference Implementation Performance

Rejected Ideas Reuse __all__ for exports

Add new export syntax

Raising an exception upon accessing unexported attributes

Open Issues

Acknowledgements

Change History

Abstract

This PEP proposes an __export__ variable that modules can define to express intent about the visibility of variables from outside the module.

For example:

# spam.py __export__ = ["Public"]

class Public: ...

class Private: ...

>>> import spam >>> 'Public' in dir(spam) True >>> 'Private' in dir(spam) False >>> spam.Public

>>> spam.Private :1: RuntimeWarning: 'Private' is not exported by 'spam'

This is not intended to be an access modifier for Python; see __export__ is not an access modifier.

Motivation

Module-level names need privacy

A developer is writing a Python module. The module is intended to have one “public” class – a class that is intended for users of the module – called PublicAPI. As part of implementing PublicAPI, the developer wants to create another class, called Helper. However, Helper is not meant to be public in the same way that PublicAPI is public. Helper is supposed to only be used by the developer of the module – a “private” API.

Nonetheless, the developer declares the two classes as such:

# spam.py class Helper: ...

class PublicAPI: ...

The problem with this is that Helper comes with no indication that it’s not a public API. It shows up in autocomplete by language servers, the dir() function, Python’s interactive help() function, and every other API meant for introspection. How are users supposed to know that they aren’t supposed to use this?

Prefixed names aren’t necessarily a great solution

In Python, the convention for declaring private names is to prefix it with _. So, the developer changes Helper into _Helper:

# spam.py class _Helper: ...

This is generally the standard for Python libraries today, but it’s not clear that this is the best long term solution. This works (with some caveats; see the sections below), but this is (subjectively) less readable, and does require more keystrokes by the maintainer. Ideally, users shouldn’t be tempted to reach for private names from modules in the first place.

However, it is acknowledged that this idea is going against 30 years of convention; even if this PEP is accepted, it’s expected that “underscored” names (names prefixed with a leading _) will remain a staple of Python for years to come. The purpose of this PEP is not to eliminate the need for _ in module-level names, but instead to clear up corner cases where a private name is ambiguous or tempting. In other words, this PEP is intended to improve expressiveness and clarity with private APIs, not to add brand new functionality.

It’s not always clear where names need prefixing

Python defines names through many different constructs, some of which are not always clear or intuitive to the developer. As a result, it can be difficult to remember where names need to be prefixed. To put this issue into perspective, imagine that a developer wants to import some other modules in their code:

# spam.py import argparse import asyncio import tabnanny

In the above example, the spam module will have argparse, asyncio, and tabnanny as seemingly public attributes. In practice, this is not good for a maintainer, because maintainers may want to remove and change imports as they please, so these attributes should not be treated as public APIs.

Python’s standard library currently sidesteps this problem through a note in the backwards compatibility policy (PEP 387) that states that imported modules are not considered public APIs and may change at any time, but unfortunately, users are unable to determine this without directly reading the backwards compatibility policy, which is not a common thing to do. The solution to this is to also prefix every imported name with _:

# spam.py import argparse as...

PEP 842 – Module Exports

Related Articles

(no title)

Scientists reverse brain aging, with a nasal spray

NHS apologises and admits Palantir have access to identifiable patient data

AI has torched the market for junior programmers

Al Vigier: Canada's AI strategy shouldn't include secret Palantir bills