Python debates PEP 842 module exports and public API boundaries

Peter Bierma has proposed PEP 842, which would let a Python module declare an export collection of names treated as its public surface. Access to anything else from outside the module would draw a runtime warning, giving authors a stronger boundary than the leading-underscore convention or all, which only shapes star imports.

The idea targets a real maintenance gap. Underscores are inconsistently respected by type checkers and autocomplete, so internal names still leak into IDEs and downstream code. Packages that intentionally expose almost nothing public, and authors who already treat anything absent from all as private, want the language to document and gently enforce that intent.

Guido van Rossum objected to the ergonomics. Maintaining a separate list is easy to get wrong and sits far from the definitions it describes, the same flaw that makes all awkward. He favored marking exports at definition time, via an @export decorator for functions and classes or a soft keyword such as export (or private) that could cover data and aliases too. Bierma agreed the first draft was deliberately conservative and argued export should remain even if syntax arrives later, as a compatibility hook similar to patterns used for lazy imports.

Gregory P. Smith asked whether assignments to non-exported names should warn, whether RuntimeWarning is the wrong channel because it reaches application users instead of library owners, and whether the same idea belongs on class namespaces. He suggested purpose-built warning categories and, longer term, syntax that might retire all.

Paul Moore raised a sharper policy case from pip. Pip treats nearly its entire surface as internal, yet tools such as pip-tools deliberately use those internals with full knowledge they are unsupported. Warnings would either punish that acknowledged pattern or require escape hatches pip does not want to bless. Same-package access across multiple modules is also unresolved: directory-based exemptions break under ordinary layouts and namespace packages, and forcing packages to jump through hoops for their own code is unattractive.

After earlier pushback against raising ImportError, the PEP moved to warnings. Michael H retracted support on that change, saying a filterable warning does not force the intentional acknowledgment library authors want and is weaker than documented break policies plus explicit dict access. Bierma replied that hard errors had drawn too much opposition, that the documentation value still mattered to him, and that an audit hook could let projects fail closed if they choose.

The thread leaves open whether export should be a list, a decorator, or new syntax; how loud the signal should be; and how packages can keep internals usable to themselves and to known consumers without declaring them public API.