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

[CAM-Gerlach]

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

• gh-98298, gh-74730: [Enum] update docs #103163
• [3.11] gh-98298, gh-74730: [Enum] update docs (GH-103163) #103227

[ethanfurman]

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

[CAM-Gerlach]

I presume I commit to main and backport to 3.11?

Yup 👍 Thanks!

[CAM-Gerlach]

Hey @ethanfurman , are we all done here?

[ethanfurman]

@CAM-Gerlach I tihnk so.

[Bktero]

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?

[ethanfurman]

The behavior is intended, the docs need updating.

[Bktero]

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]

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

[ethanfurman]

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