mirror of
https://github.com/python/cpython.git
synced 2026-04-13 23:31:02 +00:00
[3.14] gh-136672: Docs: Move parts of Enum HOWTO to API Docs (GH-139176) (GH-144802)
To avoid duplicate content in the Enum HOWTO and
API documentation which is not automatically synced,
the section about supported __dunder__ and _sunder
names is moved from HOWTO to API docs.
See also https://github.com/python/cpython/pull/136791
(cherry picked from commit 629a363ddd)
Co-authored-by: Rafael Weingartner-Ortner <38643099+RafaelWO@users.noreply.github.com>
This commit is contained in:
Miss Islington (bot)
GitHub
parent
c6dd764719
commit
1b2f0bd54c
2 changed files with 58 additions and 81 deletions
|
|
@ -965,75 +965,16 @@ want one of them to be the value::
|
|||
|
||||
|
||||
Finer Points
|
||||
^^^^^^^^^^^^
|
||||
------------
|
||||
|
||||
Supported ``__dunder__`` names
|
||||
""""""""""""""""""""""""""""""
|
||||
Supported ``__dunder__`` and ``_sunder_`` names
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
:attr:`~enum.EnumType.__members__` is a read-only ordered mapping of ``member_name``:``member``
|
||||
items. It is only available on the class.
|
||||
|
||||
:meth:`~object.__new__`, if specified, must create and return the enum members; it is
|
||||
also a very good idea to set the member's :attr:`~Enum._value_` appropriately. Once
|
||||
all the members are created it is no longer used.
|
||||
|
||||
|
||||
Supported ``_sunder_`` names
|
||||
""""""""""""""""""""""""""""
|
||||
|
||||
- :attr:`~Enum._name_` -- name of the member
|
||||
- :attr:`~Enum._value_` -- value of the member; can be set in ``__new__``
|
||||
- :meth:`~Enum._missing_` -- a lookup function used when a value is not found;
|
||||
may be overridden
|
||||
- :attr:`~Enum._ignore_` -- a list of names, either as a :class:`list` or a
|
||||
:class:`str`, that will not be transformed into members, and will be removed
|
||||
from the final class
|
||||
- :meth:`~Enum._generate_next_value_` -- used to get an appropriate value for
|
||||
an enum member; may be overridden
|
||||
- :meth:`~Enum._add_alias_` -- adds a new name as an alias to an existing
|
||||
member.
|
||||
- :meth:`~Enum._add_value_alias_` -- adds a new value as an alias to an
|
||||
existing member. See `MultiValueEnum`_ for an example.
|
||||
|
||||
.. note::
|
||||
|
||||
For standard :class:`Enum` classes the next value chosen is the highest
|
||||
value seen incremented by one.
|
||||
|
||||
For :class:`Flag` classes the next value chosen will be the next highest
|
||||
power-of-two.
|
||||
|
||||
.. versionchanged:: 3.13
|
||||
Prior versions would use the last seen value instead of the highest value.
|
||||
|
||||
.. versionadded:: 3.6 ``_missing_``, ``_order_``, ``_generate_next_value_``
|
||||
.. versionadded:: 3.7 ``_ignore_``
|
||||
.. versionadded:: 3.13 ``_add_alias_``, ``_add_value_alias_``
|
||||
|
||||
To help keep Python 2 / Python 3 code in sync an :attr:`~Enum._order_` attribute can
|
||||
be provided. It will be checked against the actual order of the enumeration
|
||||
and raise an error if the two do not match::
|
||||
|
||||
>>> class Color(Enum):
|
||||
... _order_ = 'RED GREEN BLUE'
|
||||
... RED = 1
|
||||
... BLUE = 3
|
||||
... GREEN = 2
|
||||
...
|
||||
Traceback (most recent call last):
|
||||
...
|
||||
TypeError: member order does not match _order_:
|
||||
['RED', 'BLUE', 'GREEN']
|
||||
['RED', 'GREEN', 'BLUE']
|
||||
|
||||
.. note::
|
||||
|
||||
In Python 2 code the :attr:`~Enum._order_` attribute is necessary as definition
|
||||
order is lost before it can be recorded.
|
||||
The supported ``__dunder__`` and ``_sunder_`` names can be found in the :ref:`Enum API documentation <enum-dunder-sunder>`.
|
||||
|
||||
|
||||
_Private__names
|
||||
"""""""""""""""
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
:ref:`Private names <private-name-mangling>` are not converted to enum members,
|
||||
but remain normal attributes.
|
||||
|
|
@ -1042,7 +983,7 @@ but remain normal attributes.
|
|||
|
||||
|
||||
``Enum`` member type
|
||||
""""""""""""""""""""
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Enum members are instances of their enum class, and are normally accessed as
|
||||
``EnumClass.member``. In certain situations, such as writing custom enum
|
||||
|
|
@ -1055,7 +996,7 @@ recommended.
|
|||
|
||||
|
||||
Creating members that are mixed with other data types
|
||||
"""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
When subclassing other data types, such as :class:`int` or :class:`str`, with
|
||||
an :class:`Enum`, all values after the ``=`` are passed to that data type's
|
||||
|
|
@ -1069,7 +1010,7 @@ constructor. For example::
|
|||
|
||||
|
||||
Boolean value of ``Enum`` classes and members
|
||||
"""""""""""""""""""""""""""""""""""""""""""""
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Enum classes that are mixed with non-:class:`Enum` types (such as
|
||||
:class:`int`, :class:`str`, etc.) are evaluated according to the mixed-in
|
||||
|
|
@ -1084,7 +1025,7 @@ Plain :class:`Enum` classes always evaluate as :data:`True`.
|
|||
|
||||
|
||||
``Enum`` classes with methods
|
||||
"""""""""""""""""""""""""""""
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If you give your enum subclass extra methods, like the `Planet`_
|
||||
class below, those methods will show up in a :func:`dir` of the member,
|
||||
|
|
@ -1097,7 +1038,7 @@ but not of the class::
|
|||
|
||||
|
||||
Combining members of ``Flag``
|
||||
"""""""""""""""""""""""""""""
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Iterating over a combination of :class:`Flag` members will only return the members that
|
||||
are comprised of a single bit::
|
||||
|
|
@ -1117,7 +1058,7 @@ are comprised of a single bit::
|
|||
|
||||
|
||||
``Flag`` and ``IntFlag`` minutia
|
||||
""""""""""""""""""""""""""""""""
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Using the following snippet for our examples::
|
||||
|
||||
|
|
@ -1478,6 +1419,7 @@ alias::
|
|||
behaviors as well as disallowing aliases. If the only desired change is
|
||||
disallowing aliases, the :func:`unique` decorator can be used instead.
|
||||
|
||||
.. _multi-value-enum:
|
||||
|
||||
MultiValueEnum
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
|
|
|||
|
|
@ -307,6 +307,28 @@ Data types
|
|||
No longer used, kept for backward compatibility.
|
||||
(class attribute, removed during class creation).
|
||||
|
||||
The :attr:`~Enum._order_` attribute can be provided to help keep Python 2 / Python 3 code in sync.
|
||||
It will be checked against the actual order of the enumeration and raise an error if the two do not match::
|
||||
|
||||
>>> class Color(Enum):
|
||||
... _order_ = 'RED GREEN BLUE'
|
||||
... RED = 1
|
||||
... BLUE = 3
|
||||
... GREEN = 2
|
||||
...
|
||||
Traceback (most recent call last):
|
||||
...
|
||||
TypeError: member order does not match _order_:
|
||||
['RED', 'BLUE', 'GREEN']
|
||||
['RED', 'GREEN', 'BLUE']
|
||||
|
||||
.. note::
|
||||
|
||||
In Python 2 code the :attr:`~Enum._order_` attribute is necessary as definition
|
||||
order is lost before it can be recorded.
|
||||
|
||||
.. versionadded:: 3.6
|
||||
|
||||
.. attribute:: Enum._ignore_
|
||||
|
||||
``_ignore_`` is only used during creation and is removed from the
|
||||
|
|
@ -316,6 +338,8 @@ Data types
|
|||
names will also be removed from the completed enumeration. See
|
||||
:ref:`TimePeriod <enum-time-period>` for an example.
|
||||
|
||||
.. versionadded:: 3.7
|
||||
|
||||
.. method:: Enum.__dir__(self)
|
||||
|
||||
Returns ``['__class__', '__doc__', '__module__', 'name', 'value']`` and
|
||||
|
|
@ -346,7 +370,16 @@ Data types
|
|||
:last_values: A list of the previous values.
|
||||
|
||||
A *staticmethod* that is used to determine the next value returned by
|
||||
:class:`auto`::
|
||||
:class:`auto`.
|
||||
|
||||
.. note::
|
||||
For standard :class:`Enum` classes the next value chosen is the highest
|
||||
value seen incremented by one.
|
||||
|
||||
For :class:`Flag` classes the next value chosen will be the next highest
|
||||
power-of-two.
|
||||
|
||||
This method may be overridden, e.g.::
|
||||
|
||||
>>> from enum import auto, Enum
|
||||
>>> class PowersOfThree(Enum):
|
||||
|
|
@ -359,6 +392,10 @@ Data types
|
|||
>>> PowersOfThree.SECOND.value
|
||||
9
|
||||
|
||||
.. versionadded:: 3.6
|
||||
.. versionchanged:: 3.13
|
||||
Prior versions would use the last seen value instead of the highest value.
|
||||
|
||||
.. method:: Enum.__init__(self, *args, **kwds)
|
||||
|
||||
By default, does nothing. If multiple values are given in the member
|
||||
|
|
@ -397,6 +434,8 @@ Data types
|
|||
>>> Build('deBUG')
|
||||
<Build.DEBUG: 'debug'>
|
||||
|
||||
.. versionadded:: 3.6
|
||||
|
||||
.. method:: Enum.__new__(cls, *args, **kwds)
|
||||
|
||||
By default, doesn't exist. If specified, either in the enum class
|
||||
|
|
@ -490,7 +529,8 @@ Data types
|
|||
>>> Color(42)
|
||||
<Color.RED: 1>
|
||||
|
||||
Raises a :exc:`ValueError` if the value is already linked with a different member.
|
||||
| Raises a :exc:`ValueError` if the value is already linked with a different member.
|
||||
| See :ref:`multi-value-enum` for an example.
|
||||
|
||||
.. versionadded:: 3.13
|
||||
|
||||
|
|
@ -889,6 +929,8 @@ Data types
|
|||
|
||||
---------------
|
||||
|
||||
.. _enum-dunder-sunder:
|
||||
|
||||
Supported ``__dunder__`` names
|
||||
""""""""""""""""""""""""""""""
|
||||
|
||||
|
|
@ -896,7 +938,7 @@ Supported ``__dunder__`` names
|
|||
items. It is only available on the class.
|
||||
|
||||
:meth:`~Enum.__new__`, if specified, must create and return the enum members;
|
||||
it is also a very good idea to set the member's :attr:`!_value_` appropriately.
|
||||
it is also a very good idea to set the member's :attr:`~Enum._value_` appropriately.
|
||||
Once all the members are created it is no longer used.
|
||||
|
||||
|
||||
|
|
@ -912,17 +954,10 @@ Supported ``_sunder_`` names
|
|||
from the final class
|
||||
- :attr:`~Enum._order_` -- no longer used, kept for backward
|
||||
compatibility (class attribute, removed during class creation)
|
||||
|
||||
- :meth:`~Enum._generate_next_value_` -- used to get an appropriate value for
|
||||
an enum member; may be overridden
|
||||
|
||||
.. note::
|
||||
|
||||
For standard :class:`Enum` classes the next value chosen is the highest
|
||||
value seen incremented by one.
|
||||
|
||||
For :class:`Flag` classes the next value chosen will be the next highest
|
||||
power-of-two.
|
||||
|
||||
- :meth:`~Enum._add_alias_` -- adds a new name as an alias to an existing
|
||||
member.
|
||||
- :meth:`~Enum._add_value_alias_` -- adds a new value as an alias to an
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue