Document new 3.11 enum APIs (ReprEnum, global_* and/or show_flag_values)

@ethanfurman

As 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

Working on something now. I presume I commit to main and backport to 3.11?

I presume I commit to main and backport to 3.11?

Yup 👍 Thanks!

gh-98298: [Enum] document ReprEnum, global_enum, and show_flag_values (…

pythongh-98298: [Enum] document ReprEnum, global_enum, and show_flag_…

gh-98298: [Enum] document ReprEnum, global_enum, and show_flag_values (…

@ethanfurman

Hey @ethanfurman , are we all done here?

@CAM-Gerlach

@CAM-Gerlach I tihnk so.

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 possible

Is this behavior a bug? Or is there something missing in the documentation?

The behavior is intended, the docs need updating.

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?

Yes, you can link PRs to this issue. Thanks!

gh-98298, gh-74730: [Enum] update docs (GH-103163)

pythongh-98298, pythongh-74730: [Enum] update docs (pythonGH-103163)

gh-98298, gh-74730: [Enum] update docs (GH-103163)

@Bktero

@Bktero Closing this issue. When you have more doc updates, please open a new issue. 😄

pythongh-98298, pythongh-74730: [Enum] update docs (pythonGH-103163)

Navigation Menu

Repository navigation

Document new 3.11 enum APIs (ReprEnum, global_* and/or show_flag_values) #98298

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Document new 3.11 enum APIs (ReprEnum, global_* and/or show_flag_values) #98298

Description

Linked PRs

Activity

ethanfurman commented on Oct 19, 2022

CAM-Gerlach commented on Oct 19, 2022

CAM-Gerlach commented on Oct 21, 2022

ethanfurman commented on Oct 21, 2022

Bktero commented on Jan 12, 2023

ethanfurman commented on Jan 12, 2023

Bktero commented on Jan 13, 2023

ethanfurman commented on Jan 13, 2023

ethanfurman commented on Apr 3, 2023

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions