diff options
Diffstat (limited to 'devdocs/python~3.12/library%2Fenum.html')
| -rw-r--r-- | devdocs/python~3.12/library%2Fenum.html | 448 |
1 files changed, 448 insertions, 0 deletions
diff --git a/devdocs/python~3.12/library%2Fenum.html b/devdocs/python~3.12/library%2Fenum.html new file mode 100644 index 00000000..7ca1c485 --- /dev/null +++ b/devdocs/python~3.12/library%2Fenum.html @@ -0,0 +1,448 @@ + <span id="enum-support-for-enumerations"></span><h1>enum — Support for enumerations</h1> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.4.</span></p> </div> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/enum.py">Lib/enum.py</a></p> <aside class="sidebar"> <p class="sidebar-title">Important</p> <p>This page contains the API reference information. For tutorial information and discussion of more advanced topics, see</p> <ul class="simple"> <li><a class="reference internal" href="../howto/enum#enum-basic-tutorial"><span class="std std-ref">Basic Tutorial</span></a></li> <li><a class="reference internal" href="../howto/enum#enum-advanced-tutorial"><span class="std std-ref">Advanced Tutorial</span></a></li> <li><a class="reference internal" href="../howto/enum#enum-cookbook"><span class="std std-ref">Enum Cookbook</span></a></li> </ul> </aside> <p>An enumeration:</p> <ul class="simple"> <li>is a set of symbolic names (members) bound to unique values</li> <li>can be iterated over to return its canonical (i.e. non-alias) members in definition order</li> <li>uses <em>call</em> syntax to return members by value</li> <li>uses <em>index</em> syntax to return members by name</li> </ul> <p>Enumerations are created either by using <a class="reference internal" href="../reference/compound_stmts#class"><code>class</code></a> syntax, or by using function-call syntax:</p> <pre data-language="python">>>> from enum import Enum + +>>> # class syntax +>>> class Color(Enum): +... RED = 1 +... GREEN = 2 +... BLUE = 3 + +>>> # functional syntax +>>> Color = Enum('Color', ['RED', 'GREEN', 'BLUE']) +</pre> <p>Even though we can use <a class="reference internal" href="../reference/compound_stmts#class"><code>class</code></a> syntax to create Enums, Enums are not normal Python classes. See <a class="reference internal" href="../howto/enum#enum-class-differences"><span class="std std-ref">How are Enums different?</span></a> for more details.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Nomenclature</p> <ul class="simple"> <li>The class <code>Color</code> is an <em>enumeration</em> (or <em>enum</em>)</li> <li>The attributes <code>Color.RED</code>, <code>Color.GREEN</code>, etc., are <em>enumeration members</em> (or <em>members</em>) and are functionally constants.</li> <li>The enum members have <em>names</em> and <em>values</em> (the name of <code>Color.RED</code> is <code>RED</code>, the value of <code>Color.BLUE</code> is <code>3</code>, etc.)</li> </ul> </div> <section id="module-contents"> <h2>Module Contents</h2> <p><a class="reference internal" href="#enum.EnumType" title="enum.EnumType"><code>EnumType</code></a></p> <p>The <code>type</code> for Enum and its subclasses.</p> <p><a class="reference internal" href="#enum.Enum" title="enum.Enum"><code>Enum</code></a></p> <p>Base class for creating enumerated constants.</p> <p><a class="reference internal" href="#enum.IntEnum" title="enum.IntEnum"><code>IntEnum</code></a></p> <p>Base class for creating enumerated constants that are also subclasses of <a class="reference internal" href="functions#int" title="int"><code>int</code></a>. (<a class="reference internal" href="#notes">Notes</a>)</p> <p><a class="reference internal" href="#enum.StrEnum" title="enum.StrEnum"><code>StrEnum</code></a></p> <p>Base class for creating enumerated constants that are also subclasses of <a class="reference internal" href="stdtypes#str" title="str"><code>str</code></a>. (<a class="reference internal" href="#notes">Notes</a>)</p> <p><a class="reference internal" href="#enum.Flag" title="enum.Flag"><code>Flag</code></a></p> <p>Base class for creating enumerated constants that can be combined using the bitwise operations without losing their <a class="reference internal" href="#enum.Flag" title="enum.Flag"><code>Flag</code></a> membership.</p> <p><a class="reference internal" href="#enum.IntFlag" title="enum.IntFlag"><code>IntFlag</code></a></p> <p>Base class for creating enumerated constants that can be combined using the bitwise operators without losing their <a class="reference internal" href="#enum.IntFlag" title="enum.IntFlag"><code>IntFlag</code></a> membership. <a class="reference internal" href="#enum.IntFlag" title="enum.IntFlag"><code>IntFlag</code></a> members are also subclasses of <a class="reference internal" href="functions#int" title="int"><code>int</code></a>. (<a class="reference internal" href="#notes">Notes</a>)</p> <p><a class="reference internal" href="#enum.ReprEnum" title="enum.ReprEnum"><code>ReprEnum</code></a></p> <p>Used by <a class="reference internal" href="#enum.IntEnum" title="enum.IntEnum"><code>IntEnum</code></a>, <a class="reference internal" href="#enum.StrEnum" title="enum.StrEnum"><code>StrEnum</code></a>, and <a class="reference internal" href="#enum.IntFlag" title="enum.IntFlag"><code>IntFlag</code></a> to keep the <a class="reference internal" href="stdtypes#str" title="str"><code>str()</code></a> of the mixed-in type.</p> <p><a class="reference internal" href="#enum.EnumCheck" title="enum.EnumCheck"><code>EnumCheck</code></a></p> <p>An enumeration with the values <code>CONTINUOUS</code>, <code>NAMED_FLAGS</code>, and <code>UNIQUE</code>, for use with <a class="reference internal" href="#enum.verify" title="enum.verify"><code>verify()</code></a> to ensure various constraints are met by a given enumeration.</p> <p><a class="reference internal" href="#enum.FlagBoundary" title="enum.FlagBoundary"><code>FlagBoundary</code></a></p> <p>An enumeration with the values <code>STRICT</code>, <code>CONFORM</code>, <code>EJECT</code>, and <code>KEEP</code> which allows for more fine-grained control over how invalid values are dealt with in an enumeration.</p> <p><a class="reference internal" href="#enum.auto" title="enum.auto"><code>auto</code></a></p> <p>Instances are replaced with an appropriate value for Enum members. <a class="reference internal" href="#enum.StrEnum" title="enum.StrEnum"><code>StrEnum</code></a> defaults to the lower-cased version of the member name, while other Enums default to 1 and increase from there.</p> <p><a class="reference internal" href="#enum.property" title="enum.property"><code>property()</code></a></p> <p>Allows <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code>Enum</code></a> members to have attributes without conflicting with member names. The <code>value</code> and <code>name</code> attributes are implemented this way.</p> <p><a class="reference internal" href="#enum.unique" title="enum.unique"><code>unique()</code></a></p> <p>Enum class decorator that ensures only one name is bound to any one value.</p> <p><a class="reference internal" href="#enum.verify" title="enum.verify"><code>verify()</code></a></p> <p>Enum class decorator that checks user-selectable constraints on an enumeration.</p> <p><a class="reference internal" href="#enum.member" title="enum.member"><code>member()</code></a></p> <p>Make <code>obj</code> a member. Can be used as a decorator.</p> <p><a class="reference internal" href="#enum.nonmember" title="enum.nonmember"><code>nonmember()</code></a></p> <p>Do not make <code>obj</code> a member. Can be used as a decorator.</p> <p><a class="reference internal" href="#enum.global_enum" title="enum.global_enum"><code>global_enum()</code></a></p> <p>Modify the <a class="reference internal" href="stdtypes#str" title="str"><code>str()</code></a> and <a class="reference internal" href="functions#repr" title="repr"><code>repr()</code></a> of an enum to show its members as belonging to the module instead of its class, and export the enum members to the global namespace.</p> <p><a class="reference internal" href="#enum.show_flag_values" title="enum.show_flag_values"><code>show_flag_values()</code></a></p> <p>Return a list of all power-of-two integers contained in a flag.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.6: </span><code>Flag</code>, <code>IntFlag</code>, <code>auto</code></p> </div> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.11: </span><code>StrEnum</code>, <code>EnumCheck</code>, <code>ReprEnum</code>, <code>FlagBoundary</code>, <code>property</code>, <code>member</code>, <code>nonmember</code>, <code>global_enum</code>, <code>show_flag_values</code></p> </div> </section> <section id="data-types"> <h2>Data Types</h2> <dl class="py class"> <dt class="sig sig-object py" id="enum.EnumType"> +<code>class enum.EnumType</code> </dt> <dd> +<p><em>EnumType</em> is the <a class="reference internal" href="../glossary#term-metaclass"><span class="xref std std-term">metaclass</span></a> for <em>enum</em> enumerations. It is possible to subclass <em>EnumType</em> – see <a class="reference internal" href="../howto/enum#enumtype-examples"><span class="std std-ref">Subclassing EnumType</span></a> for details.</p> <p><em>EnumType</em> is responsible for setting the correct <code>__repr__()</code>, <code>__str__()</code>, <code>__format__()</code>, and <code>__reduce__()</code> methods on the final <em>enum</em>, as well as creating the enum members, properly handling duplicates, providing iteration over the enum class, etc.</p> <dl class="py method"> <dt class="sig sig-object py" id="enum.EnumType.__call__"> +<code>__call__(cls, value, names=None, \*, module=None, qualname=None, type=None, start=1, boundary=None)</code> </dt> <dd> +<p>This method is called in two different ways:</p> <ul> <li> +<p>to look up an existing member:</p> <dl class="field-list simple"> <dt class="field-odd">cls</dt> <dd class="field-odd"> +<p>The enum class being called.</p> </dd> <dt class="field-even">value</dt> <dd class="field-even"> +<p>The value to lookup.</p> </dd> </dl> </li> <li> +<p>to use the <code>cls</code> enum to create a new enum (only if the existing enum does not have any members):</p> <dl class="field-list simple"> <dt class="field-odd">cls</dt> <dd class="field-odd"> +<p>The enum class being called.</p> </dd> <dt class="field-even">value</dt> <dd class="field-even"> +<p>The name of the new Enum to create.</p> </dd> <dt class="field-odd">names</dt> <dd class="field-odd"> +<p>The names/values of the members for the new Enum.</p> </dd> <dt class="field-even">module</dt> <dd class="field-even"> +<p>The name of the module the new Enum is created in.</p> </dd> <dt class="field-odd">qualname</dt> <dd class="field-odd"> +<p>The actual location in the module where this Enum can be found.</p> </dd> <dt class="field-even">type</dt> <dd class="field-even"> +<p>A mix-in type for the new Enum.</p> </dd> <dt class="field-odd">start</dt> <dd class="field-odd"> +<p>The first integer value for the Enum (used by <a class="reference internal" href="#enum.auto" title="enum.auto"><code>auto</code></a>).</p> </dd> <dt class="field-even">boundary</dt> <dd class="field-even"> +<p>How to handle out-of-range values from bit operations (<a class="reference internal" href="#enum.Flag" title="enum.Flag"><code>Flag</code></a> only).</p> </dd> </dl> </li> </ul> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="enum.EnumType.__contains__"> +<code>__contains__(cls, member)</code> </dt> <dd> +<p>Returns <code>True</code> if member belongs to the <code>cls</code>:</p> <pre data-language="python">>>> some_var = Color.RED +>>> some_var in Color +True +>>> Color.RED.value in Color +True +</pre> </dd> +</dl> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span>Before Python 3.12, a <code>TypeError</code> is raised if a non-Enum-member is used in a containment check.</p> </div> <dl class="py method"> <dt class="sig sig-object py" id="enum.EnumType.__dir__"> +<code>__dir__(cls)</code> </dt> <dd> +<p>Returns <code>['__class__', '__doc__', '__members__', '__module__']</code> and the names of the members in <em>cls</em>:</p> <pre data-language="python">>>> dir(Color) +['BLUE', 'GREEN', 'RED', '__class__', '__contains__', '__doc__', '__getitem__', '__init_subclass__', '__iter__', '__len__', '__members__', '__module__', '__name__', '__qualname__'] +</pre> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="enum.EnumType.__getitem__"> +<code>__getitem__(cls, name)</code> </dt> <dd> +<p>Returns the Enum member in <em>cls</em> matching <em>name</em>, or raises a <a class="reference internal" href="exceptions#KeyError" title="KeyError"><code>KeyError</code></a>:</p> <pre data-language="python">>>> Color['BLUE'] +<Color.BLUE: 3> +</pre> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="enum.EnumType.__iter__"> +<code>__iter__(cls)</code> </dt> <dd> +<p>Returns each member in <em>cls</em> in definition order:</p> <pre data-language="python">>>> list(Color) +[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 3>] +</pre> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="enum.EnumType.__len__"> +<code>__len__(cls)</code> </dt> <dd> +<p>Returns the number of member in <em>cls</em>:</p> <pre data-language="python">>>> len(Color) +3 +</pre> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="enum.EnumType.__reversed__"> +<code>__reversed__(cls)</code> </dt> <dd> +<p>Returns each member in <em>cls</em> in reverse definition order:</p> <pre data-language="python">>>> list(reversed(Color)) +[<Color.BLUE: 3>, <Color.GREEN: 2>, <Color.RED: 1>] +</pre> </dd> +</dl> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.11: </span>Before 3.11 <code>enum</code> used <code>EnumMeta</code> type, which is kept as an alias.</p> </div> </dd> +</dl> <dl class="py class"> <dt class="sig sig-object py" id="enum.Enum"> +<code>class enum.Enum</code> </dt> <dd> +<p><em>Enum</em> is the base class for all <em>enum</em> enumerations.</p> <dl class="py attribute"> <dt class="sig sig-object py" id="enum.Enum.name"> +<code>name</code> </dt> <dd> +<p>The name used to define the <code>Enum</code> member:</p> <pre data-language="python">>>> Color.BLUE.name +'BLUE' +</pre> </dd> +</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="enum.Enum.value"> +<code>value</code> </dt> <dd> +<p>The value given to the <code>Enum</code> member:</p> <pre data-language="python">>>> Color.RED.value +1 +</pre> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Enum member values</p> <p>Member values can be anything: <a class="reference internal" href="functions#int" title="int"><code>int</code></a>, <a class="reference internal" href="stdtypes#str" title="str"><code>str</code></a>, etc. If the exact value is unimportant you may use <a class="reference internal" href="#enum.auto" title="enum.auto"><code>auto</code></a> instances and an appropriate value will be chosen for you. See <a class="reference internal" href="#enum.auto" title="enum.auto"><code>auto</code></a> for the details.</p> </div> </dd> +</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="enum.Enum._ignore_"> +<code>_ignore_</code> </dt> <dd> +<p><code>_ignore_</code> is only used during creation and is removed from the enumeration once creation is complete.</p> <p><code>_ignore_</code> is a list of names that will not become members, and whose names will also be removed from the completed enumeration. See <a class="reference internal" href="../howto/enum#enum-time-period"><span class="std std-ref">TimePeriod</span></a> for an example.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="enum.Enum.__dir__"> +<code>__dir__(self)</code> </dt> <dd> +<p>Returns <code>['__class__', '__doc__', '__module__', 'name', 'value']</code> and any public methods defined on <em>self.__class__</em>:</p> <pre data-language="python">>>> from datetime import date +>>> class Weekday(Enum): +... MONDAY = 1 +... TUESDAY = 2 +... WEDNESDAY = 3 +... THURSDAY = 4 +... FRIDAY = 5 +... SATURDAY = 6 +... SUNDAY = 7 +... @classmethod +... def today(cls): +... print('today is %s' % cls(date.today().isoweekday()).name) +... +>>> dir(Weekday.SATURDAY) +['__class__', '__doc__', '__eq__', '__hash__', '__module__', 'name', 'today', 'value'] +</pre> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="enum.Enum._generate_next_value_"> +<code>_generate_next_value_(name, start, count, last_values)</code> </dt> <dd> <dl class="field-list simple"> <dt class="field-odd">name</dt> <dd class="field-odd"> +<p>The name of the member being defined (e.g. ‘RED’).</p> </dd> <dt class="field-even">start</dt> <dd class="field-even"> +<p>The start value for the Enum; the default is 1.</p> </dd> <dt class="field-odd">count</dt> <dd class="field-odd"> +<p>The number of members currently defined, not including this one.</p> </dd> <dt class="field-even">last_values</dt> <dd class="field-even"> +<p>A list of the previous values.</p> </dd> </dl> <p>A <em>staticmethod</em> that is used to determine the next value returned by <a class="reference internal" href="#enum.auto" title="enum.auto"><code>auto</code></a>:</p> <pre data-language="python">>>> from enum import auto +>>> class PowersOfThree(Enum): +... @staticmethod +... def _generate_next_value_(name, start, count, last_values): +... return 3 ** (count + 1) +... FIRST = auto() +... SECOND = auto() +... +>>> PowersOfThree.SECOND.value +9 +</pre> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="enum.Enum.__init_subclass__"> +<code>__init_subclass__(cls, \**kwds)</code> </dt> <dd> +<p>A <em>classmethod</em> that is used to further configure subsequent subclasses. By default, does nothing.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="enum.Enum._missing_"> +<code>_missing_(cls, value)</code> </dt> <dd> +<p>A <em>classmethod</em> for looking up values not found in <em>cls</em>. By default it does nothing, but can be overridden to implement custom search behavior:</p> <pre data-language="python">>>> from enum import StrEnum +>>> class Build(StrEnum): +... DEBUG = auto() +... OPTIMIZED = auto() +... @classmethod +... def _missing_(cls, value): +... value = value.lower() +... for member in cls: +... if member.value == value: +... return member +... return None +... +>>> Build.DEBUG.value +'debug' +>>> Build('deBUG') +<Build.DEBUG: 'debug'> +</pre> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="enum.Enum.__repr__"> +<code>__repr__(self)</code> </dt> <dd> +<p>Returns the string used for <em>repr()</em> calls. By default, returns the <em>Enum</em> name, member name, and value, but can be overridden:</p> <pre data-language="python">>>> class OtherStyle(Enum): +... ALTERNATE = auto() +... OTHER = auto() +... SOMETHING_ELSE = auto() +... def __repr__(self): +... cls_name = self.__class__.__name__ +... return f'{cls_name}.{self.name}' +... +>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}" +(OtherStyle.ALTERNATE, 'OtherStyle.ALTERNATE', 'OtherStyle.ALTERNATE') +</pre> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="enum.Enum.__str__"> +<code>__str__(self)</code> </dt> <dd> +<p>Returns the string used for <em>str()</em> calls. By default, returns the <em>Enum</em> name and member name, but can be overridden:</p> <pre data-language="python">>>> class OtherStyle(Enum): +... ALTERNATE = auto() +... OTHER = auto() +... SOMETHING_ELSE = auto() +... def __str__(self): +... return f'{self.name}' +... +>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}" +(<OtherStyle.ALTERNATE: 1>, 'ALTERNATE', 'ALTERNATE') +</pre> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="enum.Enum.__format__"> +<code>__format__(self)</code> </dt> <dd> +<p>Returns the string used for <em>format()</em> and <em>f-string</em> calls. By default, returns <a class="reference internal" href="#enum.Enum.__str__" title="enum.Enum.__str__"><code>__str__()</code></a> return value, but can be overridden:</p> <pre data-language="python">>>> class OtherStyle(Enum): +... ALTERNATE = auto() +... OTHER = auto() +... SOMETHING_ELSE = auto() +... def __format__(self, spec): +... return f'{self.name}' +... +>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}" +(<OtherStyle.ALTERNATE: 1>, 'OtherStyle.ALTERNATE', 'ALTERNATE') +</pre> </dd> +</dl> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Using <a class="reference internal" href="#enum.auto" title="enum.auto"><code>auto</code></a> with <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code>Enum</code></a> results in integers of increasing value, starting with <code>1</code>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span>Added <a class="reference internal" href="../howto/enum#enum-dataclass-support"><span class="std std-ref">Dataclass support</span></a></p> </div> </dd> +</dl> <dl class="py class"> <dt class="sig sig-object py" id="enum.IntEnum"> +<code>class enum.IntEnum</code> </dt> <dd> +<p><em>IntEnum</em> is the same as <em>Enum</em>, but its members are also integers and can be used anywhere that an integer can be used. If any integer operation is performed with an <em>IntEnum</em> member, the resulting value loses its enumeration status.</p> <pre data-language="python">>>> from enum import IntEnum +>>> class Number(IntEnum): +... ONE = 1 +... TWO = 2 +... THREE = 3 +... +>>> Number.THREE +<Number.THREE: 3> +>>> Number.ONE + Number.TWO +3 +>>> Number.THREE + 5 +8 +>>> Number.THREE == 3 +True +</pre> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Using <a class="reference internal" href="#enum.auto" title="enum.auto"><code>auto</code></a> with <a class="reference internal" href="#enum.IntEnum" title="enum.IntEnum"><code>IntEnum</code></a> results in integers of increasing value, starting with <code>1</code>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.11: </span><a class="reference internal" href="../reference/datamodel#object.__str__" title="object.__str__"><code>__str__()</code></a> is now <code>int.__str__()</code> to better support the <em>replacement of existing constants</em> use-case. <a class="reference internal" href="../reference/datamodel#object.__format__" title="object.__format__"><code>__format__()</code></a> was already <code>int.__format__()</code> for that same reason.</p> </div> </dd> +</dl> <dl class="py class"> <dt class="sig sig-object py" id="enum.StrEnum"> +<code>class enum.StrEnum</code> </dt> <dd> +<p><em>StrEnum</em> is the same as <em>Enum</em>, but its members are also strings and can be used in most of the same places that a string can be used. The result of any string operation performed on or with a <em>StrEnum</em> member is not part of the enumeration.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>There are places in the stdlib that check for an exact <a class="reference internal" href="stdtypes#str" title="str"><code>str</code></a> instead of a <a class="reference internal" href="stdtypes#str" title="str"><code>str</code></a> subclass (i.e. <code>type(unknown) == str</code> instead of <code>isinstance(unknown, str)</code>), and in those locations you will need to use <code>str(StrEnum.member)</code>.</p> </div> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Using <a class="reference internal" href="#enum.auto" title="enum.auto"><code>auto</code></a> with <a class="reference internal" href="#enum.StrEnum" title="enum.StrEnum"><code>StrEnum</code></a> results in the lower-cased member name as the value.</p> </div> <div class="admonition note"> <p class="admonition-title">Note</p> <p><a class="reference internal" href="../reference/datamodel#object.__str__" title="object.__str__"><code>__str__()</code></a> is <code>str.__str__()</code> to better support the <em>replacement of existing constants</em> use-case. <a class="reference internal" href="../reference/datamodel#object.__format__" title="object.__format__"><code>__format__()</code></a> is likewise <code>str.__format__()</code> for that same reason.</p> </div> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.11.</span></p> </div> </dd> +</dl> <dl class="py class"> <dt class="sig sig-object py" id="enum.Flag"> +<code>class enum.Flag</code> </dt> <dd> +<p><em>Flag</em> members support the bitwise operators <code>&</code> (<em>AND</em>), <code>|</code> (<em>OR</em>), <code>^</code> (<em>XOR</em>), and <code>~</code> (<em>INVERT</em>); the results of those operators are members of the enumeration.</p> <dl class="py method"> <dt class="sig sig-object py" id="enum.Flag.__contains__"> +<code>__contains__(self, value)</code> </dt> <dd> +<p>Returns <em>True</em> if value is in self:</p> <pre data-language="python">>>> from enum import Flag, auto +>>> class Color(Flag): +... RED = auto() +... GREEN = auto() +... BLUE = auto() +... +>>> purple = Color.RED | Color.BLUE +>>> white = Color.RED | Color.GREEN | Color.BLUE +>>> Color.GREEN in purple +False +>>> Color.GREEN in white +True +>>> purple in white +True +>>> white in purple +False +</pre> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py"> <span class="sig-name descname">__iter__(self):</span> +</dt> <dd> +<p>Returns all contained non-alias members:</p> <pre data-language="python">>>> list(Color.RED) +[<Color.RED: 1>] +>>> list(purple) +[<Color.RED: 1>, <Color.BLUE: 4>] +</pre> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.11: </span>Aliases are no longer returned during iteration.</p> </div> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py"> <span class="sig-name descname">__len__(self):</span> +</dt> <dd> +<p>Returns number of members in flag:</p> <pre data-language="python">>>> len(Color.GREEN) +1 +>>> len(white) +3 +</pre> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py"> <span class="sig-name descname">__bool__(self):</span> +</dt> <dd> +<p>Returns <em>True</em> if any members in flag, <em>False</em> otherwise:</p> <pre data-language="python">>>> bool(Color.GREEN) +True +>>> bool(white) +True +>>> black = Color(0) +>>> bool(black) +False +</pre> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="enum.Flag.__or__"> +<code>__or__(self, other)</code> </dt> <dd> +<p>Returns current flag binary or’ed with other:</p> <pre data-language="python">>>> Color.RED | Color.GREEN +<Color.RED|GREEN: 3> +</pre> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="enum.Flag.__and__"> +<code>__and__(self, other)</code> </dt> <dd> +<p>Returns current flag binary and’ed with other:</p> <pre data-language="python">>>> purple & white +<Color.RED|BLUE: 5> +>>> purple & Color.GREEN +<Color: 0> +</pre> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="enum.Flag.__xor__"> +<code>__xor__(self, other)</code> </dt> <dd> +<p>Returns current flag binary xor’ed with other:</p> <pre data-language="python">>>> purple ^ white +<Color.GREEN: 2> +>>> purple ^ Color.GREEN +<Color.RED|GREEN|BLUE: 7> +</pre> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py"> <span class="sig-name descname">__invert__(self):</span> +</dt> <dd> +<p>Returns all the flags in <em>type(self)</em> that are not in self:</p> <pre data-language="python">>>> ~white +<Color: 0> +>>> ~purple +<Color.GREEN: 2> +>>> ~Color.RED +<Color.GREEN|BLUE: 6> +</pre> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="enum.Flag._numeric_repr_"> +<code>_numeric_repr_()</code> </dt> <dd> +<p>Function used to format any remaining unnamed numeric values. Default is the value’s repr; common choices are <a class="reference internal" href="functions#hex" title="hex"><code>hex()</code></a> and <a class="reference internal" href="functions#oct" title="oct"><code>oct()</code></a>.</p> </dd> +</dl> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Using <a class="reference internal" href="#enum.auto" title="enum.auto"><code>auto</code></a> with <a class="reference internal" href="#enum.Flag" title="enum.Flag"><code>Flag</code></a> results in integers that are powers of two, starting with <code>1</code>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.11: </span>The <em>repr()</em> of zero-valued flags has changed. It is now::</p> <pre data-language="python">>>> Color(0) +<Color: 0> +</pre> </div> </dd> +</dl> <dl class="py class"> <dt class="sig sig-object py" id="enum.IntFlag"> +<code>class enum.IntFlag</code> </dt> <dd> +<p><em>IntFlag</em> is the same as <em>Flag</em>, but its members are also integers and can be used anywhere that an integer can be used.</p> <pre data-language="python">>>> from enum import IntFlag, auto +>>> class Color(IntFlag): +... RED = auto() +... GREEN = auto() +... BLUE = auto() +... +>>> Color.RED & 2 +<Color: 0> +>>> Color.RED | 2 +<Color.RED|GREEN: 3> +</pre> <p>If any integer operation is performed with an <em>IntFlag</em> member, the result is not an <em>IntFlag</em>:</p> <pre data-language="python">>>> Color.RED + 2 +3 +</pre> <p>If a <em>Flag</em> operation is performed with an <em>IntFlag</em> member and:</p> <ul class="simple"> <li>the result is a valid <em>IntFlag</em>: an <em>IntFlag</em> is returned</li> <li>the result is not a valid <em>IntFlag</em>: the result depends on the <em>FlagBoundary</em> setting</li> </ul> <p>The <em>repr()</em> of unnamed zero-valued flags has changed. It is now:</p> <pre data-language="python">>>> Color(0) +<Color: 0> +</pre> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Using <a class="reference internal" href="#enum.auto" title="enum.auto"><code>auto</code></a> with <a class="reference internal" href="#enum.IntFlag" title="enum.IntFlag"><code>IntFlag</code></a> results in integers that are powers of two, starting with <code>1</code>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.11: </span><a class="reference internal" href="../reference/datamodel#object.__str__" title="object.__str__"><code>__str__()</code></a> is now <code>int.__str__()</code> to better support the <em>replacement of existing constants</em> use-case. <a class="reference internal" href="../reference/datamodel#object.__format__" title="object.__format__"><code>__format__()</code></a> was already <code>int.__format__()</code> for that same reason.</p> <p>Inversion of an <code>IntFlag</code> now returns a positive value that is the union of all flags not in the given flag, rather than a negative value. This matches the existing <a class="reference internal" href="#enum.Flag" title="enum.Flag"><code>Flag</code></a> behavior.</p> </div> </dd> +</dl> <dl class="py class"> <dt class="sig sig-object py" id="enum.ReprEnum"> +<code>class enum.ReprEnum</code> </dt> <dd> +<p><code>ReprEnum</code> uses the <a class="reference internal" href="#enum.Enum.__repr__" title="enum.Enum.__repr__"><code>repr()</code></a> of <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code>Enum</code></a>, but the <a class="reference internal" href="stdtypes#str" title="str"><code>str()</code></a> of the mixed-in data type:</p> <ul class="simple"> <li> +<code>int.__str__()</code> for <a class="reference internal" href="#enum.IntEnum" title="enum.IntEnum"><code>IntEnum</code></a> and <a class="reference internal" href="#enum.IntFlag" title="enum.IntFlag"><code>IntFlag</code></a> +</li> <li> +<code>str.__str__()</code> for <a class="reference internal" href="#enum.StrEnum" title="enum.StrEnum"><code>StrEnum</code></a> +</li> </ul> <p>Inherit from <code>ReprEnum</code> to keep the <a class="reference internal" href="stdtypes#str" title="str"><code>str()</code></a> / <a class="reference internal" href="functions#format" title="format"><code>format()</code></a> of the mixed-in data type instead of using the <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code>Enum</code></a>-default <a class="reference internal" href="#enum.Enum.__str__" title="enum.Enum.__str__"><code>str()</code></a>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.11.</span></p> </div> </dd> +</dl> <dl class="py class"> <dt class="sig sig-object py" id="enum.EnumCheck"> +<code>class enum.EnumCheck</code> </dt> <dd> +<p><em>EnumCheck</em> contains the options used by the <a class="reference internal" href="#enum.verify" title="enum.verify"><code>verify()</code></a> decorator to ensure various constraints; failed constraints result in a <a class="reference internal" href="exceptions#ValueError" title="ValueError"><code>ValueError</code></a>.</p> <dl class="py attribute"> <dt class="sig sig-object py" id="enum.EnumCheck.UNIQUE"> +<code>UNIQUE</code> </dt> <dd> +<p>Ensure that each value has only one name:</p> <pre data-language="python">>>> from enum import Enum, verify, UNIQUE +>>> @verify(UNIQUE) +... class Color(Enum): +... RED = 1 +... GREEN = 2 +... BLUE = 3 +... CRIMSON = 1 +Traceback (most recent call last): +... +ValueError: aliases found in <enum 'Color'>: CRIMSON -> RED +</pre> </dd> +</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="enum.EnumCheck.CONTINUOUS"> +<code>CONTINUOUS</code> </dt> <dd> +<p>Ensure that there are no missing values between the lowest-valued member and the highest-valued member:</p> <pre data-language="python">>>> from enum import Enum, verify, CONTINUOUS +>>> @verify(CONTINUOUS) +... class Color(Enum): +... RED = 1 +... GREEN = 2 +... BLUE = 5 +Traceback (most recent call last): +... +ValueError: invalid enum 'Color': missing values 3, 4 +</pre> </dd> +</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="enum.EnumCheck.NAMED_FLAGS"> +<code>NAMED_FLAGS</code> </dt> <dd> +<p>Ensure that any flag groups/masks contain only named flags – useful when values are specified instead of being generated by <a class="reference internal" href="#enum.auto" title="enum.auto"><code>auto()</code></a>:</p> <pre data-language="python">>>> from enum import Flag, verify, NAMED_FLAGS +>>> @verify(NAMED_FLAGS) +... class Color(Flag): +... RED = 1 +... GREEN = 2 +... BLUE = 4 +... WHITE = 15 +... NEON = 31 +Traceback (most recent call last): +... +ValueError: invalid Flag 'Color': aliases WHITE and NEON are missing combined values of 0x18 [use enum.show_flag_values(value) for details] +</pre> </dd> +</dl> <div class="admonition note"> <p class="admonition-title">Note</p> <p>CONTINUOUS and NAMED_FLAGS are designed to work with integer-valued members.</p> </div> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.11.</span></p> </div> </dd> +</dl> <dl class="py class"> <dt class="sig sig-object py" id="enum.FlagBoundary"> +<code>class enum.FlagBoundary</code> </dt> <dd> +<p><em>FlagBoundary</em> controls how out-of-range values are handled in <em>Flag</em> and its subclasses.</p> <dl class="py attribute"> <dt class="sig sig-object py" id="enum.FlagBoundary.STRICT"> +<code>STRICT</code> </dt> <dd> +<p>Out-of-range values cause a <a class="reference internal" href="exceptions#ValueError" title="ValueError"><code>ValueError</code></a> to be raised. This is the default for <a class="reference internal" href="#enum.Flag" title="enum.Flag"><code>Flag</code></a>:</p> <pre data-language="python">>>> from enum import Flag, STRICT, auto +>>> class StrictFlag(Flag, boundary=STRICT): +... RED = auto() +... GREEN = auto() +... BLUE = auto() +... +>>> StrictFlag(2**2 + 2**4) +Traceback (most recent call last): +... +ValueError: <flag 'StrictFlag'> invalid value 20 + given 0b0 10100 + allowed 0b0 00111 +</pre> </dd> +</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="enum.FlagBoundary.CONFORM"> +<code>CONFORM</code> </dt> <dd> +<p>Out-of-range values have invalid values removed, leaving a valid <em>Flag</em> value:</p> <pre data-language="python">>>> from enum import Flag, CONFORM, auto +>>> class ConformFlag(Flag, boundary=CONFORM): +... RED = auto() +... GREEN = auto() +... BLUE = auto() +... +>>> ConformFlag(2**2 + 2**4) +<ConformFlag.BLUE: 4> +</pre> </dd> +</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="enum.FlagBoundary.EJECT"> +<code>EJECT</code> </dt> <dd> +<p>Out-of-range values lose their <em>Flag</em> membership and revert to <a class="reference internal" href="functions#int" title="int"><code>int</code></a>.</p> <pre data-language="python">>>> from enum import Flag, EJECT, auto +>>> class EjectFlag(Flag, boundary=EJECT): +... RED = auto() +... GREEN = auto() +... BLUE = auto() +... +>>> EjectFlag(2**2 + 2**4) +20 +</pre> </dd> +</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="enum.FlagBoundary.KEEP"> +<code>KEEP</code> </dt> <dd> +<p>Out-of-range values are kept, and the <em>Flag</em> membership is kept. This is the default for <a class="reference internal" href="#enum.IntFlag" title="enum.IntFlag"><code>IntFlag</code></a>:</p> <pre data-language="python">>>> from enum import Flag, KEEP, auto +>>> class KeepFlag(Flag, boundary=KEEP): +... RED = auto() +... GREEN = auto() +... BLUE = auto() +... +>>> KeepFlag(2**2 + 2**4) +<KeepFlag.BLUE|16: 20> +</pre> </dd> +</dl> </dd> +</dl> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.11.</span></p> </div> <section id="supported-dunder-names"> <h3>Supported <code>__dunder__</code> names</h3> <p><code>__members__</code> is a read-only ordered mapping of <code>member_name</code>:<code>member</code> items. It is only available on the class.</p> <p><a class="reference internal" href="../reference/datamodel#object.__new__" title="object.__new__"><code>__new__()</code></a>, if specified, must create and return the enum members; it is also a very good idea to set the member’s <code>_value_</code> appropriately. Once all the members are created it is no longer used.</p> </section> <section id="supported-sunder-names"> <h3>Supported <code>_sunder_</code> names</h3> <ul> <li> +<code>_name_</code> – name of the member</li> <li> +<code>_value_</code> – value of the member; can be set / modified in <code>__new__</code> +</li> <li> +<code>_missing_</code> – a lookup function used when a value is not found; may be overridden</li> <li> +<code>_ignore_</code> – a list of names, either as a <a class="reference internal" href="stdtypes#list" title="list"><code>list</code></a> or a <a class="reference internal" href="stdtypes#str" title="str"><code>str</code></a>, that will not be transformed into members, and will be removed from the final class</li> <li> +<code>_order_</code> – used in Python 2/3 code to ensure member order is consistent (class attribute, removed during class creation)</li> <li> +<p><code>_generate_next_value_</code> – used to get an appropriate value for an enum member; may be overridden</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>For standard <a class="reference internal" href="#enum.Enum" title="enum.Enum"><code>Enum</code></a> classes the next value chosen is the last value seen incremented by one.</p> <p>For <a class="reference internal" href="#enum.Flag" title="enum.Flag"><code>Flag</code></a> classes the next value chosen will be the next highest power-of-two, regardless of the last value seen.</p> </div> </li> </ul> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.6: </span><code>_missing_</code>, <code>_order_</code>, <code>_generate_next_value_</code></p> </div> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.7: </span><code>_ignore_</code></p> </div> </section> </section> <section id="utilities-and-decorators"> <h2>Utilities and Decorators</h2> <dl class="py class"> <dt class="sig sig-object py" id="enum.auto"> +<code>class enum.auto</code> </dt> <dd> +<p><em>auto</em> can be used in place of a value. If used, the <em>Enum</em> machinery will call an <em>Enum</em>’s <a class="reference internal" href="#enum.Enum._generate_next_value_" title="enum.Enum._generate_next_value_"><code>_generate_next_value_()</code></a> to get an appropriate value. For <em>Enum</em> and <em>IntEnum</em> that appropriate value will be the last value plus one; for <em>Flag</em> and <em>IntFlag</em> it will be the first power-of-two greater than the highest value; for <em>StrEnum</em> it will be the lower-cased version of the member’s name. Care must be taken if mixing <em>auto()</em> with manually specified values.</p> <p><em>auto</em> instances are only resolved when at the top level of an assignment:</p> <ul class="simple"> <li> +<code>FIRST = auto()</code> will work (auto() is replaced with <code>1</code>);</li> <li> +<dl class="simple"> <dt> +<code>SECOND = auto(), -2 will work (auto is replaced with 2, so 2, -2 is</code> </dt> +<dd> +<p>used to create the <code>SECOND</code> enum member;</p> </dd> </dl> </li> <li> +<code>THREE = [auto(), -3]</code> will <em>not</em> work (<code><auto instance>, -3</code> is used to create the <code>THREE</code> enum member)</li> </ul> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.11.1: </span>In prior versions, <code>auto()</code> had to be the only thing on the assignment line to work properly.</p> </div> <p><code>_generate_next_value_</code> can be overridden to customize the values used by <em>auto</em>.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>in 3.13 the default <code>_generate_next_value_</code> will always return the highest member value incremented by 1, and will fail if any member is an incompatible type.</p> </div> </dd> +</dl> <dl class="py function"> <dt class="sig sig-object py" id="enum.property"> +<code>@enum.property</code> </dt> <dd> +<p>A decorator similar to the built-in <em>property</em>, but specifically for enumerations. It allows member attributes to have the same names as members themselves.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>the <em>property</em> and the member must be defined in separate classes; for example, the <em>value</em> and <em>name</em> attributes are defined in the <em>Enum</em> class, and <em>Enum</em> subclasses can define members with the names <code>value</code> and <code>name</code>.</p> </div> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.11.</span></p> </div> </dd> +</dl> <dl class="py function"> <dt class="sig sig-object py" id="enum.unique"> +<code>@enum.unique</code> </dt> <dd> +<p>A <a class="reference internal" href="../reference/compound_stmts#class"><code>class</code></a> decorator specifically for enumerations. It searches an enumeration’s <code>__members__</code>, gathering any aliases it finds; if any are found <a class="reference internal" href="exceptions#ValueError" title="ValueError"><code>ValueError</code></a> is raised with the details:</p> <pre data-language="python">>>> from enum import Enum, unique +>>> @unique +... class Mistake(Enum): +... ONE = 1 +... TWO = 2 +... THREE = 3 +... FOUR = 3 +... +Traceback (most recent call last): +... +ValueError: duplicate values found in <enum 'Mistake'>: FOUR -> THREE +</pre> </dd> +</dl> <dl class="py function"> <dt class="sig sig-object py" id="enum.verify"> +<code>@enum.verify</code> </dt> <dd> +<p>A <a class="reference internal" href="../reference/compound_stmts#class"><code>class</code></a> decorator specifically for enumerations. Members from <a class="reference internal" href="#enum.EnumCheck" title="enum.EnumCheck"><code>EnumCheck</code></a> are used to specify which constraints should be checked on the decorated enumeration.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.11.</span></p> </div> </dd> +</dl> <dl class="py function"> <dt class="sig sig-object py" id="enum.member"> +<code>@enum.member</code> </dt> <dd> +<p>A decorator for use in enums: its target will become a member.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.11.</span></p> </div> </dd> +</dl> <dl class="py function"> <dt class="sig sig-object py" id="enum.nonmember"> +<code>@enum.nonmember</code> </dt> <dd> +<p>A decorator for use in enums: its target will not become a member.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.11.</span></p> </div> </dd> +</dl> <dl class="py function"> <dt class="sig sig-object py" id="enum.global_enum"> +<code>@enum.global_enum</code> </dt> <dd> +<p>A decorator to change the <a class="reference internal" href="stdtypes#str" title="str"><code>str()</code></a> and <a class="reference internal" href="functions#repr" title="repr"><code>repr()</code></a> of an enum to show its members as belonging to the module instead of its class. Should only be used when the enum members are exported to the module global namespace (see <a class="reference internal" href="re#re.RegexFlag" title="re.RegexFlag"><code>re.RegexFlag</code></a> for an example).</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.11.</span></p> </div> </dd> +</dl> <dl class="py function"> <dt class="sig sig-object py" id="enum.show_flag_values"> +<code>enum.show_flag_values(value)</code> </dt> <dd> +<p>Return a list of all power-of-two integers contained in a flag <em>value</em>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.11.</span></p> </div> </dd> +</dl> </section> <section id="notes"> <h2>Notes</h2> <p><a class="reference internal" href="#enum.IntEnum" title="enum.IntEnum"><code>IntEnum</code></a>, <a class="reference internal" href="#enum.StrEnum" title="enum.StrEnum"><code>StrEnum</code></a>, and <a class="reference internal" href="#enum.IntFlag" title="enum.IntFlag"><code>IntFlag</code></a></p> <p>These three enum types are designed to be drop-in replacements for existing integer- and string-based values; as such, they have extra limitations:</p> <ul class="simple"> <li> +<code>__str__</code> uses the value and not the name of the enum member</li> <li> +<code>__format__</code>, because it uses <code>__str__</code>, will also use the value of the enum member instead of its name</li> </ul> <p>If you do not need/want those limitations, you can either create your own base class by mixing in the <code>int</code> or <code>str</code> type yourself:</p> <pre data-language="python">>>> from enum import Enum +>>> class MyIntEnum(int, Enum): +... pass +</pre> <p>or you can reassign the appropriate <a class="reference internal" href="stdtypes#str" title="str"><code>str()</code></a>, etc., in your enum:</p> <pre data-language="python">>>> from enum import Enum, IntEnum +>>> class MyIntEnum(IntEnum): +... __str__ = Enum.__str__ +</pre> </section> <div class="_attribution"> + <p class="_attribution-p"> + © 2001–2023 Python Software Foundation<br>Licensed under the PSF License.<br> + <a href="https://docs.python.org/3.12/library/enum.html" class="_attribution-link">https://docs.python.org/3.12/library/enum.html</a> + </p> +</div> |