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

ethanfurman

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

ethanfurman

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

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

gvanrossum

Who is this PR waiting for now?

ethanfurman

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

@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()~~ 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 merged 21 commits into
python:masterfrom
ethanfurman:enum-global_repr

ethanfurman commented Sep 24, 2020 •

edited by bedevere-bot

Loading

Uh oh!

gvanrossum left a comment

Uh oh!

ethanfurman commented Sep 27, 2020

Uh oh!

gvanrossum commented Sep 27, 2020

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!

6 participants

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!

ethanfurman commented Sep 27, 2020

Uh oh!

gvanrossum commented Sep 27, 2020

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!

6 participants

ethanfurman commented Sep 24, 2020 •

edited by bedevere-bot

Loading