Finer Points
-^^^^^^^^^^^^
-
-Supported ``__dunder__`` 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.
+Supported ``__dunder__`` and ``_sunder_`` names
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- .. 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.
``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
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
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
``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,
Combining members of ``Flag``
-"""""""""""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Iterating over a combination of :class:`Flag` members will only return the members that
are comprised of a single bit::
``Flag`` and ``IntFlag`` minutia
-""""""""""""""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Using the following snippet for our examples::
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
^^^^^^^^^^^^^^^^^
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
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
: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):
>>> 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
>>> 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
>>> 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
---------------
+.. _enum-dunder-sunder:
+
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.
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
projects / thirdparty / Python / cpython.git / commitdiff
