gh-114071: [Enum] update docs and code for tuples/subclasses (GH-114871)

Update documentation with `__new__` and `__init__` entries.

Support use of `auto()` in tuple subclasses on member assignment lines.  Previously, auto() was only supported on the member definition line either solo or as part of a tuple:

    RED = auto()
    BLUE = auto(), 'azul'

However, since Python itself supports using tuple subclasses where tuples are expected, e.g.:

    from collections import namedtuple
    T = namedtuple('T', 'first second third')

    def test(one, two, three):
        print(one, two, three)

    test(*T(4, 5, 6))
    # 4 5 6

it made sense to also support tuple subclasses in enum definitions.
This commit is contained in:
Ethan Furman 2024-02-04 07:22:55 -08:00 committed by GitHub
parent ec69e1d0dd
commit ff7588b729
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 69 additions and 5 deletions

View file

@ -337,6 +337,17 @@ Data Types
>>> PowersOfThree.SECOND.value
9
.. method:: Enum.__init__(self, \*args, \**kwds)
By default, does nothing. If multiple values are given in the member
assignment, those values become separate arguments to ``__init__``; e.g.
>>> from enum import Enum
>>> class Weekday(Enum):
... MONDAY = 1, 'Mon'
``Weekday.__init__()`` would be called as ``Weekday.__init__(self, 1, 'Mon')``
.. method:: Enum.__init_subclass__(cls, \**kwds)
A *classmethod* that is used to further configure subsequent subclasses.
@ -364,6 +375,18 @@ Data Types
>>> Build('deBUG')
<Build.DEBUG: 'debug'>
.. method:: Enum.__new__(cls, \*args, \**kwds)
By default, doesn't exist. If specified, either in the enum class
definition or in a mixin class (such as ``int``), all values given
in the member assignment will be passed; e.g.
>>> from enum import Enum
>>> class MyIntEnum(Enum):
... SEVENTEEN = '1a', 16
results in the call ``int('1a', 16)`` and a value of ``17`` for the member.
.. method:: Enum.__repr__(self)
Returns the string used for *repr()* calls. By default, returns the
@ -477,9 +500,9 @@ Data Types
.. class:: Flag
*Flag* members support the bitwise operators ``&`` (*AND*), ``|`` (*OR*),
``^`` (*XOR*), and ``~`` (*INVERT*); the results of those operators are members
of the enumeration.
``Flag`` is the same as :class:`Enum`, but its members support the bitwise
operators ``&`` (*AND*), ``|`` (*OR*), ``^`` (*XOR*), and ``~`` (*INVERT*);
the results of those operators are members of the enumeration.
.. method:: __contains__(self, value)