Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ethanfurman merged 21 commits into from
Mar 31, 2021
Merged

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

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
aa436ed
add new repr and str for converted Int-Enums/Flags
ethanfurman Sep 18, 2020
db0386f
wip
ethanfurman Sep 24, 2020
33cfa20
make Enum.__str__ print name or value
ethanfurman Sep 24, 2020
bdffc7d
add news entry
ethanfurman Sep 24, 2020
1bd8a6a
fix tests that checked Enum str()
ethanfurman Sep 24, 2020
dfe01a1
wip
ethanfurman Sep 24, 2020
2a5ace6
fix format for global string override
ethanfurman Sep 24, 2020
722474d
update docs with new stdlib enum reprs and strs
ethanfurman Sep 24, 2020
49a46d0
plain Enum has updated str() and repr()
ethanfurman Sep 25, 2020
e01379c
_stdlib_enum -> global_enum
ethanfurman Sep 25, 2020
893c636
fix pydoc and unicode tests
ethanfurman Sep 25, 2020
6ffaf77
fix white space
ethanfurman Sep 25, 2020
9f0ab8b
fix signal tests
ethanfurman Sep 25, 2020
d782de0
update NEWS entry
ethanfurman Sep 25, 2020
1013cea
use `.__dict__` instead of `vars()`
ethanfurman Sep 29, 2020
896b608
wip
ethanfurman Mar 13, 2021
4f43964
minor updates
ethanfurman Mar 25, 2021
40910ea
rewrite enum docs; add enum how-to
ethanfurman Mar 25, 2021
7643863
Enum: streamline repr() and str(); improve docs
ethanfurman Mar 26, 2021
2b3a5cc
add ``whatsnew`` entry
ethanfurman Mar 26, 2021
663e11a
Update 3.10.rst
ethanfurman Mar 31, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
plain Enum has updated str() and repr() 
repr() = class.member_name
str() = member_name
  • Loading branch information
@ethanfurman
ethanfurman committed Mar 25, 2021
commit 49a46d0d95d11bb8dc03255d2019fed632ca82a2
72 changes: 36 additions & 36 deletions Doc/library/enum.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ Enumeration members have human readable string representations::
...while their ``repr`` has more information::

>>> print(repr(Color.RED))
<Color.RED: 1>
Color.RED

The *type* of an enumeration member is the enumeration it belongs to::

Expand Down Expand Up @@ -166,16 +166,16 @@ situations where ``Color.RED`` won't do because the exact color is not known
at program-writing time). ``Enum`` allows such access::

>>> Color(1)
<Color.RED: 1>
Color.RED
>>> Color(3)
<Color.BLUE: 3>
Color.BLUE

If you want to access enum members by *name*, use item access::

>>> Color['RED']
<Color.RED: 1>
Color.RED
>>> Color['GREEN']
<Color.GREEN: 2>
Color.GREEN

If you have an enum member and need its :attr:`name` or :attr:`value`::

Expand Down Expand Up @@ -211,11 +211,11 @@ return A::
... ALIAS_FOR_SQUARE = 2
...
>>> Shape.SQUARE
<Shape.SQUARE: 2>
Shape.SQUARE
>>> Shape.ALIAS_FOR_SQUARE
<Shape.SQUARE: 2>
Shape.SQUARE
>>> Shape(2)
<Shape.SQUARE: 2>
Shape.SQUARE

.. note::

Expand Down Expand Up @@ -262,7 +262,7 @@ If the exact value is unimportant you can use :class:`auto`::
... GREEN = auto()
...
>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]
[Color.RED, Color.BLUE, Color.GREEN]

The values are chosen by :func:`_generate_next_value_`, which can be
overridden::
Expand All @@ -278,7 +278,7 @@ overridden::
... WEST = auto()
...
>>> list(Ordinal)
[<Ordinal.NORTH: 'NORTH'>, <Ordinal.SOUTH: 'SOUTH'>, <Ordinal.EAST: 'EAST'>, <Ordinal.WEST: 'WEST'>]
[Ordinal.NORTH, Ordinal.SOUTH, Ordinal.EAST, Ordinal.WEST]

.. note::

Expand All @@ -296,7 +296,7 @@ Iteration
Iterating over the members of an enum does not provide the aliases::

>>> list(Shape)
[<Shape.SQUARE: 2>, <Shape.DIAMOND: 1>, <Shape.CIRCLE: 3>]
[Shape.SQUARE, Shape.DIAMOND, Shape.CIRCLE]

The special attribute ``__members__`` is a read-only ordered mapping of names
to members. It includes all names defined in the enumeration, including the
Expand All @@ -305,10 +305,10 @@ aliases::
>>> for name, member in Shape.__members__.items():
... name, member
...
('SQUARE', <Shape.SQUARE: 2>)
('DIAMOND', <Shape.DIAMOND: 1>)
('CIRCLE', <Shape.CIRCLE: 3>)
('ALIAS_FOR_SQUARE', <Shape.SQUARE: 2>)
('SQUARE', Shape.SQUARE)
('DIAMOND', Shape.DIAMOND)
('CIRCLE', Shape.CIRCLE)
('ALIAS_FOR_SQUARE', Shape.SQUARE)

The ``__members__`` attribute can be used for detailed programmatic access to
the enumeration members. For example, finding all the aliases::
Expand Down Expand Up @@ -386,7 +386,7 @@ usual. If we have this enumeration::
Then::

