Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
İzle 1
Yıldızla 0
Wiki 捐赠
gooderp18绿色标准版
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Ağaç: 0f75e31513
Dallar Biçim İmleri
${ item.name }
Branş ${ searchTerm } oluştur
'0f75e31513'den
${ noResults }
Green_GoodERP18_FSJ_Standard/python/Doc/html/howto/enum.html

1873 satır
183KB
Ham Suçlama Geçmiş 

  1. <!DOCTYPE html>

  2. 

  3. <html lang="en" data-content_root="../">

  4.   <head>

  5.     <meta charset="utf-8" />

  6.     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  7. <meta property="og:title" content="Enum HOWTO" />

  8. <meta property="og:type" content="website" />

  9. <meta property="og:url" content="https://docs.python.org/3/howto/enum.html" />

  10. <meta property="og:site_name" content="Python documentation" />

  11. <meta property="og:description" content="An Enum is a set of symbolic names bound to unique values. They are similar to global variables, but they offer a more useful repr(), grouping, type-safety, and a few other features. They are most ..." />

  12. <meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />

  13. <meta property="og:image:alt" content="Python documentation" />

  14. <meta name="description" content="An Enum is a set of symbolic names bound to unique values. They are similar to global variables, but they offer a more useful repr(), grouping, type-safety, and a few other features. They are most ..." />

  15. <meta property="og:image:width" content="200" />

  16. <meta property="og:image:height" content="200" />

  17. <meta name="theme-color" content="#3776ab" />

  18. 

  19.     <title>Enum HOWTO &#8212; Python 3.12.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">

  20.     

  21.     <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />

  22.     <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=bb723527" />

  23.     <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=b20cc3f5" />

  24.     

  25.     <script src="../_static/documentation_options.js?v=2c828074"></script>

  26.     <script src="../_static/doctools.js?v=888ff710"></script>

  27.     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>

  28.     

  29.     <script src="../_static/sidebar.js"></script>

  30.     

  31.     <link rel="search" type="application/opensearchdescription+xml"

  32.           title="Search within Python 3.12.3 documentation"

  33.           href="../_static/opensearch.xml"/>

  34.     <link rel="author" title="About these documents" href="../about.html" />

  35.     <link rel="index" title="Index" href="../genindex.html" />

  36.     <link rel="search" title="Search" href="../search.html" />

  37.     <link rel="copyright" title="Copyright" href="../copyright.html" />

  38.     <link rel="next" title="Functional Programming HOWTO" href="functional.html" />

  39.     <link rel="prev" title="Debugging C API extensions and CPython Internals with GDB" href="gdb_helpers.html" />

  40.     <link rel="canonical" href="https://docs.python.org/3/howto/enum.html" />

  41.     

  42.       

  43.     

  44. 

  45.     

  46.     <style>

  47.       @media only screen {

  48.         table.full-width-table {

  49.             width: 100%;

  50.         }

  51.       }

  52.     </style>

  53. <link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">

  54.     <link rel="shortcut icon" type="image/png" href="../_static/py.svg" />

  55.             <script type="text/javascript" src="../_static/copybutton.js"></script>

  56.             <script type="text/javascript" src="../_static/menu.js"></script>

  57.             <script type="text/javascript" src="../_static/search-focus.js"></script>

  58.             <script type="text/javascript" src="../_static/themetoggle.js"></script> 

  59. 

  60.   </head>

  61. <body>

  62. <div class="mobile-nav">

  63.     <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"

  64.            aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />

  65.     <nav class="nav-content" role="navigation">

  66.         <label for="menuToggler" class="toggler__label">

  67.             <span></span>

  68.         </label>

  69.         <span class="nav-items-wrapper">

  70.             <a href="https://www.python.org/" class="nav-logo">

  71.                 <img src="../_static/py.svg" alt="Python logo"/>

  72.             </a>

  73.             <span class="version_switcher_placeholder"></span>

  74.             <form role="search" class="search" action="../search.html" method="get">

  75.                 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">

  76.                     <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>

  77.                 </svg>

  78.                 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />

  79.                 <input type="submit" value="Go"/>

  80.             </form>

  81.         </span>

  82.     </nav>

  83.     <div class="menu-wrapper">

  84.         <nav class="menu" role="navigation" aria-label="main navigation">

  85.             <div class="language_switcher_placeholder"></div>

  86.             

  87. <label class="theme-selector-label">

  88.     Theme

  89.     <select class="theme-selector" oninput="activateTheme(this.value)">

  90.         <option value="auto" selected>Auto</option>

  91.         <option value="light">Light</option>

  92.         <option value="dark">Dark</option>

  93.     </select>

  94. </label>

  95.   <div>

  96.     <h3><a href="../contents.html">Table of Contents</a></h3>

  97.     <ul>

  98. <li><a class="reference internal" href="#">Enum HOWTO</a><ul>

  99. <li><a class="reference internal" href="#programmatic-access-to-enumeration-members-and-their-attributes">Programmatic access to enumeration members and their attributes</a></li>

  100. <li><a class="reference internal" href="#duplicating-enum-members-and-values">Duplicating enum members and values</a></li>

  101. <li><a class="reference internal" href="#ensuring-unique-enumeration-values">Ensuring unique enumeration values</a></li>

  102. <li><a class="reference internal" href="#using-automatic-values">Using automatic values</a></li>

  103. <li><a class="reference internal" href="#iteration">Iteration</a></li>

  104. <li><a class="reference internal" href="#comparisons">Comparisons</a></li>

  105. <li><a class="reference internal" href="#allowed-members-and-attributes-of-enumerations">Allowed members and attributes of enumerations</a></li>

  106. <li><a class="reference internal" href="#restricted-enum-subclassing">Restricted Enum subclassing</a></li>

  107. <li><a class="reference internal" href="#dataclass-support">Dataclass support</a></li>

  108. <li><a class="reference internal" href="#pickling">Pickling</a></li>

  109. <li><a class="reference internal" href="#functional-api">Functional API</a></li>

  110. <li><a class="reference internal" href="#derived-enumerations">Derived Enumerations</a><ul>

  111. <li><a class="reference internal" href="#intenum">IntEnum</a></li>

  112. <li><a class="reference internal" href="#strenum">StrEnum</a></li>

  113. <li><a class="reference internal" href="#intflag">IntFlag</a></li>

  114. <li><a class="reference internal" href="#flag">Flag</a></li>

  115. <li><a class="reference internal" href="#others">Others</a></li>

  116. </ul>

  117. </li>

  118. <li><a class="reference internal" href="#when-to-use-new-vs-init">When to use <code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code> vs. <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a><ul>

  119. <li><a class="reference internal" href="#finer-points">Finer Points</a><ul>

  120. <li><a class="reference internal" href="#supported-dunder-names">Supported <code class="docutils literal notranslate"><span class="pre">__dunder__</span></code> names</a></li>

  121. <li><a class="reference internal" href="#supported-sunder-names">Supported <code class="docutils literal notranslate"><span class="pre">_sunder_</span></code> names</a></li>

  122. <li><a class="reference internal" href="#private-names">_Private__names</a></li>

  123. <li><a class="reference internal" href="#enum-member-type"><code class="docutils literal notranslate"><span class="pre">Enum</span></code> member type</a></li>

  124. <li><a class="reference internal" href="#creating-members-that-are-mixed-with-other-data-types">Creating members that are mixed with other data types</a></li>

  125. <li><a class="reference internal" href="#boolean-value-of-enum-classes-and-members">Boolean value of <code class="docutils literal notranslate"><span class="pre">Enum</span></code> classes and members</a></li>

  126. <li><a class="reference internal" href="#enum-classes-with-methods"><code class="docutils literal notranslate"><span class="pre">Enum</span></code> classes with methods</a></li>

  127. <li><a class="reference internal" href="#combining-members-of-flag">Combining members of <code class="docutils literal notranslate"><span class="pre">Flag</span></code></a></li>

  128. <li><a class="reference internal" href="#flag-and-intflag-minutia"><code class="docutils literal notranslate"><span class="pre">Flag</span></code> and <code class="docutils literal notranslate"><span class="pre">IntFlag</span></code> minutia</a></li>

  129. </ul>

  130. </li>

  131. </ul>

  132. </li>

  133. <li><a class="reference internal" href="#how-are-enums-and-flags-different">How are Enums and Flags different?</a><ul>

  134. <li><a class="reference internal" href="#enum-classes">Enum Classes</a></li>

  135. <li><a class="reference internal" href="#flag-classes">Flag Classes</a></li>

  136. <li><a class="reference internal" href="#enum-members-aka-instances">Enum Members (aka instances)</a></li>

  137. <li><a class="reference internal" href="#flag-members">Flag Members</a></li>

  138. </ul>

  139. </li>

  140. <li><a class="reference internal" href="#enum-cookbook">Enum Cookbook</a><ul>

  141. <li><a class="reference internal" href="#omitting-values">Omitting values</a><ul>

  142. <li><a class="reference internal" href="#using-auto">Using <code class="xref py py-class docutils literal notranslate"><span class="pre">auto</span></code></a></li>

  143. <li><a class="reference internal" href="#using-object">Using <code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a></li>

  144. <li><a class="reference internal" href="#using-a-descriptive-string">Using a descriptive string</a></li>

  145. <li><a class="reference internal" href="#using-a-custom-new">Using a custom <code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code></a></li>

  146. </ul>

  147. </li>

  148. <li><a class="reference internal" href="#orderedenum">OrderedEnum</a></li>

  149. <li><a class="reference internal" href="#duplicatefreeenum">DuplicateFreeEnum</a></li>

  150. <li><a class="reference internal" href="#planet">Planet</a></li>

  151. <li><a class="reference internal" href="#timeperiod">TimePeriod</a></li>

  152. </ul>

  153. </li>

  154. <li><a class="reference internal" href="#subclassing-enumtype">Subclassing EnumType</a></li>

  155. </ul>

  156. </li>

  157. </ul>

  158. 

  159.   </div>

  160.   <div>

  161.     <h4>Previous topic</h4>

  162.     <p class="topless"><a href="gdb_helpers.html"

  163.                           title="previous chapter">Debugging C API extensions and CPython Internals with GDB</a></p>

  164.   </div>

  165.   <div>

  166.     <h4>Next topic</h4>

  167.     <p class="topless"><a href="functional.html"

  168.                           title="next chapter">Functional Programming HOWTO</a></p>

  169.   </div>

  170.   <div role="note" aria-label="source link">

  171.     <h3>This Page</h3>

  172.     <ul class="this-page-menu">

  173.       <li><a href="../bugs.html">Report a Bug</a></li>

  174.       <li>

  175.         <a href="https://github.com/python/cpython/blob/main/Doc/howto/enum.rst"

  176.             rel="nofollow">Show Source

  177.         </a>

  178.       </li>

  179.     </ul>

  180.   </div>

  181.         </nav>

  182.     </div>

  183. </div>

  184. 

  185.   

  186.     <div class="related" role="navigation" aria-label="related navigation">

  187.       <h3>Navigation</h3>

  188.       <ul>

  189.         <li class="right" style="margin-right: 10px">

  190.           <a href="../genindex.html" title="General Index"

  191.              accesskey="I">index</a></li>

  192.         <li class="right" >

  193.           <a href="../py-modindex.html" title="Python Module Index"

  194.              >modules</a> |</li>

  195.         <li class="right" >

  196.           <a href="functional.html" title="Functional Programming HOWTO"

  197.              accesskey="N">next</a> |</li>

  198.         <li class="right" >

  199.           <a href="gdb_helpers.html" title="Debugging C API extensions and CPython Internals with GDB"

  200.              accesskey="P">previous</a> |</li>

  201. 

  202.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  203.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  204.           <li class="switchers">

  205.             <div class="language_switcher_placeholder"></div>

  206.             <div class="version_switcher_placeholder"></div>

  207.           </li>

  208.           <li>

  209.               

  210.           </li>

  211.     <li id="cpython-language-and-version">

  212.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  213.     </li>

  214. 

  215.           <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python HOWTOs</a> &#187;</li>

  216.         <li class="nav-item nav-item-this"><a href="">Enum HOWTO</a></li>

  217.                 <li class="right">

  218.                     

  219. 

  220.     <div class="inline-search" role="search">

  221.         <form class="inline-search" action="../search.html" method="get">

  222.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  223.           <input type="submit" value="Go" />

  224.         </form>

  225.     </div>

  226.                      |

  227.                 </li>

  228.             <li class="right">

  229. <label class="theme-selector-label">

  230.     Theme

  231.     <select class="theme-selector" oninput="activateTheme(this.value)">

  232.         <option value="auto" selected>Auto</option>

  233.         <option value="light">Light</option>

  234.         <option value="dark">Dark</option>

  235.     </select>

  236. </label> |</li>

  237.             

  238.       </ul>

  239.     </div>    

  240. 

  241.     <div class="document">

  242.       <div class="documentwrapper">

  243.         <div class="bodywrapper">

  244.           <div class="body" role="main">

  245.             

  246.   <section id="enum-howto">

  247. <h1>Enum HOWTO<a class="headerlink" href="#enum-howto" title="Link to this heading">¶</a></h1>

  248. <p id="enum-basic-tutorial">An <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> is a set of symbolic names bound to unique values.  They are

  249. similar to global variables, but they offer a more useful <a class="reference internal" href="../library/functions.html#repr" title="repr"><code class="xref py py-func docutils literal notranslate"><span class="pre">repr()</span></code></a>,

  250. grouping, type-safety, and a few other features.</p>

  251. <p>They are most useful when you have a variable that can take one of a limited

  252. selection of values.  For example, the days of the week:</p>

  253. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">enum</span> <span class="kn">import</span> <span class="n">Enum</span>

  254. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Weekday</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  255. <span class="gp">... </span>    <span class="n">MONDAY</span> <span class="o">=</span> <span class="mi">1</span>

  256. <span class="gp">... </span>    <span class="n">TUESDAY</span> <span class="o">=</span> <span class="mi">2</span>

  257. <span class="gp">... </span>    <span class="n">WEDNESDAY</span> <span class="o">=</span> <span class="mi">3</span>

  258. <span class="gp">... </span>    <span class="n">THURSDAY</span> <span class="o">=</span> <span class="mi">4</span>

  259. <span class="gp">... </span>    <span class="n">FRIDAY</span> <span class="o">=</span> <span class="mi">5</span>

  260. <span class="gp">... </span>    <span class="n">SATURDAY</span> <span class="o">=</span> <span class="mi">6</span>

  261. <span class="gp">... </span>    <span class="n">SUNDAY</span> <span class="o">=</span> <span class="mi">7</span>

  262. </pre></div>

  263. </div>

  264. <p>Or perhaps the RGB primary colors:</p>

  265. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">enum</span> <span class="kn">import</span> <span class="n">Enum</span>

  266. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Color</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  267. <span class="gp">... </span>    <span class="n">RED</span> <span class="o">=</span> <span class="mi">1</span>

  268. <span class="gp">... </span>    <span class="n">GREEN</span> <span class="o">=</span> <span class="mi">2</span>

  269. <span class="gp">... </span>    <span class="n">BLUE</span> <span class="o">=</span> <span class="mi">3</span>

  270. </pre></div>

  271. </div>

  272. <p>As you can see, creating an <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> is as simple as writing a class that

  273. inherits from <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> itself.</p>

  274. <div class="admonition note">

  275. <p class="admonition-title">Note</p>

  276. <p>Case of Enum Members</p>

  277. <p>Because Enums are used to represent constants, and to help avoid issues

  278. with name clashes between mixin-class methods/attributes and enum names,

  279. we strongly recommend using UPPER_CASE names for members, and will be using

  280. that style in our examples.</p>

  281. </div>

  282. <p>Depending on the nature of the enum a member’s value may or may not be

  283. important, but either way that value can be used to get the corresponding

  284. member:</p>

  285. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Weekday</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>

  286. <span class="go">&lt;Weekday.WEDNESDAY: 3&gt;</span>

  287. </pre></div>

  288. </div>

  289. <p>As you can see, the <code class="docutils literal notranslate"><span class="pre">repr()</span></code> of a member shows the enum name, the member name,

  290. and the value.  The <code class="docutils literal notranslate"><span class="pre">str()</span></code> of a member shows only the enum name and member

  291. name:</p>

  292. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">Weekday</span><span class="o">.</span><span class="n">THURSDAY</span><span class="p">)</span>

  293. <span class="go">Weekday.THURSDAY</span>

  294. </pre></div>

  295. </div>

  296. <p>The <em>type</em> of an enumeration member is the enum it belongs to:</p>

  297. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">type</span><span class="p">(</span><span class="n">Weekday</span><span class="o">.</span><span class="n">MONDAY</span><span class="p">)</span>

  298. <span class="go">&lt;enum &#39;Weekday&#39;&gt;</span>

  299. <span class="gp">&gt;&gt;&gt; </span><span class="nb">isinstance</span><span class="p">(</span><span class="n">Weekday</span><span class="o">.</span><span class="n">FRIDAY</span><span class="p">,</span> <span class="n">Weekday</span><span class="p">)</span>

  300. <span class="go">True</span>

  301. </pre></div>

  302. </div>

  303. <p>Enum members have an attribute that contains just their <code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code>:</p>

  304. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">Weekday</span><span class="o">.</span><span class="n">TUESDAY</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>

  305. <span class="go">TUESDAY</span>

  306. </pre></div>

  307. </div>

  308. <p>Likewise, they have an attribute for their <code class="xref py py-attr docutils literal notranslate"><span class="pre">value</span></code>:</p>

  309. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Weekday</span><span class="o">.</span><span class="n">WEDNESDAY</span><span class="o">.</span><span class="n">value</span>

  310. <span class="go">3</span>

  311. </pre></div>

  312. </div>

  313. <p>Unlike many languages that treat enumerations solely as name/value pairs,

  314. Python Enums can have behavior added.  For example, <a class="reference internal" href="../library/datetime.html#datetime.date" title="datetime.date"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime.date</span></code></a>

  315. has two methods for returning the weekday: <code class="xref py py-meth docutils literal notranslate"><span class="pre">weekday()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">isoweekday()</span></code>.

  316. The difference is that one of them counts from 0-6 and the other from 1-7.

  317. Rather than keep track of that ourselves we can add a method to the <code class="xref py py-class docutils literal notranslate"><span class="pre">Weekday</span></code>

  318. enum to extract the day from the <code class="xref py py-class docutils literal notranslate"><span class="pre">date</span></code> instance and return the matching

  319. enum member:</p>

  320. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@classmethod</span>

  321. <span class="k">def</span> <span class="nf">from_date</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">date</span><span class="p">):</span>

  322.     <span class="k">return</span> <span class="bp">cls</span><span class="p">(</span><span class="n">date</span><span class="o">.</span><span class="n">isoweekday</span><span class="p">())</span>

  323. </pre></div>

  324. </div>

  325. <p>The complete <code class="xref py py-class docutils literal notranslate"><span class="pre">Weekday</span></code> enum now looks like this:</p>

  326. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Weekday</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  327. <span class="gp">... </span>    <span class="n">MONDAY</span> <span class="o">=</span> <span class="mi">1</span>

  328. <span class="gp">... </span>    <span class="n">TUESDAY</span> <span class="o">=</span> <span class="mi">2</span>

  329. <span class="gp">... </span>    <span class="n">WEDNESDAY</span> <span class="o">=</span> <span class="mi">3</span>

  330. <span class="gp">... </span>    <span class="n">THURSDAY</span> <span class="o">=</span> <span class="mi">4</span>

  331. <span class="gp">... </span>    <span class="n">FRIDAY</span> <span class="o">=</span> <span class="mi">5</span>

  332. <span class="gp">... </span>    <span class="n">SATURDAY</span> <span class="o">=</span> <span class="mi">6</span>

  333. <span class="gp">... </span>    <span class="n">SUNDAY</span> <span class="o">=</span> <span class="mi">7</span>

  334. <span class="gp">... </span>    <span class="c1">#</span>

  335. <span class="gp">... </span>    <span class="nd">@classmethod</span>

  336. <span class="gp">... </span>    <span class="k">def</span> <span class="nf">from_date</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">date</span><span class="p">):</span>

  337. <span class="gp">... </span>        <span class="k">return</span> <span class="bp">cls</span><span class="p">(</span><span class="n">date</span><span class="o">.</span><span class="n">isoweekday</span><span class="p">())</span>

  338. </pre></div>

  339. </div>

  340. <p>Now we can find out what today is!  Observe:</p>

  341. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">date</span>

  342. <span class="gp">&gt;&gt;&gt; </span><span class="n">Weekday</span><span class="o">.</span><span class="n">from_date</span><span class="p">(</span><span class="n">date</span><span class="o">.</span><span class="n">today</span><span class="p">())</span>     

  343. <span class="go">&lt;Weekday.TUESDAY: 2&gt;</span>

  344. </pre></div>

  345. </div>

  346. <p>Of course, if you’re reading this on some other day, you’ll see that day instead.</p>

  347. <p>This <code class="xref py py-class docutils literal notranslate"><span class="pre">Weekday</span></code> enum is great if our variable only needs one day, but

  348. what if we need several?  Maybe we’re writing a function to plot chores during

  349. a week, and don’t want to use a <a class="reference internal" href="../library/stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a> – we could use a different type

  350. of <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a>:</p>

  351. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">enum</span> <span class="kn">import</span> <span class="n">Flag</span>

  352. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Weekday</span><span class="p">(</span><span class="n">Flag</span><span class="p">):</span>

  353. <span class="gp">... </span>    <span class="n">MONDAY</span> <span class="o">=</span> <span class="mi">1</span>

  354. <span class="gp">... </span>    <span class="n">TUESDAY</span> <span class="o">=</span> <span class="mi">2</span>

  355. <span class="gp">... </span>    <span class="n">WEDNESDAY</span> <span class="o">=</span> <span class="mi">4</span>

  356. <span class="gp">... </span>    <span class="n">THURSDAY</span> <span class="o">=</span> <span class="mi">8</span>

  357. <span class="gp">... </span>    <span class="n">FRIDAY</span> <span class="o">=</span> <span class="mi">16</span>

  358. <span class="gp">... </span>    <span class="n">SATURDAY</span> <span class="o">=</span> <span class="mi">32</span>

  359. <span class="gp">... </span>    <span class="n">SUNDAY</span> <span class="o">=</span> <span class="mi">64</span>

  360. </pre></div>

  361. </div>

  362. <p>We’ve changed two things: we’re inherited from <a class="reference internal" href="../library/enum.html#enum.Flag" title="enum.Flag"><code class="xref py py-class docutils literal notranslate"><span class="pre">Flag</span></code></a>, and the values are

  363. all powers of 2.</p>

  364. <p>Just like the original <code class="xref py py-class docutils literal notranslate"><span class="pre">Weekday</span></code> enum above, we can have a single selection:</p>

  365. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">first_week_day</span> <span class="o">=</span> <span class="n">Weekday</span><span class="o">.</span><span class="n">MONDAY</span>

  366. <span class="gp">&gt;&gt;&gt; </span><span class="n">first_week_day</span>

  367. <span class="go">&lt;Weekday.MONDAY: 1&gt;</span>

  368. </pre></div>

  369. </div>

  370. <p>But <a class="reference internal" href="../library/enum.html#enum.Flag" title="enum.Flag"><code class="xref py py-class docutils literal notranslate"><span class="pre">Flag</span></code></a> also allows us to combine several members into a single

  371. variable:</p>

  372. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">weekend</span> <span class="o">=</span> <span class="n">Weekday</span><span class="o">.</span><span class="n">SATURDAY</span> <span class="o">|</span> <span class="n">Weekday</span><span class="o">.</span><span class="n">SUNDAY</span>

  373. <span class="gp">&gt;&gt;&gt; </span><span class="n">weekend</span>

  374. <span class="go">&lt;Weekday.SATURDAY|SUNDAY: 96&gt;</span>

  375. </pre></div>

  376. </div>

  377. <p>You can even iterate over a <a class="reference internal" href="../library/enum.html#enum.Flag" title="enum.Flag"><code class="xref py py-class docutils literal notranslate"><span class="pre">Flag</span></code></a> variable:</p>

  378. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">day</span> <span class="ow">in</span> <span class="n">weekend</span><span class="p">:</span>

  379. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="n">day</span><span class="p">)</span>

  380. <span class="go">Weekday.SATURDAY</span>

  381. <span class="go">Weekday.SUNDAY</span>

  382. </pre></div>

  383. </div>

  384. <p>Okay, let’s get some chores set up:</p>

  385. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">chores_for_ethan</span> <span class="o">=</span> <span class="p">{</span>

  386. <span class="gp">... </span>    <span class="s1">&#39;feed the cat&#39;</span><span class="p">:</span> <span class="n">Weekday</span><span class="o">.</span><span class="n">MONDAY</span> <span class="o">|</span> <span class="n">Weekday</span><span class="o">.</span><span class="n">WEDNESDAY</span> <span class="o">|</span> <span class="n">Weekday</span><span class="o">.</span><span class="n">FRIDAY</span><span class="p">,</span>

  387. <span class="gp">... </span>    <span class="s1">&#39;do the dishes&#39;</span><span class="p">:</span> <span class="n">Weekday</span><span class="o">.</span><span class="n">TUESDAY</span> <span class="o">|</span> <span class="n">Weekday</span><span class="o">.</span><span class="n">THURSDAY</span><span class="p">,</span>

  388. <span class="gp">... </span>    <span class="s1">&#39;answer SO questions&#39;</span><span class="p">:</span> <span class="n">Weekday</span><span class="o">.</span><span class="n">SATURDAY</span><span class="p">,</span>

  389. <span class="gp">... </span>    <span class="p">}</span>

  390. </pre></div>

  391. </div>

  392. <p>And a function to display the chores for a given day:</p>

  393. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">show_chores</span><span class="p">(</span><span class="n">chores</span><span class="p">,</span> <span class="n">day</span><span class="p">):</span>

  394. <span class="gp">... </span>    <span class="k">for</span> <span class="n">chore</span><span class="p">,</span> <span class="n">days</span> <span class="ow">in</span> <span class="n">chores</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>

  395. <span class="gp">... </span>        <span class="k">if</span> <span class="n">day</span> <span class="ow">in</span> <span class="n">days</span><span class="p">:</span>

  396. <span class="gp">... </span>            <span class="nb">print</span><span class="p">(</span><span class="n">chore</span><span class="p">)</span>

  397. <span class="gp">...</span>

  398. <span class="gp">&gt;&gt;&gt; </span><span class="n">show_chores</span><span class="p">(</span><span class="n">chores_for_ethan</span><span class="p">,</span> <span class="n">Weekday</span><span class="o">.</span><span class="n">SATURDAY</span><span class="p">)</span>

  399. <span class="go">answer SO questions</span>

  400. </pre></div>

  401. </div>

  402. <p>In cases where the actual values of the members do not matter, you can save

  403. yourself some work and use <a class="reference internal" href="../library/enum.html#enum.auto" title="enum.auto"><code class="xref py py-func docutils literal notranslate"><span class="pre">auto()</span></code></a> for the values:</p>

  404. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">enum</span> <span class="kn">import</span> <span class="n">auto</span>

  405. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Weekday</span><span class="p">(</span><span class="n">Flag</span><span class="p">):</span>

  406. <span class="gp">... </span>    <span class="n">MONDAY</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  407. <span class="gp">... </span>    <span class="n">TUESDAY</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  408. <span class="gp">... </span>    <span class="n">WEDNESDAY</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  409. <span class="gp">... </span>    <span class="n">THURSDAY</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  410. <span class="gp">... </span>    <span class="n">FRIDAY</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  411. <span class="gp">... </span>    <span class="n">SATURDAY</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  412. <span class="gp">... </span>    <span class="n">SUNDAY</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  413. <span class="gp">... </span>    <span class="n">WEEKEND</span> <span class="o">=</span> <span class="n">SATURDAY</span> <span class="o">|</span> <span class="n">SUNDAY</span>

  414. </pre></div>

  415. </div>

  416. <section id="programmatic-access-to-enumeration-members-and-their-attributes">

  417. <span id="enum-advanced-tutorial"></span><h2>Programmatic access to enumeration members and their attributes<a class="headerlink" href="#programmatic-access-to-enumeration-members-and-their-attributes" title="Link to this heading">¶</a></h2>

  418. <p>Sometimes it’s useful to access members in enumerations programmatically (i.e.

  419. situations where <code class="docutils literal notranslate"><span class="pre">Color.RED</span></code> won’t do because the exact color is not known

  420. at program-writing time).  <code class="docutils literal notranslate"><span class="pre">Enum</span></code> allows such access:</p>

  421. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>

  422. <span class="go">&lt;Color.RED: 1&gt;</span>

  423. <span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>

  424. <span class="go">&lt;Color.BLUE: 3&gt;</span>

  425. </pre></div>

  426. </div>

  427. <p>If you want to access enum members by <em>name</em>, use item access:</p>

  428. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="p">[</span><span class="s1">&#39;RED&#39;</span><span class="p">]</span>

  429. <span class="go">&lt;Color.RED: 1&gt;</span>

  430. <span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="p">[</span><span class="s1">&#39;GREEN&#39;</span><span class="p">]</span>

  431. <span class="go">&lt;Color.GREEN: 2&gt;</span>

  432. </pre></div>

  433. </div>

  434. <p>If you have an enum member and need its <code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code> or <code class="xref py py-attr docutils literal notranslate"><span class="pre">value</span></code>:</p>

  435. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">member</span> <span class="o">=</span> <span class="n">Color</span><span class="o">.</span><span class="n">RED</span>

  436. <span class="gp">&gt;&gt;&gt; </span><span class="n">member</span><span class="o">.</span><span class="n">name</span>

  437. <span class="go">&#39;RED&#39;</span>

  438. <span class="gp">&gt;&gt;&gt; </span><span class="n">member</span><span class="o">.</span><span class="n">value</span>

  439. <span class="go">1</span>

  440. </pre></div>

  441. </div>

  442. </section>

  443. <section id="duplicating-enum-members-and-values">

  444. <h2>Duplicating enum members and values<a class="headerlink" href="#duplicating-enum-members-and-values" title="Link to this heading">¶</a></h2>

  445. <p>Having two enum members with the same name is invalid:</p>

  446. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Shape</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  447. <span class="gp">... </span>    <span class="n">SQUARE</span> <span class="o">=</span> <span class="mi">2</span>

  448. <span class="gp">... </span>    <span class="n">SQUARE</span> <span class="o">=</span> <span class="mi">3</span>

  449. <span class="gp">...</span>

  450. <span class="gt">Traceback (most recent call last):</span>

  451. <span class="c">...</span>

  452. <span class="gr">TypeError</span>: <span class="n">&#39;SQUARE&#39; already defined as 2</span>

  453. </pre></div>

  454. </div>

  455. <p>However, an enum member can have other names associated with it.  Given two

  456. entries <code class="docutils literal notranslate"><span class="pre">A</span></code> and <code class="docutils literal notranslate"><span class="pre">B</span></code> with the same value (and <code class="docutils literal notranslate"><span class="pre">A</span></code> defined first), <code class="docutils literal notranslate"><span class="pre">B</span></code>

  457. is an alias for the member <code class="docutils literal notranslate"><span class="pre">A</span></code>.  By-value lookup of the value of <code class="docutils literal notranslate"><span class="pre">A</span></code> will

  458. return the member <code class="docutils literal notranslate"><span class="pre">A</span></code>.  By-name lookup of <code class="docutils literal notranslate"><span class="pre">A</span></code> will return the member <code class="docutils literal notranslate"><span class="pre">A</span></code>.

  459. By-name lookup of <code class="docutils literal notranslate"><span class="pre">B</span></code> will also return the member <code class="docutils literal notranslate"><span class="pre">A</span></code>:</p>

  460. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Shape</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  461. <span class="gp">... </span>    <span class="n">SQUARE</span> <span class="o">=</span> <span class="mi">2</span>

  462. <span class="gp">... </span>    <span class="n">DIAMOND</span> <span class="o">=</span> <span class="mi">1</span>

  463. <span class="gp">... </span>    <span class="n">CIRCLE</span> <span class="o">=</span> <span class="mi">3</span>

  464. <span class="gp">... </span>    <span class="n">ALIAS_FOR_SQUARE</span> <span class="o">=</span> <span class="mi">2</span>

  465. <span class="gp">...</span>

  466. <span class="gp">&gt;&gt;&gt; </span><span class="n">Shape</span><span class="o">.</span><span class="n">SQUARE</span>

  467. <span class="go">&lt;Shape.SQUARE: 2&gt;</span>

  468. <span class="gp">&gt;&gt;&gt; </span><span class="n">Shape</span><span class="o">.</span><span class="n">ALIAS_FOR_SQUARE</span>

  469. <span class="go">&lt;Shape.SQUARE: 2&gt;</span>

  470. <span class="gp">&gt;&gt;&gt; </span><span class="n">Shape</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>

  471. <span class="go">&lt;Shape.SQUARE: 2&gt;</span>

  472. </pre></div>

  473. </div>

  474. <div class="admonition note">

  475. <p class="admonition-title">Note</p>

  476. <p>Attempting to create a member with the same name as an already

  477. defined attribute (another member, a method, etc.) or attempting to create

  478. an attribute with the same name as a member is not allowed.</p>

  479. </div>

  480. </section>

  481. <section id="ensuring-unique-enumeration-values">

  482. <h2>Ensuring unique enumeration values<a class="headerlink" href="#ensuring-unique-enumeration-values" title="Link to this heading">¶</a></h2>

  483. <p>By default, enumerations allow multiple names as aliases for the same value.

  484. When this behavior isn’t desired, you can use the <a class="reference internal" href="../library/enum.html#enum.unique" title="enum.unique"><code class="xref py py-func docutils literal notranslate"><span class="pre">unique()</span></code></a> decorator:</p>

  485. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">enum</span> <span class="kn">import</span> <span class="n">Enum</span><span class="p">,</span> <span class="n">unique</span>

  486. <span class="gp">&gt;&gt;&gt; </span><span class="nd">@unique</span>

  487. <span class="gp">... </span><span class="k">class</span> <span class="nc">Mistake</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  488. <span class="gp">... </span>    <span class="n">ONE</span> <span class="o">=</span> <span class="mi">1</span>

  489. <span class="gp">... </span>    <span class="n">TWO</span> <span class="o">=</span> <span class="mi">2</span>

  490. <span class="gp">... </span>    <span class="n">THREE</span> <span class="o">=</span> <span class="mi">3</span>

  491. <span class="gp">... </span>    <span class="n">FOUR</span> <span class="o">=</span> <span class="mi">3</span>

  492. <span class="gp">...</span>

  493. <span class="gt">Traceback (most recent call last):</span>

  494. <span class="c">...</span>

  495. <span class="gr">ValueError</span>: <span class="n">duplicate values found in &lt;enum &#39;Mistake&#39;&gt;: FOUR -&gt; THREE</span>

  496. </pre></div>

  497. </div>

  498. </section>

  499. <section id="using-automatic-values">

  500. <h2>Using automatic values<a class="headerlink" href="#using-automatic-values" title="Link to this heading">¶</a></h2>

  501. <p>If the exact value is unimportant you can use <a class="reference internal" href="../library/enum.html#enum.auto" title="enum.auto"><code class="xref py py-class docutils literal notranslate"><span class="pre">auto</span></code></a>:</p>

  502. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">enum</span> <span class="kn">import</span> <span class="n">Enum</span><span class="p">,</span> <span class="n">auto</span>

  503. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Color</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  504. <span class="gp">... </span>    <span class="n">RED</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  505. <span class="gp">... </span>    <span class="n">BLUE</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  506. <span class="gp">... </span>    <span class="n">GREEN</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  507. <span class="gp">...</span>

  508. <span class="gp">&gt;&gt;&gt; </span><span class="p">[</span><span class="n">member</span><span class="o">.</span><span class="n">value</span> <span class="k">for</span> <span class="n">member</span> <span class="ow">in</span> <span class="n">Color</span><span class="p">]</span>

  509. <span class="go">[1, 2, 3]</span>

  510. </pre></div>

  511. </div>

  512. <p>The values are chosen by <code class="xref py py-func docutils literal notranslate"><span class="pre">_generate_next_value_()</span></code>, which can be

  513. overridden:</p>

  514. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">AutoName</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  515. <span class="gp">... </span>    <span class="nd">@staticmethod</span>

  516. <span class="gp">... </span>    <span class="k">def</span> <span class="nf">_generate_next_value_</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">start</span><span class="p">,</span> <span class="n">count</span><span class="p">,</span> <span class="n">last_values</span><span class="p">):</span>

  517. <span class="gp">... </span>        <span class="k">return</span> <span class="n">name</span>

  518. <span class="gp">...</span>

  519. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Ordinal</span><span class="p">(</span><span class="n">AutoName</span><span class="p">):</span>

  520. <span class="gp">... </span>    <span class="n">NORTH</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  521. <span class="gp">... </span>    <span class="n">SOUTH</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  522. <span class="gp">... </span>    <span class="n">EAST</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  523. <span class="gp">... </span>    <span class="n">WEST</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  524. <span class="gp">...</span>

  525. <span class="gp">&gt;&gt;&gt; </span><span class="p">[</span><span class="n">member</span><span class="o">.</span><span class="n">value</span> <span class="k">for</span> <span class="n">member</span> <span class="ow">in</span> <span class="n">Ordinal</span><span class="p">]</span>

  526. <span class="go">[&#39;NORTH&#39;, &#39;SOUTH&#39;, &#39;EAST&#39;, &#39;WEST&#39;]</span>

  527. </pre></div>

  528. </div>

  529. <div class="admonition note">

  530. <p class="admonition-title">Note</p>

  531. <p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">_generate_next_value_()</span></code> method must be defined before any members.</p>

  532. </div>

  533. </section>

  534. <section id="iteration">

  535. <h2>Iteration<a class="headerlink" href="#iteration" title="Link to this heading">¶</a></h2>

  536. <p>Iterating over the members of an enum does not provide the aliases:</p>

  537. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">Shape</span><span class="p">)</span>

  538. <span class="go">[&lt;Shape.SQUARE: 2&gt;, &lt;Shape.DIAMOND: 1&gt;, &lt;Shape.CIRCLE: 3&gt;]</span>

  539. <span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">Weekday</span><span class="p">)</span>

  540. <span class="go">[&lt;Weekday.MONDAY: 1&gt;, &lt;Weekday.TUESDAY: 2&gt;, &lt;Weekday.WEDNESDAY: 4&gt;, &lt;Weekday.THURSDAY: 8&gt;, &lt;Weekday.FRIDAY: 16&gt;, &lt;Weekday.SATURDAY: 32&gt;, &lt;Weekday.SUNDAY: 64&gt;]</span>

  541. </pre></div>

  542. </div>

  543. <p>Note that the aliases <code class="docutils literal notranslate"><span class="pre">Shape.ALIAS_FOR_SQUARE</span></code> and <code class="docutils literal notranslate"><span class="pre">Weekday.WEEKEND</span></code> aren’t shown.</p>

  544. <p>The special attribute <code class="docutils literal notranslate"><span class="pre">__members__</span></code> is a read-only ordered mapping of names

  545. to members.  It includes all names defined in the enumeration, including the

  546. aliases:</p>

  547. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">name</span><span class="p">,</span> <span class="n">member</span> <span class="ow">in</span> <span class="n">Shape</span><span class="o">.</span><span class="n">__members__</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>

  548. <span class="gp">... </span>    <span class="n">name</span><span class="p">,</span> <span class="n">member</span>

  549. <span class="gp">...</span>

  550. <span class="go">(&#39;SQUARE&#39;, &lt;Shape.SQUARE: 2&gt;)</span>

  551. <span class="go">(&#39;DIAMOND&#39;, &lt;Shape.DIAMOND: 1&gt;)</span>

  552. <span class="go">(&#39;CIRCLE&#39;, &lt;Shape.CIRCLE: 3&gt;)</span>

  553. <span class="go">(&#39;ALIAS_FOR_SQUARE&#39;, &lt;Shape.SQUARE: 2&gt;)</span>

  554. </pre></div>

  555. </div>

  556. <p>The <code class="docutils literal notranslate"><span class="pre">__members__</span></code> attribute can be used for detailed programmatic access to

  557. the enumeration members.  For example, finding all the aliases:</p>

  558. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="p">[</span><span class="n">name</span> <span class="k">for</span> <span class="n">name</span><span class="p">,</span> <span class="n">member</span> <span class="ow">in</span> <span class="n">Shape</span><span class="o">.</span><span class="n">__members__</span><span class="o">.</span><span class="n">items</span><span class="p">()</span> <span class="k">if</span> <span class="n">member</span><span class="o">.</span><span class="n">name</span> <span class="o">!=</span> <span class="n">name</span><span class="p">]</span>

  559. <span class="go">[&#39;ALIAS_FOR_SQUARE&#39;]</span>

  560. </pre></div>

  561. </div>

  562. <div class="admonition note">

  563. <p class="admonition-title">Note</p>

  564. <p>Aliases for flags include values with multiple flags set, such as <code class="docutils literal notranslate"><span class="pre">3</span></code>,

  565. and no flags set, i.e. <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p>

  566. </div>

  567. </section>

  568. <section id="comparisons">

  569. <h2>Comparisons<a class="headerlink" href="#comparisons" title="Link to this heading">¶</a></h2>

  570. <p>Enumeration members are compared by identity:</p>

  571. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="o">.</span><span class="n">RED</span> <span class="ow">is</span> <span class="n">Color</span><span class="o">.</span><span class="n">RED</span>

  572. <span class="go">True</span>

  573. <span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="o">.</span><span class="n">RED</span> <span class="ow">is</span> <span class="n">Color</span><span class="o">.</span><span class="n">BLUE</span>

  574. <span class="go">False</span>

  575. <span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="o">.</span><span class="n">RED</span> <span class="ow">is</span> <span class="ow">not</span> <span class="n">Color</span><span class="o">.</span><span class="n">BLUE</span>

  576. <span class="go">True</span>

  577. </pre></div>

  578. </div>

  579. <p>Ordered comparisons between enumeration values are <em>not</em> supported.  Enum

  580. members are not integers (but see <a class="reference internal" href="#intenum">IntEnum</a> below):</p>

  581. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="o">.</span><span class="n">RED</span> <span class="o">&lt;</span> <span class="n">Color</span><span class="o">.</span><span class="n">BLUE</span>

  582. <span class="gt">Traceback (most recent call last):</span>

  583.   File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>

  584. <span class="gr">TypeError</span>: <span class="n">&#39;&lt;&#39; not supported between instances of &#39;Color&#39; and &#39;Color&#39;</span>

  585. </pre></div>

  586. </div>

  587. <p>Equality comparisons are defined though:</p>

  588. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="o">.</span><span class="n">BLUE</span> <span class="o">==</span> <span class="n">Color</span><span class="o">.</span><span class="n">RED</span>

  589. <span class="go">False</span>

  590. <span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="o">.</span><span class="n">BLUE</span> <span class="o">!=</span> <span class="n">Color</span><span class="o">.</span><span class="n">RED</span>

  591. <span class="go">True</span>

  592. <span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="o">.</span><span class="n">BLUE</span> <span class="o">==</span> <span class="n">Color</span><span class="o">.</span><span class="n">BLUE</span>

  593. <span class="go">True</span>

  594. </pre></div>

  595. </div>

  596. <p>Comparisons against non-enumeration values will always compare not equal

  597. (again, <a class="reference internal" href="../library/enum.html#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntEnum</span></code></a> was explicitly designed to behave differently, see

  598. below):</p>

  599. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="o">.</span><span class="n">BLUE</span> <span class="o">==</span> <span class="mi">2</span>

  600. <span class="go">False</span>

  601. </pre></div>

  602. </div>

  603. <div class="admonition warning">

  604. <p class="admonition-title">Warning</p>

  605. <p>It is possible to reload modules – if a reloaded module contains

  606. enums, they will be recreated, and the new members may not

  607. compare identical/equal to the original members.</p>

  608. </div>

  609. </section>

  610. <section id="allowed-members-and-attributes-of-enumerations">

  611. <h2>Allowed members and attributes of enumerations<a class="headerlink" href="#allowed-members-and-attributes-of-enumerations" title="Link to this heading">¶</a></h2>

  612. <p>Most of the examples above use integers for enumeration values.  Using integers

  613. is short and handy (and provided by default by the <a class="reference internal" href="#functional-api">Functional API</a>), but not

  614. strictly enforced.  In the vast majority of use-cases, one doesn’t care what

  615. the actual value of an enumeration is.  But if the value <em>is</em> important,

  616. enumerations can have arbitrary values.</p>

  617. <p>Enumerations are Python classes, and can have methods and special methods as

  618. usual.  If we have this enumeration:</p>

  619. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Mood</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  620. <span class="gp">... </span>    <span class="n">FUNKY</span> <span class="o">=</span> <span class="mi">1</span>

  621. <span class="gp">... </span>    <span class="n">HAPPY</span> <span class="o">=</span> <span class="mi">3</span>

  622. <span class="gp">...</span>

  623. <span class="gp">... </span>    <span class="k">def</span> <span class="nf">describe</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  624. <span class="gp">... </span>        <span class="c1"># self is the member here</span>

  625. <span class="gp">... </span>        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">value</span>

  626. <span class="gp">...</span>

  627. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  628. <span class="gp">... </span>        <span class="k">return</span> <span class="s1">&#39;my custom str! </span><span class="si">{0}</span><span class="s1">&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">value</span><span class="p">)</span>

  629. <span class="gp">...</span>

  630. <span class="gp">... </span>    <span class="nd">@classmethod</span>

  631. <span class="gp">... </span>    <span class="k">def</span> <span class="nf">favorite_mood</span><span class="p">(</span><span class="bp">cls</span><span class="p">):</span>

  632. <span class="gp">... </span>        <span class="c1"># cls here is the enumeration</span>

  633. <span class="gp">... </span>        <span class="k">return</span> <span class="bp">cls</span><span class="o">.</span><span class="n">HAPPY</span>

  634. <span class="gp">...</span>

  635. </pre></div>

  636. </div>

  637. <p>Then:</p>

  638. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Mood</span><span class="o">.</span><span class="n">favorite_mood</span><span class="p">()</span>

  639. <span class="go">&lt;Mood.HAPPY: 3&gt;</span>

  640. <span class="gp">&gt;&gt;&gt; </span><span class="n">Mood</span><span class="o">.</span><span class="n">HAPPY</span><span class="o">.</span><span class="n">describe</span><span class="p">()</span>

  641. <span class="go">(&#39;HAPPY&#39;, 3)</span>

  642. <span class="gp">&gt;&gt;&gt; </span><span class="nb">str</span><span class="p">(</span><span class="n">Mood</span><span class="o">.</span><span class="n">FUNKY</span><span class="p">)</span>

  643. <span class="go">&#39;my custom str! 1&#39;</span>

  644. </pre></div>

  645. </div>

  646. <p>The rules for what is allowed are as follows: names that start and end with

  647. a single underscore are reserved by enum and cannot be used; all other

  648. attributes defined within an enumeration will become members of this

  649. enumeration, with the exception of special methods (<code class="xref py py-meth docutils literal notranslate"><span class="pre">__str__()</span></code>,

  650. <code class="xref py py-meth docutils literal notranslate"><span class="pre">__add__()</span></code>, etc.), descriptors (methods are also descriptors), and

  651. variable names listed in <code class="xref py py-attr docutils literal notranslate"><span class="pre">_ignore_</span></code>.</p>

  652. <p>Note:  if your enumeration defines <code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code> and/or <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code>,

  653. any value(s) given to the enum member will be passed into those methods.

  654. See <a class="reference internal" href="#planet">Planet</a> for an example.</p>

  655. <div class="admonition note">

  656. <p class="admonition-title">Note</p>

  657. <p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code> method, if defined, is used during creation of the Enum

  658. members; it is then replaced by Enum’s <code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code> which is used after

  659. class creation for lookup of existing members.  See <a class="reference internal" href="#new-vs-init"><span class="std std-ref">When to use __new__() vs. __init__()</span></a> for

  660. more details.</p>

  661. </div>

  662. </section>

  663. <section id="restricted-enum-subclassing">

  664. <h2>Restricted Enum subclassing<a class="headerlink" href="#restricted-enum-subclassing" title="Link to this heading">¶</a></h2>

  665. <p>A new <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> class must have one base enum class, up to one concrete

  666. data type, and as many <a class="reference internal" href="../library/functions.html#object" title="object"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a>-based mixin classes as needed.  The

  667. order of these base classes is:</p>

  668. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">EnumName</span><span class="p">([</span><span class="n">mix</span><span class="o">-</span><span class="ow">in</span><span class="p">,</span> <span class="o">...</span><span class="p">,]</span> <span class="p">[</span><span class="n">data</span><span class="o">-</span><span class="nb">type</span><span class="p">,]</span> <span class="n">base</span><span class="o">-</span><span class="n">enum</span><span class="p">):</span>

  669.     <span class="k">pass</span>

  670. </pre></div>

  671. </div>

  672. <p>Also, subclassing an enumeration is allowed only if the enumeration does not define

  673. any members.  So this is forbidden:</p>

  674. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">MoreColor</span><span class="p">(</span><span class="n">Color</span><span class="p">):</span>

  675. <span class="gp">... </span>    <span class="n">PINK</span> <span class="o">=</span> <span class="mi">17</span>

  676. <span class="gp">...</span>

  677. <span class="gt">Traceback (most recent call last):</span>

  678. <span class="c">...</span>

  679. <span class="gr">TypeError</span>: <span class="n">&lt;enum &#39;MoreColor&#39;&gt; cannot extend &lt;enum &#39;Color&#39;&gt;</span>

  680. </pre></div>

  681. </div>

  682. <p>But this is allowed:</p>

  683. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Foo</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  684. <span class="gp">... </span>    <span class="k">def</span> <span class="nf">some_behavior</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  685. <span class="gp">... </span>        <span class="k">pass</span>

  686. <span class="gp">...</span>

  687. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Bar</span><span class="p">(</span><span class="n">Foo</span><span class="p">):</span>

  688. <span class="gp">... </span>    <span class="n">HAPPY</span> <span class="o">=</span> <span class="mi">1</span>

  689. <span class="gp">... </span>    <span class="n">SAD</span> <span class="o">=</span> <span class="mi">2</span>

  690. <span class="gp">...</span>

  691. </pre></div>

  692. </div>

  693. <p>Allowing subclassing of enums that define members would lead to a violation of

  694. some important invariants of types and instances.  On the other hand, it makes

  695. sense to allow sharing some common behavior between a group of enumerations.

  696. (See <a class="reference internal" href="#orderedenum">OrderedEnum</a> for an example.)</p>

  697. </section>

  698. <section id="dataclass-support">

  699. <span id="enum-dataclass-support"></span><h2>Dataclass support<a class="headerlink" href="#dataclass-support" title="Link to this heading">¶</a></h2>

  700. <p>When inheriting from a <a class="reference internal" href="../library/dataclasses.html#dataclasses.dataclass" title="dataclasses.dataclass"><code class="xref py py-class docutils literal notranslate"><span class="pre">dataclass</span></code></a>,

  701. the <a class="reference internal" href="../library/enum.html#enum.Enum.__repr__" title="enum.Enum.__repr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__repr__()</span></code></a> omits the inherited class’ name.  For example:</p>

  702. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">dataclass</span><span class="p">,</span> <span class="n">field</span>

  703. <span class="gp">&gt;&gt;&gt; </span><span class="nd">@dataclass</span>

  704. <span class="gp">... </span><span class="k">class</span> <span class="nc">CreatureDataMixin</span><span class="p">:</span>

  705. <span class="gp">... </span>    <span class="n">size</span><span class="p">:</span> <span class="nb">str</span>

  706. <span class="gp">... </span>    <span class="n">legs</span><span class="p">:</span> <span class="nb">int</span>

  707. <span class="gp">... </span>    <span class="n">tail</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="n">field</span><span class="p">(</span><span class="nb">repr</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>

  708. <span class="gp">...</span>

  709. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Creature</span><span class="p">(</span><span class="n">CreatureDataMixin</span><span class="p">,</span> <span class="n">Enum</span><span class="p">):</span>

  710. <span class="gp">... </span>    <span class="n">BEETLE</span> <span class="o">=</span> <span class="s1">&#39;small&#39;</span><span class="p">,</span> <span class="mi">6</span>

  711. <span class="gp">... </span>    <span class="n">DOG</span> <span class="o">=</span> <span class="s1">&#39;medium&#39;</span><span class="p">,</span> <span class="mi">4</span>

  712. <span class="gp">...</span>

  713. <span class="gp">&gt;&gt;&gt; </span><span class="n">Creature</span><span class="o">.</span><span class="n">DOG</span>

  714. <span class="go">&lt;Creature.DOG: size=&#39;medium&#39;, legs=4&gt;</span>

  715. </pre></div>

  716. </div>

  717. <p>Use the <code class="xref py py-func docutils literal notranslate"><span class="pre">dataclass()</span></code> argument <code class="docutils literal notranslate"><span class="pre">repr=False</span></code>

  718. to use the standard <a class="reference internal" href="../library/functions.html#repr" title="repr"><code class="xref py py-func docutils literal notranslate"><span class="pre">repr()</span></code></a>.</p>

  719. <div class="versionchanged">

  720. <p><span class="versionmodified changed">Changed in version 3.12: </span>Only the dataclass fields are shown in the value area, not the dataclass’

  721. name.</p>

  722. </div>

  723. </section>

  724. <section id="pickling">

  725. <h2>Pickling<a class="headerlink" href="#pickling" title="Link to this heading">¶</a></h2>

  726. <p>Enumerations can be pickled and unpickled:</p>

  727. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">test.test_enum</span> <span class="kn">import</span> <span class="n">Fruit</span>

  728. <span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">pickle</span> <span class="kn">import</span> <span class="n">dumps</span><span class="p">,</span> <span class="n">loads</span>

  729. <span class="gp">&gt;&gt;&gt; </span><span class="n">Fruit</span><span class="o">.</span><span class="n">TOMATO</span> <span class="ow">is</span> <span class="n">loads</span><span class="p">(</span><span class="n">dumps</span><span class="p">(</span><span class="n">Fruit</span><span class="o">.</span><span class="n">TOMATO</span><span class="p">))</span>

  730. <span class="go">True</span>

  731. </pre></div>

  732. </div>

  733. <p>The usual restrictions for pickling apply: picklable enums must be defined in

  734. the top level of a module, since unpickling requires them to be importable

  735. from that module.</p>

  736. <div class="admonition note">

  737. <p class="admonition-title">Note</p>

  738. <p>With pickle protocol version 4 it is possible to easily pickle enums

  739. nested in other classes.</p>

  740. </div>

  741. <p>It is possible to modify how enum members are pickled/unpickled by defining

  742. <code class="xref py py-meth docutils literal notranslate"><span class="pre">__reduce_ex__()</span></code> in the enumeration class.  The default method is by-value,

  743. but enums with complicated values may want to use by-name:</p>

  744. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">enum</span>

  745. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">MyEnum</span><span class="p">(</span><span class="n">enum</span><span class="o">.</span><span class="n">Enum</span><span class="p">):</span>

  746. <span class="gp">... </span>    <span class="n">__reduce_ex__</span> <span class="o">=</span> <span class="n">enum</span><span class="o">.</span><span class="n">pickle_by_enum_name</span>

  747. </pre></div>

  748. </div>

  749. <div class="admonition note">

  750. <p class="admonition-title">Note</p>

  751. <p>Using by-name for flags is not recommended, as unnamed aliases will

  752. not unpickle.</p>

  753. </div>

  754. </section>

  755. <section id="functional-api">

  756. <h2>Functional API<a class="headerlink" href="#functional-api" title="Link to this heading">¶</a></h2>

  757. <p>The <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> class is callable, providing the following functional API:</p>

  758. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Animal</span> <span class="o">=</span> <span class="n">Enum</span><span class="p">(</span><span class="s1">&#39;Animal&#39;</span><span class="p">,</span> <span class="s1">&#39;ANT BEE CAT DOG&#39;</span><span class="p">)</span>

  759. <span class="gp">&gt;&gt;&gt; </span><span class="n">Animal</span>

  760. <span class="go">&lt;enum &#39;Animal&#39;&gt;</span>

  761. <span class="gp">&gt;&gt;&gt; </span><span class="n">Animal</span><span class="o">.</span><span class="n">ANT</span>

  762. <span class="go">&lt;Animal.ANT: 1&gt;</span>

  763. <span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">Animal</span><span class="p">)</span>

  764. <span class="go">[&lt;Animal.ANT: 1&gt;, &lt;Animal.BEE: 2&gt;, &lt;Animal.CAT: 3&gt;, &lt;Animal.DOG: 4&gt;]</span>

  765. </pre></div>

  766. </div>

  767. <p>The semantics of this API resemble <a class="reference internal" href="../library/collections.html#collections.namedtuple" title="collections.namedtuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">namedtuple</span></code></a>. The first

  768. argument of the call to <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> is the name of the enumeration.</p>

  769. <p>The second argument is the <em>source</em> of enumeration member names.  It can be a

  770. whitespace-separated string of names, a sequence of names, a sequence of

  771. 2-tuples with key/value pairs, or a mapping (e.g. dictionary) of names to

  772. values.  The last two options enable assigning arbitrary values to

  773. enumerations; the others auto-assign increasing integers starting with 1 (use

  774. the <code class="docutils literal notranslate"><span class="pre">start</span></code> parameter to specify a different starting value).  A

  775. new class derived from <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> is returned.  In other words, the above

  776. assignment to <code class="xref py py-class docutils literal notranslate"><span class="pre">Animal</span></code> is equivalent to:</p>

  777. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Animal</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  778. <span class="gp">... </span>    <span class="n">ANT</span> <span class="o">=</span> <span class="mi">1</span>

  779. <span class="gp">... </span>    <span class="n">BEE</span> <span class="o">=</span> <span class="mi">2</span>

  780. <span class="gp">... </span>    <span class="n">CAT</span> <span class="o">=</span> <span class="mi">3</span>

  781. <span class="gp">... </span>    <span class="n">DOG</span> <span class="o">=</span> <span class="mi">4</span>

  782. <span class="gp">...</span>

  783. </pre></div>

  784. </div>

  785. <p>The reason for defaulting to <code class="docutils literal notranslate"><span class="pre">1</span></code> as the starting number and not <code class="docutils literal notranslate"><span class="pre">0</span></code> is

  786. that <code class="docutils literal notranslate"><span class="pre">0</span></code> is <code class="docutils literal notranslate"><span class="pre">False</span></code> in a boolean sense, but by default enum members all

  787. evaluate to <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>

  788. <p>Pickling enums created with the functional API can be tricky as frame stack

  789. implementation details are used to try and figure out which module the

  790. enumeration is being created in (e.g. it will fail if you use a utility

  791. function in a separate module, and also may not work on IronPython or Jython).

  792. The solution is to specify the module name explicitly as follows:</p>

  793. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Animal</span> <span class="o">=</span> <span class="n">Enum</span><span class="p">(</span><span class="s1">&#39;Animal&#39;</span><span class="p">,</span> <span class="s1">&#39;ANT BEE CAT DOG&#39;</span><span class="p">,</span> <span class="n">module</span><span class="o">=</span><span class="vm">__name__</span><span class="p">)</span>

  794. </pre></div>

  795. </div>

  796. <div class="admonition warning">

  797. <p class="admonition-title">Warning</p>

  798. <p>If <code class="docutils literal notranslate"><span class="pre">module</span></code> is not supplied, and Enum cannot determine what it is,

  799. the new Enum members will not be unpicklable; to keep errors closer to

  800. the source, pickling will be disabled.</p>

  801. </div>

  802. <p>The new pickle protocol 4 also, in some circumstances, relies on

  803. <a class="reference internal" href="../library/stdtypes.html#definition.__qualname__" title="definition.__qualname__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__qualname__</span></code></a> being set to the location where pickle will be able

  804. to find the class.  For example, if the class was made available in class

  805. SomeData in the global scope:</p>

  806. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Animal</span> <span class="o">=</span> <span class="n">Enum</span><span class="p">(</span><span class="s1">&#39;Animal&#39;</span><span class="p">,</span> <span class="s1">&#39;ANT BEE CAT DOG&#39;</span><span class="p">,</span> <span class="n">qualname</span><span class="o">=</span><span class="s1">&#39;SomeData.Animal&#39;</span><span class="p">)</span>

  807. </pre></div>

  808. </div>

  809. <p>The complete signature is:</p>

  810. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Enum</span><span class="p">(</span>

  811.     <span class="n">value</span><span class="o">=</span><span class="s1">&#39;NewEnumName&#39;</span><span class="p">,</span>

  812.     <span class="n">names</span><span class="o">=&lt;...&gt;</span><span class="p">,</span>

  813.     <span class="o">*</span><span class="p">,</span>

  814.     <span class="n">module</span><span class="o">=</span><span class="s1">&#39;...&#39;</span><span class="p">,</span>

  815.     <span class="n">qualname</span><span class="o">=</span><span class="s1">&#39;...&#39;</span><span class="p">,</span>

  816.     <span class="nb">type</span><span class="o">=&lt;</span><span class="n">mixed</span><span class="o">-</span><span class="ow">in</span> <span class="n">class</span><span class="o">&gt;</span><span class="p">,</span>

  817.     <span class="n">start</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span>

  818.     <span class="p">)</span>

  819. </pre></div>

  820. </div>

  821. <ul>

  822. <li><p><em>value</em>: What the new enum class will record as its name.</p></li>

  823. <li><p><em>names</em>: The enum members.  This can be a whitespace- or comma-separated string

  824. (values will start at 1 unless otherwise specified):</p>

  825. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="s1">&#39;RED GREEN BLUE&#39;</span> <span class="o">|</span> <span class="s1">&#39;RED,GREEN,BLUE&#39;</span> <span class="o">|</span> <span class="s1">&#39;RED, GREEN, BLUE&#39;</span>

  826. </pre></div>

  827. </div>

  828. <p>or an iterator of names:</p>

  829. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="s1">&#39;RED&#39;</span><span class="p">,</span> <span class="s1">&#39;GREEN&#39;</span><span class="p">,</span> <span class="s1">&#39;BLUE&#39;</span><span class="p">]</span>

  830. </pre></div>

  831. </div>

  832. <p>or an iterator of (name, value) pairs:</p>

  833. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">[(</span><span class="s1">&#39;CYAN&#39;</span><span class="p">,</span> <span class="mi">4</span><span class="p">),</span> <span class="p">(</span><span class="s1">&#39;MAGENTA&#39;</span><span class="p">,</span> <span class="mi">5</span><span class="p">),</span> <span class="p">(</span><span class="s1">&#39;YELLOW&#39;</span><span class="p">,</span> <span class="mi">6</span><span class="p">)]</span>

  834. </pre></div>

  835. </div>

  836. <p>or a mapping:</p>

  837. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="s1">&#39;CHARTREUSE&#39;</span><span class="p">:</span> <span class="mi">7</span><span class="p">,</span> <span class="s1">&#39;SEA_GREEN&#39;</span><span class="p">:</span> <span class="mi">11</span><span class="p">,</span> <span class="s1">&#39;ROSEMARY&#39;</span><span class="p">:</span> <span class="mi">42</span><span class="p">}</span>

  838. </pre></div>

  839. </div>

  840. </li>

  841. <li><p><em>module</em>: name of module where new enum class can be found.</p></li>

  842. <li><p><em>qualname</em>: where in module new enum class can be found.</p></li>

  843. <li><p><em>type</em>: type to mix in to new enum class.</p></li>

  844. <li><p><em>start</em>: number to start counting at if only names are passed in.</p></li>

  845. </ul>

  846. <div class="versionchanged">

  847. <p><span class="versionmodified changed">Changed in version 3.5: </span>The <em>start</em> parameter was added.</p>

  848. </div>

  849. </section>

  850. <section id="derived-enumerations">

  851. <h2>Derived Enumerations<a class="headerlink" href="#derived-enumerations" title="Link to this heading">¶</a></h2>

  852. <section id="intenum">

  853. <h3>IntEnum<a class="headerlink" href="#intenum" title="Link to this heading">¶</a></h3>

  854. <p>The first variation of <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> that is provided is also a subclass of

  855. <a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>.  Members of an <a class="reference internal" href="../library/enum.html#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntEnum</span></code></a> can be compared to integers;

  856. by extension, integer enumerations of different types can also be compared

  857. to each other:</p>

  858. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">enum</span> <span class="kn">import</span> <span class="n">IntEnum</span>

  859. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Shape</span><span class="p">(</span><span class="n">IntEnum</span><span class="p">):</span>

  860. <span class="gp">... </span>    <span class="n">CIRCLE</span> <span class="o">=</span> <span class="mi">1</span>

  861. <span class="gp">... </span>    <span class="n">SQUARE</span> <span class="o">=</span> <span class="mi">2</span>

  862. <span class="gp">...</span>

  863. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Request</span><span class="p">(</span><span class="n">IntEnum</span><span class="p">):</span>

  864. <span class="gp">... </span>    <span class="n">POST</span> <span class="o">=</span> <span class="mi">1</span>

  865. <span class="gp">... </span>    <span class="n">GET</span> <span class="o">=</span> <span class="mi">2</span>

  866. <span class="gp">...</span>

  867. <span class="gp">&gt;&gt;&gt; </span><span class="n">Shape</span> <span class="o">==</span> <span class="mi">1</span>

  868. <span class="go">False</span>

  869. <span class="gp">&gt;&gt;&gt; </span><span class="n">Shape</span><span class="o">.</span><span class="n">CIRCLE</span> <span class="o">==</span> <span class="mi">1</span>

  870. <span class="go">True</span>

  871. <span class="gp">&gt;&gt;&gt; </span><span class="n">Shape</span><span class="o">.</span><span class="n">CIRCLE</span> <span class="o">==</span> <span class="n">Request</span><span class="o">.</span><span class="n">POST</span>

  872. <span class="go">True</span>

  873. </pre></div>

  874. </div>

  875. <p>However, they still can’t be compared to standard <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> enumerations:</p>

  876. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Shape</span><span class="p">(</span><span class="n">IntEnum</span><span class="p">):</span>

  877. <span class="gp">... </span>    <span class="n">CIRCLE</span> <span class="o">=</span> <span class="mi">1</span>

  878. <span class="gp">... </span>    <span class="n">SQUARE</span> <span class="o">=</span> <span class="mi">2</span>

  879. <span class="gp">...</span>

  880. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Color</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  881. <span class="gp">... </span>    <span class="n">RED</span> <span class="o">=</span> <span class="mi">1</span>

  882. <span class="gp">... </span>    <span class="n">GREEN</span> <span class="o">=</span> <span class="mi">2</span>

  883. <span class="gp">...</span>

  884. <span class="gp">&gt;&gt;&gt; </span><span class="n">Shape</span><span class="o">.</span><span class="n">CIRCLE</span> <span class="o">==</span> <span class="n">Color</span><span class="o">.</span><span class="n">RED</span>

  885. <span class="go">False</span>

  886. </pre></div>

  887. </div>

  888. <p><a class="reference internal" href="../library/enum.html#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntEnum</span></code></a> values behave like integers in other ways you’d expect:</p>

  889. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">int</span><span class="p">(</span><span class="n">Shape</span><span class="o">.</span><span class="n">CIRCLE</span><span class="p">)</span>

  890. <span class="go">1</span>

  891. <span class="gp">&gt;&gt;&gt; </span><span class="p">[</span><span class="s1">&#39;a&#39;</span><span class="p">,</span> <span class="s1">&#39;b&#39;</span><span class="p">,</span> <span class="s1">&#39;c&#39;</span><span class="p">][</span><span class="n">Shape</span><span class="o">.</span><span class="n">CIRCLE</span><span class="p">]</span>

  892. <span class="go">&#39;b&#39;</span>

  893. <span class="gp">&gt;&gt;&gt; </span><span class="p">[</span><span class="n">i</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">Shape</span><span class="o">.</span><span class="n">SQUARE</span><span class="p">)]</span>

  894. <span class="go">[0, 1]</span>

  895. </pre></div>

  896. </div>

  897. </section>

  898. <section id="strenum">

  899. <h3>StrEnum<a class="headerlink" href="#strenum" title="Link to this heading">¶</a></h3>

  900. <p>The second variation of <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> that is provided is also a subclass of

  901. <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>.  Members of a <a class="reference internal" href="../library/enum.html#enum.StrEnum" title="enum.StrEnum"><code class="xref py py-class docutils literal notranslate"><span class="pre">StrEnum</span></code></a> can be compared to strings;

  902. by extension, string enumerations of different types can also be compared

  903. to each other.</p>

  904. <div class="versionadded">

  905. <p><span class="versionmodified added">New in version 3.11.</span></p>

  906. </div>

  907. </section>

  908. <section id="intflag">

  909. <h3>IntFlag<a class="headerlink" href="#intflag" title="Link to this heading">¶</a></h3>

  910. <p>The next variation of <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> provided, <a class="reference internal" href="../library/enum.html#enum.IntFlag" title="enum.IntFlag"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntFlag</span></code></a>, is also based

  911. on <a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>.  The difference being <a class="reference internal" href="../library/enum.html#enum.IntFlag" title="enum.IntFlag"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntFlag</span></code></a> members can be combined

  912. using the bitwise operators (&amp;, |, ^, ~) and the result is still an

  913. <a class="reference internal" href="../library/enum.html#enum.IntFlag" title="enum.IntFlag"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntFlag</span></code></a> member, if possible.  Like <a class="reference internal" href="../library/enum.html#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntEnum</span></code></a>, <a class="reference internal" href="../library/enum.html#enum.IntFlag" title="enum.IntFlag"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntFlag</span></code></a>

  914. members are also integers and can be used wherever an <a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a> is used.</p>

  915. <div class="admonition note">

  916. <p class="admonition-title">Note</p>

  917. <p>Any operation on an <a class="reference internal" href="../library/enum.html#enum.IntFlag" title="enum.IntFlag"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntFlag</span></code></a> member besides the bit-wise operations will

  918. lose the <a class="reference internal" href="../library/enum.html#enum.IntFlag" title="enum.IntFlag"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntFlag</span></code></a> membership.</p>

  919. <p>Bit-wise operations that result in invalid <a class="reference internal" href="../library/enum.html#enum.IntFlag" title="enum.IntFlag"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntFlag</span></code></a> values will lose the

  920. <a class="reference internal" href="../library/enum.html#enum.IntFlag" title="enum.IntFlag"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntFlag</span></code></a> membership.  See <a class="reference internal" href="../library/enum.html#enum.FlagBoundary" title="enum.FlagBoundary"><code class="xref py py-class docutils literal notranslate"><span class="pre">FlagBoundary</span></code></a> for

  921. details.</p>

  922. </div>

  923. <div class="versionadded">

  924. <p><span class="versionmodified added">New in version 3.6.</span></p>

  925. </div>

  926. <div class="versionchanged">

  927. <p><span class="versionmodified changed">Changed in version 3.11.</span></p>

  928. </div>

  929. <p>Sample <a class="reference internal" href="../library/enum.html#enum.IntFlag" title="enum.IntFlag"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntFlag</span></code></a> class:</p>

  930. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">enum</span> <span class="kn">import</span> <span class="n">IntFlag</span>

  931. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Perm</span><span class="p">(</span><span class="n">IntFlag</span><span class="p">):</span>

  932. <span class="gp">... </span>    <span class="n">R</span> <span class="o">=</span> <span class="mi">4</span>

  933. <span class="gp">... </span>    <span class="n">W</span> <span class="o">=</span> <span class="mi">2</span>

  934. <span class="gp">... </span>    <span class="n">X</span> <span class="o">=</span> <span class="mi">1</span>

  935. <span class="gp">...</span>

  936. <span class="gp">&gt;&gt;&gt; </span><span class="n">Perm</span><span class="o">.</span><span class="n">R</span> <span class="o">|</span> <span class="n">Perm</span><span class="o">.</span><span class="n">W</span>

  937. <span class="go">&lt;Perm.R|W: 6&gt;</span>

  938. <span class="gp">&gt;&gt;&gt; </span><span class="n">Perm</span><span class="o">.</span><span class="n">R</span> <span class="o">+</span> <span class="n">Perm</span><span class="o">.</span><span class="n">W</span>

  939. <span class="go">6</span>

  940. <span class="gp">&gt;&gt;&gt; </span><span class="n">RW</span> <span class="o">=</span> <span class="n">Perm</span><span class="o">.</span><span class="n">R</span> <span class="o">|</span> <span class="n">Perm</span><span class="o">.</span><span class="n">W</span>

  941. <span class="gp">&gt;&gt;&gt; </span><span class="n">Perm</span><span class="o">.</span><span class="n">R</span> <span class="ow">in</span> <span class="n">RW</span>

  942. <span class="go">True</span>

  943. </pre></div>

  944. </div>

  945. <p>It is also possible to name the combinations:</p>

  946. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Perm</span><span class="p">(</span><span class="n">IntFlag</span><span class="p">):</span>

  947. <span class="gp">... </span>    <span class="n">R</span> <span class="o">=</span> <span class="mi">4</span>

  948. <span class="gp">... </span>    <span class="n">W</span> <span class="o">=</span> <span class="mi">2</span>

  949. <span class="gp">... </span>    <span class="n">X</span> <span class="o">=</span> <span class="mi">1</span>

  950. <span class="gp">... </span>    <span class="n">RWX</span> <span class="o">=</span> <span class="mi">7</span>

  951. <span class="gp">...</span>

  952. <span class="gp">&gt;&gt;&gt; </span><span class="n">Perm</span><span class="o">.</span><span class="n">RWX</span>

  953. <span class="go">&lt;Perm.RWX: 7&gt;</span>

  954. <span class="gp">&gt;&gt;&gt; </span><span class="o">~</span><span class="n">Perm</span><span class="o">.</span><span class="n">RWX</span>

  955. <span class="go">&lt;Perm: 0&gt;</span>

  956. <span class="gp">&gt;&gt;&gt; </span><span class="n">Perm</span><span class="p">(</span><span class="mi">7</span><span class="p">)</span>

  957. <span class="go">&lt;Perm.RWX: 7&gt;</span>

  958. </pre></div>

  959. </div>

  960. <div class="admonition note">

  961. <p class="admonition-title">Note</p>

  962. <p>Named combinations are considered aliases.  Aliases do not show up during

  963. iteration, but can be returned from by-value lookups.</p>

  964. </div>

  965. <div class="versionchanged">

  966. <p><span class="versionmodified changed">Changed in version 3.11.</span></p>

  967. </div>

  968. <p>Another important difference between <a class="reference internal" href="../library/enum.html#enum.IntFlag" title="enum.IntFlag"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntFlag</span></code></a> and <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> is that

  969. if no flags are set (the value is 0), its boolean evaluation is <a class="reference internal" href="../library/constants.html#False" title="False"><code class="xref py py-data docutils literal notranslate"><span class="pre">False</span></code></a>:</p>

  970. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Perm</span><span class="o">.</span><span class="n">R</span> <span class="o">&amp;</span> <span class="n">Perm</span><span class="o">.</span><span class="n">X</span>

  971. <span class="go">&lt;Perm: 0&gt;</span>

  972. <span class="gp">&gt;&gt;&gt; </span><span class="nb">bool</span><span class="p">(</span><span class="n">Perm</span><span class="o">.</span><span class="n">R</span> <span class="o">&amp;</span> <span class="n">Perm</span><span class="o">.</span><span class="n">X</span><span class="p">)</span>

  973. <span class="go">False</span>

  974. </pre></div>

  975. </div>

  976. <p>Because <a class="reference internal" href="../library/enum.html#enum.IntFlag" title="enum.IntFlag"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntFlag</span></code></a> members are also subclasses of <a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a> they can

  977. be combined with them (but may lose <a class="reference internal" href="../library/enum.html#enum.IntFlag" title="enum.IntFlag"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntFlag</span></code></a> membership:</p>

  978. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Perm</span><span class="o">.</span><span class="n">X</span> <span class="o">|</span> <span class="mi">4</span>

  979. <span class="go">&lt;Perm.R|X: 5&gt;</span>

  980. 

  981. <span class="gp">&gt;&gt;&gt; </span><span class="n">Perm</span><span class="o">.</span><span class="n">X</span> <span class="o">+</span> <span class="mi">8</span>

  982. <span class="go">9</span>

  983. </pre></div>

  984. </div>

  985. <div class="admonition note">

  986. <p class="admonition-title">Note</p>

  987. <p>The negation operator, <code class="docutils literal notranslate"><span class="pre">~</span></code>, always returns an <a class="reference internal" href="../library/enum.html#enum.IntFlag" title="enum.IntFlag"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntFlag</span></code></a> member with a

  988. positive value:</p>

  989. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="p">(</span><span class="o">~</span><span class="n">Perm</span><span class="o">.</span><span class="n">X</span><span class="p">)</span><span class="o">.</span><span class="n">value</span> <span class="o">==</span> <span class="p">(</span><span class="n">Perm</span><span class="o">.</span><span class="n">R</span><span class="o">|</span><span class="n">Perm</span><span class="o">.</span><span class="n">W</span><span class="p">)</span><span class="o">.</span><span class="n">value</span> <span class="o">==</span> <span class="mi">6</span>

  990. <span class="go">True</span>

  991. </pre></div>

  992. </div>

  993. </div>

  994. <p><a class="reference internal" href="../library/enum.html#enum.IntFlag" title="enum.IntFlag"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntFlag</span></code></a> members can also be iterated over:</p>

  995. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">RW</span><span class="p">)</span>

  996. <span class="go">[&lt;Perm.R: 4&gt;, &lt;Perm.W: 2&gt;]</span>

  997. </pre></div>

  998. </div>

  999. <div class="versionadded">

  1000. <p><span class="versionmodified added">New in version 3.11.</span></p>

  1001. </div>

  1002. </section>

  1003. <section id="flag">

  1004. <h3>Flag<a class="headerlink" href="#flag" title="Link to this heading">¶</a></h3>

  1005. <p>The last variation is <a class="reference internal" href="../library/enum.html#enum.Flag" title="enum.Flag"><code class="xref py py-class docutils literal notranslate"><span class="pre">Flag</span></code></a>.  Like <a class="reference internal" href="../library/enum.html#enum.IntFlag" title="enum.IntFlag"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntFlag</span></code></a>, <a class="reference internal" href="../library/enum.html#enum.Flag" title="enum.Flag"><code class="xref py py-class docutils literal notranslate"><span class="pre">Flag</span></code></a>

  1006. members can be combined using the bitwise operators (&amp;, |, ^, ~).  Unlike

  1007. <a class="reference internal" href="../library/enum.html#enum.IntFlag" title="enum.IntFlag"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntFlag</span></code></a>, they cannot be combined with, nor compared against, any

  1008. other <a class="reference internal" href="../library/enum.html#enum.Flag" title="enum.Flag"><code class="xref py py-class docutils literal notranslate"><span class="pre">Flag</span></code></a> enumeration, nor <a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>.  While it is possible to

  1009. specify the values directly it is recommended to use <a class="reference internal" href="../library/enum.html#enum.auto" title="enum.auto"><code class="xref py py-class docutils literal notranslate"><span class="pre">auto</span></code></a> as the

  1010. value and let <a class="reference internal" href="../library/enum.html#enum.Flag" title="enum.Flag"><code class="xref py py-class docutils literal notranslate"><span class="pre">Flag</span></code></a> select an appropriate value.</p>

  1011. <div class="versionadded">

  1012. <p><span class="versionmodified added">New in version 3.6.</span></p>

  1013. </div>

  1014. <p>Like <a class="reference internal" href="../library/enum.html#enum.IntFlag" title="enum.IntFlag"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntFlag</span></code></a>, if a combination of <a class="reference internal" href="../library/enum.html#enum.Flag" title="enum.Flag"><code class="xref py py-class docutils literal notranslate"><span class="pre">Flag</span></code></a> members results in no

  1015. flags being set, the boolean evaluation is <a class="reference internal" href="../library/constants.html#False" title="False"><code class="xref py py-data docutils literal notranslate"><span class="pre">False</span></code></a>:</p>

  1016. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">enum</span> <span class="kn">import</span> <span class="n">Flag</span><span class="p">,</span> <span class="n">auto</span>

  1017. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Color</span><span class="p">(</span><span class="n">Flag</span><span class="p">):</span>

  1018. <span class="gp">... </span>    <span class="n">RED</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  1019. <span class="gp">... </span>    <span class="n">BLUE</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  1020. <span class="gp">... </span>    <span class="n">GREEN</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  1021. <span class="gp">...</span>

  1022. <span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="o">.</span><span class="n">RED</span> <span class="o">&amp;</span> <span class="n">Color</span><span class="o">.</span><span class="n">GREEN</span>

  1023. <span class="go">&lt;Color: 0&gt;</span>

  1024. <span class="gp">&gt;&gt;&gt; </span><span class="nb">bool</span><span class="p">(</span><span class="n">Color</span><span class="o">.</span><span class="n">RED</span> <span class="o">&amp;</span> <span class="n">Color</span><span class="o">.</span><span class="n">GREEN</span><span class="p">)</span>

  1025. <span class="go">False</span>

  1026. </pre></div>

  1027. </div>

  1028. <p>Individual flags should have values that are powers of two (1, 2, 4, 8, …),

  1029. while combinations of flags will not:</p>

  1030. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Color</span><span class="p">(</span><span class="n">Flag</span><span class="p">):</span>

  1031. <span class="gp">... </span>    <span class="n">RED</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  1032. <span class="gp">... </span>    <span class="n">BLUE</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  1033. <span class="gp">... </span>    <span class="n">GREEN</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  1034. <span class="gp">... </span>    <span class="n">WHITE</span> <span class="o">=</span> <span class="n">RED</span> <span class="o">|</span> <span class="n">BLUE</span> <span class="o">|</span> <span class="n">GREEN</span>

  1035. <span class="gp">...</span>

  1036. <span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="o">.</span><span class="n">WHITE</span>

  1037. <span class="go">&lt;Color.WHITE: 7&gt;</span>

  1038. </pre></div>

  1039. </div>

  1040. <p>Giving a name to the “no flags set” condition does not change its boolean

  1041. value:</p>

  1042. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Color</span><span class="p">(</span><span class="n">Flag</span><span class="p">):</span>

  1043. <span class="gp">... </span>    <span class="n">BLACK</span> <span class="o">=</span> <span class="mi">0</span>

  1044. <span class="gp">... </span>    <span class="n">RED</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  1045. <span class="gp">... </span>    <span class="n">BLUE</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  1046. <span class="gp">... </span>    <span class="n">GREEN</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  1047. <span class="gp">...</span>

  1048. <span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="o">.</span><span class="n">BLACK</span>

  1049. <span class="go">&lt;Color.BLACK: 0&gt;</span>

  1050. <span class="gp">&gt;&gt;&gt; </span><span class="nb">bool</span><span class="p">(</span><span class="n">Color</span><span class="o">.</span><span class="n">BLACK</span><span class="p">)</span>

  1051. <span class="go">False</span>

  1052. </pre></div>

  1053. </div>

  1054. <p><a class="reference internal" href="../library/enum.html#enum.Flag" title="enum.Flag"><code class="xref py py-class docutils literal notranslate"><span class="pre">Flag</span></code></a> members can also be iterated over:</p>

  1055. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">purple</span> <span class="o">=</span> <span class="n">Color</span><span class="o">.</span><span class="n">RED</span> <span class="o">|</span> <span class="n">Color</span><span class="o">.</span><span class="n">BLUE</span>

  1056. <span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">purple</span><span class="p">)</span>

  1057. <span class="go">[&lt;Color.RED: 1&gt;, &lt;Color.BLUE: 2&gt;]</span>

  1058. </pre></div>

  1059. </div>

  1060. <div class="versionadded">

  1061. <p><span class="versionmodified added">New in version 3.11.</span></p>

  1062. </div>

  1063. <div class="admonition note">

  1064. <p class="admonition-title">Note</p>

  1065. <p>For the majority of new code, <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> and <a class="reference internal" href="../library/enum.html#enum.Flag" title="enum.Flag"><code class="xref py py-class docutils literal notranslate"><span class="pre">Flag</span></code></a> are strongly

  1066. recommended, since <a class="reference internal" href="../library/enum.html#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntEnum</span></code></a> and <a class="reference internal" href="../library/enum.html#enum.IntFlag" title="enum.IntFlag"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntFlag</span></code></a> break some

  1067. semantic promises of an enumeration (by being comparable to integers, and

  1068. thus by transitivity to other unrelated enumerations).  <a class="reference internal" href="../library/enum.html#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntEnum</span></code></a>

  1069. and <a class="reference internal" href="../library/enum.html#enum.IntFlag" title="enum.IntFlag"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntFlag</span></code></a> should be used only in cases where <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> and

  1070. <a class="reference internal" href="../library/enum.html#enum.Flag" title="enum.Flag"><code class="xref py py-class docutils literal notranslate"><span class="pre">Flag</span></code></a> will not do; for example, when integer constants are replaced

  1071. with enumerations, or for interoperability with other systems.</p>

  1072. </div>

  1073. </section>

  1074. <section id="others">

  1075. <h3>Others<a class="headerlink" href="#others" title="Link to this heading">¶</a></h3>

  1076. <p>While <a class="reference internal" href="../library/enum.html#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntEnum</span></code></a> is part of the <a class="reference internal" href="../library/enum.html#module-enum" title="enum: Implementation of an enumeration class."><code class="xref py py-mod docutils literal notranslate"><span class="pre">enum</span></code></a> module, it would be very

  1077. simple to implement independently:</p>

  1078. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">IntEnum</span><span class="p">(</span><span class="nb">int</span><span class="p">,</span> <span class="n">Enum</span><span class="p">):</span>

  1079.     <span class="k">pass</span>

  1080. </pre></div>

  1081. </div>

  1082. <p>This demonstrates how similar derived enumerations can be defined; for example

  1083. a <code class="xref py py-class docutils literal notranslate"><span class="pre">FloatEnum</span></code> that mixes in <a class="reference internal" href="../library/functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a> instead of <a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>.</p>

  1084. <p>Some rules:</p>

  1085. <ol class="arabic simple">

  1086. <li><p>When subclassing <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a>, mix-in types must appear before

  1087. <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> itself in the sequence of bases, as in the <a class="reference internal" href="../library/enum.html#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntEnum</span></code></a>

  1088. example above.</p></li>

  1089. <li><p>Mix-in types must be subclassable. For example, <a class="reference internal" href="../library/functions.html#bool" title="bool"><code class="xref py py-class docutils literal notranslate"><span class="pre">bool</span></code></a> and

  1090. <a class="reference internal" href="../library/stdtypes.html#range" title="range"><code class="xref py py-class docutils literal notranslate"><span class="pre">range</span></code></a> are not subclassable and will throw an error during Enum

  1091. creation if used as the mix-in type.</p></li>

  1092. <li><p>While <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> can have members of any type, once you mix in an

  1093. additional type, all the members must have values of that type, e.g.

  1094. <a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a> above.  This restriction does not apply to mix-ins which only

  1095. add methods and don’t specify another type.</p></li>

  1096. <li><p>When another data type is mixed in, the <code class="xref py py-attr docutils literal notranslate"><span class="pre">value</span></code> attribute is <em>not the

  1097. same</em> as the enum member itself, although it is equivalent and will compare

  1098. equal.</p></li>

  1099. <li><p>A <code class="docutils literal notranslate"><span class="pre">data</span> <span class="pre">type</span></code> is a mixin that defines <code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code>, or a

  1100. <a class="reference internal" href="../library/dataclasses.html#dataclasses.dataclass" title="dataclasses.dataclass"><code class="xref py py-class docutils literal notranslate"><span class="pre">dataclass</span></code></a></p></li>

  1101. <li><p>%-style formatting:  <code class="docutils literal notranslate"><span class="pre">%s</span></code> and <code class="docutils literal notranslate"><span class="pre">%r</span></code> call the <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> class’s

  1102. <code class="xref py py-meth docutils literal notranslate"><span class="pre">__str__()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">__repr__()</span></code> respectively; other codes (such as

  1103. <code class="docutils literal notranslate"><span class="pre">%i</span></code> or <code class="docutils literal notranslate"><span class="pre">%h</span></code> for IntEnum) treat the enum member as its mixed-in type.</p></li>

  1104. <li><p><a class="reference internal" href="../reference/lexical_analysis.html#f-strings"><span class="std std-ref">Formatted string literals</span></a>, <a class="reference internal" href="../library/stdtypes.html#str.format" title="str.format"><code class="xref py py-meth docutils literal notranslate"><span class="pre">str.format()</span></code></a>,

  1105. and <a class="reference internal" href="../library/functions.html#format" title="format"><code class="xref py py-func docutils literal notranslate"><span class="pre">format()</span></code></a> will use the enum’s <code class="xref py py-meth docutils literal notranslate"><span class="pre">__str__()</span></code> method.</p></li>

  1106. </ol>

  1107. <div class="admonition note">

  1108. <p class="admonition-title">Note</p>

  1109. <p>Because <a class="reference internal" href="../library/enum.html#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntEnum</span></code></a>, <a class="reference internal" href="../library/enum.html#enum.IntFlag" title="enum.IntFlag"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntFlag</span></code></a>, and <a class="reference internal" href="../library/enum.html#enum.StrEnum" title="enum.StrEnum"><code class="xref py py-class docutils literal notranslate"><span class="pre">StrEnum</span></code></a> are

  1110. designed to be drop-in replacements for existing constants, their

  1111. <code class="xref py py-meth docutils literal notranslate"><span class="pre">__str__()</span></code> method has been reset to their data types’

  1112. <code class="xref py py-meth docutils literal notranslate"><span class="pre">__str__()</span></code> method.</p>

  1113. </div>

  1114. </section>

  1115. </section>

  1116. <section id="when-to-use-new-vs-init">

  1117. <span id="new-vs-init"></span><h2>When to use <code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code> vs. <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code><a class="headerlink" href="#when-to-use-new-vs-init" title="Link to this heading">¶</a></h2>

  1118. <p><code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code> must be used whenever you want to customize the actual value of

  1119. the <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> member.  Any other modifications may go in either

  1120. <code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code> or <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code>, with <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> being preferred.</p>

  1121. <p>For example, if you want to pass several items to the constructor, but only

  1122. want one of them to be the value:</p>

  1123. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Coordinate</span><span class="p">(</span><span class="nb">bytes</span><span class="p">,</span> <span class="n">Enum</span><span class="p">):</span>

  1124. <span class="gp">... </span><span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>

  1125. <span class="gp">... </span><span class="sd">    Coordinate with binary codes that can be indexed by the int code.</span>

  1126. <span class="gp">... </span><span class="sd">    &quot;&quot;&quot;</span>

  1127. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__new__</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">label</span><span class="p">,</span> <span class="n">unit</span><span class="p">):</span>

  1128. <span class="gp">... </span>        <span class="n">obj</span> <span class="o">=</span> <span class="nb">bytes</span><span class="o">.</span><span class="fm">__new__</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="p">[</span><span class="n">value</span><span class="p">])</span>

  1129. <span class="gp">... </span>        <span class="n">obj</span><span class="o">.</span><span class="n">_value_</span> <span class="o">=</span> <span class="n">value</span>

  1130. <span class="gp">... </span>        <span class="n">obj</span><span class="o">.</span><span class="n">label</span> <span class="o">=</span> <span class="n">label</span>

  1131. <span class="gp">... </span>        <span class="n">obj</span><span class="o">.</span><span class="n">unit</span> <span class="o">=</span> <span class="n">unit</span>

  1132. <span class="gp">... </span>        <span class="k">return</span> <span class="n">obj</span>

  1133. <span class="gp">... </span>    <span class="n">PX</span> <span class="o">=</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="s1">&#39;P.X&#39;</span><span class="p">,</span> <span class="s1">&#39;km&#39;</span><span class="p">)</span>

  1134. <span class="gp">... </span>    <span class="n">PY</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="s1">&#39;P.Y&#39;</span><span class="p">,</span> <span class="s1">&#39;km&#39;</span><span class="p">)</span>

  1135. <span class="gp">... </span>    <span class="n">VX</span> <span class="o">=</span> <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="s1">&#39;V.X&#39;</span><span class="p">,</span> <span class="s1">&#39;km/s&#39;</span><span class="p">)</span>

  1136. <span class="gp">... </span>    <span class="n">VY</span> <span class="o">=</span> <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="s1">&#39;V.Y&#39;</span><span class="p">,</span> <span class="s1">&#39;km/s&#39;</span><span class="p">)</span>

  1137. <span class="gp">...</span>

  1138. 

  1139. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">Coordinate</span><span class="p">[</span><span class="s1">&#39;PY&#39;</span><span class="p">])</span>

  1140. <span class="go">Coordinate.PY</span>

  1141. 

  1142. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">Coordinate</span><span class="p">(</span><span class="mi">3</span><span class="p">))</span>

  1143. <span class="go">Coordinate.VY</span>

  1144. </pre></div>

  1145. </div>

  1146. <div class="admonition warning">

  1147. <p class="admonition-title">Warning</p>

  1148. <p><em>Do not</em> call <code class="docutils literal notranslate"><span class="pre">super().__new__()</span></code>, as the lookup-only <code class="docutils literal notranslate"><span class="pre">__new__</span></code> is the one

  1149. that is found; instead, use the data type directly.</p>

  1150. </div>

  1151. <section id="finer-points">

  1152. <h3>Finer Points<a class="headerlink" href="#finer-points" title="Link to this heading">¶</a></h3>

  1153. <section id="supported-dunder-names">

  1154. <h4>Supported <code class="docutils literal notranslate"><span class="pre">__dunder__</span></code> names<a class="headerlink" href="#supported-dunder-names" title="Link to this heading">¶</a></h4>

  1155. <p><code class="xref py py-attr docutils literal notranslate"><span class="pre">__members__</span></code> is a read-only ordered mapping of <code class="docutils literal notranslate"><span class="pre">member_name</span></code>:<code class="docutils literal notranslate"><span class="pre">member</span></code>

  1156. items.  It is only available on the class.</p>

  1157. <p><code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code>, if specified, must create and return the enum members; it is

  1158. also a very good idea to set the member’s <code class="xref py py-attr docutils literal notranslate"><span class="pre">_value_</span></code> appropriately.  Once

  1159. all the members are created it is no longer used.</p>

  1160. </section>

  1161. <section id="supported-sunder-names">

  1162. <h4>Supported <code class="docutils literal notranslate"><span class="pre">_sunder_</span></code> names<a class="headerlink" href="#supported-sunder-names" title="Link to this heading">¶</a></h4>

  1163. <ul class="simple">

  1164. <li><p><code class="docutils literal notranslate"><span class="pre">_name_</span></code> – name of the member</p></li>

  1165. <li><p><code class="docutils literal notranslate"><span class="pre">_value_</span></code> – value of the member; can be set / modified in <code class="docutils literal notranslate"><span class="pre">__new__</span></code></p></li>

  1166. <li><p><code class="docutils literal notranslate"><span class="pre">_missing_</span></code> – a lookup function used when a value is not found; may be

  1167. overridden</p></li>

  1168. <li><p><code class="docutils literal notranslate"><span class="pre">_ignore_</span></code> – a list of names, either as a <a class="reference internal" href="../library/stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a> or a <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>,

  1169. that will not be transformed into members, and will be removed from the final

  1170. class</p></li>

  1171. <li><p><code class="docutils literal notranslate"><span class="pre">_order_</span></code> – used in Python 2/3 code to ensure member order is consistent

  1172. (class attribute, removed during class creation)</p></li>

  1173. <li><p><code class="docutils literal notranslate"><span class="pre">_generate_next_value_</span></code> – used by the <a class="reference internal" href="#functional-api">Functional API</a> and by

  1174. <a class="reference internal" href="../library/enum.html#enum.auto" title="enum.auto"><code class="xref py py-class docutils literal notranslate"><span class="pre">auto</span></code></a> to get an appropriate value for an enum member; may be

  1175. overridden</p></li>

  1176. </ul>

  1177. <div class="admonition note">

  1178. <p class="admonition-title">Note</p>

  1179. <p>For standard <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> classes the next value chosen is the last value seen

  1180. incremented by one.</p>

  1181. <p>For <a class="reference internal" href="../library/enum.html#enum.Flag" title="enum.Flag"><code class="xref py py-class docutils literal notranslate"><span class="pre">Flag</span></code></a> classes the next value chosen will be the next highest

  1182. power-of-two, regardless of the last value seen.</p>

  1183. </div>

  1184. <div class="versionadded">

  1185. <p><span class="versionmodified added">New in version 3.6: </span><code class="docutils literal notranslate"><span class="pre">_missing_</span></code>, <code class="docutils literal notranslate"><span class="pre">_order_</span></code>, <code class="docutils literal notranslate"><span class="pre">_generate_next_value_</span></code></p>

  1186. </div>

  1187. <div class="versionadded">

  1188. <p><span class="versionmodified added">New in version 3.7: </span><code class="docutils literal notranslate"><span class="pre">_ignore_</span></code></p>

  1189. </div>

  1190. <p>To help keep Python 2 / Python 3 code in sync an <code class="xref py py-attr docutils literal notranslate"><span class="pre">_order_</span></code> attribute can

  1191. be provided.  It will be checked against the actual order of the enumeration

  1192. and raise an error if the two do not match:</p>

  1193. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Color</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  1194. <span class="gp">... </span>    <span class="n">_order_</span> <span class="o">=</span> <span class="s1">&#39;RED GREEN BLUE&#39;</span>

  1195. <span class="gp">... </span>    <span class="n">RED</span> <span class="o">=</span> <span class="mi">1</span>

  1196. <span class="gp">... </span>    <span class="n">BLUE</span> <span class="o">=</span> <span class="mi">3</span>

  1197. <span class="gp">... </span>    <span class="n">GREEN</span> <span class="o">=</span> <span class="mi">2</span>

  1198. <span class="gp">...</span>

  1199. <span class="gt">Traceback (most recent call last):</span>

  1200. <span class="c">...</span>

  1201. <span class="gr">TypeError</span>: <span class="n">member order does not match _order_:</span>

  1202. <span class="x">  [&#39;RED&#39;, &#39;BLUE&#39;, &#39;GREEN&#39;]</span>

  1203. <span class="x">  [&#39;RED&#39;, &#39;GREEN&#39;, &#39;BLUE&#39;]</span>

  1204. </pre></div>

  1205. </div>

  1206. <div class="admonition note">

  1207. <p class="admonition-title">Note</p>

  1208. <p>In Python 2 code the <code class="xref py py-attr docutils literal notranslate"><span class="pre">_order_</span></code> attribute is necessary as definition

  1209. order is lost before it can be recorded.</p>

  1210. </div>

  1211. </section>

  1212. <section id="private-names">

  1213. <h4>_Private__names<a class="headerlink" href="#private-names" title="Link to this heading">¶</a></h4>

  1214. <p><a class="reference internal" href="../reference/expressions.html#private-name-mangling"><span class="std std-ref">Private names</span></a> are not converted to enum members,

  1215. but remain normal attributes.</p>

  1216. <div class="versionchanged">

  1217. <p><span class="versionmodified changed">Changed in version 3.11.</span></p>

  1218. </div>

  1219. </section>

  1220. <section id="enum-member-type">

  1221. <h4><code class="docutils literal notranslate"><span class="pre">Enum</span></code> member type<a class="headerlink" href="#enum-member-type" title="Link to this heading">¶</a></h4>

  1222. <p>Enum members are instances of their enum class, and are normally accessed as

  1223. <code class="docutils literal notranslate"><span class="pre">EnumClass.member</span></code>.  In certain situations, such as writing custom enum

  1224. behavior, being able to access one member directly from another is useful,

  1225. and is supported; however, in order to avoid name clashes between member names

  1226. and attributes/methods from mixed-in classes, upper-case names are strongly

  1227. recommended.</p>

  1228. <div class="versionchanged">

  1229. <p><span class="versionmodified changed">Changed in version 3.5.</span></p>

  1230. </div>

  1231. </section>

  1232. <section id="creating-members-that-are-mixed-with-other-data-types">

  1233. <h4>Creating members that are mixed with other data types<a class="headerlink" href="#creating-members-that-are-mixed-with-other-data-types" title="Link to this heading">¶</a></h4>

  1234. <p>When subclassing other data types, such as <a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a> or <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>, with

  1235. an <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a>, all values after the <code class="docutils literal notranslate"><span class="pre">=</span></code> are passed to that data type’s

  1236. constructor.  For example:</p>

  1237. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">MyEnum</span><span class="p">(</span><span class="n">IntEnum</span><span class="p">):</span>      <span class="c1"># help(int) -&gt; int(x, base=10) -&gt; integer</span>

  1238. <span class="gp">... </span>    <span class="n">example</span> <span class="o">=</span> <span class="s1">&#39;11&#39;</span><span class="p">,</span> <span class="mi">16</span>      <span class="c1"># so x=&#39;11&#39; and base=16</span>

  1239. <span class="gp">...</span>

  1240. <span class="gp">&gt;&gt;&gt; </span><span class="n">MyEnum</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">value</span>        <span class="c1"># and hex(11) is...</span>

  1241. <span class="go">17</span>

  1242. </pre></div>

  1243. </div>

  1244. </section>

  1245. <section id="boolean-value-of-enum-classes-and-members">

  1246. <h4>Boolean value of <code class="docutils literal notranslate"><span class="pre">Enum</span></code> classes and members<a class="headerlink" href="#boolean-value-of-enum-classes-and-members" title="Link to this heading">¶</a></h4>

  1247. <p>Enum classes that are mixed with non-<a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> types (such as

  1248. <a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>, <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>, etc.) are evaluated according to the mixed-in

  1249. type’s rules; otherwise, all members evaluate as <a class="reference internal" href="../library/constants.html#True" title="True"><code class="xref py py-data docutils literal notranslate"><span class="pre">True</span></code></a>.  To make your

  1250. own enum’s boolean evaluation depend on the member’s value add the following to

  1251. your class:</p>

  1252. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="fm">__bool__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  1253.     <span class="k">return</span> <span class="nb">bool</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">value</span><span class="p">)</span>

  1254. </pre></div>

  1255. </div>

  1256. <p>Plain <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> classes always evaluate as <a class="reference internal" href="../library/constants.html#True" title="True"><code class="xref py py-data docutils literal notranslate"><span class="pre">True</span></code></a>.</p>

  1257. </section>

  1258. <section id="enum-classes-with-methods">

  1259. <h4><code class="docutils literal notranslate"><span class="pre">Enum</span></code> classes with methods<a class="headerlink" href="#enum-classes-with-methods" title="Link to this heading">¶</a></h4>

  1260. <p>If you give your enum subclass extra methods, like the <a class="reference internal" href="#planet">Planet</a>

  1261. class below, those methods will show up in a <a class="reference internal" href="../library/functions.html#dir" title="dir"><code class="xref py py-func docutils literal notranslate"><span class="pre">dir()</span></code></a> of the member,

  1262. but not of the class:</p>

  1263. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">dir</span><span class="p">(</span><span class="n">Planet</span><span class="p">)</span>                         

  1264. <span class="go">[&#39;EARTH&#39;, &#39;JUPITER&#39;, &#39;MARS&#39;, &#39;MERCURY&#39;, &#39;NEPTUNE&#39;, &#39;SATURN&#39;, &#39;URANUS&#39;, &#39;VENUS&#39;, &#39;__class__&#39;, &#39;__doc__&#39;, &#39;__members__&#39;, &#39;__module__&#39;]</span>

  1265. <span class="gp">&gt;&gt;&gt; </span><span class="nb">dir</span><span class="p">(</span><span class="n">Planet</span><span class="o">.</span><span class="n">EARTH</span><span class="p">)</span>                   

  1266. <span class="go">[&#39;__class__&#39;, &#39;__doc__&#39;, &#39;__module__&#39;, &#39;mass&#39;, &#39;name&#39;, &#39;radius&#39;, &#39;surface_gravity&#39;, &#39;value&#39;]</span>

  1267. </pre></div>

  1268. </div>

  1269. </section>

  1270. <section id="combining-members-of-flag">

  1271. <h4>Combining members of <code class="docutils literal notranslate"><span class="pre">Flag</span></code><a class="headerlink" href="#combining-members-of-flag" title="Link to this heading">¶</a></h4>

  1272. <p>Iterating over a combination of <a class="reference internal" href="../library/enum.html#enum.Flag" title="enum.Flag"><code class="xref py py-class docutils literal notranslate"><span class="pre">Flag</span></code></a> members will only return the members that

  1273. are comprised of a single bit:</p>

  1274. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Color</span><span class="p">(</span><span class="n">Flag</span><span class="p">):</span>

  1275. <span class="gp">... </span>    <span class="n">RED</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  1276. <span class="gp">... </span>    <span class="n">GREEN</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  1277. <span class="gp">... </span>    <span class="n">BLUE</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  1278. <span class="gp">... </span>    <span class="n">MAGENTA</span> <span class="o">=</span> <span class="n">RED</span> <span class="o">|</span> <span class="n">BLUE</span>

  1279. <span class="gp">... </span>    <span class="n">YELLOW</span> <span class="o">=</span> <span class="n">RED</span> <span class="o">|</span> <span class="n">GREEN</span>

  1280. <span class="gp">... </span>    <span class="n">CYAN</span> <span class="o">=</span> <span class="n">GREEN</span> <span class="o">|</span> <span class="n">BLUE</span>

  1281. <span class="gp">...</span>

  1282. <span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>  <span class="c1"># named combination</span>

  1283. <span class="go">&lt;Color.YELLOW: 3&gt;</span>

  1284. <span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="p">(</span><span class="mi">7</span><span class="p">)</span>      <span class="c1"># not named combination</span>

  1285. <span class="go">&lt;Color.RED|GREEN|BLUE: 7&gt;</span>

  1286. </pre></div>

  1287. </div>

  1288. </section>

  1289. <section id="flag-and-intflag-minutia">

  1290. <h4><code class="docutils literal notranslate"><span class="pre">Flag</span></code> and <code class="docutils literal notranslate"><span class="pre">IntFlag</span></code> minutia<a class="headerlink" href="#flag-and-intflag-minutia" title="Link to this heading">¶</a></h4>

  1291. <p>Using the following snippet for our examples:</p>

  1292. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Color</span><span class="p">(</span><span class="n">IntFlag</span><span class="p">):</span>

  1293. <span class="gp">... </span>    <span class="n">BLACK</span> <span class="o">=</span> <span class="mi">0</span>

  1294. <span class="gp">... </span>    <span class="n">RED</span> <span class="o">=</span> <span class="mi">1</span>

  1295. <span class="gp">... </span>    <span class="n">GREEN</span> <span class="o">=</span> <span class="mi">2</span>

  1296. <span class="gp">... </span>    <span class="n">BLUE</span> <span class="o">=</span> <span class="mi">4</span>

  1297. <span class="gp">... </span>    <span class="n">PURPLE</span> <span class="o">=</span> <span class="n">RED</span> <span class="o">|</span> <span class="n">BLUE</span>

  1298. <span class="gp">... </span>    <span class="n">WHITE</span> <span class="o">=</span> <span class="n">RED</span> <span class="o">|</span> <span class="n">GREEN</span> <span class="o">|</span> <span class="n">BLUE</span>

  1299. <span class="gp">...</span>

  1300. </pre></div>

  1301. </div>

  1302. <p>the following are true:</p>

  1303. <ul>

  1304. <li><p>single-bit flags are canonical</p></li>

  1305. <li><p>multi-bit and zero-bit flags are aliases</p></li>

  1306. <li><p>only canonical flags are returned during iteration:</p>

  1307. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">Color</span><span class="o">.</span><span class="n">WHITE</span><span class="p">)</span>

  1308. <span class="go">[&lt;Color.RED: 1&gt;, &lt;Color.GREEN: 2&gt;, &lt;Color.BLUE: 4&gt;]</span>

  1309. </pre></div>

  1310. </div>

  1311. </li>

  1312. <li><p>negating a flag or flag set returns a new flag/flag set with the

  1313. corresponding positive integer value:</p>

  1314. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="o">.</span><span class="n">BLUE</span>

  1315. <span class="go">&lt;Color.BLUE: 4&gt;</span>

  1316. 

  1317. <span class="gp">&gt;&gt;&gt; </span><span class="o">~</span><span class="n">Color</span><span class="o">.</span><span class="n">BLUE</span>

  1318. <span class="go">&lt;Color.RED|GREEN: 3&gt;</span>

  1319. </pre></div>

  1320. </div>

  1321. </li>

  1322. <li><p>names of pseudo-flags are constructed from their members’ names:</p>

  1323. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="p">(</span><span class="n">Color</span><span class="o">.</span><span class="n">RED</span> <span class="o">|</span> <span class="n">Color</span><span class="o">.</span><span class="n">GREEN</span><span class="p">)</span><span class="o">.</span><span class="n">name</span>

  1324. <span class="go">&#39;RED|GREEN&#39;</span>

  1325. </pre></div>

  1326. </div>

  1327. </li>

  1328. <li><p>multi-bit flags, aka aliases, can be returned from operations:</p>

  1329. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="o">.</span><span class="n">RED</span> <span class="o">|</span> <span class="n">Color</span><span class="o">.</span><span class="n">BLUE</span>

  1330. <span class="go">&lt;Color.PURPLE: 5&gt;</span>

  1331. 

  1332. <span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="p">(</span><span class="mi">7</span><span class="p">)</span>  <span class="c1"># or Color(-1)</span>

  1333. <span class="go">&lt;Color.WHITE: 7&gt;</span>

  1334. 

  1335. <span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>

  1336. <span class="go">&lt;Color.BLACK: 0&gt;</span>

  1337. </pre></div>

  1338. </div>

  1339. </li>

  1340. <li><p>membership / containment checking: zero-valued flags are always considered

  1341. to be contained:</p>

  1342. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="o">.</span><span class="n">BLACK</span> <span class="ow">in</span> <span class="n">Color</span><span class="o">.</span><span class="n">WHITE</span>

  1343. <span class="go">True</span>

  1344. </pre></div>

  1345. </div>

  1346. <p>otherwise, only if all bits of one flag are in the other flag will True

  1347. be returned:</p>

  1348. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="o">.</span><span class="n">PURPLE</span> <span class="ow">in</span> <span class="n">Color</span><span class="o">.</span><span class="n">WHITE</span>

  1349. <span class="go">True</span>

  1350. 

  1351. <span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="o">.</span><span class="n">GREEN</span> <span class="ow">in</span> <span class="n">Color</span><span class="o">.</span><span class="n">PURPLE</span>

  1352. <span class="go">False</span>

  1353. </pre></div>

  1354. </div>

  1355. </li>

  1356. </ul>

  1357. <p>There is a new boundary mechanism that controls how out-of-range / invalid

  1358. bits are handled: <code class="docutils literal notranslate"><span class="pre">STRICT</span></code>, <code class="docutils literal notranslate"><span class="pre">CONFORM</span></code>, <code class="docutils literal notranslate"><span class="pre">EJECT</span></code>, and <code class="docutils literal notranslate"><span class="pre">KEEP</span></code>:</p>

  1359. <ul class="simple">

  1360. <li><p>STRICT –&gt; raises an exception when presented with invalid values</p></li>

  1361. <li><p>CONFORM –&gt; discards any invalid bits</p></li>

  1362. <li><p>EJECT –&gt; lose Flag status and become a normal int with the given value</p></li>

  1363. <li><p>KEEP –&gt; keep the extra bits</p>

  1364. <ul>

  1365. <li><p>keeps Flag status and extra bits</p></li>

  1366. <li><p>extra bits do not show up in iteration</p></li>

  1367. <li><p>extra bits do show up in repr() and str()</p></li>

  1368. </ul>

  1369. </li>

  1370. </ul>

  1371. <p>The default for Flag is <code class="docutils literal notranslate"><span class="pre">STRICT</span></code>, the default for <code class="docutils literal notranslate"><span class="pre">IntFlag</span></code> is <code class="docutils literal notranslate"><span class="pre">EJECT</span></code>,

  1372. and the default for <code class="docutils literal notranslate"><span class="pre">_convert_</span></code> is <code class="docutils literal notranslate"><span class="pre">KEEP</span></code> (see <code class="docutils literal notranslate"><span class="pre">ssl.Options</span></code> for an

  1373. example of when <code class="docutils literal notranslate"><span class="pre">KEEP</span></code> is needed).</p>

  1374. </section>

  1375. </section>

  1376. </section>

  1377. <section id="how-are-enums-and-flags-different">

  1378. <span id="enum-class-differences"></span><h2>How are Enums and Flags different?<a class="headerlink" href="#how-are-enums-and-flags-different" title="Link to this heading">¶</a></h2>

  1379. <p>Enums have a custom metaclass that affects many aspects of both derived <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a>

  1380. classes and their instances (members).</p>

  1381. <section id="enum-classes">

  1382. <h3>Enum Classes<a class="headerlink" href="#enum-classes" title="Link to this heading">¶</a></h3>

  1383. <p>The <a class="reference internal" href="../library/enum.html#enum.EnumType" title="enum.EnumType"><code class="xref py py-class docutils literal notranslate"><span class="pre">EnumType</span></code></a> metaclass is responsible for providing the

  1384. <code class="xref py py-meth docutils literal notranslate"><span class="pre">__contains__()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">__dir__()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code> and other methods that

  1385. allow one to do things with an <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> class that fail on a typical

  1386. class, such as <code class="docutils literal notranslate"><span class="pre">list(Color)</span></code> or <code class="docutils literal notranslate"><span class="pre">some_enum_var</span> <span class="pre">in</span> <span class="pre">Color</span></code>.  <a class="reference internal" href="../library/enum.html#enum.EnumType" title="enum.EnumType"><code class="xref py py-class docutils literal notranslate"><span class="pre">EnumType</span></code></a> is

  1387. responsible for ensuring that various other methods on the final <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a>

  1388. class are correct (such as <code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">__getnewargs__()</span></code>,

  1389. <code class="xref py py-meth docutils literal notranslate"><span class="pre">__str__()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">__repr__()</span></code>).</p>

  1390. </section>

  1391. <section id="flag-classes">

  1392. <h3>Flag Classes<a class="headerlink" href="#flag-classes" title="Link to this heading">¶</a></h3>

  1393. <p>Flags have an expanded view of aliasing: to be canonical, the value of a flag

  1394. needs to be a power-of-two value, and not a duplicate name.  So, in addition to the

  1395. <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> definition of alias, a flag with no value (a.k.a. <code class="docutils literal notranslate"><span class="pre">0</span></code>) or with more than one

  1396. power-of-two value (e.g. <code class="docutils literal notranslate"><span class="pre">3</span></code>) is considered an alias.</p>

  1397. </section>

  1398. <section id="enum-members-aka-instances">

  1399. <h3>Enum Members (aka instances)<a class="headerlink" href="#enum-members-aka-instances" title="Link to this heading">¶</a></h3>

  1400. <p>The most interesting thing about enum members is that they are singletons.

  1401. <a class="reference internal" href="../library/enum.html#enum.EnumType" title="enum.EnumType"><code class="xref py py-class docutils literal notranslate"><span class="pre">EnumType</span></code></a> creates them all while it is creating the enum class itself,

  1402. and then puts a custom <code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code> in place to ensure that no new ones are

  1403. ever instantiated by returning only the existing member instances.</p>

  1404. </section>

  1405. <section id="flag-members">

  1406. <h3>Flag Members<a class="headerlink" href="#flag-members" title="Link to this heading">¶</a></h3>

  1407. <p>Flag members can be iterated over just like the <a class="reference internal" href="../library/enum.html#enum.Flag" title="enum.Flag"><code class="xref py py-class docutils literal notranslate"><span class="pre">Flag</span></code></a> class, and only the

  1408. canonical members will be returned.  For example:</p>

  1409. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">Color</span><span class="p">)</span>

  1410. <span class="go">[&lt;Color.RED: 1&gt;, &lt;Color.GREEN: 2&gt;, &lt;Color.BLUE: 4&gt;]</span>

  1411. </pre></div>

  1412. </div>

  1413. <p>(Note that <code class="docutils literal notranslate"><span class="pre">BLACK</span></code>, <code class="docutils literal notranslate"><span class="pre">PURPLE</span></code>, and <code class="docutils literal notranslate"><span class="pre">WHITE</span></code> do not show up.)</p>

  1414. <p>Inverting a flag member returns the corresponding positive value,

  1415. rather than a negative value — for example:</p>

  1416. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="o">~</span><span class="n">Color</span><span class="o">.</span><span class="n">RED</span>

  1417. <span class="go">&lt;Color.GREEN|BLUE: 6&gt;</span>

  1418. </pre></div>

  1419. </div>

  1420. <p>Flag members have a length corresponding to the number of power-of-two values

  1421. they contain.  For example:</p>

  1422. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">len</span><span class="p">(</span><span class="n">Color</span><span class="o">.</span><span class="n">PURPLE</span><span class="p">)</span>

  1423. <span class="go">2</span>

  1424. </pre></div>

  1425. </div>

  1426. </section>

  1427. </section>

  1428. <section id="enum-cookbook">

  1429. <span id="id1"></span><h2>Enum Cookbook<a class="headerlink" href="#enum-cookbook" title="Link to this heading">¶</a></h2>

  1430. <p>While <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a>, <a class="reference internal" href="../library/enum.html#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntEnum</span></code></a>, <a class="reference internal" href="../library/enum.html#enum.StrEnum" title="enum.StrEnum"><code class="xref py py-class docutils literal notranslate"><span class="pre">StrEnum</span></code></a>, <a class="reference internal" href="../library/enum.html#enum.Flag" title="enum.Flag"><code class="xref py py-class docutils literal notranslate"><span class="pre">Flag</span></code></a>, and

  1431. <a class="reference internal" href="../library/enum.html#enum.IntFlag" title="enum.IntFlag"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntFlag</span></code></a> are expected to cover the majority of use-cases, they cannot

  1432. cover them all.  Here are recipes for some different types of enumerations

  1433. that can be used directly, or as examples for creating one’s own.</p>

  1434. <section id="omitting-values">

  1435. <h3>Omitting values<a class="headerlink" href="#omitting-values" title="Link to this heading">¶</a></h3>

  1436. <p>In many use-cases, one doesn’t care what the actual value of an enumeration

  1437. is. There are several ways to define this type of simple enumeration:</p>

  1438. <ul class="simple">

  1439. <li><p>use instances of <a class="reference internal" href="../library/enum.html#enum.auto" title="enum.auto"><code class="xref py py-class docutils literal notranslate"><span class="pre">auto</span></code></a> for the value</p></li>

  1440. <li><p>use instances of <a class="reference internal" href="../library/functions.html#object" title="object"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a> as the value</p></li>

  1441. <li><p>use a descriptive string as the value</p></li>

  1442. <li><p>use a tuple as the value and a custom <code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code> to replace the

  1443. tuple with an <a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a> value</p></li>

  1444. </ul>

  1445. <p>Using any of these methods signifies to the user that these values are not

  1446. important, and also enables one to add, remove, or reorder members without

  1447. having to renumber the remaining members.</p>

  1448. <section id="using-auto">

  1449. <h4>Using <a class="reference internal" href="../library/enum.html#enum.auto" title="enum.auto"><code class="xref py py-class docutils literal notranslate"><span class="pre">auto</span></code></a><a class="headerlink" href="#using-auto" title="Link to this heading">¶</a></h4>

  1450. <p>Using <a class="reference internal" href="../library/enum.html#enum.auto" title="enum.auto"><code class="xref py py-class docutils literal notranslate"><span class="pre">auto</span></code></a> would look like:</p>

  1451. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Color</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  1452. <span class="gp">... </span>    <span class="n">RED</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  1453. <span class="gp">... </span>    <span class="n">BLUE</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  1454. <span class="gp">... </span>    <span class="n">GREEN</span> <span class="o">=</span> <span class="n">auto</span><span class="p">()</span>

  1455. <span class="gp">...</span>

  1456. <span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="o">.</span><span class="n">GREEN</span>

  1457. <span class="go">&lt;Color.GREEN: 3&gt;</span>

  1458. </pre></div>

  1459. </div>

  1460. </section>

  1461. <section id="using-object">

  1462. <h4>Using <a class="reference internal" href="../library/functions.html#object" title="object"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a><a class="headerlink" href="#using-object" title="Link to this heading">¶</a></h4>

  1463. <p>Using <a class="reference internal" href="../library/functions.html#object" title="object"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a> would look like:</p>

  1464. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Color</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  1465. <span class="gp">... </span>    <span class="n">RED</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span>

  1466. <span class="gp">... </span>    <span class="n">GREEN</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span>

  1467. <span class="gp">... </span>    <span class="n">BLUE</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span>

  1468. <span class="gp">...</span>

  1469. <span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="o">.</span><span class="n">GREEN</span>                         

  1470. <span class="go">&lt;Color.GREEN: &lt;object object at 0x...&gt;&gt;</span>

  1471. </pre></div>

  1472. </div>

  1473. <p>This is also a good example of why you might want to write your own

  1474. <code class="xref py py-meth docutils literal notranslate"><span class="pre">__repr__()</span></code>:</p>

  1475. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Color</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  1476. <span class="gp">... </span>    <span class="n">RED</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span>

  1477. <span class="gp">... </span>    <span class="n">GREEN</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span>

  1478. <span class="gp">... </span>    <span class="n">BLUE</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span>

  1479. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  1480. <span class="gp">... </span>        <span class="k">return</span> <span class="s2">&quot;&lt;</span><span class="si">%s</span><span class="s2">.</span><span class="si">%s</span><span class="s2">&gt;&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span><span class="o">.</span><span class="vm">__name__</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">_name_</span><span class="p">)</span>

  1481. <span class="gp">...</span>

  1482. <span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="o">.</span><span class="n">GREEN</span>

  1483. <span class="go">&lt;Color.GREEN&gt;</span>

  1484. </pre></div>

  1485. </div>

  1486. </section>

  1487. <section id="using-a-descriptive-string">

  1488. <h4>Using a descriptive string<a class="headerlink" href="#using-a-descriptive-string" title="Link to this heading">¶</a></h4>

  1489. <p>Using a string as the value would look like:</p>

  1490. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Color</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  1491. <span class="gp">... </span>    <span class="n">RED</span> <span class="o">=</span> <span class="s1">&#39;stop&#39;</span>

  1492. <span class="gp">... </span>    <span class="n">GREEN</span> <span class="o">=</span> <span class="s1">&#39;go&#39;</span>

  1493. <span class="gp">... </span>    <span class="n">BLUE</span> <span class="o">=</span> <span class="s1">&#39;too fast!&#39;</span>

  1494. <span class="gp">...</span>

  1495. <span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="o">.</span><span class="n">GREEN</span>

  1496. <span class="go">&lt;Color.GREEN: &#39;go&#39;&gt;</span>

  1497. </pre></div>

  1498. </div>

  1499. </section>

  1500. <section id="using-a-custom-new">

  1501. <h4>Using a custom <code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code><a class="headerlink" href="#using-a-custom-new" title="Link to this heading">¶</a></h4>

  1502. <p>Using an auto-numbering <code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code> would look like:</p>

  1503. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">AutoNumber</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  1504. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__new__</span><span class="p">(</span><span class="bp">cls</span><span class="p">):</span>

  1505. <span class="gp">... </span>        <span class="n">value</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="bp">cls</span><span class="o">.</span><span class="n">__members__</span><span class="p">)</span> <span class="o">+</span> <span class="mi">1</span>

  1506. <span class="gp">... </span>        <span class="n">obj</span> <span class="o">=</span> <span class="nb">object</span><span class="o">.</span><span class="fm">__new__</span><span class="p">(</span><span class="bp">cls</span><span class="p">)</span>

  1507. <span class="gp">... </span>        <span class="n">obj</span><span class="o">.</span><span class="n">_value_</span> <span class="o">=</span> <span class="n">value</span>

  1508. <span class="gp">... </span>        <span class="k">return</span> <span class="n">obj</span>

  1509. <span class="gp">...</span>

  1510. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Color</span><span class="p">(</span><span class="n">AutoNumber</span><span class="p">):</span>

  1511. <span class="gp">... </span>    <span class="n">RED</span> <span class="o">=</span> <span class="p">()</span>

  1512. <span class="gp">... </span>    <span class="n">GREEN</span> <span class="o">=</span> <span class="p">()</span>

  1513. <span class="gp">... </span>    <span class="n">BLUE</span> <span class="o">=</span> <span class="p">()</span>

  1514. <span class="gp">...</span>

  1515. <span class="gp">&gt;&gt;&gt; </span><span class="n">Color</span><span class="o">.</span><span class="n">GREEN</span>

  1516. <span class="go">&lt;Color.GREEN: 2&gt;</span>

  1517. </pre></div>

  1518. </div>

  1519. <p>To make a more general purpose <code class="docutils literal notranslate"><span class="pre">AutoNumber</span></code>, add <code class="docutils literal notranslate"><span class="pre">*args</span></code> to the signature:</p>

  1520. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">AutoNumber</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  1521. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__new__</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">):</span>      <span class="c1"># this is the only change from above</span>

  1522. <span class="gp">... </span>        <span class="n">value</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="bp">cls</span><span class="o">.</span><span class="n">__members__</span><span class="p">)</span> <span class="o">+</span> <span class="mi">1</span>

  1523. <span class="gp">... </span>        <span class="n">obj</span> <span class="o">=</span> <span class="nb">object</span><span class="o">.</span><span class="fm">__new__</span><span class="p">(</span><span class="bp">cls</span><span class="p">)</span>

  1524. <span class="gp">... </span>        <span class="n">obj</span><span class="o">.</span><span class="n">_value_</span> <span class="o">=</span> <span class="n">value</span>

  1525. <span class="gp">... </span>        <span class="k">return</span> <span class="n">obj</span>

  1526. <span class="gp">...</span>

  1527. </pre></div>

  1528. </div>

  1529. <p>Then when you inherit from <code class="docutils literal notranslate"><span class="pre">AutoNumber</span></code> you can write your own <code class="docutils literal notranslate"><span class="pre">__init__</span></code>

  1530. to handle any extra arguments:</p>

  1531. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Swatch</span><span class="p">(</span><span class="n">AutoNumber</span><span class="p">):</span>

  1532. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">pantone</span><span class="o">=</span><span class="s1">&#39;unknown&#39;</span><span class="p">):</span>

  1533. <span class="gp">... </span>        <span class="bp">self</span><span class="o">.</span><span class="n">pantone</span> <span class="o">=</span> <span class="n">pantone</span>

  1534. <span class="gp">... </span>    <span class="n">AUBURN</span> <span class="o">=</span> <span class="s1">&#39;3497&#39;</span>

  1535. <span class="gp">... </span>    <span class="n">SEA_GREEN</span> <span class="o">=</span> <span class="s1">&#39;1246&#39;</span>

  1536. <span class="gp">... </span>    <span class="n">BLEACHED_CORAL</span> <span class="o">=</span> <span class="p">()</span> <span class="c1"># New color, no Pantone code yet!</span>

  1537. <span class="gp">...</span>

  1538. <span class="gp">&gt;&gt;&gt; </span><span class="n">Swatch</span><span class="o">.</span><span class="n">SEA_GREEN</span>

  1539. <span class="go">&lt;Swatch.SEA_GREEN: 2&gt;</span>

  1540. <span class="gp">&gt;&gt;&gt; </span><span class="n">Swatch</span><span class="o">.</span><span class="n">SEA_GREEN</span><span class="o">.</span><span class="n">pantone</span>

  1541. <span class="go">&#39;1246&#39;</span>

  1542. <span class="gp">&gt;&gt;&gt; </span><span class="n">Swatch</span><span class="o">.</span><span class="n">BLEACHED_CORAL</span><span class="o">.</span><span class="n">pantone</span>

  1543. <span class="go">&#39;unknown&#39;</span>

  1544. </pre></div>

  1545. </div>

  1546. <div class="admonition note">

  1547. <p class="admonition-title">Note</p>

  1548. <p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code> method, if defined, is used during creation of the Enum

  1549. members; it is then replaced by Enum’s <code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code> which is used after

  1550. class creation for lookup of existing members.</p>

  1551. </div>

  1552. <div class="admonition warning">

  1553. <p class="admonition-title">Warning</p>

  1554. <p><em>Do not</em> call <code class="docutils literal notranslate"><span class="pre">super().__new__()</span></code>, as the lookup-only <code class="docutils literal notranslate"><span class="pre">__new__</span></code> is the one

  1555. that is found; instead, use the data type directly – e.g.:</p>

  1556. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">obj</span> <span class="o">=</span> <span class="nb">int</span><span class="o">.</span><span class="fm">__new__</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>

  1557. </pre></div>

  1558. </div>

  1559. </div>

  1560. </section>

  1561. </section>

  1562. <section id="orderedenum">

  1563. <h3>OrderedEnum<a class="headerlink" href="#orderedenum" title="Link to this heading">¶</a></h3>

  1564. <p>An ordered enumeration that is not based on <a class="reference internal" href="../library/enum.html#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntEnum</span></code></a> and so maintains

  1565. the normal <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> invariants (such as not being comparable to other

  1566. enumerations):</p>

  1567. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">OrderedEnum</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  1568. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__ge__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>

  1569. <span class="gp">... </span>        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span> <span class="ow">is</span> <span class="n">other</span><span class="o">.</span><span class="vm">__class__</span><span class="p">:</span>

  1570. <span class="gp">... </span>            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">value</span> <span class="o">&gt;=</span> <span class="n">other</span><span class="o">.</span><span class="n">value</span>

  1571. <span class="gp">... </span>        <span class="k">return</span> <span class="bp">NotImplemented</span>

  1572. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__gt__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>

  1573. <span class="gp">... </span>        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span> <span class="ow">is</span> <span class="n">other</span><span class="o">.</span><span class="vm">__class__</span><span class="p">:</span>

  1574. <span class="gp">... </span>            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">value</span> <span class="o">&gt;</span> <span class="n">other</span><span class="o">.</span><span class="n">value</span>

  1575. <span class="gp">... </span>        <span class="k">return</span> <span class="bp">NotImplemented</span>

  1576. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__le__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>

  1577. <span class="gp">... </span>        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span> <span class="ow">is</span> <span class="n">other</span><span class="o">.</span><span class="vm">__class__</span><span class="p">:</span>

  1578. <span class="gp">... </span>            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">value</span> <span class="o">&lt;=</span> <span class="n">other</span><span class="o">.</span><span class="n">value</span>

  1579. <span class="gp">... </span>        <span class="k">return</span> <span class="bp">NotImplemented</span>

  1580. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__lt__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>

  1581. <span class="gp">... </span>        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span> <span class="ow">is</span> <span class="n">other</span><span class="o">.</span><span class="vm">__class__</span><span class="p">:</span>

  1582. <span class="gp">... </span>            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">value</span> <span class="o">&lt;</span> <span class="n">other</span><span class="o">.</span><span class="n">value</span>

  1583. <span class="gp">... </span>        <span class="k">return</span> <span class="bp">NotImplemented</span>

  1584. <span class="gp">...</span>

  1585. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Grade</span><span class="p">(</span><span class="n">OrderedEnum</span><span class="p">):</span>

  1586. <span class="gp">... </span>    <span class="n">A</span> <span class="o">=</span> <span class="mi">5</span>

  1587. <span class="gp">... </span>    <span class="n">B</span> <span class="o">=</span> <span class="mi">4</span>

  1588. <span class="gp">... </span>    <span class="n">C</span> <span class="o">=</span> <span class="mi">3</span>

  1589. <span class="gp">... </span>    <span class="n">D</span> <span class="o">=</span> <span class="mi">2</span>

  1590. <span class="gp">... </span>    <span class="n">F</span> <span class="o">=</span> <span class="mi">1</span>

  1591. <span class="gp">...</span>

  1592. <span class="gp">&gt;&gt;&gt; </span><span class="n">Grade</span><span class="o">.</span><span class="n">C</span> <span class="o">&lt;</span> <span class="n">Grade</span><span class="o">.</span><span class="n">A</span>

  1593. <span class="go">True</span>

  1594. </pre></div>

  1595. </div>

  1596. </section>

  1597. <section id="duplicatefreeenum">

  1598. <h3>DuplicateFreeEnum<a class="headerlink" href="#duplicatefreeenum" title="Link to this heading">¶</a></h3>

  1599. <p>Raises an error if a duplicate member value is found instead of creating an

  1600. alias:</p>

  1601. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">DuplicateFreeEnum</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  1602. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">):</span>

  1603. <span class="gp">... </span>        <span class="bp">cls</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span>

  1604. <span class="gp">... </span>        <span class="k">if</span> <span class="nb">any</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">value</span> <span class="o">==</span> <span class="n">e</span><span class="o">.</span><span class="n">value</span> <span class="k">for</span> <span class="n">e</span> <span class="ow">in</span> <span class="bp">cls</span><span class="p">):</span>

  1605. <span class="gp">... </span>            <span class="n">a</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span>

  1606. <span class="gp">... </span>            <span class="n">e</span> <span class="o">=</span> <span class="bp">cls</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">value</span><span class="p">)</span><span class="o">.</span><span class="n">name</span>

  1607. <span class="gp">... </span>            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>

  1608. <span class="gp">... </span>                <span class="s2">&quot;aliases not allowed in DuplicateFreeEnum:  </span><span class="si">%r</span><span class="s2"> --&gt; </span><span class="si">%r</span><span class="s2">&quot;</span>

  1609. <span class="gp">... </span>                <span class="o">%</span> <span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">e</span><span class="p">))</span>

  1610. <span class="gp">...</span>

  1611. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Color</span><span class="p">(</span><span class="n">DuplicateFreeEnum</span><span class="p">):</span>

  1612. <span class="gp">... </span>    <span class="n">RED</span> <span class="o">=</span> <span class="mi">1</span>

  1613. <span class="gp">... </span>    <span class="n">GREEN</span> <span class="o">=</span> <span class="mi">2</span>

  1614. <span class="gp">... </span>    <span class="n">BLUE</span> <span class="o">=</span> <span class="mi">3</span>

  1615. <span class="gp">... </span>    <span class="n">GRENE</span> <span class="o">=</span> <span class="mi">2</span>

  1616. <span class="gp">...</span>

  1617. <span class="gt">Traceback (most recent call last):</span>

  1618. <span class="w">  </span><span class="c">...</span>

  1619. <span class="gr">ValueError</span>: <span class="n">aliases not allowed in DuplicateFreeEnum:  &#39;GRENE&#39; --&gt; &#39;GREEN&#39;</span>

  1620. </pre></div>

  1621. </div>

  1622. <div class="admonition note">

  1623. <p class="admonition-title">Note</p>

  1624. <p>This is a useful example for subclassing Enum to add or change other

  1625. behaviors as well as disallowing aliases.  If the only desired change is

  1626. disallowing aliases, the <a class="reference internal" href="../library/enum.html#enum.unique" title="enum.unique"><code class="xref py py-func docutils literal notranslate"><span class="pre">unique()</span></code></a> decorator can be used instead.</p>

  1627. </div>

  1628. </section>

  1629. <section id="planet">

  1630. <h3>Planet<a class="headerlink" href="#planet" title="Link to this heading">¶</a></h3>

  1631. <p>If <code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code> or <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> is defined, the value of the enum member

  1632. will be passed to those methods:</p>

  1633. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Planet</span><span class="p">(</span><span class="n">Enum</span><span class="p">):</span>

  1634. <span class="gp">... </span>    <span class="n">MERCURY</span> <span class="o">=</span> <span class="p">(</span><span class="mf">3.303e+23</span><span class="p">,</span> <span class="mf">2.4397e6</span><span class="p">)</span>

  1635. <span class="gp">... </span>    <span class="n">VENUS</span>   <span class="o">=</span> <span class="p">(</span><span class="mf">4.869e+24</span><span class="p">,</span> <span class="mf">6.0518e6</span><span class="p">)</span>

  1636. <span class="gp">... </span>    <span class="n">EARTH</span>   <span class="o">=</span> <span class="p">(</span><span class="mf">5.976e+24</span><span class="p">,</span> <span class="mf">6.37814e6</span><span class="p">)</span>

  1637. <span class="gp">... </span>    <span class="n">MARS</span>    <span class="o">=</span> <span class="p">(</span><span class="mf">6.421e+23</span><span class="p">,</span> <span class="mf">3.3972e6</span><span class="p">)</span>

  1638. <span class="gp">... </span>    <span class="n">JUPITER</span> <span class="o">=</span> <span class="p">(</span><span class="mf">1.9e+27</span><span class="p">,</span>   <span class="mf">7.1492e7</span><span class="p">)</span>

  1639. <span class="gp">... </span>    <span class="n">SATURN</span>  <span class="o">=</span> <span class="p">(</span><span class="mf">5.688e+26</span><span class="p">,</span> <span class="mf">6.0268e7</span><span class="p">)</span>

  1640. <span class="gp">... </span>    <span class="n">URANUS</span>  <span class="o">=</span> <span class="p">(</span><span class="mf">8.686e+25</span><span class="p">,</span> <span class="mf">2.5559e7</span><span class="p">)</span>

  1641. <span class="gp">... </span>    <span class="n">NEPTUNE</span> <span class="o">=</span> <span class="p">(</span><span class="mf">1.024e+26</span><span class="p">,</span> <span class="mf">2.4746e7</span><span class="p">)</span>

  1642. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">mass</span><span class="p">,</span> <span class="n">radius</span><span class="p">):</span>

  1643. <span class="gp">... </span>        <span class="bp">self</span><span class="o">.</span><span class="n">mass</span> <span class="o">=</span> <span class="n">mass</span>       <span class="c1"># in kilograms</span>

  1644. <span class="gp">... </span>        <span class="bp">self</span><span class="o">.</span><span class="n">radius</span> <span class="o">=</span> <span class="n">radius</span>   <span class="c1"># in meters</span>

  1645. <span class="gp">... </span>    <span class="nd">@property</span>

  1646. <span class="gp">... </span>    <span class="k">def</span> <span class="nf">surface_gravity</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  1647. <span class="gp">... </span>        <span class="c1"># universal gravitational constant  (m3 kg-1 s-2)</span>

  1648. <span class="gp">... </span>        <span class="n">G</span> <span class="o">=</span> <span class="mf">6.67300E-11</span>

  1649. <span class="gp">... </span>        <span class="k">return</span> <span class="n">G</span> <span class="o">*</span> <span class="bp">self</span><span class="o">.</span><span class="n">mass</span> <span class="o">/</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">radius</span> <span class="o">*</span> <span class="bp">self</span><span class="o">.</span><span class="n">radius</span><span class="p">)</span>

  1650. <span class="gp">...</span>

  1651. <span class="gp">&gt;&gt;&gt; </span><span class="n">Planet</span><span class="o">.</span><span class="n">EARTH</span><span class="o">.</span><span class="n">value</span>

  1652. <span class="go">(5.976e+24, 6378140.0)</span>

  1653. <span class="gp">&gt;&gt;&gt; </span><span class="n">Planet</span><span class="o">.</span><span class="n">EARTH</span><span class="o">.</span><span class="n">surface_gravity</span>

  1654. <span class="go">9.802652743337129</span>

  1655. </pre></div>

  1656. </div>

  1657. </section>

  1658. <section id="timeperiod">

  1659. <span id="enum-time-period"></span><h3>TimePeriod<a class="headerlink" href="#timeperiod" title="Link to this heading">¶</a></h3>

  1660. <p>An example to show the <code class="xref py py-attr docutils literal notranslate"><span class="pre">_ignore_</span></code> attribute in use:</p>

  1661. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">timedelta</span>

  1662. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Period</span><span class="p">(</span><span class="n">timedelta</span><span class="p">,</span> <span class="n">Enum</span><span class="p">):</span>

  1663. <span class="gp">... </span>    <span class="s2">&quot;different lengths of time&quot;</span>

  1664. <span class="gp">... </span>    <span class="n">_ignore_</span> <span class="o">=</span> <span class="s1">&#39;Period i&#39;</span>

  1665. <span class="gp">... </span>    <span class="n">Period</span> <span class="o">=</span> <span class="nb">vars</span><span class="p">()</span>

  1666. <span class="gp">... </span>    <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">367</span><span class="p">):</span>

  1667. <span class="gp">... </span>        <span class="n">Period</span><span class="p">[</span><span class="s1">&#39;day_</span><span class="si">%d</span><span class="s1">&#39;</span> <span class="o">%</span> <span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">i</span>

  1668. <span class="gp">...</span>

  1669. <span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">Period</span><span class="p">)[:</span><span class="mi">2</span><span class="p">]</span>

  1670. <span class="go">[&lt;Period.day_0: datetime.timedelta(0)&gt;, &lt;Period.day_1: datetime.timedelta(days=1)&gt;]</span>

  1671. <span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">Period</span><span class="p">)[</span><span class="o">-</span><span class="mi">2</span><span class="p">:]</span>

  1672. <span class="go">[&lt;Period.day_365: datetime.timedelta(days=365)&gt;, &lt;Period.day_366: datetime.timedelta(days=366)&gt;]</span>

  1673. </pre></div>

  1674. </div>

  1675. </section>

  1676. </section>

  1677. <section id="subclassing-enumtype">

  1678. <span id="enumtype-examples"></span><h2>Subclassing EnumType<a class="headerlink" href="#subclassing-enumtype" title="Link to this heading">¶</a></h2>

  1679. <p>While most enum needs can be met by customizing <a class="reference internal" href="../library/enum.html#enum.Enum" title="enum.Enum"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a> subclasses,

  1680. either with class decorators or custom functions, <a class="reference internal" href="../library/enum.html#enum.EnumType" title="enum.EnumType"><code class="xref py py-class docutils literal notranslate"><span class="pre">EnumType</span></code></a> can be

  1681. subclassed to provide a different Enum experience.</p>

  1682. </section>

  1683. </section>

  1684. 

  1685. 

  1686.             <div class="clearer"></div>

  1687.           </div>

  1688.         </div>

  1689.       </div>

  1690.       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">

  1691.         <div class="sphinxsidebarwrapper">

  1692.   <div>

  1693.     <h3><a href="../contents.html">Table of Contents</a></h3>

  1694.     <ul>

  1695. <li><a class="reference internal" href="#">Enum HOWTO</a><ul>

  1696. <li><a class="reference internal" href="#programmatic-access-to-enumeration-members-and-their-attributes">Programmatic access to enumeration members and their attributes</a></li>

  1697. <li><a class="reference internal" href="#duplicating-enum-members-and-values">Duplicating enum members and values</a></li>

  1698. <li><a class="reference internal" href="#ensuring-unique-enumeration-values">Ensuring unique enumeration values</a></li>

  1699. <li><a class="reference internal" href="#using-automatic-values">Using automatic values</a></li>

  1700. <li><a class="reference internal" href="#iteration">Iteration</a></li>

  1701. <li><a class="reference internal" href="#comparisons">Comparisons</a></li>

  1702. <li><a class="reference internal" href="#allowed-members-and-attributes-of-enumerations">Allowed members and attributes of enumerations</a></li>

  1703. <li><a class="reference internal" href="#restricted-enum-subclassing">Restricted Enum subclassing</a></li>

  1704. <li><a class="reference internal" href="#dataclass-support">Dataclass support</a></li>

  1705. <li><a class="reference internal" href="#pickling">Pickling</a></li>

  1706. <li><a class="reference internal" href="#functional-api">Functional API</a></li>

  1707. <li><a class="reference internal" href="#derived-enumerations">Derived Enumerations</a><ul>

  1708. <li><a class="reference internal" href="#intenum">IntEnum</a></li>

  1709. <li><a class="reference internal" href="#strenum">StrEnum</a></li>

  1710. <li><a class="reference internal" href="#intflag">IntFlag</a></li>

  1711. <li><a class="reference internal" href="#flag">Flag</a></li>

  1712. <li><a class="reference internal" href="#others">Others</a></li>

  1713. </ul>

  1714. </li>

  1715. <li><a class="reference internal" href="#when-to-use-new-vs-init">When to use <code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code> vs. <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a><ul>

  1716. <li><a class="reference internal" href="#finer-points">Finer Points</a><ul>

  1717. <li><a class="reference internal" href="#supported-dunder-names">Supported <code class="docutils literal notranslate"><span class="pre">__dunder__</span></code> names</a></li>

  1718. <li><a class="reference internal" href="#supported-sunder-names">Supported <code class="docutils literal notranslate"><span class="pre">_sunder_</span></code> names</a></li>

  1719. <li><a class="reference internal" href="#private-names">_Private__names</a></li>

  1720. <li><a class="reference internal" href="#enum-member-type"><code class="docutils literal notranslate"><span class="pre">Enum</span></code> member type</a></li>

  1721. <li><a class="reference internal" href="#creating-members-that-are-mixed-with-other-data-types">Creating members that are mixed with other data types</a></li>

  1722. <li><a class="reference internal" href="#boolean-value-of-enum-classes-and-members">Boolean value of <code class="docutils literal notranslate"><span class="pre">Enum</span></code> classes and members</a></li>

  1723. <li><a class="reference internal" href="#enum-classes-with-methods"><code class="docutils literal notranslate"><span class="pre">Enum</span></code> classes with methods</a></li>

  1724. <li><a class="reference internal" href="#combining-members-of-flag">Combining members of <code class="docutils literal notranslate"><span class="pre">Flag</span></code></a></li>

  1725. <li><a class="reference internal" href="#flag-and-intflag-minutia"><code class="docutils literal notranslate"><span class="pre">Flag</span></code> and <code class="docutils literal notranslate"><span class="pre">IntFlag</span></code> minutia</a></li>

  1726. </ul>

  1727. </li>

  1728. </ul>

  1729. </li>

  1730. <li><a class="reference internal" href="#how-are-enums-and-flags-different">How are Enums and Flags different?</a><ul>

  1731. <li><a class="reference internal" href="#enum-classes">Enum Classes</a></li>

  1732. <li><a class="reference internal" href="#flag-classes">Flag Classes</a></li>

  1733. <li><a class="reference internal" href="#enum-members-aka-instances">Enum Members (aka instances)</a></li>

  1734. <li><a class="reference internal" href="#flag-members">Flag Members</a></li>

  1735. </ul>

  1736. </li>

  1737. <li><a class="reference internal" href="#enum-cookbook">Enum Cookbook</a><ul>

  1738. <li><a class="reference internal" href="#omitting-values">Omitting values</a><ul>

  1739. <li><a class="reference internal" href="#using-auto">Using <code class="xref py py-class docutils literal notranslate"><span class="pre">auto</span></code></a></li>

  1740. <li><a class="reference internal" href="#using-object">Using <code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a></li>

  1741. <li><a class="reference internal" href="#using-a-descriptive-string">Using a descriptive string</a></li>

  1742. <li><a class="reference internal" href="#using-a-custom-new">Using a custom <code class="xref py py-meth docutils literal notranslate"><span class="pre">__new__()</span></code></a></li>

  1743. </ul>

  1744. </li>

  1745. <li><a class="reference internal" href="#orderedenum">OrderedEnum</a></li>

  1746. <li><a class="reference internal" href="#duplicatefreeenum">DuplicateFreeEnum</a></li>

  1747. <li><a class="reference internal" href="#planet">Planet</a></li>

  1748. <li><a class="reference internal" href="#timeperiod">TimePeriod</a></li>

  1749. </ul>

  1750. </li>

  1751. <li><a class="reference internal" href="#subclassing-enumtype">Subclassing EnumType</a></li>

  1752. </ul>

  1753. </li>

  1754. </ul>

  1755. 

  1756.   </div>

  1757.   <div>

  1758.     <h4>Previous topic</h4>

  1759.     <p class="topless"><a href="gdb_helpers.html"

  1760.                           title="previous chapter">Debugging C API extensions and CPython Internals with GDB</a></p>

  1761.   </div>

  1762.   <div>

  1763.     <h4>Next topic</h4>

  1764.     <p class="topless"><a href="functional.html"

  1765.                           title="next chapter">Functional Programming HOWTO</a></p>

  1766.   </div>

  1767.   <div role="note" aria-label="source link">

  1768.     <h3>This Page</h3>

  1769.     <ul class="this-page-menu">

  1770.       <li><a href="../bugs.html">Report a Bug</a></li>

  1771.       <li>

  1772.         <a href="https://github.com/python/cpython/blob/main/Doc/howto/enum.rst"

  1773.             rel="nofollow">Show Source

  1774.         </a>

  1775.       </li>

  1776.     </ul>

  1777.   </div>

  1778.         </div>

  1779. <div id="sidebarbutton" title="Collapse sidebar">

  1780. <span>«</span>

  1781. </div>

  1782. 

  1783.       </div>

  1784.       <div class="clearer"></div>

  1785.     </div>  

  1786.     <div class="related" role="navigation" aria-label="related navigation">

  1787.       <h3>Navigation</h3>

  1788.       <ul>

  1789.         <li class="right" style="margin-right: 10px">

  1790.           <a href="../genindex.html" title="General Index"

  1791.              >index</a></li>

  1792.         <li class="right" >

  1793.           <a href="../py-modindex.html" title="Python Module Index"

  1794.              >modules</a> |</li>

  1795.         <li class="right" >

  1796.           <a href="functional.html" title="Functional Programming HOWTO"

  1797.              >next</a> |</li>

  1798.         <li class="right" >

  1799.           <a href="gdb_helpers.html" title="Debugging C API extensions and CPython Internals with GDB"

  1800.              >previous</a> |</li>

  1801. 

  1802.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  1803.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  1804.           <li class="switchers">

  1805.             <div class="language_switcher_placeholder"></div>

  1806.             <div class="version_switcher_placeholder"></div>

  1807.           </li>

  1808.           <li>

  1809.               

  1810.           </li>

  1811.     <li id="cpython-language-and-version">

  1812.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  1813.     </li>

  1814. 

  1815.           <li class="nav-item nav-item-1"><a href="index.html" >Python HOWTOs</a> &#187;</li>

  1816.         <li class="nav-item nav-item-this"><a href="">Enum HOWTO</a></li>

  1817.                 <li class="right">

  1818.                     

  1819. 

  1820.     <div class="inline-search" role="search">

  1821.         <form class="inline-search" action="../search.html" method="get">

  1822.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  1823.           <input type="submit" value="Go" />

  1824.         </form>

  1825.     </div>

  1826.                      |

  1827.                 </li>

  1828.             <li class="right">

  1829. <label class="theme-selector-label">

  1830.     Theme

  1831.     <select class="theme-selector" oninput="activateTheme(this.value)">

  1832.         <option value="auto" selected>Auto</option>

  1833.         <option value="light">Light</option>

  1834.         <option value="dark">Dark</option>

  1835.     </select>

  1836. </label> |</li>

  1837.             

  1838.       </ul>

  1839.     </div>  

  1840.     <div class="footer">

  1841.     &copy; 

  1842.       <a href="../copyright.html">

  1843.     

  1844.     Copyright

  1845.     

  1846.       </a>

  1847.      2001-2024, Python Software Foundation.

  1848.     <br />

  1849.     This page is licensed under the Python Software Foundation License Version 2.

  1850.     <br />

  1851.     Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.

  1852.     <br />

  1853.     

  1854.       See <a href="/license.html">History and License</a> for more information.<br />

  1855.     

  1856.     

  1857.     <br />

  1858. 

  1859.     The Python Software Foundation is a non-profit corporation.

  1860. <a href="https://www.python.org/psf/donations/">Please donate.</a>

  1861. <br />

  1862.     <br />

  1863.       Last updated on Apr 09, 2024 (13:47 UTC).

  1864.     

  1865.       <a href="/bugs.html">Found a bug</a>?

  1866.     

  1867.     <br />

  1868. 

  1869.     Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.

  1870.     </div>

  1871. 

  1872.   </body>

  1873. </html>
上海开阖软件有限公司 沪ICP备12045867号-1