GeezerVison is showing github.com — Document new 3.11 enum APIs (ReprEnum, global_* and/or show_flag_values) · Issue #98298 · python/cpython
Document new 3.11 enum APIs (ReprEnum, global_* and/or show_flag_values) #98298DescriptionAs discovered in #98295 , there are several undocumented new APIs in the enum module:
ReprEnum and is documented in What's New (and exported in __all__), but not anywhere in the enum library module documentation, which seems like an oversight.- Likewise,
global_enum is documented in What's New (and exported in __all__) and was previously documented in the library docs, but that documentation was reverted in bpo-40066: Revert "Revert "bpo-40066: [Enum] update str() and format() output..." #30637 , and not restored, so I'm unsure on the current status.
global_str, global_enum_repr and global_flag_repr were added (to replace the __str__() and __repr__() of the appropriate classes) and are not marked as private (_) and are exported by __all__, but aren't documented either. Should they be?show_flag_values was added and is not in __all__, but its use is referred to in an error message (cited in the docs) and it is not marked private (_). Should this be documented as well?
@ethanfurman your guidance here would be much appreciated, thanks. I'm happy to review/copyedit a PR, or if you prefer, I can draft something and you review it. Ideally, we should get this in before the 3.11 release in a week or so...
Related: #95913
Linked PRs
Activityethanfurman commented on Oct 19, 2022 Working on something now. I presume I commit to main and backport to 3.11? Reacted by C.A.M. Gerlach Reacted by C.A.M. Gerlach CAM-Gerlach commented on Oct 19, 2022
I presume I commit to main and backport to 3.11?
Yup 👍 Thanks! added a commit that references this issue on Oct 21, 2022gh-98298: [Enum] document ReprEnum, global_enum, and show_flag_values (… added 2 commits that reference this issue on Oct 21, 2022pythongh-98298: [Enum] document ReprEnum, global_enum, and show_flag_… gh-98298: [Enum] document ReprEnum, global_enum, and show_flag_values (… CAM-Gerlach commented on Oct 21, 2022 ethanfurman commented on Oct 21, 2022 Bktero commented on Jan 12, 2023 Hi!
Inthe documentation, we can read (3.11.1) :
@enum.global_enum
A decorator to change the str() and repr() of an enum to show its members as belonging to the module instead of its class
It is not said that members of the enum are also added to the global namespace. Example:
from enum import global_enum, Enum
@global_enum
class Foo(Enum):
BAR = 1
print(BAR) # the documentation doesn't tell that this is possibleIs this behavior a bug? Or is there something missing in the documentation? Reacted by C.A.M. Gerlach ethanfurman commented on Jan 12, 2023 The behavior is intended, the docs need updating. Bktero commented on Jan 13, 2023 I have been testing the almost all the new enum features yesterday, and I have other points for improving the documentation.
Should I create a new issue or is there an existing issue I can contribute to? EDIT: this current issue is not closed, so I can add stuff here, right? ethanfurman commented on Jan 13, 2023 Yes, you can link PRs to this issue. Thanks! ethanfurman commented on Apr 3, 2023 @Bktero Closing this issue. When you have more doc updates, please open a new issue. 😄
MetadataMetadataStatusShow more project fields
DevelopmentNo branches or pull requestsIssue actions
|