>>> Mood.favorite_mood()
<Mood.HAPPY: 3>
Mood.HAPPY
>>> Mood.HAPPY.describe()
('HAPPY', 3)
>>> str(Mood.FUNKY)
Expand Down Expand Up @@ -473,11 +473,11 @@ The :class:`Enum` class is callable, providing the following functional API::
>>> Animal
<enum 'Animal'>
>>> Animal.ANT
<Animal.ANT: 1>
Animal.ANT
>>> Animal.ANT.value
1
>>> list(Animal)
[<Animal.ANT: 1>, <Animal.BEE: 2>, <Animal.CAT: 3>, <Animal.DOG: 4>]
[Animal.ANT, Animal.BEE, Animal.CAT, Animal.DOG]

The semantics of this API resemble :class:`~collections.namedtuple`. The first
argument of the call to :class:`Enum` is the name of the enumeration.
Expand Down Expand Up @@ -665,7 +665,7 @@ Sample :class:`IntFlag` class::
... X = 1
...
>>> Perm.R | Perm.W
<Perm.R|W: 6>
Perm.R|Perm.W
>>> Perm.R + Perm.W
6
>>> RW = Perm.R | Perm.W
Expand All @@ -680,11 +680,11 @@ It is also possible to name the combinations::
... X = 1
... RWX = 7
>>> Perm.RWX
<Perm.RWX: 7>
Perm.RWX
>>> ~Perm.RWX
<Perm: 0>
Perm(0)
>>> Perm(7)
<Perm.RWX: 7>
Perm.RWX

.. note::

Expand All @@ -697,7 +697,7 @@ 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>
Perm(0)
>>> bool(Perm.R & Perm.X)
False

Expand All @@ -721,7 +721,7 @@ be combined with them (but may lose :class:`IntFlag` membership::
:class:`IntFlag` members can also be iterated over::

>>> list(RW)
[<Perm.R: 4>, <Perm.W: 2>]
[Perm.R, Perm.W]

.. versionadded:: 3.10

Expand All @@ -748,7 +748,7 @@ flags being set, the boolean evaluation is :data:`False`::
... GREEN = auto()
...
>>> Color.RED & Color.GREEN
<Color: 0>
Color(0)
>>> bool(Color.RED & Color.GREEN)
False

Expand All @@ -762,7 +762,7 @@ while combinations of flags won't::
... WHITE = RED | BLUE | GREEN
...
>>> Color.WHITE
<Color.WHITE: 7>
Color.WHITE

Giving a name to the "no flags set" condition does not change its boolean
value::
Expand All @@ -774,15 +774,15 @@ value::
... GREEN = auto()
...
>>> Color.BLACK
<Color.BLACK: 0>
Color.BLACK
>>> bool(Color.BLACK)
False

:class:`Flag` members can also be iterated over::

>>> purple = Color.RED | Color.BLUE
>>> list(purple)
[<Color.RED: 1>, <Color.BLUE: 2>]
[Color.RED, Color.BLUE]

.. versionadded:: 3.10

Expand Down Expand Up @@ -984,7 +984,7 @@ to handle any extra arguments::
... BLEACHED_CORAL = () # New color, no Pantone code yet!
...
>>> Swatch.SEA_GREEN
<Swatch.SEA_GREEN>
Swatch.SEA_GREEN
>>> Swatch.SEA_GREEN.pantone
'1246'
>>> Swatch.BLEACHED_CORAL.pantone
Expand Down Expand Up @@ -1110,9 +1110,9 @@ An example to show the :attr:`_ignore_` attribute in use::
... Period['day_%d' % i] = i
...
>>> list(Period)[:2]
[<Period.day_0: datetime.timedelta(0)>, <Period.day_1: datetime.timedelta(days=1)>]
[Period.day_0, Period.day_1]
>>> list(Period)[-2:]
[<Period.day_365: datetime.timedelta(days=365)>, <Period.day_366: datetime.timedelta(days=366)>]
[Period.day_365, Period.day_366]


How are Enums different?
Expand Down Expand Up @@ -1250,7 +1250,7 @@ constructor. For example::
... example = '11', 16 # '11' will be interpreted as a hexadecimal
... # number
>>> MyEnum.example

@serhiy-storchaka serhiy-storchaka Sep 27, 2020

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@ethanfurman ethanfurman Mar 26, 2021

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

<MyEnum.example: 17>
MyEnum.example


Boolean value of ``Enum`` classes and members
Expand Down Expand Up @@ -1295,10 +1295,10 @@ are comprised of a single bit::
... YELLOW = RED | GREEN
... CYAN = GREEN | BLUE
...
>>> Color(3)
<Color.YELLOW: 3>
>>> Color(7)
<Color.RED|GREEN|BLUE: 7>
>>> Color(3) # named combination
Color.YELLOW
>>> Color(7) # not named combination
Color.RED|Color.GREEN|Color.BLUE

``StrEnum`` and :meth:`str.__str__`
"""""""""""""""""""""""""""""""""""
Expand Down
5 changes: 2 additions & 3 deletions Lib/enum.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -960,11 +960,10 @@ def _missing_(cls, value):
return None

def __repr__(self):
return "<%s.%s: %r>" % (
self.__class__.__name__, self._name_, self._value_)
return "%s.%s" % ( self.__class__.__name__, self._name_)

def __str__(self):
return "%s.%s" % (self.__class__.__name__, self._name_)
return "%s" % (self._name_, )

def __dir__(self):
"""
Expand Down
Loading