Enum: modify __repr__, __str__; update docs

[ethanfurman]

BPO	40066
Nosy	@warsaw, @rhettinger, @scoder, @vstinner, @tiran, @ezio-melotti, @ethanfurman, @serhiy-storchaka, @The-Compiler, @vedgar, @mscuthbert, @pablogsal, @kulikjak, @kumaraditya303
PRs	bpo-40066: Enum: modify repr() and str() #22392 bpo-40066: Enum global repr doctest #25116 bpo-40066: Enum: add (re)import of Flag for doctests #25118 bpo-40066: [Enum] update str() and format() output #30582 Revert "bpo-40066: [Enum] update str() and format() output" #30632 bpo-40066: Revert "Revert "bpo-40066: [Enum] update str() and format() output..." #30637 bpo-40066: [Enum] fix doc and unit tests #30643

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/ethanfurman'
closed_at = <Date 2022-01-23.00:28:03.406>
created_at = <Date 2020-03-25.19:48:58.219>
labels = ['type-feature', 'library', '3.10', '3.11']
title = 'Enum: modify __repr__, __str__; update docs'
updated_at = <Date 2022-01-23.00:28:03.406>
user = 'https://github.com/ethanfurman'

bugs.python.org fields:

activity = <Date 2022-01-23.00:28:03.406>
actor = 'ethan.furman'
assignee = 'ethan.furman'
closed = True
closed_date = <Date 2022-01-23.00:28:03.406>
closer = 'ethan.furman'
components = ['Library (Lib)']
creation = <Date 2020-03-25.19:48:58.219>
creator = 'ethan.furman'
dependencies = []
files = []
hgrepos = []
issue_num = 40066
keywords = ['patch']
message_count = 25.0
messages = ['365019', '366190', '376900', '376913', '376915', '376918', '377495', '378019', '378239', '389869', '390895', '390956', '390976', '396790', '410676', '410711', '410758', '410773', '410775', '410796', '410797', '410801', '410802', '410803', '410805']
nosy_count = 16.0
nosy_names = ['barry', 'rhettinger', 'scoder', 'vstinner', 'christian.heimes', 'ezio.melotti', 'mrabarnett', 'eli.bendersky', 'ethan.furman', 'serhiy.storchaka', 'The Compiler', 'veky', 'mscuthbert', 'pablogsal', 'kulikjak', 'kumaraditya']
pr_nums = ['22392', '25116', '25118', '30582', '30632', '30637', '30643']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue40066'
versions = ['Python 3.10', 'Python 3.11']

[ethanfurman]

Serhiy had the idea of having Enum._convert also modify the __str__ and __repr__ of newly created enumerations to display the module name instead of the enumeration name (https://bugs.python.org/msg325007):

--> socket.AF_UNIX
<AddressFamily.AF_UNIX: 1> ==> <socket.AF_UNIX: 1>

--> print(socket.AF_UNIX)
AddressFamily.AF_UNIX ==> socket.AF_UNIX

Thoughts?

[vedgar]

_in some cases when enum instances are exposed as module globals_

Yes. And repr should be inverse of eval, but it's probably too late for that. :-/

[ethanfurman]

Looks like the re module's flags have been updated separately in bpo-36548:

  >>> import re
  >>> re.I
  re.IGNORECASE

  >>> print(re.I)
  # should also be re.IGNORECASE

  >>> re.I|re.S|re.X
  re.IGNORECASE|re.DOTALL|re.VERBOSE

For stdlib Enum conversions are we happy with that? Or should __str__ just print the numeric value?

[vedgar]

If it's considered to be not too backwards-incompatible, I think it would be nice to have str different from repr. That way we can finetune what exactly we need. But we can already do almost exactly that with *int* instead of *str*, so it's not too compelling.

Much more important thing is the "repr as inverse of eval". Is there any way we can have that for our own enums (as a mixin or a decorator)?

    @module_global(re)
    class RegexFlag(Enum):
        ...

It would be fantastic. :-)

[ethanfurman]

"repr as inverse of eval" is nice to have, but it is not a requirement.