PEP 844: public and private builtins - #5079
Open
warsaw wants to merge 15 commits into
Open
Conversation
Documentation build overview
11 files changed ·
|
hugovk
reviewed
Aug 6, 2026
vstinner
reviewed
Aug 6, 2026
| Acknowledgements | ||
| ================ | ||
|
|
||
| Thanks to Peter Bierma and Neil Girdhar, whose :pep:`842` and PEP 843 prompted this proposal, and to |
Member
There was a problem hiding this comment.
Even if PEP 843 PR is not merged yet, it would be better to use a link:
Suggested change
| Thanks to Peter Bierma and Neil Girdhar, whose :pep:`842` and PEP 843 prompted this proposal, and to | |
| Thanks to Peter Bierma and Neil Girdhar, whose :pep:`842` and :pep:`843` prompted this proposal, and to |
Member
Author
There was a problem hiding this comment.
I can't apply this one until 843 is actually published, otherwise the build fails. I have a TODO to clean these up.
Member
There was a problem hiding this comment.
Oh, I didn't know that it emits an error. So it makes sense to not add a link yet!
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
ZeroIntensity
left a comment
ZeroIntensity
left a comment
Member
There was a problem hiding this comment.
I caught a few grammatical issues, but otherwise this looks good. It'd be good to get this up soon so people can share thoughts on it in contrast to the new 842 revision.
| Motivation | ||
| ========== | ||
|
|
||
| The :attr:`module global variable <module.__all__>` ``__all__`` is the mechanism Python currently |
Member
There was a problem hiding this comment.
This looks weird in the output because "module global variable" is rendered as code. I suggest doing this:
Suggested change
| The :attr:`module global variable <module.__all__>` ``__all__`` is the mechanism Python currently | |
| The module global variable :attr:`~module.__all__` is the mechanism Python currently |
|
|
||
| :pep:`842` gives two reasons why ``__all__`` is inadequate. The first is that ``__all__`` drifts | ||
| out of sync with the module. That is true, and it is precisely the problem ``atpublic`` and this | ||
| PEP solves. However a *new list of string literals in the same distant part of the file* does not |
Member
There was a problem hiding this comment.
- The subject here is plural, so it should be "solve" instead of "solves".
- "However" needs a trailing comma.
Suggested change
| PEP solves. However a *new list of string literals in the same distant part of the file* does not | |
| PEP solve. However, a *new list of string literals in the same distant part of the file* does not |
|
|
||
| ``Widget`` is named once to import it, and twice more to export it. That's a big violation of DRY! | ||
| Hand-maintaining ``__all__`` would name it only twice, so for re-exports specifically, ``public()`` | ||
| is not merely unhelpful, it is a step backwards. |
Member
There was a problem hiding this comment.
Comma splice:
Suggested change
| is not merely unhelpful, it is a step backwards. | |
| is not merely unhelpful; it is a step backwards. |
or:
Suggested change
| is not merely unhelpful, it is a step backwards. | |
| is not merely unhelpful, but rather it is a step backwards. |
|
|
||
| The conclusion is that the data and type alias use cases, which are the places a decorator | ||
| genuinely cannot be utilized, do not require new syntax at all. They require a function call that | ||
| tools can learn to read, alleviating the need for a dedicated, new ``export`` keyword. |
Member
There was a problem hiding this comment.
"Alleviating" feels awkward here; you alleviate a problem, not a solution. Maybe "removing" instead?
Suggested change
| tools can learn to read, alleviating the need for a dedicated, new ``export`` keyword. | |
| tools can learn to read, removing the need for a dedicated, new ``export`` keyword. |
| gained over the decade of ``atpublic``'s existence that requiring a third-party dependency (or an | ||
| import at the top of every module) to spell something this fundamental is friction that discourages | ||
| its use. It is also awkward in exactly the places where it matters most: the standard library | ||
| itself, and small single file modules. |
Member
There was a problem hiding this comment.
This needs a hyphen:
Suggested change
| itself, and small single file modules. | |
| itself, and small single-file modules. |
| tools can learn to read, alleviating the need for a dedicated, new ``export`` keyword. | ||
|
|
||
|
|
||
| .. _pep-844-urgency: |
Comment on lines
+228
to
+229
| module-level objects may be decorated. Decorating a method inside a class body is not supported, | ||
| since ``__all__`` documents module contents, not class contents. |
Member
There was a problem hiding this comment.
This is very nitpicky, but what happens if you decorate a method? Is it an error, or does it append the name to __all__?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Initial draft of a PEP to go along side 842 and 843 (hence the claim on 844)