cpython icon indicating copy to clipboard operation
cpython copied to clipboard

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

Open CAM-Gerlach opened this issue 3 years ago • 0 comments

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 #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

CAM-Gerlach avatar Oct 15 '22 20:10 CAM-Gerlach