1165 lines
124 KiB
HTML
1165 lines
124 KiB
HTML
<!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 — 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> »</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> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="python.html" accesskey="U">Python Runtime Services</a> »</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">"""Class for keeping track of an item in inventory."""</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">-></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">@</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">@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">@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">@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">@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">@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">@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">@dataclass</span></code> decorator.</p>
|
||
<p>By default, <code class="docutils literal notranslate"><span class="pre">@dataclass</span></code> will not implicitly add a <a class="reference internal" href="../reference/datamodel.html#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__hash__()</span></code></a>
|
||
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">@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">@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">@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"># 'a' 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 'b'</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">@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">'x'</span><span class="p">:</span> <span class="mi">10</span><span class="p">,</span> <span class="s1">'y'</span><span class="p">:</span> <span class="mi">20</span><span class="p">}</span>
|
||
|
||
<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">'mylist'</span><span class="p">:</span> <span class="p">[{</span><span class="s1">'x'</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span> <span class="s1">'y'</span><span class="p">:</span> <span class="mi">0</span><span class="p">},</span> <span class="p">{</span><span class="s1">'x'</span><span class="p">:</span> <span class="mi">10</span><span class="p">,</span> <span class="s1">'y'</span><span class="p">:</span> <span class="mi">4</span><span class="p">}]}</span>
|
||
</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">@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">@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">'C'</span><span class="p">,</span>
|
||
<span class="p">[(</span><span class="s1">'x'</span><span class="p">,</span> <span class="nb">int</span><span class="p">),</span>
|
||
<span class="s1">'y'</span><span class="p">,</span>
|
||
<span class="p">(</span><span class="s1">'z'</span><span class="p">,</span> <span class="nb">int</span><span class="p">,</span> <span class="n">field</span><span class="p">(</span><span class="n">default</span><span class="o">=</span><span class="mi">5</span><span class="p">))],</span>
|
||
<span class="n">namespace</span><span class="o">=</span><span class="p">{</span><span class="s1">'add_one'</span><span class="p">:</span> <span class="k">lambda</span> <span class="bp">self</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">x</span> <span class="o">+</span> <span class="mi">1</span><span class="p">})</span>
|
||
</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">'typing.Any'</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">@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">@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">@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">'j'</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">@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">@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">@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">@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">"_"</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> »</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> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="python.html" >Python Runtime Services</a> »</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">
|
||
©
|
||
<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> |