bunny-lab/Borealis-Github-Replica
1
0
Fork 0
mirror of https://github.com/bunny-lab-io/Borealis.git synced 2025-10-28 07:41:58 -06:00
Code Issues Packages Projects Releases Wiki Activity
Files
e71b845c9acf46abc7ce8324d931e7f90c8113e0
Borealis-Github-Replica/Dependencies/Python/Doc/html/library/dataclasses.html

1165 lines
124 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta property="og:title" content="dataclasses — Data Classes" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://docs.python.org/3/library/dataclasses.html" />
<meta property="og:site_name" content="Python documentation" />
<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..." />
<meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />
<meta property="og:image:alt" content="Python documentation" />
<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..." />
<meta property="og:image:width" content="200">
<meta property="og:image:height" content="200">
<meta name="theme-color" content="#3776ab">
<title>dataclasses — Data Classes &#8212; Python 3.13.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=23252803" />
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />
<script src="../_static/documentation_options.js?v=5d57ca2d"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.13.3 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="contextlib — Utilities for with-statement contexts" href="contextlib.html" />
<link rel="prev" title="warnings — Warning control" href="warnings.html" />
<link rel="canonical" href="https://docs.python.org/3/library/dataclasses.html">
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/menu.js"></script>
<script type="text/javascript" src="../_static/search-focus.js"></script>
<script type="text/javascript" src="../_static/themetoggle.js"></script>
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
<meta name="readthedocs-addons-api-version" content="1">
</head>
<body>
<div class="mobile-nav">
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
<nav class="nav-content" role="navigation">
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<span class="nav-items-wrapper">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Python logo"/>
</a>
<span class="version_switcher_placeholder"></span>
<form role="search" class="search" action="../search.html" method="get">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
<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>
</svg>
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />
<input type="submit" value="Go"/>
</form>
</span>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label>
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<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>
<li><a class="reference internal" href="#module-contents">Module contents</a></li>
<li><a class="reference internal" href="#post-init-processing">Post-init processing</a></li>
<li><a class="reference internal" href="#class-variables">Class variables</a></li>
<li><a class="reference internal" href="#init-only-variables">Init-only variables</a></li>
<li><a class="reference internal" href="#frozen-instances">Frozen instances</a></li>
<li><a class="reference internal" href="#inheritance">Inheritance</a></li>
<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>
<li><a class="reference internal" href="#default-factory-functions">Default factory functions</a></li>
<li><a class="reference internal" href="#mutable-default-values">Mutable default values</a></li>
<li><a class="reference internal" href="#descriptor-typed-fields">Descriptor-typed fields</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="warnings.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">warnings</span></code> — Warning control</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="contextlib.html"
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>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/main/Doc/library/dataclasses.rst"
rel="nofollow">Show Source
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="contextlib.html" title="contextlib — Utilities for with-statement contexts"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="warnings.html" title="warnings — Warning control"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.13.3 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="python.html" accesskey="U">Python Runtime Services</a> &#187;</li>
<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>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />
<input type="submit" value="Go" />
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-dataclasses">
<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>
<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.13/Lib/dataclasses.py">Lib/dataclasses.py</a></p>
<hr class="docutils" />
<p>This module provides a decorator and functions for automatically
adding 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> and
<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 described
in <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>
<p>The member variables to use in these generated methods are defined
using <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>
<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>
<span class="nd">@dataclass</span>
<span class="k">class</span><span class="w"> </span><span class="nc">InventoryItem</span><span class="p">:</span>
<span class="w"> </span><span class="sd">&quot;&quot;&quot;Class for keeping track of an item in inventory.&quot;&quot;&quot;</span>
<span class="n">name</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">unit_price</span><span class="p">:</span> <span class="nb">float</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="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">-&gt;</span> <span class="nb">float</span><span class="p">:</span>
<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>
</pre></div>
</div>
<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>
<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>
<span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>
<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>
<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>
</pre></div>
</div>
<p>Note that this method is automatically added to the class: it is not
directly specified in the <code class="xref py py-class docutils literal notranslate"><span class="pre">InventoryItem</span></code> definition shown above.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.7.</span></p>
</div>
<section id="module-contents">
<h2>Module contents<a class="headerlink" href="#module-contents" title="Link to this heading"></a></h2>
<dl class="py function">
<dt class="sig sig-object py" id="dataclasses.dataclass">
<span class="sig-prename descclassname"><span class="pre">&#64;</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>
<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 generated
<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>
<p>The <code class="docutils literal notranslate"><span class="pre">&#64;dataclass</span></code> decorator examines the class to find
<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 a
<a class="reference internal" href="../glossary.html#term-variable-annotation"><span class="xref std std-term">type annotation</span></a>. With two
exceptions described below, nothing in <code class="docutils literal notranslate"><span class="pre">&#64;dataclass</span></code>
examines the type specified in the variable annotation.</p>
<p>The order of the fields in all of the generated methods is the
order in which they appear in the class definition.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">&#64;dataclass</span></code> decorator will add various “dunder” methods to
the class, described below. If any of the added methods already
exist in the class, the behavior depends on the parameter, as documented
below. The decorator returns the same class that it is called on; no new
class is created.</p>
<p>If <code class="docutils literal notranslate"><span class="pre">&#64;dataclass</span></code> is used just as a simple decorator with no parameters,
it acts as if it has the default values documented in this
signature. That is, these three uses of <code class="docutils literal notranslate"><span class="pre">&#64;dataclass</span></code> are
equivalent:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>
<span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>
<span class="o">...</span>
<span class="nd">@dataclass</span><span class="p">()</span>
<span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>
<span class="o">...</span>
<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>
<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>
<span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>
<span class="o">...</span>
</pre></div>
</div>
<p>The parameters to <code class="docutils literal notranslate"><span class="pre">&#64;dataclass</span></code> are:</p>
<ul>
<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 be
generated.</p>
<p>If the class already defines <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code>, this parameter is
ignored.</p>
</li>
<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 be
generated. The generated repr string will have the class name and
the name and repr of each field, in the order they are defined in
the class. Fields that are marked as being excluded from the repr
are not included. For example:
<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>
<p>If the class already defines <code class="xref py py-meth docutils literal notranslate"><span class="pre">__repr__()</span></code>, this parameter is
ignored.</p>
</li>
<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 be
generated. This method compares the class as if it were a tuple
of its fields, in order. Both instances in the comparison must
be of the identical type.</p>
<p>If the class already defines <code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code>, this parameter is
ignored.</p>
</li>
<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>,
<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 be
generated. These compare the class as if it were a tuple of its
fields, in order. Both instances in the comparison must be of the
identical type. If <em>order</em> is true and <em>eq</em> is false, 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> is raised.</p>
<p>If the class already defines any of <code class="xref py py-meth docutils literal notranslate"><span class="pre">__lt__()</span></code>,
<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>, 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>
</li>
<li><p><em>unsafe_hash</em>: If <code class="docutils literal notranslate"><span class="pre">False</span></code> (the default), 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> method
is generated according to how <em>eq</em> and <em>frozen</em> are set.</p>
<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 are
added to hashed collections such as dictionaries and sets. Having a
<code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code> implies that instances of the class are immutable.
Mutability is a complicated property that depends on the programmer’s
intent, the existence and behavior of <code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code>, and the values of
the <em>eq</em> and <em>frozen</em> flags in the <code class="docutils literal notranslate"><span class="pre">&#64;dataclass</span></code> decorator.</p>
<p>By default, <code class="docutils literal notranslate"><span class="pre">&#64;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>
method unless it is safe to do so. Neither will it add or change an
existing explicitly defined <code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code> method. Setting the class
attribute <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, as
described in the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code> documentation.</p>
<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>,
then <code class="docutils literal notranslate"><span class="pre">&#64;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.
Although not recommended, you can force <code class="docutils literal notranslate"><span class="pre">&#64;dataclass</span></code> to create a
<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 case
if your class is logically immutable but can still be mutated.
This is a specialized use case and should be considered carefully.</p>
<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>
method. Note that you cannot both have an explicit <code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code>
method in your dataclass and set <code class="docutils literal notranslate"><span class="pre">unsafe_hash=True</span></code>; this 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>.</p>
<p>If <em>eq</em> and <em>frozen</em> are both true, by default <code class="docutils literal notranslate"><span class="pre">&#64;dataclass</span></code> will
generate 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 and
<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 it
unhashable (which it is, since it is mutable). If <em>eq</em> is false,
<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>
method of the superclass will be used (if the superclass is
<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>
</li>
<li><p><em>frozen</em>: If true (the default is <code class="docutils literal notranslate"><span class="pre">False</span></code>), assigning to fields will
generate an exception. This emulates read-only frozen instances. 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 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> is raised. See the discussion below.</p></li>
<li><p><em>match_args</em>: If true (the default is <code class="docutils literal notranslate"><span class="pre">True</span></code>), the
<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 of
non 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 if
<code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> is not generated, see above). If false, or if
<code class="xref py py-attr docutils literal notranslate"><span class="pre">__match_args__</span></code> is already defined in the class, then
<code class="xref py py-attr docutils literal notranslate"><span class="pre">__match_args__</span></code> will not be generated.</p></li>
</ul>
<blockquote>
<div><div class="versionadded">
<p><span class="versionmodified added">Added in version 3.10.</span></p>
</div>
</div></blockquote>
<ul>
<li><p><em>kw_only</em>: If true (the default value is <code class="docutils literal notranslate"><span class="pre">False</span></code>), then all
fields will be marked as keyword-only. If a field is marked as
keyword-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>
parameter generated from a keyword-only field must be specified
with 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>
glossary entry for details. Also see the
<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>
<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>
</li>
</ul>
<blockquote>
<div><div class="versionadded">
<p><span class="versionmodified added">Added in version 3.10.</span></p>
</div>
</div></blockquote>
<ul class="simple">
<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> attribute
will be generated and new class will be returned instead of the original one.
If <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>
is raised.</p></li>
</ul>
<blockquote>
<div><div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Calling no-arg <a class="reference internal" href="functions.html#super" title="super"><code class="xref py py-func docutils literal notranslate"><span class="pre">super()</span></code></a> in dataclasses using <code class="docutils literal notranslate"><span class="pre">slots=True</span></code>
will result in the following exception being raised:
<code class="docutils literal notranslate"><span class="pre">TypeError:</span> <span class="pre">super(type,</span> <span class="pre">obj):</span> <span class="pre">obj</span> <span class="pre">must</span> <span class="pre">be</span> <span class="pre">an</span> <span class="pre">instance</span> <span class="pre">or</span> <span class="pre">subtype</span> <span class="pre">of</span> <span class="pre">type</span></code>.
The two-arg <a class="reference internal" href="functions.html#super" title="super"><code class="xref py py-func docutils literal notranslate"><span class="pre">super()</span></code></a> is a valid workaround.
See <a class="reference external" href="https://github.com/python/cpython/issues/90562">gh-90562</a> for full details.</p>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<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>
when 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>.
Either use <code class="docutils literal notranslate"><span class="pre">__init_subclass__</span></code> with no parameters
or use default values as a workaround.
See <a class="reference external" href="https://github.com/python/cpython/issues/91126">gh-91126</a> for full details.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.10.</span></p>
</div>
<div class="versionchanged">
<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>
of 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>
to prevent <a class="reference internal" href="../reference/datamodel.html#datamodel-note-slots"><span class="std std-ref">overriding them</span></a>.
Therefore, do not use <code class="xref py py-attr docutils literal notranslate"><span class="pre">__slots__</span></code> to retrieve the field names of a
dataclass. 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.
To be able to determine inherited slots,
base 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>
</div>
</div></blockquote>
<ul class="simple">
<li><p><em>weakref_slot</em>: If true (the default is <code class="docutils literal notranslate"><span class="pre">False</span></code>), add a slot
named “__weakref__”, which is required to make an instance
<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>.
It is an error to specify <code class="docutils literal notranslate"><span class="pre">weakref_slot=True</span></code>
without also specifying <code class="docutils literal notranslate"><span class="pre">slots=True</span></code>.</p></li>
</ul>
<blockquote>
<div><div class="versionadded">
<p><span class="versionmodified added">Added in version 3.11.</span></p>
</div>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">field</span></code>s may optionally specify a default value, using normal
Python syntax:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>
<span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>
<span class="n">a</span><span class="p">:</span> <span class="nb">int</span> <span class="c1"># &#39;a&#39; has no default value</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="c1"># assign a default value for &#39;b&#39;</span>
</pre></div>
</div>
<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 added
<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>
<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>
</pre></div>
</div>
<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 value
follows a field with a default value. This is true whether this
occurs in a single class, or as a result of class inheritance.</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="dataclasses.field">
<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><span class="sig-paren">)</span><a class="headerlink" href="#dataclasses.field" title="Link to this definition"></a></dt>
<dd><p>For common and simple use cases, no other functionality is
required. There are, however, some dataclass features that
require additional per-field information. To satisfy this need for
additional information, you can replace the default field value
with a call to the provided <code class="xref py py-func docutils literal notranslate"><span class="pre">field()</span></code> function. For example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>
<span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>
<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>
<span class="n">c</span> <span class="o">=</span> <span class="n">C</span><span class="p">()</span>
<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>
</pre></div>
</div>
<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 to
detect if some parameters are provided by the user. This sentinel is
used because <code class="docutils literal notranslate"><span class="pre">None</span></code> is a valid value for some parameters with
a distinct meaning. No code should directly use 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.</p>
<p>The parameters to <code class="xref py py-func docutils literal notranslate"><span class="pre">field()</span></code> are:</p>
<ul>
<li><p><em>default</em>: If provided, this will be the default value for this
field. This is needed because the <code class="xref py py-func docutils literal notranslate"><span class="pre">field()</span></code> call itself
replaces the normal position of the default value.</p></li>
<li><p><em>default_factory</em>: If provided, it must be a zero-argument
callable that will be called when a default value is needed for
this field. Among other purposes, this can be used to specify
fields with mutable default values, as discussed below. It is an
error to specify both <em>default</em> and <em>default_factory</em>.</p></li>
<li><p><em>init</em>: If true (the default), this field is included as a
parameter 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>
<li><p><em>repr</em>: If true (the default), this field is included in the
string 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>
<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 is
included 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,
this field is excluded from 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>.
If <code class="docutils literal notranslate"><span class="pre">None</span></code> (the default), use the value of <em>compare</em>: this would
normally be the expected behavior, since a field should be included
in the hash if it’s used for comparisons. Setting this value to anything
other than <code class="docutils literal notranslate"><span class="pre">None</span></code> is discouraged.</p>
<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>
would be if a field is expensive to compute a hash value for,
that field is needed for equality testing, and there are other
fields that contribute to the type’s hash value. Even if a field
is excluded from the hash, it will still be used for comparisons.</p>
</li>
<li><p><em>compare</em>: If true (the default), this field is included in the
generated 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>,
<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>
<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 as
an empty dict. This value is wrapped in
<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 exposed
on 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 Data
Classes, and is provided as a third-party extension mechanism.
Multiple third-parties can each have their own key, to use as a
namespace in the metadata.</p></li>
<li><p><em>kw_only</em>: If true, this field will be marked as keyword-only.
This 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’s
parameters are computed.</p>
<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>
</li>
</ul>
<blockquote>
<div><div class="versionadded">
<p><span class="versionmodified added">Added in version 3.10.</span></p>
</div>
</div></blockquote>
<p>If the default value of a field is specified by a call to
<code class="xref py py-func docutils literal notranslate"><span class="pre">field()</span></code>, then the class attribute for this field will be
replaced by the specified <em>default</em> value. If <em>default</em> is not
provided, then the class attribute will be deleted. The intent is
that after the <a class="reference internal" href="#dataclasses.dataclass" title="dataclasses.dataclass"><code class="xref py py-func docutils literal notranslate"><span class="pre">&#64;dataclass</span></code></a> decorator runs, the class
attributes will all contain the default values for the fields, just
as if the default value itself were specified. For example,
after:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>
<span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>
<span class="n">x</span><span class="p">:</span> <span class="nb">int</span>
<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>
<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>
<span class="n">t</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">20</span>
</pre></div>
</div>
<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 attribute
<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> and
<code class="xref py py-attr docutils literal notranslate"><span class="pre">C.y</span></code> will not be set.</p>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="dataclasses.Field">
<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>
<dd><p><code class="xref py py-class docutils literal notranslate"><span class="pre">Field</span></code> objects describe each defined field. These objects
are 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>
module-level method (see below). Users should never instantiate a
<code class="xref py py-class docutils literal notranslate"><span class="pre">Field</span></code> object directly. Its documented attributes are:</p>
<ul class="simple">
<li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code>: The name of the field.</p></li>
<li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code>: The type of the field.</p></li>
<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>,
<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 identical
meaning 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>
</ul>
<p>Other attributes may exist, but they are private and must not be
inspected or relied on.</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="dataclasses.fields">
<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>
<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 this
dataclass. Accepts either a dataclass, or an instance of a dataclass.
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 not passed a dataclass or instance of one.
Does 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>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="dataclasses.asdict">
<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>
<dd><p>Converts the dataclass <em>obj</em> to a dict (by using the
factory function <em>dict_factory</em>). Each dataclass is converted
to 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,
lists, and tuples are recursed into. Other objects are copied with
<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>
<p>Example of using <code class="xref py py-func docutils literal notranslate"><span class="pre">asdict()</span></code> on nested dataclasses:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>
<span class="k">class</span><span class="w"> </span><span class="nc">Point</span><span class="p">:</span>
<span class="n">x</span><span class="p">:</span> <span class="nb">int</span>
<span class="n">y</span><span class="p">:</span> <span class="nb">int</span>
<span class="nd">@dataclass</span>
<span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>
<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>
<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>
<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">&#39;x&#39;</span><span class="p">:</span> <span class="mi">10</span><span class="p">,</span> <span class="s1">&#39;y&#39;</span><span class="p">:</span> <span class="mi">20</span><span class="p">}</span>
<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>
<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">&#39;mylist&#39;</span><span class="p">:</span> <span class="p">[{</span><span class="s1">&#39;x&#39;</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span> <span class="s1">&#39;y&#39;</span><span class="p">:</span> <span class="mi">0</span><span class="p">},</span> <span class="p">{</span><span class="s1">&#39;x&#39;</span><span class="p">:</span> <span class="mi">10</span><span class="p">,</span> <span class="s1">&#39;y&#39;</span><span class="p">:</span> <span class="mi">4</span><span class="p">}]}</span>
</pre></div>
</div>
<p>To create a shallow copy, the following workaround may be used:</p>
<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>
</pre></div>
</div>
<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 dataclass
instance.</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="dataclasses.astuple">
<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>
<dd><p>Converts the dataclass <em>obj</em> to a tuple (by using the
factory function <em>tuple_factory</em>). Each dataclass is converted
to a tuple of its field values. dataclasses, dicts, lists, and
tuples are recursed into. Other objects are copied with
<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>
<p>Continuing from the previous example:</p>
<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>
<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>
</pre></div>
</div>
<p>To create a shallow copy, the following workaround may be used:</p>
<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>
</pre></div>
</div>
<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 dataclass
instance.</p>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="dataclasses.make_dataclass">
<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><span class="sig-paren">)</span><a class="headerlink" href="#dataclasses.make_dataclass" title="Link to this definition"></a></dt>
<dd><p>Creates a new dataclass with name <em>cls_name</em>, fields as defined
in <em>fields</em>, base classes as given in <em>bases</em>, and initialized
with a namespace as given in <em>namespace</em>. <em>fields</em> is an
iterable 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>,
or <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,
<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>,
<em>repr</em>, <em>eq</em>, <em>order</em>, <em>unsafe_hash</em>, <em>frozen</em>,
<em>match_args</em>, <em>kw_only</em>, <em>slots</em>, and <em>weakref_slot</em> have
the same meaning as they do in <a class="reference internal" href="#dataclasses.dataclass" title="dataclasses.dataclass"><code class="xref py py-func docutils literal notranslate"><span class="pre">&#64;dataclass</span></code></a>.</p>
<p>If <em>module</em> is defined, the <code class="xref py py-attr docutils literal notranslate"><span class="pre">__module__</span></code> attribute
of the dataclass is set to that value.
By default, it is set to the module name of the caller.</p>
<p>This function is not strictly required, because any Python
mechanism for creating a new class with <code class="xref py py-attr docutils literal notranslate"><span class="pre">__annotations__</span></code> can
then apply the <a class="reference internal" href="#dataclasses.dataclass" title="dataclasses.dataclass"><code class="xref py py-func docutils literal notranslate"><span class="pre">&#64;dataclass</span></code></a> function to convert that class to
a dataclass. This function is provided as a convenience. For
example:</p>
<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">&#39;C&#39;</span><span class="p">,</span>
<span class="p">[(</span><span class="s1">&#39;x&#39;</span><span class="p">,</span> <span class="nb">int</span><span class="p">),</span>
<span class="s1">&#39;y&#39;</span><span class="p">,</span>
<span class="p">(</span><span class="s1">&#39;z&#39;</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>
<span class="n">namespace</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;add_one&#39;</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>
</pre></div>
</div>
<p>Is equivalent to:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>
<span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>
<span class="n">x</span><span class="p">:</span> <span class="nb">int</span>
<span class="n">y</span><span class="p">:</span> <span class="s1">&#39;typing.Any&#39;</span>
<span class="n">z</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">5</span>
<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>
<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>
</pre></div>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="dataclasses.replace">
<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>
<dd><p>Creates a new object of the same type as <em>obj</em>, replacing
fields with values from <em>changes</em>. If <em>obj</em> is not a Data
Class, 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 not
field names of the given dataclass, 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>.</p>
<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>
method of the dataclass. This ensures that
<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>
<p>Init-only variables without default values, if any exist, must be
specified 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 to
<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>
<p>It is an error for <em>changes</em> to contain any fields that are
defined 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 raised
in this case.</p>
<p>Be forewarned about how <code class="docutils literal notranslate"><span class="pre">init=False</span></code> fields work during a call to
<code class="xref py py-func docutils literal notranslate"><span class="pre">replace()</span></code>. They are not copied from the source object, but
rather 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’re
initialized at all. It is expected that <code class="docutils literal notranslate"><span class="pre">init=False</span></code> fields will
be rarely and judiciously used. If they are used, it might be wise
to have alternate class constructors, or perhaps a custom
<code class="xref py py-func docutils literal notranslate"><span class="pre">replace()</span></code> (or similarly named) method which handles instance
copying.</p>
<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>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py" id="dataclasses.is_dataclass">
<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>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if its parameter is a dataclass (including subclasses of a
dataclass) or an instance of one, otherwise return <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
<p>If you need to know if a class is an instance of a dataclass (and
not a dataclass itself), then add a further check for <code class="docutils literal notranslate"><span class="pre">not</span>
<span class="pre">isinstance(obj,</span> <span class="pre">type)</span></code>:</p>
<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>
<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>
</pre></div>
</div>
</dd></dl>
<dl class="py data">
<dt class="sig sig-object py" id="dataclasses.MISSING">
<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>
<dd><p>A sentinel value signifying a missing default or default_factory.</p>
</dd></dl>
<dl class="py data">
<dt class="sig sig-object py" id="dataclasses.KW_ONLY">
<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>
<dd><p>A sentinel value used as a type annotation. Any fields after a
pseudo-field with the type of <code class="xref py py-const docutils literal notranslate"><span class="pre">KW_ONLY</span></code> are marked as
keyword-only fields. Note that a pseudo-field of type
<code class="xref py py-const docutils literal notranslate"><span class="pre">KW_ONLY</span></code> is otherwise completely ignored. This includes the
name of such a field. By convention, a name of <code class="docutils literal notranslate"><span class="pre">_</span></code> is used for a
<code class="xref py py-const docutils literal notranslate"><span class="pre">KW_ONLY</span></code> field. Keyword-only fields signify
<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 when
the class is instantiated.</p>
<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>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>
<span class="k">class</span><span class="w"> </span><span class="nc">Point</span><span class="p">:</span>
<span class="n">x</span><span class="p">:</span> <span class="nb">float</span>
<span class="n">_</span><span class="p">:</span> <span class="n">KW_ONLY</span>
<span class="n">y</span><span class="p">:</span> <span class="nb">float</span>
<span class="n">z</span><span class="p">:</span> <span class="nb">float</span>
<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>
</pre></div>
</div>
<p>In a single dataclass, it is an error to specify more than one
field whose type is <code class="xref py py-const docutils literal notranslate"><span class="pre">KW_ONLY</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.10.</span></p>
</div>
</dd></dl>
<dl class="py exception">
<dt class="sig sig-object py" id="dataclasses.FrozenInstanceError">
<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>
<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> 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 called on a dataclass which was defined with
<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>
</dd></dl>
</section>
<section id="post-init-processing">
<span id="id1"></span><h2>Post-init processing<a class="headerlink" href="#post-init-processing" title="Link to this heading"></a></h2>
<dl class="py function">
<dt class="sig sig-object py" id="dataclasses.__post_init__">
<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>
<dd><p>When defined on the class, it will be called by 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>, normally as <code class="xref py py-meth docutils literal notranslate"><span class="pre">self.__post_init__()</span></code>.
However, if any <code class="docutils literal notranslate"><span class="pre">InitVar</span></code> fields are defined, they will also be
passed to <code class="xref py py-meth docutils literal notranslate"><span class="pre">__post_init__()</span></code> in the order they were defined in the
class. If no <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> method is generated, then
<code class="xref py py-meth docutils literal notranslate"><span class="pre">__post_init__()</span></code> will not automatically be called.</p>
<p>Among other uses, this allows for initializing field values that
depend on one or more other fields. For example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>
<span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>
<span class="n">a</span><span class="p">:</span> <span class="nb">float</span>
<span class="n">b</span><span class="p">:</span> <span class="nb">float</span>
<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>
<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="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>
</pre></div>
</div>
</dd></dl>
<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-func docutils literal notranslate"><span class="pre">&#64;dataclass</span></code></a> does not call base
class <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> method
that has to be called, it is common to call this method in a
<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>
<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>
<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>
<span class="bp">self</span><span class="o">.</span><span class="n">height</span> <span class="o">=</span> <span class="n">height</span>
<span class="bp">self</span><span class="o">.</span><span class="n">width</span> <span class="o">=</span> <span class="n">width</span>
<span class="nd">@dataclass</span>
<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>
<span class="n">side</span><span class="p">:</span> <span class="nb">float</span>
<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="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>
</pre></div>
</div>
<p>Note, however, that in general the dataclass-generated <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> methods
don’t need to be called, since the derived dataclass will take care of
initializing all fields of any base class that is a dataclass itself.</p>
<p>See the section below on init-only variables for ways to pass
parameters to <code class="xref py py-meth docutils literal notranslate"><span class="pre">__post_init__()</span></code>. Also see the warning about how
<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>
</section>
<section id="class-variables">
<span id="dataclasses-class-variables"></span><h2>Class variables<a class="headerlink" href="#class-variables" title="Link to this heading"></a></h2>
<p>One of the few places where <a class="reference internal" href="#dataclasses.dataclass" title="dataclasses.dataclass"><code class="xref py py-func docutils literal notranslate"><span class="pre">&#64;dataclass</span></code></a> actually inspects the type
of a field is to determine if a field is a class variable as defined
in <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 is
<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 excluded
from consideration as a field and is ignored by the dataclass
mechanisms. Such <code class="docutils literal notranslate"><span class="pre">ClassVar</span></code> pseudo-fields are not returned by the
module-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>
</section>
<section id="init-only-variables">
<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>
<p>Another place where <a class="reference internal" href="#dataclasses.dataclass" title="dataclasses.dataclass"><code class="xref py py-func docutils literal notranslate"><span class="pre">&#64;dataclass</span></code></a> inspects a type annotation is to
determine if a field is an init-only variable. It does this by seeing
if the type of a field is of type <code class="docutils literal notranslate"><span class="pre">dataclasses.InitVar</span></code>. If a field
is an <code class="docutils literal notranslate"><span class="pre">InitVar</span></code>, it is considered a pseudo-field called an init-only
field. As it is not a true field, it is not returned by the
module-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 as
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, and are passed to
the 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 used
by dataclasses.</p>
<p>For example, suppose a field will be initialized from a database, if a
value is not provided when creating the class:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>
<span class="k">class</span><span class="w"> </span><span class="nc">C</span><span class="p">:</span>
<span class="n">i</span><span class="p">:</span> <span class="nb">int</span>
<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>
<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>
<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>
<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>
<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">&#39;j&#39;</span><span class="p">)</span>
<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>
</pre></div>
</div>
<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> and
<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>
</section>
<section id="frozen-instances">
<span id="dataclasses-frozen"></span><h2>Frozen instances<a class="headerlink" href="#frozen-instances" title="Link to this heading"></a></h2>
<p>It is not possible to create truly immutable Python objects. However,
by 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-func docutils literal notranslate"><span class="pre">&#64;dataclass</span></code></a> decorator you can
emulate immutability. In that case, dataclasses will add
<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. These
methods 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>
<p>There is a tiny performance penalty when using <code class="docutils literal notranslate"><span class="pre">frozen=True</span></code>:
<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, and
must use <code class="xref py py-meth docutils literal notranslate"><span class="pre">object.__setattr__()</span></code>.</p>
</section>
<section id="inheritance">
<span id="dataclasses-inheritance"></span><h2>Inheritance<a class="headerlink" href="#inheritance" title="Link to this heading"></a></h2>
<p>When the dataclass is being created by the <a class="reference internal" href="#dataclasses.dataclass" title="dataclasses.dataclass"><code class="xref py py-func docutils literal notranslate"><span class="pre">&#64;dataclass</span></code></a> decorator,
it looks through all of the class’s base classes in reverse MRO (that
is, 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,
adds the fields from that base class to an ordered mapping of fields.
After all of the base class fields are added, it adds its own fields
to the ordered mapping. All of the generated methods will use this
combined, calculated ordered mapping of fields. Because the fields
are in insertion order, derived classes override base classes. An
example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>
<span class="k">class</span><span class="w"> </span><span class="nc">Base</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="n">y</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span>
<span class="nd">@dataclass</span>
<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>
<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="n">x</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">15</span>
</pre></div>
</div>
<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 final
type 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>
<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>
<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>
</pre></div>
</div>
</section>
<section id="re-ordering-of-keyword-only-parameters-in-init">
<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>
<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, any
keyword-only parameters are moved to come after all regular
(non-keyword-only) parameters. This is a requirement of how
keyword-only parameters are implemented in Python: they must come
after non-keyword-only parameters.</p>
<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-only
fields, 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>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>
<span class="k">class</span><span class="w"> </span><span class="nc">Base</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="n">_</span><span class="p">:</span> <span class="n">KW_ONLY</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="n">w</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">1</span>
<span class="nd">@dataclass</span>
<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>
<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="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>
</pre></div>
</div>
<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>
<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>
</pre></div>
</div>
<p>Note that the parameters have been re-ordered from how they appear in
the list of fields: parameters derived from regular fields are
followed by parameters derived from keyword-only fields.</p>
<p>The relative ordering of keyword-only parameters is maintained in the
re-ordered <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> parameter list.</p>
</section>
<section id="default-factory-functions">
<h2>Default factory functions<a class="headerlink" href="#default-factory-functions" title="Link to this heading"></a></h2>
<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 with
zero arguments when a default value for the field is needed. For
example, to create a new instance of a list, use:</p>
<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>
</pre></div>
</div>
<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>)
and the field also specifies <em>default_factory</em>, then the default
factory function will always be called from the generated
<code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> function. This happens because there is no other
way to give the field an initial value.</p>
</section>
<section id="mutable-default-values">
<h2>Mutable default values<a class="headerlink" href="#mutable-default-values" title="Link to this heading"></a></h2>
<p>Python stores default member variable values in class attributes.
Consider this example, not using dataclasses:</p>
<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>
<span class="n">x</span> <span class="o">=</span> <span class="p">[]</span>
<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>
<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>
<span class="n">o1</span> <span class="o">=</span> <span class="n">C</span><span class="p">()</span>
<span class="n">o2</span> <span class="o">=</span> <span class="n">C</span><span class="p">()</span>
<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>
<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>
<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>
<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>
</pre></div>
</div>
<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 class
variable <code class="xref py py-attr docutils literal notranslate"><span class="pre">x</span></code>, as expected.</p>
<p>Using dataclasses, <em>if</em> this code was valid:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>
<span class="k">class</span><span class="w"> </span><span class="nc">D</span><span class="p">:</span>
<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>
<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>
<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>
</pre></div>
</div>
<p>it would generate code similar to:</p>
<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>
<span class="n">x</span> <span class="o">=</span> <span class="p">[]</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="o">=</span><span class="n">x</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="n">x</span>
<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>
<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>
<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>
</pre></div>
</div>
<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>.
That 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 value
for <code class="xref py py-attr docutils literal notranslate"><span class="pre">x</span></code> when creating a class instance will share the same copy
of <code class="xref py py-attr docutils literal notranslate"><span class="pre">x</span></code>. Because dataclasses just use normal Python class
creation they also share this behavior. There is no general way
for Data Classes to detect this condition. Instead, the
<a class="reference internal" href="#dataclasses.dataclass" title="dataclasses.dataclass"><code class="xref py py-func docutils literal notranslate"><span class="pre">&#64;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 it
detects an unhashable default parameter. The assumption is that if
a value is unhashable, it is mutable. This is a partial solution,
but it does protect against many common errors.</p>
<p>Using default factory functions is a way to create new instances of
mutable types as default values for fields:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@dataclass</span>
<span class="k">class</span><span class="w"> </span><span class="nc">D</span><span class="p">:</span>
<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>
<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>
</pre></div>
</div>
<div class="versionchanged">
<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>,
<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 as
default values. Unhashability is used to approximate
mutability.</p>
</div>
</section>
<section id="descriptor-typed-fields">
<h2>Descriptor-typed fields<a class="headerlink" href="#descriptor-typed-fields" title="Link to this heading"></a></h2>
<p>Fields that are assigned <a class="reference internal" href="../reference/datamodel.html#descriptors"><span class="std std-ref">descriptor objects</span></a> as their
default value have the following special behaviors:</p>
<ul class="simple">
<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 is
passed 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 the
descriptor object.</p></li>
<li><p>Similarly, when getting or setting the field, the descriptor’s
<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 or
overwriting the descriptor object.</p></li>
<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-func docutils literal notranslate"><span class="pre">&#64;dataclass</span></code></a>
will call the descriptor’s <code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code> method using its class access
form: <code class="docutils literal notranslate"><span class="pre">descriptor.__get__(obj=None,</span> <span class="pre">type=cls)</span></code>. If the
descriptor returns a value in this case, it will be used as the
field’s default. On the other hand, if the descriptor raises
<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 be
provided for the field.</p></li>
</ul>
<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>
<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>
<span class="bp">self</span><span class="o">.</span><span class="n">_default</span> <span class="o">=</span> <span class="n">default</span>
<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>
<span class="bp">self</span><span class="o">.</span><span class="n">_name</span> <span class="o">=</span> <span class="s2">&quot;_&quot;</span> <span class="o">+</span> <span class="n">name</span>
<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>
<span class="k">if</span> <span class="n">obj</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_default</span>
<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>
<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>
<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>
<span class="nd">@dataclass</span>
<span class="k">class</span><span class="w"> </span><span class="nc">InventoryItem</span><span class="p">:</span>
<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>
<span class="n">i</span> <span class="o">=</span> <span class="n">InventoryItem</span><span class="p">()</span>
<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>
<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>
<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>
</pre></div>
</div>
<p>Note that if a field is annotated with a descriptor type, but is not assigned
a descriptor object as its default value, the field will act like a normal
field.</p>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<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>
<li><a class="reference internal" href="#module-contents">Module contents</a></li>
<li><a class="reference internal" href="#post-init-processing">Post-init processing</a></li>
<li><a class="reference internal" href="#class-variables">Class variables</a></li>
<li><a class="reference internal" href="#init-only-variables">Init-only variables</a></li>
<li><a class="reference internal" href="#frozen-instances">Frozen instances</a></li>
<li><a class="reference internal" href="#inheritance">Inheritance</a></li>
<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>
<li><a class="reference internal" href="#default-factory-functions">Default factory functions</a></li>
<li><a class="reference internal" href="#mutable-default-values">Mutable default values</a></li>
<li><a class="reference internal" href="#descriptor-typed-fields">Descriptor-typed fields</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="warnings.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">warnings</span></code> — Warning control</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="contextlib.html"
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>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/main/Doc/library/dataclasses.rst"
rel="nofollow">Show Source
</a>
</li>
</ul>
</div>
</div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="contextlib.html" title="contextlib — Utilities for with-statement contexts"
>next</a> |</li>
<li class="right" >
<a href="warnings.html" title="warnings — Warning control"
>previous</a> |</li>
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.13.3 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="python.html" >Python Runtime Services</a> &#187;</li>
<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>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />
<input type="submit" value="Go" />
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="footer">
&copy;
<a href="../copyright.html">
Copyright
</a>
2001-2025, Python Software Foundation.
<br />
This page is licensed under the Python Software Foundation License Version 2.
<br />
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
<br />
See <a href="/license.html">History and License</a> for more information.<br />
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
<br />
Last updated on Apr 08, 2025 (14:33 UTC).
<a href="/bugs.html">Found a bug</a>?
<br />
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink