bpo-40066: Enum: modify `repr()` and `str()` by ethanfurman · Pull Request #22392 · python/cpython · GitHub

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

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().)

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.

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.

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)?

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.

Perm(0) would look better.

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

And here I would prefer Perm.X|8.

It is now Perm.X|0x8

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.

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.

re?

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

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.

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.

Also the versionchanged directive is needed in the module documentation.

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.

Who is this PR waiting for now?

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

@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 1st1, asvetlov and tiran 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 done

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

bpo-40066: Enum: modify `repr()` and `str()` by ethanfurman · Pull Request #22392 · python/cpython · GitHub

Repository navigation

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

bpo-40066: Enum: modify repr() and str()#22392ethanfurman merged 21 commits intopython:masterpython/cpython:masterfrom ethanfurman:enum-global_reprethanfurman/cpython:enum-global_reprCopy head branch name to clipboard

Conversation

ethanfurman commented Sep 24, 2020 • edited by bedevere-bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gvanrossum left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ethanfurman commented Sep 27, 2020

Uh oh!

gvanrossum commented Sep 27, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gvanrossum commented Oct 3, 2020

Uh oh!

ethanfurman commented Oct 5, 2020

Uh oh!

ethanfurman commented Mar 26, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

bpo-40066: Enum: modify repr() and str()#22392
ethanfurman merged 21 commits into
python:masterfrom
ethanfurman:enum-global_repr

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