bpo-40066: Enum: modify `repr()` and `str()` #22392

ethanfurman · 2020-09-24T04:55:46Z

Enumerations created from Enum._convert_ will have their repr() changed to be

module.member_name

and their str() to be

member_name

The exception is StrEnum, whose str() will be

value

as in, the member's value.

https://bugs.python.org/issue40066

gvanrossum

Nice. How did you track down all the docs that need to be changed? (I note there aren't any doc changes do to the change in str().)

Lib/enum.py

Lib/re.py

gvanrossum · 2020-09-26T21:44:06Z

Misc/NEWS.d/next/Library/2020-09-23-21-58-34.bpo-40066.f1dr_5.rst

+Enum's `repr()` and `str()` have changed: `repr()` is now *EnumClass.MemberName*
+and `str()` is *MemberName*.  Additionally, stdlib Enum's whose contents are
+available as module attributes, such as `RegexFlag.IGNORECASE`, have their
+`repr()` as *module.name*, e.g. `re.IGNORECASE`.


Maybe also add a section to what's new in 3.10?

I thought blurb did that?

No, blurb just updates Misc/NEWS, which is an endless list of things (though more focused than the commit log :-).

What's new in 3.10 is a separate doc written by human editor who curate the most important news and group it by affected area.

https://docs.python.org/3.10/whatsnew/3.10.html

Also the versionchanged directive is needed in the module documentation.

ethanfurman · 2020-09-27T00:04:27Z

Nice. How did you track down all the docs that need to be changed? (I note there aren't any doc changes do to the change in str().)

grep -R "<[A-Za-z\.]*: [^>]*>" *

Assuming no one comes up with a strong reason to not commit this PR, I will need to do some rewriting of enum.rst -- there's currently a good-sized section dealing with valueless Enums and updating the repr() to not show the value, etc.

gvanrossum · 2020-09-27T01:10:32Z

grep -R "<[A-Za-z\.]*: [^>]*>" *

That doesn't look for occurrences of the str() though, which doesn't have any funky markup.

Assuming no one comes up with a strong reason to not commit this PR, I will need to do some rewriting of enum.rst -- there's currently a good-sized section dealing with valueless Enums and updating the repr() to not show the value, etc.

Are you planning to do that in the same PR? (I recommend it.)

FWIW you're unlikely to get anyone to tell you not to commit this from GitHub reviewers or bpo readers. Was there a python-ideas thread? Maybe you want to ask Raymond (if he didn't already concur)?

serhiy-storchaka · 2020-09-27T08:09:27Z

Doc/library/enum.rst

    >>> ~Perm.RWX
-    <Perm.-8: -8>
+    Perm.-8


In this case I would prefer ~Perm.RWX or Perm(-8). But this may be a different issue.

Negative values are no longer a thing -- they are converted to their positive equivalent.

serhiy-storchaka · 2020-09-27T08:10:30Z

Doc/library/enum.rst


 Another important difference between :class:`IntFlag` and :class:`Enum` is that
 if no flags are set (the value is 0), its boolean evaluation is :data:`False`::

    >>> Perm.R & Perm.X
-    <Perm.0: 0>
+    Perm.0


Perm(0) would look better.

I went with 0x0 to match other non-Flag values, similarly to the way re.RegexFlag does it.

serhiy-storchaka · 2020-09-27T08:11:30Z

Doc/library/enum.rst

    >>> bool(Perm.R & Perm.X)
    False

 Because :class:`IntFlag` members are also subclasses of :class:`int` they can
 be combined with them::

    >>> Perm.X | 8
-    <Perm.8|X: 9>
+    Perm.8|Perm.X


And here I would prefer Perm.X|8.

It is now Perm.X|0x8

serhiy-storchaka · 2020-09-27T08:16:21Z

Doc/library/enum.rst

@@ -1198,7 +1198,7 @@ constructor.  For example::
    ...     example = '11', 16      # '11' will be interpreted as a hexadecimal
    ...                             # number
    >>> MyEnum.example


I think that it would more useful to use MyEnum.example.value or int(MyEnum.example) in the example.

Yes, I added the .value here and in other places.

serhiy-storchaka · 2020-09-27T08:18:31Z

Lib/enum.py

-                raise ValueError(f'_sunder_ names, such as "{key}", are '
-                                  'reserved for future Enum use')
+                raise ValueError(
+                        '_sunder_ names, such as %r, are reserved for future Enum use'


You can use f-string with !r.

Yes, but I'm not using f-strings anywhere else.

At some point I'll switch all the %-interpolations to use f-strings.

serhiy-storchaka · 2020-09-27T08:33:09Z

Lib/enum.py

+    for m in self.__class__:
+        if value & m._value_:
+            value &= ~m._value_
+            members.append('re.%s' % (m._name_, ))


Oops. Looks like I need to add a test for that branch of code.

serhiy-storchaka · 2020-09-27T08:39:25Z

Lib/enum.py

@@ -946,3 +942,42 @@ def _decompose(flag, value):
        # we have the breakdown, don't need the value member itself
        members.pop(0)
    return members, not_covered
+
+def global_int_repr(self):
+    return '%s.%s' % (self.__class__.__module__, self.name)


What if add an attribute to the enum class which is set to the class name by default and can be set to the module name for enums whose members are exposed as globals?

return '%s.%s' % (self.__class__._namespacename, self.name)

It will make easier customization of the repr.

I think writing a custom __repr__ is not that difficult.

serhiy-storchaka · 2020-09-27T08:41:58Z

Lib/enum.py

+            value &= ~m._value_
+            members.append('re.%s' % (m._name_, ))
+    if value:
+        members.append(hex(value))


For general code I would add a class method for converting value to string. Depending on the class octal or binary may be better than hexadecimal.

Fair point.

serhiy-storchaka · 2020-09-27T08:45:16Z

Misc/NEWS.d/next/Library/2020-09-23-21-58-34.bpo-40066.f1dr_5.rst

+Enum's `repr()` and `str()` have changed: `repr()` is now *EnumClass.MemberName*
+and `str()` is *MemberName*.  Additionally, stdlib Enum's whose contents are
+available as module attributes, such as `RegexFlag.IGNORECASE`, have their
+`repr()` as *module.name*, e.g. `re.IGNORECASE`.


Also the versionchanged directive is needed in the module documentation.

iritkatriel · 2020-10-02T11:03:27Z

Lib/enum.py

+            self._name_ = '%s' % '|'.join([
+                    str(m._name_ or m._value_) for m in members
+                    ])
+        return self._name_


Now whichever of __str__ and __repr__ is called first will initialize _name_ for all time. Even if they do the same thing now, they might drift in the future. Should this initialization code be in a common function to make sure it's consistent? One option would be to override name() and do it there.

The name is now initialized when the pseudo-member is created.

gvanrossum · 2020-10-03T23:53:00Z

Who is this PR waiting for now?

ethanfurman · 2020-10-05T04:14:30Z

GvR wrote:

Who is this PR waiting for now?

For me to make a few changes, and hopefully for Raymond to chime in. I'll update the bpo issue in case he didn't see my email.

non-StrEnum `__str__` will print the member name StrEnum `__str__` will print the member value

create enum._stdlib_enum decorator for Enums created the normal way: it adjusts `__repr__` and `__str__` to be the same as if the Enum had been created using `_convert_` update various modules to use the new decorator

if `enum.__str__` is either `Enum.__str__` or `global_enum_str` use the value's `__format__`

repr() = class.member_name str() = member_name

rename to `global_enum` and have `global_enum` update the module's namespace with the members remove `_stdlib_enum` where the enums were not being exported to the module's namespace

* rename global_int_repr --> global_enum_repr * adjust global_flag_repr to print hex number for out-of-range values * extract function when _generate_next_value_ is a static method

- repr() is now ``enum_class.member_name`` - str() is now ``member_name`` - add HOW-TO section for ``Enum`` - change main documentation to be an API reference

ethanfurman · 2021-03-26T05:26:17Z

@gvanrossum RE: looking for Enum.__str__ output in docs: I manually checked the module documentation for each one that had enum constants.

In Python 3.10 the repr and str representation of Enums changed from str: 'ClassName.NAME' -> 'NAME' repr: '<ClassName.NAME: value>' -> 'ClassName.NAME' which is more consistent with what str/repr should do, however this breaks boilerplate which needs to get the ClassName.NAME version in all versions of Python. Thus, we locally monkey patch our preferred str representation in here. bpo-40066 python/cpython#22392

the-knights-who-say-ni added the CLA signed label Sep 24, 2020

bedevere-bot added the awaiting core review label Sep 24, 2020

ethanfurman requested a review from serhiy-storchaka September 24, 2020 04:55

ethanfurman requested review from tiran, 1st1 and asvetlov as code owners September 24, 2020 07:00

ethanfurman requested review from gvanrossum and removed request for 1st1 and asvetlov September 25, 2020 18:11

ethanfurman self-assigned this Sep 25, 2020

gvanrossum reviewed Sep 26, 2020

View reviewed changes

serhiy-storchaka reviewed Sep 27, 2020

View reviewed changes

iritkatriel reviewed Oct 2, 2020

View reviewed changes

ethanfurman added 13 commits March 24, 2021 17:36

add new repr and str for converted Int-Enums/Flags

aa436ed

wip

db0386f

make Enum.__str__ print name or value

33cfa20

non-StrEnum `__str__` will print the member name StrEnum `__str__` will print the member value

add news entry

bdffc7d

fix tests that checked Enum str()

1bd8a6a

wip

dfe01a1

create enum._stdlib_enum decorator for Enums created the normal way: it adjusts `__repr__` and `__str__` to be the same as if the Enum had been created using `_convert_` update various modules to use the new decorator

fix format for global string override

2a5ace6

if `enum.__str__` is either `Enum.__str__` or `global_enum_str` use the value's `__format__`

update docs with new stdlib enum reprs and strs

722474d

plain Enum has updated str() and repr()

49a46d0

repr() = class.member_name str() = member_name

_stdlib_enum -> global_enum

e01379c

rename to `global_enum` and have `global_enum` update the module's namespace with the members remove `_stdlib_enum` where the enums were not being exported to the module's namespace

fix pydoc and unicode tests

893c636

fix white space

6ffaf77

fix signal tests

9f0ab8b

ethanfurman added 6 commits March 24, 2021 17:36

update NEWS entry

d782de0

use .__dict__ instead of vars()

1013cea

wip

896b608

minor updates

4f43964

* rename global_int_repr --> global_enum_repr * adjust global_flag_repr to print hex number for out-of-range values * extract function when _generate_next_value_ is a static method

rewrite enum docs; add enum how-to

40910ea

Enum: streamline repr() and str(); improve docs

7643863

- repr() is now ``enum_class.member_name`` - str() is now ``member_name`` - add HOW-TO section for ``Enum`` - change main documentation to be an API reference

ethanfurman force-pushed the enum-global_repr branch from ea6308a to 7643863 Compare March 26, 2021 04:30

add whatsnew entry

2b3a5cc

ethanfurman changed the title ~~bpo-40066: Enum global repr() and str()~~ bpo-40066: Enum: modify repr() and str() Mar 31, 2021

Update 3.10.rst

663e11a

ethanfurman merged commit b775106 into python:master Mar 31, 2021

bedevere-bot removed the awaiting core review label Mar 31, 2021

tirkarthi mentioned this pull request Apr 7, 2021

[BUG] More Python 3.10 test failures cython/cython#4100

Closed

ethanfurman deleted the enum-global_repr branch April 15, 2021 14:23

tacaswell mentioned this pull request May 4, 2021

FIX: MouseButton representation in boilerplate generated signatures matplotlib/matplotlib#20148

Merged

3 tasks

jacobtylerwalls mentioned this pull request Jun 30, 2021

Make doctests compatible with expected enum changes in Python 3.11 cuthbertLab/music21#1048

Closed

JelleZijlstra mentioned this pull request May 22, 2022

enum.EnumMeta renaming #93064

Closed

jborean93 mentioned this pull request Jul 11, 2022

Python 3.11.0b4 str(enum) giving integer value and not name #94763

Closed

mmmarcos mentioned this pull request Oct 21, 2022

socket.getaddrinfo Py3.10 docs say "AddressFamily.SOCK_STREAM" #98026

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

bpo-40066: Enum: modify `repr()` and `str()` #22392

bpo-40066: Enum: modify `repr()` and `str()` #22392

ethanfurman commented Sep 24, 2020 •

edited by bedevere-bot

Loading

gvanrossum left a comment

gvanrossum Sep 26, 2020

ethanfurman Sep 26, 2020

gvanrossum Sep 27, 2020

gvanrossum Sep 27, 2020

serhiy-storchaka Sep 27, 2020

ethanfurman commented Sep 27, 2020

gvanrossum commented Sep 27, 2020

serhiy-storchaka Sep 27, 2020

ethanfurman Mar 26, 2021

serhiy-storchaka Sep 27, 2020

ethanfurman Mar 26, 2021

serhiy-storchaka Sep 27, 2020

ethanfurman Mar 26, 2021

serhiy-storchaka Sep 27, 2020

ethanfurman Mar 26, 2021

serhiy-storchaka Sep 27, 2020

ethanfurman Sep 28, 2020

ethanfurman Mar 26, 2021

serhiy-storchaka Sep 27, 2020

ethanfurman Sep 28, 2020

serhiy-storchaka Sep 27, 2020

ethanfurman Mar 26, 2021

serhiy-storchaka Sep 27, 2020

ethanfurman Mar 26, 2021

serhiy-storchaka Sep 27, 2020

iritkatriel Oct 2, 2020

ethanfurman Mar 26, 2021

gvanrossum commented Oct 3, 2020

ethanfurman commented Oct 5, 2020

ethanfurman commented Mar 26, 2021

bpo-40066: Enum: modify repr() and str() #22392

bpo-40066: Enum: modify repr() and str() #22392

Conversation

ethanfurman commented Sep 24, 2020 • edited by bedevere-bot Loading

gvanrossum left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ethanfurman commented Sep 27, 2020

gvanrossum commented Sep 27, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gvanrossum commented Oct 3, 2020

ethanfurman commented Oct 5, 2020

ethanfurman commented Mar 26, 2021

bpo-40066: Enum: modify `repr()` and `str()` #22392

bpo-40066: Enum: modify `repr()` and `str()` #22392

ethanfurman commented Sep 24, 2020 •

edited by bedevere-bot

Loading