parthtamu/rag-code-assistant
0
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="dataclasses — Data Classes" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/dataclasses.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/dataclasses.py This module provides a decorator and functions for automatically adding generated special methods such as__init__() and__repr__() to user-defined classes. It was ori..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_dataclasses_5925ca6d.png" />15<meta property="og:image:alt" content="Source code: Lib/dataclasses.py This module provides a decorator and functions for automatically adding generated special methods such as__init__() and__repr__() to user-defined classes. It was ori..." />16<meta name="description" content="Source code: Lib/dataclasses.py This module provides a decorator and functions for automatically adding generated special methods such as__init__() and__repr__() to user-defined classes. It was ori..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20 <title>dataclasses — Data Classes — Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21 22 <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23 <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24 <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25 <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26 <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27 28 <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29 <script src="../_static/doctools.js?v=9bcbadda"></script>30 <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31 <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32 33 <script src="../_static/sidebar.js"></script>34 35 <link rel="search" type="application/opensearchdescription+xml"36 title="Search within Python 3.15.0a6 documentation"37 href="../_static/opensearch.xml"/>38 <link rel="author" title="About these documents" href="../about.html" />39 <link rel="index" title="Index" href="../genindex.html" />40 <link rel="search" title="Search" href="../search.html" />41 <link rel="copyright" title="Copyright" href="../copyright.html" />42 <link rel="next" title="contextlib — Utilities for with-statement contexts" href="contextlib.html" />43 <link rel="prev" title="warnings — Warning control" href="warnings.html" />44 45 46 <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47 48 <link rel="canonical" href="https://docs.python.org/3/library/dataclasses.html">49 50 51 52 53 <style>54 @media only screen {55 table.full-width-table {56 width: 100%;57 }58 }59 </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61 <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62 <script type="text/javascript" src="../_static/copybutton.js"></script>63 <script type="text/javascript" src="../_static/menu.js"></script>64 <script type="text/javascript" src="../_static/search-focus.js"></script>65 <script type="text/javascript" src="../_static/themetoggle.js"></script> 66 <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67 <meta name="readthedocs-addons-api-version" content="1">68 69 </head>70<body>71<div class="mobile-nav">72 <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73 aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74 <nav class="nav-content" role="navigation">75 <label for="menuToggler" class="toggler__label">76 <span></span>77 </label>78 <span class="nav-items-wrapper">79 <a href="https://www.python.org/" class="nav-logo">80 <img src="../_static/py.svg" alt="Python logo">81 </a>82 <span class="version_switcher_placeholder"></span>83 <form role="search" class="search" action="../search.html" method="get">84 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85 <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>86 </svg>87 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88 <input type="submit" value="Go">89 </form>90 </span>91 </nav>92 <div class="menu-wrapper">93 <nav class="menu" role="navigation" aria-label="main navigation">94 <div class="language_switcher_placeholder"></div>95 96<label class="theme-selector-label">97 Theme98 <select class="theme-selector" oninput="activateTheme(this.value)">99 <option value="auto" selected>Auto</option>100 <option value="light">Light</option>101 <option value="dark">Dark</option>102 </select>103</label>104 <div>105 <h3><a href="../contents.html">Table of Contents</a></h3>106 <ul>107<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dataclasses</span></code> — Data Classes</a><ul>108<li><a class="reference internal" href="#module-contents">Module contents</a></li>109<li><a class="reference internal" href="#post-init-processing">Post-init processing</a></li>110<li><a class="reference internal" href="#class-variables">Class variables</a></li>111<li><a class="reference internal" href="#init-only-variables">Init-only variables</a></li>112<li><a class="reference internal" href="#frozen-instances">Frozen instances</a></li>113<li><a class="reference internal" href="#inheritance">Inheritance</a></li>114<li><a class="reference internal" href="#re-ordering-of-keyword-only-parameters-in-init">Re-ordering of keyword-only parameters in <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a></li>115<li><a class="reference internal" href="#default-factory-functions">Default factory functions</a></li>116<li><a class="reference internal" href="#mutable-default-values">Mutable default values</a></li>117<li><a class="reference internal" href="#descriptor-typed-fields">Descriptor-typed fields</a></li>118</ul>119</li>120</ul>121 122 </div>123 <div>124 <h4>Previous topic</h4>125 <p class="topless"><a href="warnings.html"126 title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">warnings</span></code> — Warning control</a></p>127 </div>128 <div>129 <h4>Next topic</h4>130 <p class="topless"><a href="contextlib.html"131 title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">contextlib</span></code> — Utilities for <code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code>-statement contexts</a></p>132 </div>133 <script>134 document.addEventListener('DOMContentLoaded', () => {135 const title = document.querySelector('meta[property="og:title"]').content;136 const elements = document.querySelectorAll('.improvepage');137 const pageurl = window.location.href.split('?')[0];138 elements.forEach(element => {139 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));140 url.searchParams.set('pagetitle', title);141 url.searchParams.set('pageurl', pageurl);142 url.searchParams.set('pagesource', "library/dataclasses.rst");143 element.href = url.toString();144 });145 });146 </script>147 <div role="note" aria-label="source link">148 <h3>This page</h3>149 <ul class="this-page-menu">150 <li><a href="../bugs.html">Report a bug</a></li>151 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>152 <li>153 <a href="https://github.com/python/cpython/blob/main/Doc/library/dataclasses.rst?plain=1"154 rel="nofollow">Show source155 </a>156 </li>157 158 </ul>159 </div>160 </nav>161 </div>162</div>163 164 165 <div class="related" role="navigation" aria-label="Related">166 <h3>Navigation</h3>167 <ul>168 <li class="right" style="margin-right: 10px">169 <a href="../genindex.html" title="General Index"170 accesskey="I">index</a></li>171 <li class="right" >172 <a href="../py-modindex.html" title="Python Module Index"173 >modules</a> |</li>174 <li class="right" >175 <a href="contextlib.html" title="contextlib — Utilities for with-statement contexts"176 accesskey="N">next</a> |</li>177 <li class="right" >178 <a href="warnings.html" title="warnings — Warning control"179 accesskey="P">previous</a> |</li>180 181 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>182 <li><a href="https://www.python.org/">Python</a> »</li>183 <li class="switchers">184 <div class="language_switcher_placeholder"></div>185 <div class="version_switcher_placeholder"></div>186 </li>187 <li>188 189 </li>190 <li id="cpython-language-and-version">191 <a href="../index.html">3.15.0a6 Documentation</a> »192 </li>193 194 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>195 <li class="nav-item nav-item-2"><a href="python.html" accesskey="U">Python Runtime Services</a> »</li>196 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">dataclasses</span></code> — Data Classes</a></li>197 <li class="right">198 199 200 <div class="inline-search" role="search">201 <form class="inline-search" action="../search.html" method="get">202 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">203 <input type="submit" value="Go">204 </form>205 </div>206 |207 </li>208 <li class="right">209<label class="theme-selector-label">210 Theme211 <select class="theme-selector" oninput="activateTheme(this.value)">212 <option value="auto" selected>Auto</option>213 <option value="light">Light</option>214 <option value="dark">Dark</option>215 </select>216</label> |</li>217 218 </ul>219 </div> 220 221 <div class="document">222 <div class="documentwrapper">223 <div class="bodywrapper">224 <div class="body" role="main">225 226 <section id="module-dataclasses">227<span id="dataclasses-data-classes"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">dataclasses</span></code> — Data Classes<a class="headerlink" href="#module-dataclasses" title="Link to this heading">¶</a></h1>228<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/dataclasses.py">Lib/dataclasses.py</a></p>229<hr class="docutils" />230<p>This module provides a decorator and functions for automatically231adding generated <a class="reference internal" href="../glossary.html#term-special-method"><span class="xref std std-term">special methods</span></a> such as <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> and232<a class="reference internal" href="../reference/datamodel.html#object.__repr__" title="object.__repr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__repr__()</span></code></a> to user-defined classes. It was originally described233in <span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0557/"><strong>PEP 557</strong></a>.</p>234<p>The member variables to use in these generated methods are defined235using <span class="target" id="index-1"></span><a class="pep reference external" href="https://peps.python.org/pep-0526/"><strong>PEP 526</strong></a> type annotations. For example, this code:</p>236<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">dataclasses</span><span class="w"> </span><span class="kn">import</span> <span class="n">dataclass</span>237 238<span class="nd">@dataclass</span>239<span class="k">class</span><span class="w"> </span><span class="nc">InventoryItem</span><span class="p">:</span>240<span class="w"> </span><span class="sd">"""Class for keeping track of an item in inventory."""</span>241 <span class="n">name</span><span class="p">:</span> <span class="nb">str</span>242 <span class="n">unit_price</span><span class="p">:</span> <span class="nb">float</span>243 <span class="n">quantity_on_hand</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span>244 245 <span class="k">def</span><span class="w"> </span><span class="nf">total_cost</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-></span> <span class="nb">float</span><span class="p">:</span>246 <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">unit_price</span> <span class="o">*</span> <span class="bp">self</span><span class="o">.</span><span class="n">quantity_on_hand</span>247</pre></div>248</div>249<p>will add, among other things, a <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> that looks like:</p>250<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">unit_price</span><span class="p">:</span> <span class="nb">float</span><span class="p">,</span> <span class="n">quantity_on_hand</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span><span class="p">):</span>251 <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>252 <span class="bp">self</span><span class="o">.</span><span class="n">unit_price</span> <span class="o">=</span> <span class="n">unit_price</span>253 <span class="bp">self</span><span class="o">.</span><span class="n">quantity_on_hand</span> <span class="o">=</span> <span class="n">quantity_on_hand</span>254</pre></div>255</div>256<p>Note that this method is automatically added to the class: it is not257directly specified in the <code class="xref py py-class docutils literal notranslate"><span class="pre">InventoryItem</span></code> definition shown above.</p>258<div class="versionadded">259<p><span class="versionmodified added">Added in version 3.7.</span></p>260</div>261<section id="module-contents">262<h2>Module contents<a class="headerlink" href="#module-contents" title="Link to this heading">¶</a></h2>263<dl class="py function">264<dt class="sig sig-object py" id="dataclasses.dataclass">265<span class="sig-prename descclassname"><span class="pre">@</span></span><span class="sig-prename descclassname"><span class="pre">dataclasses.</span></span><span class="sig-name descname"><span class="pre">dataclass</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">init</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">repr</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">eq</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">order</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">unsafe_hash</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">frozen</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">match_args</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">kw_only</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">slots</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">weakref_slot</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#dataclasses.dataclass" title="Link to this definition">¶</a></dt>266<dd><p>This function is a <a class="reference internal" href="../glossary.html#term-decorator"><span class="xref std std-term">decorator</span></a> that is used to add generated267<a class="reference internal" href="../glossary.html#term-special-method"><span class="xref std std-term">special methods</span></a> to classes, as described below.</p>268<p>The <code class="docutils literal notranslate"><span class="pre">@dataclass</span></code> decorator examines the class to find269<code class="docutils literal notranslate"><span class="pre">field</span></code>s. A <code class="docutils literal notranslate"><span class="pre">field</span></code> is defined as a class variable that has a270<a class="reference internal" href="../glossary.html#term-variable-annotation"><span class="xref std std-term">type annotation</span></a>. With two271exceptions described below, nothing in <code class="docutils literal notranslate"><span class="pre">@dataclass</span></code>272examines the type specified in the variable annotation.</p>273<p>The order of the fields in all of the generated methods is the274order in which they appear in the class definition.</p>275<p>The <code class="docutils literal notranslate"><span class="pre">@dataclass</span></code> decorator will add various “dunder” methods to276the class, described below. If any of the added methods already277exist in the class, the behavior depends on the parameter, as documented278below. The decorator returns the same class that it is called on; no new279class is created.</p>280<p>If <code class="docutils literal notranslate"><span class="pre">@dataclass</span></code> is used just as a simple decorator with no parameters,281it acts as if it has the default values documented in this282signature. That is, these three uses of <code class="docutils literal notranslate"><span class="pre">@dataclass</span></code> are283equivalent:</p>284<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>285<span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>286 <span class="o">...</span>287 288<span class="nd">@dataclass</span><span class="p">()</span>289<span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>290 <span class="o">...</span>291 292<span class="nd">@dataclass</span><span class="p">(</span><span class="n">init</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="nb">repr</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">eq</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">order</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">unsafe_hash</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">frozen</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>293 <span class="n">match_args</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">kw_only</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">slots</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">weakref_slot</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>294<span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>295 <span class="o">...</span>296</pre></div>297</div>298<p>The parameters to <code class="docutils literal notranslate"><span class="pre">@dataclass</span></code> are:</p>299<ul>300<li><p><em>init</em>: If true (the default), a <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> method will be301generated.</p>302<p>If the class already defines <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code>, this parameter is303ignored.</p>304</li>305<li><p><em>repr</em>: If true (the default), a <a class="reference internal" href="../reference/datamodel.html#object.__repr__" title="object.__repr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__repr__()</span></code></a> method will be306generated. The generated repr string will have the class name and307the name and repr of each field, in the order they are defined in308the class. Fields that are marked as being excluded from the repr309are not included. For example:310<code class="docutils literal notranslate"><span class="pre">InventoryItem(name='widget',</span> <span class="pre">unit_price=3.0,</span> <span class="pre">quantity_on_hand=10)</span></code>.</p>311<p>If the class already defines <code class="xref py py-meth docutils literal notranslate"><span class="pre">__repr__()</span></code>, this parameter is312ignored.</p>313</li>314<li><p><em>eq</em>: If true (the default), an <a class="reference internal" href="../reference/datamodel.html#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code></a> method will be315generated. This method compares the class as if it were a tuple316of its fields, in order. Both instances in the comparison must317be of the identical type.</p>318<p>If the class already defines <code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code>, this parameter is319ignored.</p>320</li>321<li><p><em>order</em>: If true (the default is <code class="docutils literal notranslate"><span class="pre">False</span></code>), <a class="reference internal" href="../reference/datamodel.html#object.__lt__" title="object.__lt__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__lt__()</span></code></a>,322<a class="reference internal" href="../reference/datamodel.html#object.__le__" title="object.__le__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__le__()</span></code></a>, <a class="reference internal" href="../reference/datamodel.html#object.__gt__" title="object.__gt__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__gt__()</span></code></a>, and <a class="reference internal" href="../reference/datamodel.html#object.__ge__" title="object.__ge__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__ge__()</span></code></a> methods will be323generated. These compare the class as if it were a tuple of its324fields, in order. Both instances in the comparison must be of the325identical type. If <em>order</em> is true and <em>eq</em> is false, a326<a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is raised.</p>327<p>If the class already defines any of <code class="xref py py-meth docutils literal notranslate"><span class="pre">__lt__()</span></code>,328<code class="xref py py-meth docutils literal notranslate"><span class="pre">__le__()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">__gt__()</span></code>, or <code class="xref py py-meth docutils literal notranslate"><span class="pre">__ge__()</span></code>, then329<a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> is raised.</p>330</li>331<li><p><em>unsafe_hash</em>: If true, force <code class="docutils literal notranslate"><span class="pre">dataclasses</span></code> to create a332<a class="reference internal" href="../reference/datamodel.html#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a> method, even though it may not be safe to do so.333Otherwise, generate a <code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code> method according to how334<em>eq</em> and <em>frozen</em> are set.335The default value is <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>336<p><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code> is used by built-in <a class="reference internal" href="functions.html#hash" title="hash"><code class="xref py py-meth docutils literal notranslate"><span class="pre">hash()</span></code></a>, and when objects are337added to hashed collections such as dictionaries and sets. Having a338<code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code> implies that instances of the class are immutable.339Mutability is a complicated property that depends on the programmer’s340intent, the existence and behavior of <code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code>, and the values of341the <em>eq</em> and <em>frozen</em> flags in the <code class="docutils literal notranslate"><span class="pre">@dataclass</span></code> decorator.</p>342<p>By default, <code class="docutils literal notranslate"><span class="pre">@dataclass</span></code> will not implicitly add a <a class="reference internal" href="../reference/datamodel.html#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a>343method unless it is safe to do so. Neither will it add or change an344existing explicitly defined <code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code> method. Setting the class345attribute <code class="docutils literal notranslate"><span class="pre">__hash__</span> <span class="pre">=</span> <span class="pre">None</span></code> has a specific meaning to Python, as346described in the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code> documentation.</p>347<p>If <code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code> is not explicitly defined, or if it is set to <code class="docutils literal notranslate"><span class="pre">None</span></code>,348then <code class="docutils literal notranslate"><span class="pre">@dataclass</span></code> <em>may</em> add an implicit <code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code> method.349Although not recommended, you can force <code class="docutils literal notranslate"><span class="pre">@dataclass</span></code> to create a350<code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code> method with <code class="docutils literal notranslate"><span class="pre">unsafe_hash=True</span></code>. This might be the case351if your class is logically immutable but can still be mutated.352This is a specialized use case and should be considered carefully.</p>353<p>Here are the rules governing implicit creation of a <code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code>354method. Note that you cannot both have an explicit <code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code>355method in your dataclass and set <code class="docutils literal notranslate"><span class="pre">unsafe_hash=True</span></code>; this will result356in a <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.</p>357<p>If <em>eq</em> and <em>frozen</em> are both true, by default <code class="docutils literal notranslate"><span class="pre">@dataclass</span></code> will358generate a <code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code> method for you. If <em>eq</em> is true and359<em>frozen</em> is false, <code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code> will be set to <code class="docutils literal notranslate"><span class="pre">None</span></code>, marking it360unhashable (which it is, since it is mutable). If <em>eq</em> is false,361<code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code> will be left untouched meaning the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code>362method of the superclass will be used (if the superclass is363<a class="reference internal" href="functions.html#object" title="object"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a>, this means it will fall back to id-based hashing).</p>364</li>365<li><p><em>frozen</em>: If true (the default is <code class="docutils literal notranslate"><span class="pre">False</span></code>), assigning to fields will366generate an exception. This emulates read-only frozen instances.367See the <a class="reference internal" href="#dataclasses-frozen"><span class="std std-ref">discussion</span></a> below.</p>368<p>If <a class="reference internal" href="../reference/datamodel.html#object.__setattr__" title="object.__setattr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__setattr__()</span></code></a> or <a class="reference internal" href="../reference/datamodel.html#object.__delattr__" title="object.__delattr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__delattr__()</span></code></a> is defined in the class369and <em>frozen</em> is true, then <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> is raised.</p>370</li>371<li><p><em>match_args</em>: If true (the default is <code class="docutils literal notranslate"><span class="pre">True</span></code>), the372<a class="reference internal" href="../reference/datamodel.html#object.__match_args__" title="object.__match_args__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__match_args__</span></code></a> tuple will be created from the list of373non keyword-only parameters to the generated <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> method (even if374<code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> is not generated, see above). If false, or if375<code class="xref py py-attr docutils literal notranslate"><span class="pre">__match_args__</span></code> is already defined in the class, then376<code class="xref py py-attr docutils literal notranslate"><span class="pre">__match_args__</span></code> will not be generated.</p></li>377</ul>378<blockquote>379<div><div class="versionadded">380<p><span class="versionmodified added">Added in version 3.10.</span></p>381</div>382</div></blockquote>383<ul>384<li><p><em>kw_only</em>: If true (the default value is <code class="docutils literal notranslate"><span class="pre">False</span></code>), then all385fields will be marked as keyword-only. If a field is marked as386keyword-only, then the only effect is that the <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a>387parameter generated from a keyword-only field must be specified388with a keyword when <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> is called. See the <a class="reference internal" href="../glossary.html#term-parameter"><span class="xref std std-term">parameter</span></a>389glossary entry for details. Also see the390<a class="reference internal" href="#dataclasses.KW_ONLY" title="dataclasses.KW_ONLY"><code class="xref py py-const docutils literal notranslate"><span class="pre">KW_ONLY</span></code></a> section.</p>391<p>Keyword-only fields are not included in <code class="xref py py-attr docutils literal notranslate"><span class="pre">__match_args__</span></code>.</p>392</li>393</ul>394<blockquote>395<div><div class="versionadded">396<p><span class="versionmodified added">Added in version 3.10.</span></p>397</div>398</div></blockquote>399<ul class="simple">400<li><p><em>slots</em>: If true (the default is <code class="docutils literal notranslate"><span class="pre">False</span></code>), <a class="reference internal" href="../reference/datamodel.html#object.__slots__" title="object.__slots__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__slots__</span></code></a> attribute401will be generated and new class will be returned instead of the original one.402If <code class="xref py py-attr docutils literal notranslate"><span class="pre">__slots__</span></code> is already defined in the class, then <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>403is raised.</p></li>404</ul>405<blockquote>406<div><div class="admonition warning">407<p class="admonition-title">Warning</p>408<p>Passing parameters to a base class <a class="reference internal" href="../reference/datamodel.html#object.__init_subclass__" title="object.__init_subclass__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init_subclass__()</span></code></a>409when using <code class="docutils literal notranslate"><span class="pre">slots=True</span></code> will result in a <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.410Either use <code class="docutils literal notranslate"><span class="pre">__init_subclass__</span></code> with no parameters411or use default values as a workaround.412See <a class="reference external" href="https://github.com/python/cpython/issues/91126">gh-91126</a> for full details.</p>413</div>414<div class="versionadded">415<p><span class="versionmodified added">Added in version 3.10.</span></p>416</div>417<div class="versionchanged">418<p><span class="versionmodified changed">Changed in version 3.11: </span>If a field name is already included in the <code class="xref py py-attr docutils literal notranslate"><span class="pre">__slots__</span></code>419of a base class, it will not be included in the generated <code class="xref py py-attr docutils literal notranslate"><span class="pre">__slots__</span></code>420to prevent <a class="reference internal" href="../reference/datamodel.html#datamodel-note-slots"><span class="std std-ref">overriding them</span></a>.421Therefore, do not use <code class="xref py py-attr docutils literal notranslate"><span class="pre">__slots__</span></code> to retrieve the field names of a422dataclass. Use <a class="reference internal" href="#dataclasses.fields" title="dataclasses.fields"><code class="xref py py-func docutils literal notranslate"><span class="pre">fields()</span></code></a> instead.423To be able to determine inherited slots,424base class <code class="xref py py-attr docutils literal notranslate"><span class="pre">__slots__</span></code> may be any iterable, but <em>not</em> an iterator.</p>425</div>426</div></blockquote>427<ul class="simple">428<li><p><em>weakref_slot</em>: If true (the default is <code class="docutils literal notranslate"><span class="pre">False</span></code>), add a slot429named “__weakref__”, which is required to make an instance430<a class="reference internal" href="weakref.html#weakref.ref" title="weakref.ref"><code class="xref py py-func docutils literal notranslate"><span class="pre">weakref-able</span></code></a>.431It is an error to specify <code class="docutils literal notranslate"><span class="pre">weakref_slot=True</span></code>432without also specifying <code class="docutils literal notranslate"><span class="pre">slots=True</span></code>.</p></li>433</ul>434<blockquote>435<div><div class="versionadded">436<p><span class="versionmodified added">Added in version 3.11.</span></p>437</div>438</div></blockquote>439<p><code class="docutils literal notranslate"><span class="pre">field</span></code>s may optionally specify a default value, using normal440Python syntax:</p>441<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>442<span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>443 <span class="n">a</span><span class="p">:</span> <span class="nb">int</span> <span class="c1"># 'a' has no default value</span>444 <span class="n">b</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span> <span class="c1"># assign a default value for 'b'</span>445</pre></div>446</div>447<p>In this example, both <code class="xref py py-attr docutils literal notranslate"><span class="pre">a</span></code> and <code class="xref py py-attr docutils literal notranslate"><span class="pre">b</span></code> will be included in the added448<a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> method, which will be defined as:</p>449<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">a</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">b</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span><span class="p">):</span>450</pre></div>451</div>452<p><a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> will be raised if a field without a default value453follows a field with a default value. This is true whether this454occurs in a single class, or as a result of class inheritance.</p>455</dd></dl>456 457<dl class="py function">458<dt class="sig sig-object py" id="dataclasses.field">459<span class="sig-prename descclassname"><span class="pre">dataclasses.</span></span><span class="sig-name descname"><span class="pre">field</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">default</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">MISSING</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">default_factory</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">MISSING</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">init</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">repr</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">hash</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">compare</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">metadata</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">kw_only</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">MISSING</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">doc</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#dataclasses.field" title="Link to this definition">¶</a></dt>460<dd><p>For common and simple use cases, no other functionality is461required. There are, however, some dataclass features that462require additional per-field information. To satisfy this need for463additional information, you can replace the default field value464with a call to the provided <code class="xref py py-func docutils literal notranslate"><span class="pre">field()</span></code> function. For example:</p>465<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>466<span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>467 <span class="n">mylist</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">int</span><span class="p">]</span> <span class="o">=</span> <span class="n">field</span><span class="p">(</span><span class="n">default_factory</span><span class="o">=</span><span class="nb">list</span><span class="p">)</span>468 469<span class="n">c</span> <span class="o">=</span> <span class="n">C</span><span class="p">()</span>470<span class="n">c</span><span class="o">.</span><span class="n">mylist</span> <span class="o">+=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">]</span>471</pre></div>472</div>473<p>As shown above, the <a class="reference internal" href="#dataclasses.MISSING" title="dataclasses.MISSING"><code class="xref py py-const docutils literal notranslate"><span class="pre">MISSING</span></code></a> value is a sentinel object used to474detect if some parameters are provided by the user. This sentinel is475used because <code class="docutils literal notranslate"><span class="pre">None</span></code> is a valid value for some parameters with476a distinct meaning. No code should directly use the <code class="xref py py-const docutils literal notranslate"><span class="pre">MISSING</span></code> value.</p>477<p>The parameters to <code class="xref py py-func docutils literal notranslate"><span class="pre">field()</span></code> are:</p>478<ul>479<li><p><em>default</em>: If provided, this will be the default value for this480field. This is needed because the <code class="xref py py-func docutils literal notranslate"><span class="pre">field()</span></code> call itself481replaces the normal position of the default value.</p></li>482<li><p><em>default_factory</em>: If provided, it must be a zero-argument483callable that will be called when a default value is needed for484this field. Among other purposes, this can be used to specify485fields with mutable default values, as discussed below. It is an486error to specify both <em>default</em> and <em>default_factory</em>.</p></li>487<li><p><em>init</em>: If true (the default), this field is included as a488parameter to the generated <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> method.</p></li>489<li><p><em>repr</em>: If true (the default), this field is included in the490string returned by the generated <a class="reference internal" href="../reference/datamodel.html#object.__repr__" title="object.__repr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__repr__()</span></code></a> method.</p></li>491<li><p><em>hash</em>: This can be a bool or <code class="docutils literal notranslate"><span class="pre">None</span></code>. If true, this field is492included in the generated <a class="reference internal" href="../reference/datamodel.html#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a> method. If false,493this field is excluded from the generated <code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code>.494If <code class="docutils literal notranslate"><span class="pre">None</span></code> (the default), use the value of <em>compare</em>: this would495normally be the expected behavior, since a field should be included496in the hash if it’s used for comparisons. Setting this value to anything497other than <code class="docutils literal notranslate"><span class="pre">None</span></code> is discouraged.</p>498<p>One possible reason to set <code class="docutils literal notranslate"><span class="pre">hash=False</span></code> but <code class="docutils literal notranslate"><span class="pre">compare=True</span></code>499would be if a field is expensive to compute a hash value for,500that field is needed for equality testing, and there are other501fields that contribute to the type’s hash value. Even if a field502is excluded from the hash, it will still be used for comparisons.</p>503</li>504<li><p><em>compare</em>: If true (the default), this field is included in the505generated equality and comparison methods (<a class="reference internal" href="../reference/datamodel.html#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code></a>,506<a class="reference internal" href="../reference/datamodel.html#object.__gt__" title="object.__gt__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__gt__()</span></code></a>, et al.).</p></li>507<li><p><em>metadata</em>: This can be a mapping or <code class="docutils literal notranslate"><span class="pre">None</span></code>. <code class="docutils literal notranslate"><span class="pre">None</span></code> is treated as508an empty dict. This value is wrapped in509<a class="reference internal" href="types.html#types.MappingProxyType" title="types.MappingProxyType"><code class="xref py py-func docutils literal notranslate"><span class="pre">MappingProxyType()</span></code></a> to make it read-only, and exposed510on the <a class="reference internal" href="#dataclasses.Field" title="dataclasses.Field"><code class="xref py py-class docutils literal notranslate"><span class="pre">Field</span></code></a> object. It is not used at all by Data511Classes, and is provided as a third-party extension mechanism.512Multiple third-parties can each have their own key, to use as a513namespace in the metadata.</p></li>514<li><p><em>kw_only</em>: If true, this field will be marked as keyword-only.515This is used when the generated <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> method’s516parameters are computed.</p>517<p>Keyword-only fields are also not included in <code class="xref py py-attr docutils literal notranslate"><span class="pre">__match_args__</span></code>.</p>518</li>519</ul>520<blockquote>521<div><div class="versionadded">522<p><span class="versionmodified added">Added in version 3.10.</span></p>523</div>524</div></blockquote>525<ul class="simple">526<li><p><em>doc</em>: optional docstring for this field.</p></li>527</ul>528<blockquote>529<div><div class="versionadded">530<p><span class="versionmodified added">Added in version 3.14.</span></p>531</div>532</div></blockquote>533<p>If the default value of a field is specified by a call to534<code class="xref py py-func docutils literal notranslate"><span class="pre">field()</span></code>, then the class attribute for this field will be535replaced by the specified <em>default</em> value. If <em>default</em> is not536provided, then the class attribute will be deleted. The intent is537that after the <a class="reference internal" href="#dataclasses.dataclass" title="dataclasses.dataclass"><code class="xref py py-deco docutils literal notranslate"><span class="pre">@dataclass</span></code></a> decorator runs, the class538attributes will all contain the default values for the fields, just539as if the default value itself were specified. For example,540after:</p>541<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>542<span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>543 <span class="n">x</span><span class="p">:</span> <span class="nb">int</span>544 <span class="n">y</span><span class="p">:</span> <span class="nb">int</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>545 <span class="n">z</span><span class="p">:</span> <span class="nb">int</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="mi">10</span><span class="p">)</span>546 <span class="n">t</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">20</span>547</pre></div>548</div>549<p>The class attribute <code class="xref py py-attr docutils literal notranslate"><span class="pre">C.z</span></code> will be <code class="docutils literal notranslate"><span class="pre">10</span></code>, the class attribute550<code class="xref py py-attr docutils literal notranslate"><span class="pre">C.t</span></code> will be <code class="docutils literal notranslate"><span class="pre">20</span></code>, and the class attributes <code class="xref py py-attr docutils literal notranslate"><span class="pre">C.x</span></code> and551<code class="xref py py-attr docutils literal notranslate"><span class="pre">C.y</span></code> will not be set.</p>552<div class="versionchanged">553<p><span class="versionmodified changed">Changed in version 3.15.0a6 (unreleased): </span>If <em>metadata</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, use an empty <a class="reference internal" href="stdtypes.html#frozendict" title="frozendict"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozendict</span></code></a>, instead554of a <a class="reference internal" href="types.html#types.MappingProxyType" title="types.MappingProxyType"><code class="xref py py-func docutils literal notranslate"><span class="pre">MappingProxyType()</span></code></a> of an empty <a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a>.</p>555</div>556</dd></dl>557 558<dl class="py class">559<dt class="sig sig-object py" id="dataclasses.Field">560<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">dataclasses.</span></span><span class="sig-name descname"><span class="pre">Field</span></span><a class="headerlink" href="#dataclasses.Field" title="Link to this definition">¶</a></dt>561<dd><p><code class="xref py py-class docutils literal notranslate"><span class="pre">Field</span></code> objects describe each defined field. These objects562are created internally, and are returned by the <a class="reference internal" href="#dataclasses.fields" title="dataclasses.fields"><code class="xref py py-func docutils literal notranslate"><span class="pre">fields()</span></code></a>563module-level method (see below). Users should never instantiate a564<code class="xref py py-class docutils literal notranslate"><span class="pre">Field</span></code> object directly. Its documented attributes are:</p>565<ul class="simple">566<li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code>: The name of the field.</p></li>567<li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code>: The type of the field.</p></li>568<li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">default</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">default_factory</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">init</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">repr</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">hash</span></code>,569<code class="xref py py-attr docutils literal notranslate"><span class="pre">compare</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">metadata</span></code>, and <code class="xref py py-attr docutils literal notranslate"><span class="pre">kw_only</span></code> have the identical570meaning and values as they do in the <a class="reference internal" href="#dataclasses.field" title="dataclasses.field"><code class="xref py py-func docutils literal notranslate"><span class="pre">field()</span></code></a> function.</p></li>571</ul>572<p>Other attributes may exist, but they are private and must not be573inspected or relied on.</p>574</dd></dl>575 576<dl class="py class">577<dt class="sig sig-object py" id="dataclasses.InitVar">578<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">dataclasses.</span></span><span class="sig-name descname"><span class="pre">InitVar</span></span><a class="headerlink" href="#dataclasses.InitVar" title="Link to this definition">¶</a></dt>579<dd><p><code class="docutils literal notranslate"><span class="pre">InitVar[T]</span></code> type annotations describe variables that are <a class="reference internal" href="#dataclasses-init-only-variables"><span class="std std-ref">init-only</span></a>. Fields annotated with <code class="xref py py-class docutils literal notranslate"><span class="pre">InitVar</span></code>580are considered pseudo-fields, and thus are neither returned by the581<a class="reference internal" href="#dataclasses.fields" title="dataclasses.fields"><code class="xref py py-func docutils literal notranslate"><span class="pre">fields()</span></code></a> function nor used in any way except adding them as582parameters to <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> and an optional583<a class="reference internal" href="#dataclasses.__post_init__" title="dataclasses.__post_init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__post_init__()</span></code></a>.</p>584</dd></dl>585 586<dl class="py function">587<dt class="sig sig-object py" id="dataclasses.fields">588<span class="sig-prename descclassname"><span class="pre">dataclasses.</span></span><span class="sig-name descname"><span class="pre">fields</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">class_or_instance</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#dataclasses.fields" title="Link to this definition">¶</a></dt>589<dd><p>Returns a tuple of <a class="reference internal" href="#dataclasses.Field" title="dataclasses.Field"><code class="xref py py-class docutils literal notranslate"><span class="pre">Field</span></code></a> objects that define the fields for this590dataclass. Accepts either a dataclass, or an instance of a dataclass.591Raises <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if not passed a dataclass or instance of one.592Does not return pseudo-fields which are <code class="docutils literal notranslate"><span class="pre">ClassVar</span></code> or <code class="docutils literal notranslate"><span class="pre">InitVar</span></code>.</p>593</dd></dl>594 595<dl class="py function">596<dt class="sig sig-object py" id="dataclasses.asdict">597<span class="sig-prename descclassname"><span class="pre">dataclasses.</span></span><span class="sig-name descname"><span class="pre">asdict</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">dict_factory</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">dict</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#dataclasses.asdict" title="Link to this definition">¶</a></dt>598<dd><p>Converts the dataclass <em>obj</em> to a dict (by using the599factory function <em>dict_factory</em>). Each dataclass is converted600to a dict of its fields, as <code class="docutils literal notranslate"><span class="pre">name:</span> <span class="pre">value</span></code> pairs. dataclasses, dicts,601lists, and tuples are recursed into. Other objects are copied with602<a class="reference internal" href="copy.html#copy.deepcopy" title="copy.deepcopy"><code class="xref py py-func docutils literal notranslate"><span class="pre">copy.deepcopy()</span></code></a>.</p>603<p>Example of using <code class="xref py py-func docutils literal notranslate"><span class="pre">asdict()</span></code> on nested dataclasses:</p>604<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>605<span class="k">class</span><span class="w"> </span><span class="nc">Point</span><span class="p">:</span>606 <span class="n">x</span><span class="p">:</span> <span class="nb">int</span>607 <span class="n">y</span><span class="p">:</span> <span class="nb">int</span>608 609<span class="nd">@dataclass</span>610<span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>611 <span class="n">mylist</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="n">Point</span><span class="p">]</span>612 613<span class="n">p</span> <span class="o">=</span> <span class="n">Point</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="mi">20</span><span class="p">)</span>614<span class="k">assert</span> <span class="n">asdict</span><span class="p">(</span><span class="n">p</span><span class="p">)</span> <span class="o">==</span> <span class="p">{</span><span class="s1">'x'</span><span class="p">:</span> <span class="mi">10</span><span class="p">,</span> <span class="s1">'y'</span><span class="p">:</span> <span class="mi">20</span><span class="p">}</span>615 616<span class="n">c</span> <span class="o">=</span> <span class="n">C</span><span class="p">([</span><span class="n">Point</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="n">Point</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="mi">4</span><span class="p">)])</span>617<span class="k">assert</span> <span class="n">asdict</span><span class="p">(</span><span class="n">c</span><span class="p">)</span> <span class="o">==</span> <span class="p">{</span><span class="s1">'mylist'</span><span class="p">:</span> <span class="p">[{</span><span class="s1">'x'</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span> <span class="s1">'y'</span><span class="p">:</span> <span class="mi">0</span><span class="p">},</span> <span class="p">{</span><span class="s1">'x'</span><span class="p">:</span> <span class="mi">10</span><span class="p">,</span> <span class="s1">'y'</span><span class="p">:</span> <span class="mi">4</span><span class="p">}]}</span>618</pre></div>619</div>620<p>To create a shallow copy, the following workaround may be used:</p>621<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="n">field</span><span class="o">.</span><span class="n">name</span><span class="p">:</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">field</span><span class="o">.</span><span class="n">name</span><span class="p">)</span> <span class="k">for</span> <span class="n">field</span> <span class="ow">in</span> <span class="n">fields</span><span class="p">(</span><span class="n">obj</span><span class="p">)}</span>622</pre></div>623</div>624<p><code class="xref py py-func docutils literal notranslate"><span class="pre">asdict()</span></code> raises <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if <em>obj</em> is not a dataclass625instance.</p>626</dd></dl>627 628<dl class="py function">629<dt class="sig sig-object py" id="dataclasses.astuple">630<span class="sig-prename descclassname"><span class="pre">dataclasses.</span></span><span class="sig-name descname"><span class="pre">astuple</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">tuple_factory</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">tuple</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#dataclasses.astuple" title="Link to this definition">¶</a></dt>631<dd><p>Converts the dataclass <em>obj</em> to a tuple (by using the632factory function <em>tuple_factory</em>). Each dataclass is converted633to a tuple of its field values. dataclasses, dicts, lists, and634tuples are recursed into. Other objects are copied with635<a class="reference internal" href="copy.html#copy.deepcopy" title="copy.deepcopy"><code class="xref py py-func docutils literal notranslate"><span class="pre">copy.deepcopy()</span></code></a>.</p>636<p>Continuing from the previous example:</p>637<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">assert</span> <span class="n">astuple</span><span class="p">(</span><span class="n">p</span><span class="p">)</span> <span class="o">==</span> <span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="mi">20</span><span class="p">)</span>638<span class="k">assert</span> <span class="n">astuple</span><span class="p">(</span><span class="n">c</span><span class="p">)</span> <span class="o">==</span> <span class="p">([(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="mi">4</span><span class="p">)],)</span>639</pre></div>640</div>641<p>To create a shallow copy, the following workaround may be used:</p>642<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nb">tuple</span><span class="p">(</span><span class="nb">getattr</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">field</span><span class="o">.</span><span class="n">name</span><span class="p">)</span> <span class="k">for</span> <span class="n">field</span> <span class="ow">in</span> <span class="n">dataclasses</span><span class="o">.</span><span class="n">fields</span><span class="p">(</span><span class="n">obj</span><span class="p">))</span>643</pre></div>644</div>645<p><code class="xref py py-func docutils literal notranslate"><span class="pre">astuple()</span></code> raises <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if <em>obj</em> is not a dataclass646instance.</p>647</dd></dl>648 649<dl class="py function">650<dt class="sig sig-object py" id="dataclasses.make_dataclass">651<span class="sig-prename descclassname"><span class="pre">dataclasses.</span></span><span class="sig-name descname"><span class="pre">make_dataclass</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">cls_name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fields</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">bases</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">()</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">namespace</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">init</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">repr</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">eq</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">order</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">unsafe_hash</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">frozen</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">match_args</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">kw_only</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">slots</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">weakref_slot</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">module</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">decorator</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">dataclass</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#dataclasses.make_dataclass" title="Link to this definition">¶</a></dt>652<dd><p>Creates a new dataclass with name <em>cls_name</em>, fields as defined653in <em>fields</em>, base classes as given in <em>bases</em>, and initialized654with a namespace as given in <em>namespace</em>. <em>fields</em> is an655iterable whose elements are each either <code class="docutils literal notranslate"><span class="pre">name</span></code>, <code class="docutils literal notranslate"><span class="pre">(name,</span> <span class="pre">type)</span></code>,656or <code class="docutils literal notranslate"><span class="pre">(name,</span> <span class="pre">type,</span> <span class="pre">Field)</span></code>. If just <code class="docutils literal notranslate"><span class="pre">name</span></code> is supplied,657<a class="reference internal" href="typing.html#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal notranslate"><span class="pre">typing.Any</span></code></a> is used for <code class="docutils literal notranslate"><span class="pre">type</span></code>. The values of <em>init</em>,658<em>repr</em>, <em>eq</em>, <em>order</em>, <em>unsafe_hash</em>, <em>frozen</em>,659<em>match_args</em>, <em>kw_only</em>, <em>slots</em>, and <em>weakref_slot</em> have660the same meaning as they do in <a class="reference internal" href="#dataclasses.dataclass" title="dataclasses.dataclass"><code class="xref py py-deco docutils literal notranslate"><span class="pre">@dataclass</span></code></a>.</p>661<p>If <em>module</em> is defined, the <code class="xref py py-attr docutils literal notranslate"><span class="pre">__module__</span></code> attribute662of the dataclass is set to that value.663By default, it is set to the module name of the caller.</p>664<p>The <em>decorator</em> parameter is a callable that will be used to create the dataclass.665It should take the class object as a first argument and the same keyword arguments666as <a class="reference internal" href="#dataclasses.dataclass" title="dataclasses.dataclass"><code class="xref py py-deco docutils literal notranslate"><span class="pre">@dataclass</span></code></a>. By default, the <code class="xref py py-deco docutils literal notranslate"><span class="pre">@dataclass</span></code>667function is used.</p>668<p>This function is not strictly required, because any Python669mechanism for creating a new class with <a class="reference internal" href="../reference/datamodel.html#object.__annotations__" title="object.__annotations__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__annotations__</span></code></a> can670then apply the <a class="reference internal" href="#dataclasses.dataclass" title="dataclasses.dataclass"><code class="xref py py-deco docutils literal notranslate"><span class="pre">@dataclass</span></code></a> function to convert that class to671a dataclass. This function is provided as a convenience. For672example:</p>673<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">C</span> <span class="o">=</span> <span class="n">make_dataclass</span><span class="p">(</span><span class="s1">'C'</span><span class="p">,</span>674 <span class="p">[(</span><span class="s1">'x'</span><span class="p">,</span> <span class="nb">int</span><span class="p">),</span>675 <span class="s1">'y'</span><span class="p">,</span>676 <span class="p">(</span><span class="s1">'z'</span><span class="p">,</span> <span class="nb">int</span><span class="p">,</span> <span class="n">field</span><span class="p">(</span><span class="n">default</span><span class="o">=</span><span class="mi">5</span><span class="p">))],</span>677 <span class="n">namespace</span><span class="o">=</span><span class="p">{</span><span class="s1">'add_one'</span><span class="p">:</span> <span class="k">lambda</span> <span class="bp">self</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">x</span> <span class="o">+</span> <span class="mi">1</span><span class="p">})</span>678</pre></div>679</div>680<p>Is equivalent to:</p>681<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>682<span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>683 <span class="n">x</span><span class="p">:</span> <span class="nb">int</span>684 <span class="n">y</span><span class="p">:</span> <span class="s1">'typing.Any'</span>685 <span class="n">z</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">5</span>686 687 <span class="k">def</span><span class="w"> </span><span class="nf">add_one</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>688 <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">x</span> <span class="o">+</span> <span class="mi">1</span>689</pre></div>690</div>691<div class="versionadded">692<p><span class="versionmodified added">Added in version 3.14: </span>Added the <em>decorator</em> parameter.</p>693</div>694</dd></dl>695 696<dl class="py function">697<dt class="sig sig-object py" id="dataclasses.replace">698<span class="sig-prename descclassname"><span class="pre">dataclasses.</span></span><span class="sig-name descname"><span class="pre">replace</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">changes</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#dataclasses.replace" title="Link to this definition">¶</a></dt>699<dd><p>Creates a new object of the same type as <em>obj</em>, replacing700fields with values from <em>changes</em>. If <em>obj</em> is not a Data701Class, raises <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>. If keys in <em>changes</em> are not702field names of the given dataclass, raises <code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code>.</p>703<p>The newly returned object is created by calling the <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a>704method of the dataclass. This ensures that705<a class="reference internal" href="#dataclasses.__post_init__" title="dataclasses.__post_init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__post_init__()</span></code></a>, if present, is also called.</p>706<p>Init-only variables without default values, if any exist, must be707specified on the call to <code class="xref py py-func docutils literal notranslate"><span class="pre">replace()</span></code> so that they can be passed to708<code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> and <a class="reference internal" href="#dataclasses.__post_init__" title="dataclasses.__post_init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__post_init__()</span></code></a>.</p>709<p>It is an error for <em>changes</em> to contain any fields that are710defined as having <code class="docutils literal notranslate"><span class="pre">init=False</span></code>. A <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> will be raised711in this case.</p>712<p>Be forewarned about how <code class="docutils literal notranslate"><span class="pre">init=False</span></code> fields work during a call to713<code class="xref py py-func docutils literal notranslate"><span class="pre">replace()</span></code>. They are not copied from the source object, but714rather are initialized in <a class="reference internal" href="#dataclasses.__post_init__" title="dataclasses.__post_init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__post_init__()</span></code></a>, if they’re715initialized at all. It is expected that <code class="docutils literal notranslate"><span class="pre">init=False</span></code> fields will716be rarely and judiciously used. If they are used, it might be wise717to have alternate class constructors, or perhaps a custom718<code class="xref py py-func docutils literal notranslate"><span class="pre">replace()</span></code> (or similarly named) method which handles instance719copying.</p>720<p>Dataclass instances are also supported by generic function <a class="reference internal" href="copy.html#copy.replace" title="copy.replace"><code class="xref py py-func docutils literal notranslate"><span class="pre">copy.replace()</span></code></a>.</p>721</dd></dl>722 723<dl class="py function">724<dt class="sig sig-object py" id="dataclasses.is_dataclass">725<span class="sig-prename descclassname"><span class="pre">dataclasses.</span></span><span class="sig-name descname"><span class="pre">is_dataclass</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#dataclasses.is_dataclass" title="Link to this definition">¶</a></dt>726<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if its parameter is a dataclass (including subclasses of a727dataclass) or an instance of one, otherwise return <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>728<p>If you need to know if a class is an instance of a dataclass (and729not a dataclass itself), then add a further check for <code class="docutils literal notranslate"><span class="pre">not</span>730<span class="pre">isinstance(obj,</span> <span class="pre">type)</span></code>:</p>731<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">is_dataclass_instance</span><span class="p">(</span><span class="n">obj</span><span class="p">):</span>732 <span class="k">return</span> <span class="n">is_dataclass</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span> <span class="ow">and</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="nb">type</span><span class="p">)</span>733</pre></div>734</div>735</dd></dl>736 737<dl class="py data">738<dt class="sig sig-object py" id="dataclasses.MISSING">739<span class="sig-prename descclassname"><span class="pre">dataclasses.</span></span><span class="sig-name descname"><span class="pre">MISSING</span></span><a class="headerlink" href="#dataclasses.MISSING" title="Link to this definition">¶</a></dt>740<dd><p>A sentinel value signifying a missing default or default_factory.</p>741</dd></dl>742 743<dl class="py data">744<dt class="sig sig-object py" id="dataclasses.KW_ONLY">745<span class="sig-prename descclassname"><span class="pre">dataclasses.</span></span><span class="sig-name descname"><span class="pre">KW_ONLY</span></span><a class="headerlink" href="#dataclasses.KW_ONLY" title="Link to this definition">¶</a></dt>746<dd><p>A sentinel value used as a type annotation. Any fields after a747pseudo-field with the type of <code class="xref py py-const docutils literal notranslate"><span class="pre">KW_ONLY</span></code> are marked as748keyword-only fields. Note that a pseudo-field of type749<code class="xref py py-const docutils literal notranslate"><span class="pre">KW_ONLY</span></code> is otherwise completely ignored. This includes the750name of such a field. By convention, a name of <code class="docutils literal notranslate"><span class="pre">_</span></code> is used for a751<code class="xref py py-const docutils literal notranslate"><span class="pre">KW_ONLY</span></code> field. Keyword-only fields signify752<a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> parameters that must be specified as keywords when753the class is instantiated.</p>754<p>In this example, the fields <code class="docutils literal notranslate"><span class="pre">y</span></code> and <code class="docutils literal notranslate"><span class="pre">z</span></code> will be marked as keyword-only fields:</p>755<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>756<span class="k">class</span><span class="w"> </span><span class="nc">Point</span><span class="p">:</span>757 <span class="n">x</span><span class="p">:</span> <span class="nb">float</span>758 <span class="n">_</span><span class="p">:</span> <span class="n">KW_ONLY</span>759 <span class="n">y</span><span class="p">:</span> <span class="nb">float</span>760 <span class="n">z</span><span class="p">:</span> <span class="nb">float</span>761 762<span class="n">p</span> <span class="o">=</span> <span class="n">Point</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="n">y</span><span class="o">=</span><span class="mf">1.5</span><span class="p">,</span> <span class="n">z</span><span class="o">=</span><span class="mf">2.0</span><span class="p">)</span>763</pre></div>764</div>765<p>In a single dataclass, it is an error to specify more than one766field whose type is <code class="xref py py-const docutils literal notranslate"><span class="pre">KW_ONLY</span></code>.</p>767<div class="versionadded">768<p><span class="versionmodified added">Added in version 3.10.</span></p>769</div>770</dd></dl>771 772<dl class="py exception">773<dt class="sig sig-object py" id="dataclasses.FrozenInstanceError">774<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">dataclasses.</span></span><span class="sig-name descname"><span class="pre">FrozenInstanceError</span></span><a class="headerlink" href="#dataclasses.FrozenInstanceError" title="Link to this definition">¶</a></dt>775<dd><p>Raised when an implicitly defined <a class="reference internal" href="../reference/datamodel.html#object.__setattr__" title="object.__setattr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__setattr__()</span></code></a> or776<a class="reference internal" href="../reference/datamodel.html#object.__delattr__" title="object.__delattr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__delattr__()</span></code></a> is called on a dataclass which was defined with777<code class="docutils literal notranslate"><span class="pre">frozen=True</span></code>. It is a subclass of <a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a>.</p>778</dd></dl>779 780</section>781<section id="post-init-processing">782<span id="id1"></span><h2>Post-init processing<a class="headerlink" href="#post-init-processing" title="Link to this heading">¶</a></h2>783<dl class="py function">784<dt class="sig sig-object py" id="dataclasses.__post_init__">785<span class="sig-prename descclassname"><span class="pre">dataclasses.</span></span><span class="sig-name descname"><span class="pre">__post_init__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#dataclasses.__post_init__" title="Link to this definition">¶</a></dt>786<dd><p>When defined on the class, it will be called by the generated787<a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a>, normally as <code class="xref py py-meth docutils literal notranslate"><span class="pre">self.__post_init__()</span></code>.788However, if any <code class="docutils literal notranslate"><span class="pre">InitVar</span></code> fields are defined, they will also be789passed to <code class="xref py py-meth docutils literal notranslate"><span class="pre">__post_init__()</span></code> in the order they were defined in the790class. If no <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> method is generated, then791<code class="xref py py-meth docutils literal notranslate"><span class="pre">__post_init__()</span></code> will not automatically be called.</p>792<p>Among other uses, this allows for initializing field values that793depend on one or more other fields. For example:</p>794<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>795<span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>796 <span class="n">a</span><span class="p">:</span> <span class="nb">float</span>797 <span class="n">b</span><span class="p">:</span> <span class="nb">float</span>798 <span class="n">c</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="n">field</span><span class="p">(</span><span class="n">init</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>799 800 <span class="k">def</span><span class="w"> </span><span class="nf">__post_init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>801 <span class="bp">self</span><span class="o">.</span><span class="n">c</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">a</span> <span class="o">+</span> <span class="bp">self</span><span class="o">.</span><span class="n">b</span>802</pre></div>803</div>804</dd></dl>805 806<p>The <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> method generated by <a class="reference internal" href="#dataclasses.dataclass" title="dataclasses.dataclass"><code class="xref py py-deco docutils literal notranslate"><span class="pre">@dataclass</span></code></a> does not call base807class <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> methods. If the base class has an <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> method808that has to be called, it is common to call this method in a809<a class="reference internal" href="#dataclasses.__post_init__" title="dataclasses.__post_init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__post_init__()</span></code></a> method:</p>810<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">Rectangle</span><span class="p">:</span>811 <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">height</span><span class="p">,</span> <span class="n">width</span><span class="p">):</span>812 <span class="bp">self</span><span class="o">.</span><span class="n">height</span> <span class="o">=</span> <span class="n">height</span>813 <span class="bp">self</span><span class="o">.</span><span class="n">width</span> <span class="o">=</span> <span class="n">width</span>814 815<span class="nd">@dataclass</span>816<span class="k">class</span><span class="w"> </span><span class="nc">Square</span><span class="p">(</span><span class="n">Rectangle</span><span class="p">):</span>817 <span class="n">side</span><span class="p">:</span> <span class="nb">float</span>818 819 <span class="k">def</span><span class="w"> </span><span class="nf">__post_init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>820 <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">side</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">side</span><span class="p">)</span>821</pre></div>822</div>823<p>Note, however, that in general the dataclass-generated <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> methods824don’t need to be called, since the derived dataclass will take care of825initializing all fields of any base class that is a dataclass itself.</p>826<p>See the section below on init-only variables for ways to pass827parameters to <code class="xref py py-meth docutils literal notranslate"><span class="pre">__post_init__()</span></code>. Also see the warning about how828<a class="reference internal" href="#dataclasses.replace" title="dataclasses.replace"><code class="xref py py-func docutils literal notranslate"><span class="pre">replace()</span></code></a> handles <code class="docutils literal notranslate"><span class="pre">init=False</span></code> fields.</p>829</section>830<section id="class-variables">831<span id="dataclasses-class-variables"></span><h2>Class variables<a class="headerlink" href="#class-variables" title="Link to this heading">¶</a></h2>832<p>One of the few places where <a class="reference internal" href="#dataclasses.dataclass" title="dataclasses.dataclass"><code class="xref py py-deco docutils literal notranslate"><span class="pre">@dataclass</span></code></a> actually inspects the type833of a field is to determine if a field is a class variable as defined834in <span class="target" id="index-2"></span><a class="pep reference external" href="https://peps.python.org/pep-0526/"><strong>PEP 526</strong></a>. It does this by checking if the type of the field is835<a class="reference internal" href="typing.html#typing.ClassVar" title="typing.ClassVar"><code class="xref py py-data docutils literal notranslate"><span class="pre">typing.ClassVar</span></code></a>. If a field is a <code class="docutils literal notranslate"><span class="pre">ClassVar</span></code>, it is excluded836from consideration as a field and is ignored by the dataclass837mechanisms. Such <code class="docutils literal notranslate"><span class="pre">ClassVar</span></code> pseudo-fields are not returned by the838module-level <a class="reference internal" href="#dataclasses.fields" title="dataclasses.fields"><code class="xref py py-func docutils literal notranslate"><span class="pre">fields()</span></code></a> function.</p>839</section>840<section id="init-only-variables">841<span id="dataclasses-init-only-variables"></span><h2>Init-only variables<a class="headerlink" href="#init-only-variables" title="Link to this heading">¶</a></h2>842<p>Another place where <a class="reference internal" href="#dataclasses.dataclass" title="dataclasses.dataclass"><code class="xref py py-deco docutils literal notranslate"><span class="pre">@dataclass</span></code></a> inspects a type annotation is to843determine if a field is an init-only variable. It does this by seeing844if the type of a field is of type <a class="reference internal" href="#dataclasses.InitVar" title="dataclasses.InitVar"><code class="xref py py-class docutils literal notranslate"><span class="pre">InitVar</span></code></a>. If a field845is an <code class="xref py py-class docutils literal notranslate"><span class="pre">InitVar</span></code>, it is considered a pseudo-field called an init-only846field. As it is not a true field, it is not returned by the847module-level <a class="reference internal" href="#dataclasses.fields" title="dataclasses.fields"><code class="xref py py-func docutils literal notranslate"><span class="pre">fields()</span></code></a> function. Init-only fields are added as848parameters to the generated <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> method, and are passed to849the optional <a class="reference internal" href="#dataclasses.__post_init__" title="dataclasses.__post_init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__post_init__()</span></code></a> method. They are not otherwise used850by dataclasses.</p>851<p>For example, suppose a field will be initialized from a database, if a852value is not provided when creating the class:</p>853<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>854<span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>855 <span class="n">i</span><span class="p">:</span> <span class="nb">int</span>856 <span class="n">j</span><span class="p">:</span> <span class="nb">int</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>857 <span class="n">database</span><span class="p">:</span> <span class="n">InitVar</span><span class="p">[</span><span class="n">DatabaseType</span> <span class="o">|</span> <span class="kc">None</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>858 859 <span class="k">def</span><span class="w"> </span><span class="nf">__post_init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">database</span><span class="p">):</span>860 <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">j</span> <span class="ow">is</span> <span class="kc">None</span> <span class="ow">and</span> <span class="n">database</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>861 <span class="bp">self</span><span class="o">.</span><span class="n">j</span> <span class="o">=</span> <span class="n">database</span><span class="o">.</span><span class="n">lookup</span><span class="p">(</span><span class="s1">'j'</span><span class="p">)</span>862 863<span class="n">c</span> <span class="o">=</span> <span class="n">C</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="n">database</span><span class="o">=</span><span class="n">my_database</span><span class="p">)</span>864</pre></div>865</div>866<p>In this case, <a class="reference internal" href="#dataclasses.fields" title="dataclasses.fields"><code class="xref py py-func docutils literal notranslate"><span class="pre">fields()</span></code></a> will return <a class="reference internal" href="#dataclasses.Field" title="dataclasses.Field"><code class="xref py py-class docutils literal notranslate"><span class="pre">Field</span></code></a> objects for <code class="xref py py-attr docutils literal notranslate"><span class="pre">i</span></code> and867<code class="xref py py-attr docutils literal notranslate"><span class="pre">j</span></code>, but not for <code class="xref py py-attr docutils literal notranslate"><span class="pre">database</span></code>.</p>868</section>869<section id="frozen-instances">870<span id="dataclasses-frozen"></span><h2>Frozen instances<a class="headerlink" href="#frozen-instances" title="Link to this heading">¶</a></h2>871<p>It is not possible to create truly immutable Python objects. However,872by passing <code class="docutils literal notranslate"><span class="pre">frozen=True</span></code> to the <a class="reference internal" href="#dataclasses.dataclass" title="dataclasses.dataclass"><code class="xref py py-deco docutils literal notranslate"><span class="pre">@dataclass</span></code></a> decorator you can873emulate immutability. In that case, dataclasses will add874<a class="reference internal" href="../reference/datamodel.html#object.__setattr__" title="object.__setattr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__setattr__()</span></code></a> and <a class="reference internal" href="../reference/datamodel.html#object.__delattr__" title="object.__delattr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__delattr__()</span></code></a> methods to the class. These875methods will raise a <a class="reference internal" href="#dataclasses.FrozenInstanceError" title="dataclasses.FrozenInstanceError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FrozenInstanceError</span></code></a> when invoked.</p>876<p>There is a tiny performance penalty when using <code class="docutils literal notranslate"><span class="pre">frozen=True</span></code>:877<a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> cannot use simple assignment to initialize fields, and878must use <code class="xref py py-meth docutils literal notranslate"><span class="pre">object.__setattr__()</span></code>.</p>879</section>880<section id="inheritance">881<span id="dataclasses-inheritance"></span><h2>Inheritance<a class="headerlink" href="#inheritance" title="Link to this heading">¶</a></h2>882<p>When the dataclass is being created by the <a class="reference internal" href="#dataclasses.dataclass" title="dataclasses.dataclass"><code class="xref py py-deco docutils literal notranslate"><span class="pre">@dataclass</span></code></a> decorator,883it looks through all of the class’s base classes in reverse MRO (that884is, starting at <a class="reference internal" href="functions.html#object" title="object"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a>) and, for each dataclass that it finds,885adds the fields from that base class to an ordered mapping of fields.886After all of the base class fields are added, it adds its own fields887to the ordered mapping. All of the generated methods will use this888combined, calculated ordered mapping of fields. Because the fields889are in insertion order, derived classes override base classes. An890example:</p>891<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>892<span class="k">class</span><span class="w"> </span><span class="nc">Base</span><span class="p">:</span>893 <span class="n">x</span><span class="p">:</span> <span class="n">Any</span> <span class="o">=</span> <span class="mf">15.0</span>894 <span class="n">y</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span>895 896<span class="nd">@dataclass</span>897<span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>898 <span class="n">z</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">10</span>899 <span class="n">x</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">15</span>900</pre></div>901</div>902<p>The final list of fields is, in order, <code class="xref py py-attr docutils literal notranslate"><span class="pre">x</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">y</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">z</span></code>. The final903type of <code class="xref py py-attr docutils literal notranslate"><span class="pre">x</span></code> is <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>, as specified in class <code class="xref py py-class docutils literal notranslate"><span class="pre">C</span></code>.</p>904<p>The generated <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> method for <code class="xref py py-class docutils literal notranslate"><span class="pre">C</span></code> will look like:</p>905<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">x</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">15</span><span class="p">,</span> <span class="n">y</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">z</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">10</span><span class="p">):</span>906</pre></div>907</div>908</section>909<section id="re-ordering-of-keyword-only-parameters-in-init">910<h2>Re-ordering of keyword-only parameters in <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code><a class="headerlink" href="#re-ordering-of-keyword-only-parameters-in-init" title="Link to this heading">¶</a></h2>911<p>After the parameters needed for <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> are computed, any912keyword-only parameters are moved to come after all regular913(non-keyword-only) parameters. This is a requirement of how914keyword-only parameters are implemented in Python: they must come915after non-keyword-only parameters.</p>916<p>In this example, <code class="xref py py-attr docutils literal notranslate"><span class="pre">Base.y</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">Base.w</span></code>, and <code class="xref py py-attr docutils literal notranslate"><span class="pre">D.t</span></code> are keyword-only917fields, and <code class="xref py py-attr docutils literal notranslate"><span class="pre">Base.x</span></code> and <code class="xref py py-attr docutils literal notranslate"><span class="pre">D.z</span></code> are regular fields:</p>918<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>919<span class="k">class</span><span class="w"> </span><span class="nc">Base</span><span class="p">:</span>920 <span class="n">x</span><span class="p">:</span> <span class="n">Any</span> <span class="o">=</span> <span class="mf">15.0</span>921 <span class="n">_</span><span class="p">:</span> <span class="n">KW_ONLY</span>922 <span class="n">y</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span>923 <span class="n">w</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">1</span>924 925<span class="nd">@dataclass</span>926<span class="k">class</span><span class="w"> </span><span class="nc">D</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>927 <span class="n">z</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">10</span>928 <span class="n">t</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="n">field</span><span class="p">(</span><span class="n">kw_only</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>929</pre></div>930</div>931<p>The generated <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> method for <code class="xref py py-class docutils literal notranslate"><span class="pre">D</span></code> will look like:</p>932<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">x</span><span class="p">:</span> <span class="n">Any</span> <span class="o">=</span> <span class="mf">15.0</span><span class="p">,</span> <span class="n">z</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">10</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">y</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">w</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span> <span class="n">t</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span><span class="p">):</span>933</pre></div>934</div>935<p>Note that the parameters have been re-ordered from how they appear in936the list of fields: parameters derived from regular fields are937followed by parameters derived from keyword-only fields.</p>938<p>The relative ordering of keyword-only parameters is maintained in the939re-ordered <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> parameter list.</p>940</section>941<section id="default-factory-functions">942<h2>Default factory functions<a class="headerlink" href="#default-factory-functions" title="Link to this heading">¶</a></h2>943<p>If a <a class="reference internal" href="#dataclasses.field" title="dataclasses.field"><code class="xref py py-func docutils literal notranslate"><span class="pre">field()</span></code></a> specifies a <em>default_factory</em>, it is called with944zero arguments when a default value for the field is needed. For945example, to create a new instance of a list, use:</p>946<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">mylist</span><span class="p">:</span> <span class="nb">list</span> <span class="o">=</span> <span class="n">field</span><span class="p">(</span><span class="n">default_factory</span><span class="o">=</span><span class="nb">list</span><span class="p">)</span>947</pre></div>948</div>949<p>If a field is excluded from <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> (using <code class="docutils literal notranslate"><span class="pre">init=False</span></code>)950and the field also specifies <em>default_factory</em>, then the default951factory function will always be called from the generated952<code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> function. This happens because there is no other953way to give the field an initial value.</p>954</section>955<section id="mutable-default-values">956<h2>Mutable default values<a class="headerlink" href="#mutable-default-values" title="Link to this heading">¶</a></h2>957<p>Python stores default member variable values in class attributes.958Consider this example, not using dataclasses:</p>959<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>960 <span class="n">x</span> <span class="o">=</span> <span class="p">[]</span>961 <span class="k">def</span><span class="w"> </span><span class="nf">add</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">element</span><span class="p">):</span>962 <span class="bp">self</span><span class="o">.</span><span class="n">x</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">element</span><span class="p">)</span>963 964<span class="n">o1</span> <span class="o">=</span> <span class="n">C</span><span class="p">()</span>965<span class="n">o2</span> <span class="o">=</span> <span class="n">C</span><span class="p">()</span>966<span class="n">o1</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>967<span class="n">o2</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>968<span class="k">assert</span> <span class="n">o1</span><span class="o">.</span><span class="n">x</span> <span class="o">==</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">]</span>969<span class="k">assert</span> <span class="n">o1</span><span class="o">.</span><span class="n">x</span> <span class="ow">is</span> <span class="n">o2</span><span class="o">.</span><span class="n">x</span>970</pre></div>971</div>972<p>Note that the two instances of class <code class="xref py py-class docutils literal notranslate"><span class="pre">C</span></code> share the same class973variable <code class="xref py py-attr docutils literal notranslate"><span class="pre">x</span></code>, as expected.</p>974<p>Using dataclasses, <em>if</em> this code was valid:</p>975<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>976<span class="k">class</span><span class="w"> </span><span class="nc">D</span><span class="p">:</span>977 <span class="n">x</span><span class="p">:</span> <span class="nb">list</span> <span class="o">=</span> <span class="p">[]</span> <span class="c1"># This code raises ValueError</span>978 <span class="k">def</span><span class="w"> </span><span class="nf">add</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">element</span><span class="p">):</span>979 <span class="bp">self</span><span class="o">.</span><span class="n">x</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">element</span><span class="p">)</span>980</pre></div>981</div>982<p>it would generate code similar to:</p>983<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">D</span><span class="p">:</span>984 <span class="n">x</span> <span class="o">=</span> <span class="p">[]</span>985 <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">x</span><span class="o">=</span><span class="n">x</span><span class="p">):</span>986 <span class="bp">self</span><span class="o">.</span><span class="n">x</span> <span class="o">=</span> <span class="n">x</span>987 <span class="k">def</span><span class="w"> </span><span class="nf">add</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">element</span><span class="p">):</span>988 <span class="bp">self</span><span class="o">.</span><span class="n">x</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">element</span><span class="p">)</span>989 990<span class="k">assert</span> <span class="n">D</span><span class="p">()</span><span class="o">.</span><span class="n">x</span> <span class="ow">is</span> <span class="n">D</span><span class="p">()</span><span class="o">.</span><span class="n">x</span>991</pre></div>992</div>993<p>This has the same issue as the original example using class <code class="xref py py-class docutils literal notranslate"><span class="pre">C</span></code>.994That is, two instances of class <code class="xref py py-class docutils literal notranslate"><span class="pre">D</span></code> that do not specify a value995for <code class="xref py py-attr docutils literal notranslate"><span class="pre">x</span></code> when creating a class instance will share the same copy996of <code class="xref py py-attr docutils literal notranslate"><span class="pre">x</span></code>. Because dataclasses just use normal Python class997creation they also share this behavior. There is no general way998for Data Classes to detect this condition. Instead, the999<a class="reference internal" href="#dataclasses.dataclass" title="dataclasses.dataclass"><code class="xref py py-deco docutils literal notranslate"><span class="pre">@dataclass</span></code></a> decorator will raise a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> if it1000detects an unhashable default parameter. The assumption is that if1001a value is unhashable, it is mutable. This is a partial solution,1002but it does protect against many common errors.</p>1003<p>Using default factory functions is a way to create new instances of1004mutable types as default values for fields:</p>1005<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>1006<span class="k">class</span><span class="w"> </span><span class="nc">D</span><span class="p">:</span>1007 <span class="n">x</span><span class="p">:</span> <span class="nb">list</span> <span class="o">=</span> <span class="n">field</span><span class="p">(</span><span class="n">default_factory</span><span class="o">=</span><span class="nb">list</span><span class="p">)</span>1008 1009<span class="k">assert</span> <span class="n">D</span><span class="p">()</span><span class="o">.</span><span class="n">x</span> <span class="ow">is</span> <span class="ow">not</span> <span class="n">D</span><span class="p">()</span><span class="o">.</span><span class="n">x</span>1010</pre></div>1011</div>1012<div class="versionchanged">1013<p><span class="versionmodified changed">Changed in version 3.11: </span>Instead of looking for and disallowing objects of type <a class="reference internal" href="stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a>,1014<a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a>, or <a class="reference internal" href="stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a>, unhashable objects are now not allowed as1015default values. Unhashability is used to approximate1016mutability.</p>1017</div>1018</section>1019<section id="descriptor-typed-fields">1020<h2>Descriptor-typed fields<a class="headerlink" href="#descriptor-typed-fields" title="Link to this heading">¶</a></h2>1021<p>Fields that are assigned <a class="reference internal" href="../reference/datamodel.html#descriptors"><span class="std std-ref">descriptor objects</span></a> as their1022default value have the following special behaviors:</p>1023<ul class="simple">1024<li><p>The value for the field passed to the dataclass’s <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> method is1025passed to the descriptor’s <a class="reference internal" href="../reference/datamodel.html#object.__set__" title="object.__set__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__set__()</span></code></a> method rather than overwriting the1026descriptor object.</p></li>1027<li><p>Similarly, when getting or setting the field, the descriptor’s1028<a class="reference internal" href="../reference/datamodel.html#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code></a> or <code class="xref py py-meth docutils literal notranslate"><span class="pre">__set__()</span></code> method is called rather than returning or1029overwriting the descriptor object.</p></li>1030<li><p>To determine whether a field contains a default value, <a class="reference internal" href="#dataclasses.dataclass" title="dataclasses.dataclass"><code class="xref py py-deco docutils literal notranslate"><span class="pre">@dataclass</span></code></a>1031will call the descriptor’s <code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code> method using its class access1032form: <code class="docutils literal notranslate"><span class="pre">descriptor.__get__(obj=None,</span> <span class="pre">type=cls)</span></code>. If the1033descriptor returns a value in this case, it will be used as the1034field’s default. On the other hand, if the descriptor raises1035<a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a> in this situation, no default value will be1036provided for the field.</p></li>1037</ul>1038<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">IntConversionDescriptor</span><span class="p">:</span>1039 <span class="k">def</span><span class="w"> </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="p">,</span> <span class="n">default</span><span class="p">):</span>1040 <span class="bp">self</span><span class="o">.</span><span class="n">_default</span> <span class="o">=</span> <span class="n">default</span>1041 1042 <span class="k">def</span><span class="w"> </span><span class="nf">__set_name__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">owner</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>1043 <span class="bp">self</span><span class="o">.</span><span class="n">_name</span> <span class="o">=</span> <span class="s2">"_"</span> <span class="o">+</span> <span class="n">name</span>1044 1045 <span class="k">def</span><span class="w"> </span><span class="fm">__get__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="nb">type</span><span class="p">):</span>1046 <span class="k">if</span> <span class="n">obj</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>1047 <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_default</span>1048 1049 <span class="k">return</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">obj</span><span class="p">,</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">_default</span><span class="p">)</span>1050 1051 <span class="k">def</span><span class="w"> </span><span class="fm">__set__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>1052 <span class="nb">setattr</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">_name</span><span class="p">,</span> <span class="nb">int</span><span class="p">(</span><span class="n">value</span><span class="p">))</span>1053 1054<span class="nd">@dataclass</span>1055<span class="k">class</span><span class="w"> </span><span class="nc">InventoryItem</span><span class="p">:</span>1056 <span class="n">quantity_on_hand</span><span class="p">:</span> <span class="n">IntConversionDescriptor</span> <span class="o">=</span> <span class="n">IntConversionDescriptor</span><span class="p">(</span><span class="n">default</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>1057 1058<span class="n">i</span> <span class="o">=</span> <span class="n">InventoryItem</span><span class="p">()</span>1059<span class="nb">print</span><span class="p">(</span><span class="n">i</span><span class="o">.</span><span class="n">quantity_on_hand</span><span class="p">)</span> <span class="c1"># 100</span>1060<span class="n">i</span><span class="o">.</span><span class="n">quantity_on_hand</span> <span class="o">=</span> <span class="mf">2.5</span> <span class="c1"># calls __set__ with 2.5</span>1061<span class="nb">print</span><span class="p">(</span><span class="n">i</span><span class="o">.</span><span class="n">quantity_on_hand</span><span class="p">)</span> <span class="c1"># 2</span>1062</pre></div>1063</div>1064<p>Note that if a field is annotated with a descriptor type, but is not assigned1065a descriptor object as its default value, the field will act like a normal1066field.</p>1067</section>1068</section>1069 1070 1071 <div class="clearer"></div>1072 </div>1073 </div>1074 </div>1075 <div class="sphinxsidebar" role="navigation" aria-label="Main">1076 <div class="sphinxsidebarwrapper">1077 <div>1078 <h3><a href="../contents.html">Table of Contents</a></h3>1079 <ul>1080<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dataclasses</span></code> — Data Classes</a><ul>1081<li><a class="reference internal" href="#module-contents">Module contents</a></li>1082<li><a class="reference internal" href="#post-init-processing">Post-init processing</a></li>1083<li><a class="reference internal" href="#class-variables">Class variables</a></li>1084<li><a class="reference internal" href="#init-only-variables">Init-only variables</a></li>1085<li><a class="reference internal" href="#frozen-instances">Frozen instances</a></li>1086<li><a class="reference internal" href="#inheritance">Inheritance</a></li>1087<li><a class="reference internal" href="#re-ordering-of-keyword-only-parameters-in-init">Re-ordering of keyword-only parameters in <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a></li>1088<li><a class="reference internal" href="#default-factory-functions">Default factory functions</a></li>1089<li><a class="reference internal" href="#mutable-default-values">Mutable default values</a></li>1090<li><a class="reference internal" href="#descriptor-typed-fields">Descriptor-typed fields</a></li>1091</ul>1092</li>1093</ul>1094 1095 </div>1096 <div>1097 <h4>Previous topic</h4>1098 <p class="topless"><a href="warnings.html"1099 title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">warnings</span></code> — Warning control</a></p>1100 </div>1101 <div>1102 <h4>Next topic</h4>1103 <p class="topless"><a href="contextlib.html"1104 title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">contextlib</span></code> — Utilities for <code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code>-statement contexts</a></p>1105 </div>1106 <script>1107 document.addEventListener('DOMContentLoaded', () => {1108 const title = document.querySelector('meta[property="og:title"]').content;1109 const elements = document.querySelectorAll('.improvepage');1110 const pageurl = window.location.href.split('?')[0];1111 elements.forEach(element => {1112 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));1113 url.searchParams.set('pagetitle', title);1114 url.searchParams.set('pageurl', pageurl);1115 url.searchParams.set('pagesource', "library/dataclasses.rst");1116 element.href = url.toString();1117 });1118 });1119 </script>1120 <div role="note" aria-label="source link">1121 <h3>This page</h3>1122 <ul class="this-page-menu">1123 <li><a href="../bugs.html">Report a bug</a></li>1124 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>1125 <li>1126 <a href="https://github.com/python/cpython/blob/main/Doc/library/dataclasses.rst?plain=1"1127 rel="nofollow">Show source1128 </a>1129 </li>1130 1131 </ul>1132 </div>1133 </div>1134<div id="sidebarbutton" title="Collapse sidebar">1135<span>«</span>1136</div>1137 1138 </div>1139 <div class="clearer"></div>1140 </div> 1141 <div class="related" role="navigation" aria-label="Related">1142 <h3>Navigation</h3>1143 <ul>1144 <li class="right" style="margin-right: 10px">1145 <a href="../genindex.html" title="General Index"1146 >index</a></li>1147 <li class="right" >1148 <a href="../py-modindex.html" title="Python Module Index"1149 >modules</a> |</li>1150 <li class="right" >1151 <a href="contextlib.html" title="contextlib — Utilities for with-statement contexts"1152 >next</a> |</li>1153 <li class="right" >1154 <a href="warnings.html" title="warnings — Warning control"1155 >previous</a> |</li>1156 1157 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>1158 <li><a href="https://www.python.org/">Python</a> »</li>1159 <li class="switchers">1160 <div class="language_switcher_placeholder"></div>1161 <div class="version_switcher_placeholder"></div>1162 </li>1163 <li>1164 1165 </li>1166 <li id="cpython-language-and-version">1167 <a href="../index.html">3.15.0a6 Documentation</a> »1168 </li>1169 1170 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>1171 <li class="nav-item nav-item-2"><a href="python.html" >Python Runtime Services</a> »</li>1172 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">dataclasses</span></code> — Data Classes</a></li>1173 <li class="right">1174 1175 1176 <div class="inline-search" role="search">1177 <form class="inline-search" action="../search.html" method="get">1178 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">1179 <input type="submit" value="Go">1180 </form>1181 </div>1182 |1183 </li>1184 <li class="right">1185<label class="theme-selector-label">1186 Theme1187 <select class="theme-selector" oninput="activateTheme(this.value)">1188 <option value="auto" selected>Auto</option>1189 <option value="light">Light</option>1190 <option value="dark">Dark</option>1191 </select>1192</label> |</li>1193 1194 </ul>1195 </div> 1196 <div class="footer">1197 © <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.1198 <br>1199 This page is licensed under the Python Software Foundation License Version 2.1200 <br>