Undo rejected PEP-663 changes:
- restore `repr()` to its 3.10 status
- restore `str()` to its 3.10 status
New changes:
- `IntEnum` and `IntFlag` now leave `__str__` as the original `int.__str__` so that str() and format() return the same result
- zero-valued flags without a name have a slightly changed repr(), e.g. `repr(Color(0)) == '<Color: 0>'`
- update `dir()` for mixed-in types to return all the methods and attributes of the mixed-in type
- added `_numeric_repr_` to `Flag` to control display of unnamed values
- enums without doc strings have a more comprehensive doc string added
- `ReprEnum` added -- inheriting from this makes it so only `__repr__` is replaced, not `__str__` nor `__format__`; `IntEnum`, `IntFlag`, and `StrEnum` all inherit from `ReprEnum`
In `__set_name__` there is a check for the `_value_` attribute and an attempt to add it if missing; this adds a test to cover the case for simple enums with a custom `__new__` method.
add tests that exercise the `_missing_` error path for `Flag` and `IntFlag`
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: Ethan Furman <ethan@stoneleaf.us>
Modify the ``EnumType.__dir__()`` and ``Enum.__dir__()`` to ensure
that user-defined methods and methods inherited from mixin classes always
show up in the output of `help()`. This change also makes it easier for
IDEs to provide auto-completion.
* Fix typo in __repr__ code
* Add more tests for global int flag reprs
* use last module if multi-module string
- when an enum's `__module__` contains several module names, only
use the last one
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
Co-authored-by: Ethan Furman <ethan@stoneleaf.us>
* [Enum] reduce scope of new format behavior
Instead of treating all Enums the same for format(), only user mixed-in
enums will be affected. In other words, IntEnum and IntFlag will not be
changing the format() behavior, due to the requirement that they be
drop-in replacements of existing integer constants.
If a user creates their own integer-based enum, then the new behavior
will apply:
class Grades(int, Enum):
A = 5
B = 4
C = 3
D = 2
F = 0
Now: format(Grades.B) -> DeprecationWarning and '4'
3.12: -> no warning, and 'B'
by-value lookups could fail on complex enums, necessitating a check for
__reduce__ and possibly sabotaging the final enum;
by-name lookups should never fail, and sabotaging is no longer necessary
for class-based enum creation.
This enables, for example, two base Enums to both inherit from `str`, and then both be mixed into the same final Enum:
class Str1Enum(str, Enum):
# some behavior here
class Str2Enum(str, Enum):
# some more behavior here
class FinalStrEnum(Str1Enum, Str2Enum):
# this now works
In 3.12 ``True`` or ``False`` will be returned for all containment checks,
with ``True`` being returned if the value is either a member of that enum
or one of its members' value.
In 3.12 the enum member, not the member's value, will be used for
format() calls. Format specifiers can be used to retain the current
display of enum members:
Example enumeration:
class Color(IntEnum):
RED = 1
GREEN = 2
BLUE = 3
Current behavior:
f'{Color.RED}' --> '1'
Future behavior:
f'{Color.RED}' --> 'RED'
Using d specifier:
f'{Color.RED:d}' --> '1'
Using specifiers can be done now and is future-compatible.
Previously TestIntEnumConvert and TestStrEnumConvert would end up
converting the module level variables from their regular int form
to a `test.test_enum.X` instance after _convert would run. This
meant that after a single test ran, the next set of _convert
functions would be operating on the enum instances rather than
ints. This would cause some tests such as the one involving format
to fail when running under a mode that repeatedly runs test such
as the refleak finder.
add:
* `_simple_enum` decorator to transform a normal class into an enum
* `_test_simple_enum` function to compare
* `_old_convert_` to enable checking `_convert_` generated enums
`_simple_enum` takes a normal class and converts it into an enum:
@simple_enum(Enum)
class Color:
RED = 1
GREEN = 2
BLUE = 3
`_old_convert_` works much like` _convert_` does, using the original logic:
# in a test file
import socket, enum
CheckedAddressFamily = enum._old_convert_(
enum.IntEnum, 'AddressFamily', 'socket',
lambda C: C.isupper() and C.startswith('AF_'),
source=_socket,
)
`_test_simple_enum` takes a traditional enum and a simple enum and
compares the two:
# in the REPL or the same module as Color
class CheckedColor(Enum):
RED = 1
GREEN = 2
BLUE = 3
_test_simple_enum(CheckedColor, Color)
_test_simple_enum(CheckedAddressFamily, socket.AddressFamily)
Any important differences will raise a TypeError
add:
_simple_enum decorator to transform a normal class into an enum
_test_simple_enum function to compare
_old_convert_ to enable checking _convert_ generated enums
_simple_enum takes a normal class and converts it into an enum:
@simple_enum(Enum)
class Color:
RED = 1
GREEN = 2
BLUE = 3
_old_convert_ works much like _convert_ does, using the original logic:
# in a test file
import socket, enum
CheckedAddressFamily = enum._old_convert_(
enum.IntEnum, 'AddressFamily', 'socket',
lambda C: C.isupper() and C.startswith('AF_'),
source=_socket,
)
test_simple_enum takes a traditional enum and a simple enum and
compares the two:
# in the REPL or the same module as Color
class CheckedColor(Enum):
RED = 1
GREEN = 2
BLUE = 3
_test_simple_enum(CheckedColor, Color)
_test_simple_enum(CheckedAddressFamily, socket.AddressFamily)
Any important differences will raise a TypeError
* Enum: streamline repr() and str(); improve docs
- repr() is now ``enum_class.member_name``
- stdlib global enums are ``module_name.member_name``
- str() is now ``member_name``
- add HOW-TO section for ``Enum``
- change main documentation to be an API reference
In 3.5 (?) a speed optimization made it possible to access members as
attributes of other members, i.e. ``Color.RED.BLUE``. This was always
discouraged in the docs, and other recent optimizations has made that
one no longer necessary. Because some may be relying on it anyway, it
is being deprecated in 3.10, and will be removed in 3.11.
* [Enum] only include .rst test if file available
In order to ensure the ReST documentation is up to date for Enum,
use doctest to check it -- but only if the .rst files have not
been stripped.
Flag members are now divided by one-bit verses multi-bit, with multi-bit being treated as aliases. Iterating over a flag only returns the contained single-bit flags.
Iterating, repr(), and str() show members in definition order.
When constructing combined-member flags, any extra integer values are either discarded (CONFORM), turned into ints (EJECT) or treated as errors (STRICT). Flag classes can specify which of those three behaviors is desired:
>>> class Test(Flag, boundary=CONFORM):
... ONE = 1
... TWO = 2
...
>>> Test(5)
<Test.ONE: 1>
Besides the three above behaviors, there is also KEEP, which should not be used unless necessary -- for example, _convert_ specifies KEEP as there are flag sets in the stdlib that are incomplete and/or inconsistent (e.g. ssl.Options). KEEP will, as the name suggests, keep all bits; however, iterating over a flag with extra bits will only return the canonical flags contained, not the extra bits.
Iteration is now in member definition order. If member definition order
matches increasing value order, then a more efficient method of flag
decomposition is used; otherwise, sort() is called on the results of
that method to get definition order.
``re`` module:
repr() has been modified to support as closely as possible its previous
output; the big difference is that inverted flags cannot be output as
before because the inversion operation now always returns the comparable
positive result; i.e.
re.A|re.I|re.M|re.S is ~(re.L|re.U|re.S|re.T|re.DEBUG)
in both of the above terms, the ``value`` is 282.
re's tests have been updated to reflect the modifications to repr().
`type.__new__` calls `__set_name__` and `__init_subclass__`, which means
that any work metaclasses do after calling `super().__new__()` will not
be available to those two methods. In particular, `Enum` classes that
want to make use of `__init_subclass__` will not see any members.
Almost all customization is therefore moved to before the
`type.__new__()` call, including changing all members to a proto member
descriptor with a `__set_name__` that will do the final conversion of a
member to be an instance of the `Enum` class.
This allows easier Enum construction in unusual cases, such as including dynamic member definitions into a class definition:
# created dynamically
foo_defines = {'FOO_CAT': 'aloof', 'BAR_DOG': 'friendly', 'FOO_HORSE': 'big'}
class Foo(Enum):
vars().update({
k: v
for k, v in foo_defines.items()
if k.startswith('FOO_')
})
def upper(self):
# example method
return self.value.upper()
The default for auto() is to return an integer, which doesn't work for `StrEnum`. The new `_generate_next_value_` for `StrEnum` returns the member name, lower cased.
When creating an Enum, type.__new__ calls __init_subclass__, but at that point the members have not been added.
This patch suppresses the initial call, then manually calls the ancestor __init_subclass__ before returning the new Enum class.
Christian Heimes
Nikita Sobolev
Ethan Furman
Kumar Aditya
Victor Stinner
Alex Waygood
Serhiy Storchaka
Pablo Galindo Salgado
Brandon Schabell
Ammar Askar