davidbgk
/
larlet-fr-david-cache

<!doctype html><!-- This is a valid HTML5 document. -->
<!-- Screen readers, SEO, extensions and so on. -->
<html lang=fr>
<!-- Has to be within the first 1024 bytes, hence before the <title>
  See: https://www.w3.org/TR/2012/CR-html5-20121217/document-metadata.html#charset -->
<meta charset=utf-8>
<!-- Why no `X-UA-Compatible` meta: https://stackoverflow.com/a/6771584 -->
<!-- The viewport meta is quite crowded and we are responsible for that.
  See: https://codepen.io/tigt/post/meta-viewport-for-2015 -->
<meta name=viewport content="width=device-width,minimum-scale=1,initial-scale=1,shrink-to-fit=no">
<!-- Required to make a valid HTML5 document. -->
<title>The Ultimate Guide to Data Classes in Python 3.7 (archive) — David Larlet</title>
<!-- Generated from https://realfavicongenerator.net/ such a mess. -->
<link rel="apple-touch-icon" sizes="180x180" href="/static/david/icons/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/static/david/icons/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/static/david/icons/favicon-16x16.png">
<link rel="manifest" href="/manifest.json">
<link rel="mask-icon" href="/static/david/icons/safari-pinned-tab.svg" color="#5bbad5">
<link rel="shortcut icon" href="/static/david/icons/favicon.ico">
<meta name="apple-mobile-web-app-title" content="David Larlet">
<meta name="application-name" content="David Larlet">
<meta name="msapplication-TileColor" content="#da532c">
<meta name="msapplication-config" content="/static/david/icons/browserconfig.xml">
<meta name="theme-color" content="#f0f0ea">
<!-- That good ol' feed, subscribe :p. -->
<link rel=alternate type="application/atom+xml" title=Feed href="/david/log/">

  <meta name="robots" content="noindex, nofollow">
  <meta content="origin-when-cross-origin" name="referrer">
  <!-- Canonical URL for SEO purposes -->
  <link rel="canonical" href="https://realpython.com/python-data-classes/">

<style>
/* http://meyerweb.com/eric/tools/css/reset/ */
html, body, div, span,
h1, h2, h3, h4, h5, h6, p, blockquote, pre,
a, abbr, address, big, cite, code,
del, dfn, em, img, ins,
small, strike, strong, tt, var,
dl, dt, dd, ol, ul, li,
fieldset, form, label, legend,
table, caption, tbody, tfoot, thead, tr, th, td,
article, aside, canvas, details, embed,
figure, figcaption, footer, header, hgroup,
menu, nav, output, ruby, section, summary,
time, mark, audio, video {
  margin: 0;
  padding: 0;
  border: 0;
  font-size: 100%;
  font: inherit;
  vertical-align: baseline;
}
/* HTML5 display-role reset for older browsers */
article, aside, details, figcaption, figure,
footer, header, hgroup, menu, nav, section { display: block; }
body { line-height: 1; }
blockquote, q { quotes: none; }
blockquote:before, blockquote:after,
q:before, q:after {
  content: '';
  content: none;
}
table {
  border-collapse: collapse;
  border-spacing: 0;
}

/* http://practicaltypography.com/equity.html */
/* https://calendar.perfplanet.com/2016/no-font-face-bulletproof-syntax/ */
/* https://www.filamentgroup.com/lab/js-web-fonts.html */
@font-face {
  font-family: 'EquityTextB';
  src: url('/static/david/css/fonts/Equity-Text-B-Regular-webfont.woff2') format('woff2'),
       url('/static/david/css/fonts/Equity-Text-B-Regular-webfont.woff') format('woff');
  font-weight: 300;
  font-style: normal;
  font-display: swap;
}
@font-face {
  font-family: 'EquityTextB';
  src: url('/static/david/css/fonts/Equity-Text-B-Italic-webfont.woff2') format('woff2'),
       url('/static/david/css/fonts/Equity-Text-B-Italic-webfont.woff') format('woff');
  font-weight: 300;
  font-style: italic;
  font-display: swap;
}
@font-face {
  font-family: 'EquityTextB';
  src: url('/static/david/css/fonts/Equity-Text-B-Bold-webfont.woff2') format('woff2'),
       url('/static/david/css/fonts/Equity-Text-B-Bold-webfont.woff') format('woff');
  font-weight: 700;
  font-style: normal;
  font-display: swap;
}

@font-face {
  font-family: 'ConcourseT3';
  src: url('/static/david/css/fonts/concourse_t3_regular-webfont-20190806.woff2') format('woff2'),
       url('/static/david/css/fonts/concourse_t3_regular-webfont-20190806.woff') format('woff');
  font-weight: 300;
  font-style: normal;
  font-display: swap;
}


/* http://practice.typekit.com/lesson/caring-about-opentype-features/ */
body {
  /* http://www.cssfontstack.com/ Palatino 99% Win 86% Mac */
  font-family: "EquityTextB", Palatino, serif;
  background-color: #f0f0ea;
  color: #07486c;
  font-kerning: normal;
  -moz-osx-font-smoothing: grayscale;
  -webkit-font-smoothing: subpixel-antialiased;
  text-rendering: optimizeLegibility;
  font-variant-ligatures: common-ligatures contextual;
  font-feature-settings: "kern", "liga", "clig", "calt";
}
pre, code, kbd, samp, var, tt {
  font-family: 'TriplicateT4c', monospace;
}
em {
  font-style: italic;
  color: #323a45;
}
strong {
  font-weight: bold;
  color: black;
}
nav {
  background-color: #323a45;
  color: #f0f0ea;
  display: flex;
  justify-content: space-around;
  padding: 1rem .5rem;
}
  nav:last-child {
    border-bottom: 1vh solid #2d7474;
  }
  nav a {
    color: #f0f0ea;
  }
  nav abbr {
    border-bottom: 1px dotted white;
  }

h1 {
  border-top: 1vh solid #2d7474;
  border-bottom: .2vh dotted #2d7474;
  background-color: #e3e1e1;
  color: #323a45;
  text-align: center;
  padding: 5rem 0 4rem 0;
  width: 100%;
  font-family: 'ConcourseT3';
  display: flex;
  flex-direction: column;
}
  h1.single {
    padding-bottom: 10rem;
  }
  h1 span {
    position: absolute;
    top: 1vh;
    left: 20%;
    line-height: 0;
  }
    h1 span a {
      line-height: 1.7;
      padding: 1rem 1.2rem .6rem 1.2rem;
      border-radius: 0 0 6% 6%;
      background: #2d7474;
      font-size: 1.3rem;
      color: white;
      text-decoration: none;
    }
h2 {
  margin: 4rem 0 1rem;
  border-top: .2vh solid #2d7474;
  padding-top: 1vh;
}
h3 {
  text-align: center;
  margin: 3rem 0 .75em;
}
hr {
  height: .4rem;
  width: .4rem;
  border-radius: .4rem;
  background: #07486c;
  margin: 2.5rem auto;
}
time {
  display: bloc;
  margin-left: 0 !important;
}
ul, ol {
  margin: 2rem;
}
ul {
  list-style-type: square;
}
a {
  text-decoration-skip-ink: auto;
  text-decoration-thickness: 0.05em;
  text-underline-offset: 0.09em;
}
article {
  max-width: 50rem;
  display: flex;
  flex-direction: column;
  margin: 2rem auto;
}
  article.single {
    border-top: .2vh dotted #2d7474;
    margin: -6rem auto 1rem auto;
    background: #f0f0ea;
    padding: 2rem;
  }
  article p:last-child {
    margin-bottom: 1rem;
  }
p {
  padding: 0 .5rem;
  margin-left: 3rem;
}
  p + p,
  figure + p {
    margin-top: 2rem;
  }

blockquote {
  background-color: #e3e1e1;
  border-left: .5vw solid #2d7474;
  display: flex;
  flex-direction: column;
  align-items: center;
  padding: 1rem;
  margin: 1.5rem;
}
  blockquote cite {
    font-style: italic;
  }
  blockquote p {
    margin-left: 0;
  }

figure {
  border-top: .2vh solid #2d7474;
  background-color: #e3e1e1;
  text-align: center;
  padding: 1.5rem 0;
  margin: 1rem 0 0;
  font-size: 1.5rem;
  width: 100%;
}
  figure img {
    max-width: 250px;
    max-height: 250px;
    border: .5vw solid #323a45;
    padding: 1px;
  }
figcaption {
  padding: 1rem;
  line-height: 1.4;
}
aside {
  display: flex;
  flex-direction: column;
  background-color: #e3e1e1;
  padding: 1rem 0;
  border-bottom: .2vh solid #07486c;
}
  aside p {
    max-width: 50rem;
    margin: 0 auto;
  }

/* https://fvsch.com/code/css-locks/ */
p, li, pre, code, kbd, samp, var, tt, time, details, figcaption {
  font-size: 1rem;
  line-height: calc( 1.5em + 0.2 * 1rem );
}
h1 {
  font-size: 1.9rem;
  line-height: calc( 1.2em + 0.2 * 1rem );
}
h2 {
  font-size: 1.6rem;
  line-height: calc( 1.3em + 0.2 * 1rem );
}
h3 {
  font-size: 1.35rem;
  line-height: calc( 1.4em + 0.2 * 1rem );
}
@media (min-width: 20em) {
  /* The (100vw - 20rem) / (50 - 20) part
     resolves to 0-1rem, depending on the
     viewport width (between 20em and 50em). */
  p, li, pre, code, kbd, samp, var, tt, time, details, figcaption {
    font-size: calc( 1rem + .6 * (100vw - 20rem) / (50 - 20) );
    line-height: calc( 1.5em + 0.2 * (100vw - 50rem) / (20 - 50) );
    margin-left: 0;
  }
  h1 {
    font-size: calc( 1.9rem + 1.5 * (100vw - 20rem) / (50 - 20) );
    line-height: calc( 1.2em + 0.2 * (100vw - 50rem) / (20 - 50) );
  }
  h2 {
    font-size: calc( 1.5rem + 1.5 * (100vw - 20rem) / (50 - 20) );
    line-height: calc( 1.3em + 0.2 * (100vw - 50rem) / (20 - 50) );
  }
  h3 {
    font-size: calc( 1.35rem + 1.5 * (100vw - 20rem) / (50 - 20) );
    line-height: calc( 1.4em + 0.2 * (100vw - 50rem) / (20 - 50) );
  }
}
@media (min-width: 50em) {
  /* The right part of the addition *must* be a
     rem value. In this example we *could* change
     the whole declaration to font-size:2.5rem,
     but if our baseline value was not expressed
     in rem we would have to use calc. */
  p, li, pre, code, kbd, samp, var, tt, time, details, figcaption {
    font-size: calc( 1rem + .6 * 1rem );
    line-height: 1.5em;
  }
  p, li, pre, details {
    margin-left: 3rem;
  }
  h1 {
    font-size: calc( 1.9rem + 1.5 * 1rem );
    line-height: 1.2em;
  }
  h2 {
    font-size: calc( 1.5rem + 1.5 * 1rem );
    line-height: 1.3em;
  }
  h3 {
    font-size: calc( 1.35rem + 1.5 * 1rem );
    line-height: 1.4em;
  }
  figure img {
    max-width: 500px;
    max-height: 500px;
  }
}

figure.unsquared {
  margin-bottom: 1.5rem;
}
  figure.unsquared img {
    height: inherit;
  }


@media print {
  body { font-size: 100%; }
  a:after { content: " (" attr(href) ")"; }
  a, a:link, a:visited, a:after {
    text-decoration: underline;
    text-shadow: none !important;
    background-image: none !important;
    background: white;
    color: black;
  }
  abbr[title] { border-bottom: 0; }
  abbr[title]:after { content: " (" attr(title) ")"; }
  img { page-break-inside: avoid; }
  @page { margin: 2cm .5cm; }
  h1, h2, h3 { page-break-after: avoid; }
  p3 { orphans: 3; widows: 3; }
  img {
    max-width: 250px !important;
    max-height: 250px !important;
  }
  nav, aside { display: none; }
}

ul.with_columns {
  column-count: 1;
}
@media (min-width: 20em) {
  ul.with_columns {
    column-count: 2;
  }
}
@media (min-width: 50em) {
  ul.with_columns {
    column-count: 3;
  }
}
ul.with_two_columns {
  column-count: 1;
}
@media (min-width: 20em) {
  ul.with_two_columns {
    column-count: 1;
  }
}
@media (min-width: 50em) {
  ul.with_two_columns {
    column-count: 2;
  }
}

.gallery {
  display: flex;
  flex-wrap: wrap;
  justify-content: space-around;
}
  .gallery figure img {
    margin-left: 1rem;
    margin-right: 1rem;
  }
  .gallery figure figcaption {
    font-family: 'ConcourseT3'
  }

footer {
  font-family: 'ConcourseT3';
  display: flex;
  flex-direction: column;
  border-top: 3px solid white;
  padding: 4rem 0;
  background-color: #07486c;
  color: white;
}
  footer > * {
    max-width: 50rem;
    margin: 0 auto;
  }
  footer a {
    color: #f1c40f;
  }
  footer .avatar {
    width: 200px;
    height: 200px;
    border-radius: 50%;
    float: left;
    -webkit-shape-outside: circle();
    shape-outside: circle();
    margin-right: 2rem;
    padding: 2px 5px 5px 2px;
    background: white;
    border-left: 1px solid #f1c40f;
    border-top: 1px solid #f1c40f;
    border-right: 5px solid #f1c40f;
    border-bottom: 5px solid #f1c40f;
  }
</style>

<h1>
  <span><a id="jumper" href="#jumpto" title="Un peu perdu ?">?</a></span>
  The Ultimate Guide to Data Classes in Python 3.7 (archive)
  <time>Pour la pérennité des contenus liés. Non-indexé, retrait sur simple email.</time>
</h1>
<section>
  <article>
    <h3><a href="https://realpython.com/python-data-classes/">Source originale du contenu</a></h3>
    <p>One new and exciting feature coming in Python 3.7 is the data class. A data class is a class typically containing mainly data, although there aren’t really any restrictions. It is created using the new <code>@dataclass</code> decorator, as follows:</p>

<div class="highlight python"><pre><span/><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">dataclass</span>

<span class="nd">@dataclass</span>
<span class="k">class</span> <span class="nc">DataClassCard</span><span class="p">:</span>
<span class="n">rank</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">suit</span><span class="p">:</span> <span class="nb">str</span>

</pre></div>

<div class="alert alert-primary" role="alert">
<p><strong>Note:</strong> This code, as well as all other examples in this tutorial, will only work in Python 3.7 and above.</p>
</div>

<p>A data class comes with basic functionality already implemented. For instance, you can instantiate, print, and compare data class instances straight out of the box:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts</span> <span class="o">=</span> <span class="n">DataClassCard</span><span class="p">(</span><span class="s1">'Q'</span><span class="p">,</span> <span class="s1">'Hearts'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts</span><span class="o">.</span><span class="n">rank</span>
<span class="go">'Q'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts</span>
<span class="go">DataClassCard(rank='Q', suit='Hearts')</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts</span> <span class="o">==</span> <span class="n">DataClassCard</span><span class="p">(</span><span class="s1">'Q'</span><span class="p">,</span> <span class="s1">'Hearts'</span><span class="p">)</span>
<span class="go">True</span>
</pre></div>

<p>Compare that to a regular class. A minimal regular class would look something like this:</p>

<div class="highlight python"><pre><span/><span class="k">class</span> <span class="nc">RegularCard</span>
    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">rank</span><span class="p">,</span> <span class="n">suit</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">rank</span> <span class="o">=</span> <span class="n">rank</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">suit</span> <span class="o">=</span> <span class="n">suit</span>
</pre></div>

<p>While this is not much more code to write, you can already see signs of the boilerplate pain: <code>rank</code> and <code>suit</code> are both repeated three times simply to initialize an object. Furthermore, if you try to use this plain class, you’ll notice that the representation of the objects is not very descriptive, and for some reason a queen of hearts is not the same as a queen of hearts:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts</span> <span class="o">=</span> <span class="n">RegularCard</span><span class="p">(</span><span class="s1">'Q'</span><span class="p">,</span> <span class="s1">'Hearts'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts</span><span class="o">.</span><span class="n">rank</span>
<span class="go">'Q'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts</span>
<span class="go">&lt;__main__.RegularCard object at 0x7fb6eee35d30&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts</span> <span class="o">==</span> <span class="n">RegularCard</span><span class="p">(</span><span class="s1">'Q'</span><span class="p">,</span> <span class="s1">'Hearts'</span><span class="p">)</span>
<span class="go">False</span>
</pre></div>

<p>Seems like data classes are helping us out behind the scenes. By default, data classes implement a <code>.__repr__()</code> method to provide a nice string representation and an <code>.__eq__()</code> method that can do basic object comparisons. For the <code>RegularCard</code> class to imitate the data class above, you need to add these methods as well:</p>

<div class="highlight python"><pre><span/><span class="k">class</span> <span class="nc">RegularCard</span>
    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">rank</span><span class="p">,</span> <span class="n">suit</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">rank</span> <span class="o">=</span> <span class="n">rank</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">suit</span> <span class="o">=</span> <span class="n">suit</span>

    <span class="k">def</span> <span class="fm">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="p">(</span><span class="n">f</span><span class="s1">'{self.__class__.__name__}'</span>
                <span class="n">f</span><span class="s1">'(rank={self.rank!r}, suit={self.suit!r})'</span><span class="p">)</span>

    <span class="k">def</span> <span class="fm">__eq__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
        <span class="k">if</span> <span class="n">other</span><span class="o">.</span><span class="vm">__class__</span> <span class="ow">is</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span><span class="p">:</span>
            <span class="k">return</span> <span class="bp">NotImplemented</span>
        <span class="k">return</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">rank</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">suit</span><span class="p">)</span> <span class="o">==</span> <span class="p">(</span><span class="n">other</span><span class="o">.</span><span class="n">rank</span><span class="p">,</span> <span class="n">other</span><span class="o">.</span><span class="n">suit</span><span class="p">)</span>

</pre></div>

<p>In this tutorial, you will learn exactly which conveniences data classes provide. In addition to nice representations and comparisons, you’ll see:</p>

<ul>
<li>How to add default values to data class fields</li>
<li>How data classes allow for ordering of objects</li>
<li>How to represent immutable data</li>
<li>How data classes handle inheritance</li>
</ul>

<p>We will soon dive deeper into those features of data classes. However, you might be thinking that you have already seen something like this before.</p>

<h2 id="alternatives-to-data-classes">Alternatives to Data Classes</h2>

<p>For simple data structures, you have probably already used <a href="https://dbader.org/blog/records-structs-and-data-transfer-objects-in-python">a <code>tuple</code> or a <code>dict</code></a>. You could represent the queen of hearts card in either of the following ways:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts_tuple</span> <span class="o">=</span> <span class="p">(</span><span class="s1">'Q'</span><span class="p">,</span> <span class="s1">'Hearts'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts_dict</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'rank'</span><span class="p">:</span> <span class="s1">'Q'</span><span class="p">,</span> <span class="s1">'suit'</span><span class="p">:</span> <span class="s1">'Hearts'</span><span class="p">}</span>
</pre></div>

<p>It works. However, it puts a lot of responsibility on you as a programmer:</p>

<ul>
<li>You need to remember that the <code>queen_of_hearts_...</code> variable represents a card.</li>
<li>For the <code>_tuple</code> version, you need to remember the order of the attributes. Writing <code>('Spades', 'A')</code> will mess up your program but probably not give you an easily understandable error message.</li>
<li>If you use the <code>_dict</code>, you must make sure the names of the attributes are consistent. For instance <code>{'value': 'A', 'suit': 'Spades'}</code> will not work as expected.</li>
</ul>

<p>Furthermore, using these structures is not ideal:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts_tuple</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>  <span class="c1"># No named access</span>
<span class="go">'Q'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts_dict</span><span class="p">[</span><span class="s1">'suit'</span><span class="p">]</span>  <span class="c1"># Would be nicer with .suit</span>
<span class="go">'Hearts'</span>
</pre></div>

<p>A better alternative is the <a href="https://dbader.org/blog/writing-clean-python-with-namedtuples"><code>namedtuple</code></a>. It has long been used to create readable small data structures. We can in fact recreate the data class example above using a <code>namedtuple</code> like this:</p>

<div class="highlight python"><pre><span/><span class="kn">from</span> <span class="nn">collections</span> <span class="kn">import</span> <span class="n">namedtuple</span>

<span class="n">NamedTupleCard</span> <span class="o">=</span> <span class="n">namedtuple</span><span class="p">(</span><span class="s1">'NamedTupleCard'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'rank'</span><span class="p">,</span> <span class="s1">'suit'</span><span class="p">])</span>

</pre></div>

<p>This definition of <code>NamedTupleCard</code> will give the exact same output as our <code>DataClassCard</code> example did:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts</span> <span class="o">=</span> <span class="n">NamedTupleCard</span><span class="p">(</span><span class="s1">'Q'</span><span class="p">,</span> <span class="s1">'Hearts'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts</span><span class="o">.</span><span class="n">rank</span>
<span class="go">'Q'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts</span>
<span class="go">NamedTupleCard(rank='Q', suit='Hearts')</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts</span> <span class="o">==</span> <span class="n">NamedTupleCard</span><span class="p">(</span><span class="s1">'Q'</span><span class="p">,</span> <span class="s1">'Hearts'</span><span class="p">)</span>
<span class="go">True</span>
</pre></div>

<p>So why even bother with data classes? First of all, data classes come with many more features than you have seen so far. At the same time, the <code>namedtuple</code> has some other features that are not necessarily desirable. By design, a <code>namedtuple</code> is a regular tuple. This can be seen in comparisons, for instance:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts</span> <span class="o">==</span> <span class="p">(</span><span class="s1">'Q'</span><span class="p">,</span> <span class="s1">'Hearts'</span><span class="p">)</span>
<span class="go">True</span>
</pre></div>

<p>While this might seem like a good thing, this lack of awareness about its own type can lead to subtle and hard-to-find bugs, especially since it will also happily compare two different <code>namedtuple</code> classes:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">Person</span> <span class="o">=</span> <span class="n">namedtuple</span><span class="p">(</span><span class="s1">'Person'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'first_initial'</span><span class="p">,</span> <span class="s1">'last_name'</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ace_of_spades</span> <span class="o">=</span> <span class="n">NamedTupleCard</span><span class="p">(</span><span class="s1">'A'</span><span class="p">,</span> <span class="s1">'Spades'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ace_of_spades</span> <span class="o">==</span> <span class="n">Person</span><span class="p">(</span><span class="s1">'A'</span><span class="p">,</span> <span class="s1">'Spades'</span><span class="p">)</span>
<span class="go">True</span>
</pre></div>

<p>The <code>namedtuple</code> also comes with some restrictions. For instance, it is hard to add default values to some of the fields in a <code>namedtuple</code>. A <code>namedtuple</code> is also by nature immutable. That is, the value of a <code>namedtuple</code> can never change. In some applications, this is an awesome feature, but in other settings, it would be nice to have more flexibility:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">card</span> <span class="o">=</span> <span class="n">NamedTupleCard</span><span class="p">(</span><span class="s1">'7'</span><span class="p">,</span> <span class="s1">'Diamonds'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">card</span><span class="o">.</span><span class="n">rank</span> <span class="o">=</span> <span class="s1">'9'</span>
<span class="go">AttributeError: can't set attribute</span>
</pre></div>

<p>Data classes will not replace all uses of <code>namedtuple</code>. For instance, if you need your data structure to behave like a tuple, then a named tuple is a great alternative!</p>

<p>Another alternative, and one of the <a href="https://mail.python.org/pipermail/python-dev/2017-December/151034.html">inspirations for data classes</a>, is the <a href="http://www.attrs.org"><code>attrs</code> project</a>. With <code>attrs</code> installed (<code>pip install attrs</code>), you can write a card class as follows:</p>

<div class="highlight python"><pre><span/><span class="kn">import</span> <span class="nn">attr</span>

<span class="nd">@attr.s</span>
<span class="k">class</span> <span class="nc">AttrsCard</span><span class="p">:</span>
<span class="n">rank</span> <span class="o">=</span> <span class="n">attr</span><span class="o">.</span><span class="n">ib</span><span class="p">()</span>
<span class="n">suit</span> <span class="o">=</span> <span class="n">attr</span><span class="o">.</span><span class="n">ib</span><span class="p">()</span>

</pre></div>

<p>This can be used in exactly the same way as the <code>DataClassCard</code> and <code>NamedTupleCard</code> examples earlier. The <code>attrs</code> project is great and does support some features that data classes do not, including converters and validators. Furthermore, <code>attrs</code> has been around for a while and is supported in Python 2.7 as well as Python 3.4 and up. However, as <code>attrs</code> is not a part of the standard library, it does add an external dependency to your projects. Through data classes, similar functionality will be available everywhere.</p>

<p>In addition to <code>tuple</code>, <code>dict</code>, <code>namedtuple</code>, and <code>attrs</code>, there are <a href="https://www.python.org/dev/peps/pep-0557/#rationale">many other similar projects</a>, including <a href="https://docs.python.org/library/typing.html#typing.NamedTuple"><code>typing.NamedTuple</code></a>, <a href="https://pypi.org/project/namedlist/"><code>namedlist</code></a>, <a href="https://pypi.org/project/attrdict/"><code>attrdict</code></a>, <a href="https://pypi.org/project/plumber/"><code>plumber</code></a>, and <a href="https://pypi.org/project/fields/"><code>fields</code></a>. While data classes are a great new alternative, there are still use cases where one of the older variants fits better. For instance, if you need compatibility with a specific API expecting tuples or need functionality not supported in data classes.</p>

<h2 id="basic-data-classes">Basic Data Classes</h2>

<p>Let us get back to data classes. As an example, we will create a <code>Position</code> class that will represent geographic positions with a name as well as the latitude and longitude:</p>

<div class="highlight python"><pre><span/><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">dataclass</span>

<span class="nd">@dataclass</span>
<span class="k">class</span> <span class="nc">Position</span><span class="p">:</span>
<span class="n">name</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">lon</span><span class="p">:</span> <span class="nb">float</span>
<span class="n">lat</span><span class="p">:</span> <span class="nb">float</span>

</pre></div>

<p>What makes this a data class is the <a href="https://realpython.com/primer-on-python-decorators/"><code>@dataclass</code> decorator</a> just above the class definition. Beneath the <code>class Position:</code> line, you simply list the fields you want in your data class. The <code>:</code> notation used for the fields is using a new feature in Python 3.6 called <a href="https://www.python.org/dev/peps/pep-0526/">variable annotations</a>. We will <a href="#type-hints">soon</a> talk more about this notation and why we specify data types like <code>str</code> and <code>float</code>.</p>

<p>Those few lines of code are all you need. The new class is ready for use:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">pos</span> <span class="o">=</span> <span class="n">Position</span><span class="p">(</span><span class="s1">'Oslo'</span><span class="p">,</span> <span class="mf">10.8</span><span class="p">,</span> <span class="mf">59.9</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">pos</span><span class="p">)</span>
<span class="go">Position(name='Oslo', lon=10.8, lat=59.9)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pos</span><span class="o">.</span><span class="n">lat</span>
<span class="go">59.9</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">f</span><span class="s1">'{pos.name} is at {pos.lat}°N, {pos.lon}°E'</span><span class="p">)</span>
<span class="go">Oslo is at 59.9°N, 10.8°E</span>
</pre></div>

<p>You can also create data classes similarly to how named tuples are created. The following is (almost) equivalent to the definition of <code>Position</code> above:</p>

<div class="highlight python"><pre><span/><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">make_dataclass</span>

<span class="n">Position</span> <span class="o">=</span> <span class="n">make_dataclass</span><span class="p">(</span><span class="s1">'Position'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'name'</span><span class="p">,</span> <span class="s1">'lat'</span><span class="p">,</span> <span class="s1">'lon'</span><span class="p">])</span>

</pre></div>

<p>A data class is a regular Python class. The only thing that sets it apart is that it has basic <a href="https://docs.python.org/reference/datamodel.html#basic-customization">data model methods</a> like <code>.__init__()</code>, <code>.__repr__()</code>, and <code>.__eq__()</code> implemented for you.</p>

<h3 id="default-values">Default Values</h3>

<p>It is easy to add default values to the fields of your data class:</p>

<div class="highlight python"><pre><span/><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">dataclass</span>

<span class="nd">@dataclass</span>
<span class="k">class</span> <span class="nc">Position</span><span class="p">:</span>
<span class="n">name</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">lon</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span>
<span class="n">lat</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span>

</pre></div>

<p>This works exactly as if you had specified the default values in the definition of the <code>.__init__()</code> method of a regular class:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">Position</span><span class="p">(</span><span class="s1">'Null Island'</span><span class="p">)</span>
<span class="go">Position(name='Null Island', lon=0.0, lat=0.0)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Position</span><span class="p">(</span><span class="s1">'Greenwich'</span><span class="p">,</span> <span class="n">lat</span><span class="o">=</span><span class="mf">51.8</span><span class="p">)</span>
<span class="go">Position(name='Greenwich', lon=0.0, lat=51.8)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Position</span><span class="p">(</span><span class="s1">'Vancouver'</span><span class="p">,</span> <span class="o">-</span><span class="mf">123.1</span><span class="p">,</span> <span class="mf">49.3</span><span class="p">)</span>
<span class="go">Position(name='Vancouver', lon=-123.1, lat=49.3)</span>
</pre></div>

<p><a href="#advanced-default-values">Later</a> you will learn about <code>default_factory</code>, which gives a way to provide more complicated default values.</p>

<h3 id="type-hints">Type Hints</h3>

<p>So far, we have not made a big fuss of the fact that data classes support <a href="https://www.youtube.com/watch?v=2xWhaALHTvU">typing</a> out of the box. You have probably noticed that we defined the fields with a type hint: <code>name: str</code> says that <code>name</code> should be a text string (<code>str</code> type).</p>

<p>In fact, adding some kind of type hint is mandatory when defining the fields in your data class. Without a type hint, the field will not be a part of the data class. However, if you do not want to add explicit types to your data class, use <code>typing.Any</code>:</p>

<div class="highlight python"><pre><span/><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">dataclass</span>
<span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">Any</span>

<span class="nd">@dataclass</span>
<span class="k">class</span> <span class="nc">WithoutExplicitTypes</span><span class="p">:</span>
<span class="n">name</span><span class="p">:</span> <span class="n">Any</span>
<span class="n">value</span><span class="p">:</span> <span class="n">Any</span> <span class="o">=</span> <span class="mi">42</span>

</pre></div>

<p>While you need to add type hints in some form when using data classes, these types are not enforced at runtime. The following code runs without any problems:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">Position</span><span class="p">(</span><span class="mf">3.14</span><span class="p">,</span> <span class="s1">'pi day'</span><span class="p">,</span> <span class="mi">2018</span><span class="p">)</span>
<span class="go">Position(name=3.14, lon='pi day', lat=2018)</span>
</pre></div>

<p>This is how typing in Python usually works: <a href="https://www.python.org/dev/peps/pep-0484/#non-goals">Python is and will always be a dynamically typed language</a>. To actually catch type errors, type checkers like <a href="http://mypy-lang.org">Mypy</a> can be run on your source code.</p>

<h3 id="adding-methods">Adding Methods</h3>

<p>You already know that a data class is just a regular class. That means that you can freely add your own methods to a data class. As an example, let us calculate the distance between one position and another, along the Earth’s surface. One way to do this is by using <a href="https://en.wikipedia.org/wiki/Haversine_formula">the haversine formula</a>:</p>

<p><a href="https://files.realpython.com/media/haversine_formula_150.fb2b87d122a4.png"><img class="img-fluid mb-3  mx-auto d-block" src="https://files.realpython.com/media/haversine_formula_150.fb2b87d122a4.png" alt="The haversine formula"/></a></p>

<p>You can add a <code>.distance_to()</code> method to your data class just like you can with normal classes:</p>

<div class="highlight python"><pre><span/><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">dataclass</span>
<span class="kn">from</span> <span class="nn">math</span> <span class="kn">import</span> <span class="n">asin</span><span class="p">,</span> <span class="n">cos</span><span class="p">,</span> <span class="n">radians</span><span class="p">,</span> <span class="n">sin</span><span class="p">,</span> <span class="n">sqrt</span>

<span class="nd">@dataclass</span>
<span class="k">class</span> <span class="nc">Position</span><span class="p">:</span>
<span class="n">name</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">lon</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span>
<span class="n">lat</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span>

    <span class="k">def</span> <span class="nf">distance_to</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
        <span class="n">r</span> <span class="o">=</span> <span class="mi">6371</span>  <span class="c1"># Earth radius in kilometers</span>
        <span class="n">lam_1</span><span class="p">,</span> <span class="n">lam_2</span> <span class="o">=</span> <span class="n">radians</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">lon</span><span class="p">),</span> <span class="n">radians</span><span class="p">(</span><span class="n">other</span><span class="o">.</span><span class="n">lon</span><span class="p">)</span>
        <span class="n">phi_1</span><span class="p">,</span> <span class="n">phi_2</span> <span class="o">=</span> <span class="n">radians</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">lat</span><span class="p">),</span> <span class="n">radians</span><span class="p">(</span><span class="n">other</span><span class="o">.</span><span class="n">lat</span><span class="p">)</span>
        <span class="n">h</span> <span class="o">=</span> <span class="p">(</span><span class="n">sin</span><span class="p">((</span><span class="n">phi_2</span> <span class="o">-</span> <span class="n">phi_1</span><span class="p">)</span> <span class="o">/</span> <span class="mi">2</span><span class="p">)</span><span class="o">**</span><span class="mi">2</span>
             <span class="o">+</span> <span class="n">cos</span><span class="p">(</span><span class="n">phi_1</span><span class="p">)</span> <span class="o">*</span> <span class="n">cos</span><span class="p">(</span><span class="n">phi_2</span><span class="p">)</span> <span class="o">*</span> <span class="n">sin</span><span class="p">((</span><span class="n">lam_2</span> <span class="o">-</span> <span class="n">lam_1</span><span class="p">)</span> <span class="o">/</span> <span class="mi">2</span><span class="p">)</span><span class="o">**</span><span class="mi">2</span><span class="p">)</span>
        <span class="k">return</span> <span class="mi">2</span> <span class="o">*</span> <span class="n">r</span> <span class="o">*</span> <span class="n">asin</span><span class="p">(</span><span class="n">sqrt</span><span class="p">(</span><span class="n">h</span><span class="p">))</span>

</pre></div>

<p>It works as you would expect:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">oslo</span> <span class="o">=</span> <span class="n">Position</span><span class="p">(</span><span class="s1">'Oslo'</span><span class="p">,</span> <span class="mf">10.8</span><span class="p">,</span> <span class="mf">59.9</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">vancouver</span> <span class="o">=</span> <span class="n">Position</span><span class="p">(</span><span class="s1">'Vancouver'</span><span class="p">,</span> <span class="o">-</span><span class="mf">123.1</span><span class="p">,</span> <span class="mf">49.3</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">oslo</span><span class="o">.</span><span class="n">distance_to</span><span class="p">(</span><span class="n">vancouver</span><span class="p">)</span>
<span class="go">7181.7841229421165</span>
</pre></div>

<h2 id="more-flexible-data-classes">More Flexible Data Classes</h2>

<p>So far, you have seen some of the basic features of the data class: it gives you some convenience methods, and you can still add default values and other methods. Now you will learn about some more advanced features like parameters to the <code>@dataclass</code> decorator and the <code>field()</code> function. Together, they give you more control when creating a data class.</p>

<p>Let us return to the playing card example you saw at the beginning of the tutorial and add a class containing a deck of cards while we are at it:</p>

<div class="highlight python"><pre><span/><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">dataclass</span>
<span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">List</span>

<span class="nd">@dataclass</span>
<span class="k">class</span> <span class="nc">PlayingCard</span><span class="p">:</span>
<span class="n">rank</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">suit</span><span class="p">:</span> <span class="nb">str</span>

<span class="nd">@dataclass</span>
<span class="k">class</span> <span class="nc">Deck</span><span class="p">:</span>
<span class="n">cards</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="n">PlayingCard</span><span class="p">]</span>

</pre></div>

<p>A simple deck containing only two cards can be created like this:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts</span> <span class="o">=</span> <span class="n">PlayingCard</span><span class="p">(</span><span class="s1">'Q'</span><span class="p">,</span> <span class="s1">'Hearts'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ace_of_spades</span> <span class="o">=</span> <span class="n">PlayingCard</span><span class="p">(</span><span class="s1">'A'</span><span class="p">,</span> <span class="s1">'Spades'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">two_cards</span> <span class="o">=</span> <span class="n">Deck</span><span class="p">([</span><span class="n">queen_of_hearts</span><span class="p">,</span> <span class="n">ace_of_spades</span><span class="p">])</span>
<span class="go">Deck(cards=[PlayingCard(rank='Q', suit='Hearts'),</span>
<span class="go">            PlayingCard(rank='A', suit='Spades')])</span>
</pre></div>

<h3 id="advanced-default-values">Advanced Default Values</h3>

<p>Say that you want to give a default value to the <code>Deck</code>. It would for example be convenient if <code>Deck()</code> created a <a href="https://en.wikipedia.org/wiki/French_playing_cards">regular (French) deck</a> of 52 playing cards. First, specify the different ranks and suits. Then, add a function <code>make_french_deck()</code> that creates a list of instances of <code>PlayingCard</code>:</p>

<div class="highlight python"><pre><span/><span class="n">RANKS</span> <span class="o">=</span> <span class="s1">'2 3 4 5 6 7 8 9 10 J Q K A'</span><span class="o">.</span><span class="n">split</span><span class="p">()</span>
<span class="n">SUITS</span> <span class="o">=</span> <span class="s1">'♣ ♢ ♡ ♠'</span><span class="o">.</span><span class="n">split</span><span class="p">()</span>

<span class="k">def</span> <span class="nf">make_french_deck</span><span class="p">():</span>
<span class="k">return</span> <span class="p">[</span><span class="n">PlayingCard</span><span class="p">(</span><span class="n">r</span><span class="p">,</span> <span class="n">s</span><span class="p">)</span> <span class="k">for</span> <span class="n">s</span> <span class="ow">in</span> <span class="n">SUITS</span> <span class="k">for</span> <span class="n">r</span> <span class="ow">in</span> <span class="n">RANKS</span><span class="p">]</span>

</pre></div>

<p>For fun, the four different suits are specified using their <a href="https://en.wikipedia.org/wiki/Playing_cards_in_Unicode">Unicode symbols</a>.</p>

<blockquote>
<p><strong>Note:</strong> Above, we used Unicode glyphs like <code>♠</code> directly in the source code. We could do this because <a href="https://docs.python.org/howto/unicode.html#unicode-literals-in-python-source-code">Python supports writing source code in UTF-8 by default</a>. Refer to <a href="https://en.wikipedia.org/wiki/Unicode_input">this page on Unicode input</a> for how to enter these on your system. You could also enter the Unicode symbols for the suits using <code>\N</code> named character escapes (like <code>\N{BLACK SPADE SUIT}</code>) or <code>\u</code> Unicode escapes (like <code>\u2660</code>).</p>
</blockquote>

<p>To simplify comparisons of cards later, the ranks and suits are also listed in their usual order.</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">make_french_deck</span><span class="p">()</span>
<span class="go">[PlayingCard(rank='2', suit='♣'), PlayingCard(rank='3', suit='♣'), ...</span>
<span class="go"> PlayingCard(rank='K', suit='♠'), PlayingCard(rank='A', suit='♠')]</span>
</pre></div>

<p>In theory, you could now use this function to specify a default value for <code>Deck.cards</code>:</p>

<div class="highlight python"><pre><span/><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">dataclass</span>
<span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">List</span>

<span class="nd">@dataclass</span>
<span class="k">class</span> <span class="nc">Deck</span><span class="p">:</span> <span class="c1"># Will NOT work</span>
<span class="n">cards</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="n">PlayingCard</span><span class="p">]</span> <span class="o">=</span> <span class="n">make_french_deck</span><span class="p">()</span>

</pre></div>

<p>Don’t do this! This introduces one of the most common anti-patterns in Python: <a href="http://docs.python-guide.org/en/latest/writing/gotchas/#mutable-default-arguments">using mutable default arguments</a>. The problem is that all instances of <code>Deck</code> will use the same list object as the default value of the <code>.cards</code> property. This means that if, say, one card is removed from one <code>Deck</code>, then it disappears from all other instances of <code>Deck</code> as well. Actually, data classes try to <a href="https://www.python.org/dev/peps/pep-0557/#mutable-default-values">prevent you from doing this</a>, and the code above will raise a <code>ValueError</code>.</p>

<p>Instead, data classes use something called a <code>default_factory</code> to handle mutable default values. To use <code>default_factory</code> (and many other cool features of data classes), you need to use the <code>field()</code> specifier:</p>

<div class="highlight python"><pre><span/><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">dataclass</span><span class="p">,</span> <span class="n">field</span>
<span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">List</span>

<span class="nd">@dataclass</span>
<span class="k">class</span> <span class="nc">Deck</span><span class="p">:</span>
<span class="n">cards</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="n">PlayingCard</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="n">make_french_deck</span><span class="p">)</span>

</pre></div>

<p>The argument to <code>default_factory</code> can be any zero parameter callable. Now it is easy to create a full deck of playing cards:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">Deck</span><span class="p">()</span>
<span class="go">Deck(cards=[PlayingCard(rank='2', suit='♣'), PlayingCard(rank='3', suit='♣'), ...</span>
<span class="go">            PlayingCard(rank='K', suit='♠'), PlayingCard(rank='A', suit='♠')])</span>
</pre></div>

<p>The <code>field()</code> specifier is used to customize each field of a data class individually. You will see some other examples later. For reference, these are the parameters <code>field()</code> supports:</p>

<ul>
<li><code>default</code>: Default value of the field</li>
<li><code>default_factory</code>: Function that returns the initial value of the field</li>
<li><code>init</code>: Use field in <code>.__init__()</code> method? (Default is <code>True</code>.)</li>
<li><code>repr</code>: Use field in <code>repr</code> of the object? (Default is <code>True</code>.)</li>
<li><code>compare</code>: Include the field in comparisons? (Default is <code>True</code>.)</li>
<li><code>hash</code>: Include the field when calculating <code>hash()</code>? (Default is to use the same as for <code>compare</code>.)</li>
<li><code>metadata</code>: A mapping with information about the field</li>
</ul>

<p>In the <code>Position</code> example, you saw how to add simple default values by writing <code>lat: float = 0.0</code>. However, if you also want to customize the field, for instance to hide it in the <code>repr</code>, you need to use the <code>default</code> parameter: <code>lat: float = field(default=0.0, repr=False)</code>. You may not specify both <code>default</code> and <code>default_factory</code>.</p>

<p>The <code>metadata</code> parameter is not used by the data classes themselves but is available for you (or third party packages) to attach information to fields. In the <code>Position</code> example, you could for instance specify that latitude and longitude should be given in degrees:</p>

<div class="highlight python"><pre><span/><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">dataclass</span><span class="p">,</span> <span class="n">field</span>

<span class="nd">@dataclass</span>
<span class="k">class</span> <span class="nc">Position</span><span class="p">:</span>
<span class="n">name</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">lon</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">default</span><span class="o">=</span><span class="mf">0.0</span><span class="p">,</span> <span class="n">metadata</span><span class="o">=</span><span class="p">{</span><span class="s1">'unit'</span><span class="p">:</span> <span class="s1">'degrees'</span><span class="p">})</span>
<span class="n">lat</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">default</span><span class="o">=</span><span class="mf">0.0</span><span class="p">,</span> <span class="n">metadata</span><span class="o">=</span><span class="p">{</span><span class="s1">'unit'</span><span class="p">:</span> <span class="s1">'degrees'</span><span class="p">})</span>

</pre></div>

<p>The metadata (and other information about a field) can be retrieved using the <code>fields()</code> function (note the plural <em>s</em>):</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">fields</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">fields</span><span class="p">(</span><span class="n">Position</span><span class="p">)</span>
<span class="go">(Field(name='name',type=&lt;class 'str'&gt;,...,metadata={}),</span>
<span class="go"> Field(name='lon',type=&lt;class 'float'&gt;,...,metadata={'unit': 'degrees'}),</span>
<span class="go"> Field(name='lat',type=&lt;class 'float'&gt;,...,metadata={'unit': 'degrees'}))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">lat_unit</span> <span class="o">=</span> <span class="n">fields</span><span class="p">(</span><span class="n">Position</span><span class="p">)[</span><span class="mi">2</span><span class="p">]</span><span class="o">.</span><span class="n">metadata</span><span class="p">[</span><span class="s1">'unit'</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">lat_unit</span>
<span class="go">'degrees'</span>
</pre></div>

<h3 id="you-need-representation">You Need Representation?</h3>

<p>Recall that we can create decks of cards out of thin air:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">Deck</span><span class="p">()</span>
<span class="go">Deck(cards=[PlayingCard(rank='2', suit='♣'), PlayingCard(rank='3', suit='♣'), ...</span>
<span class="go">            PlayingCard(rank='K', suit='♠'), PlayingCard(rank='A', suit='♠')])</span>
</pre></div>

<p>While this representation of a <code>Deck</code> is explicit and readable, it is also very verbose. I have deleted 48 of the 52 cards in the deck in the output above. On an 80-column display, simply printing the full <code>Deck</code> takes up 22 lines! Let us add a more concise representation. In general, a Python object has <a href="https://dbader.org/blog/python-repr-vs-str">two different string representations</a>:</p>

<ul>
<li>
<p><code>repr(obj)</code> is defined by <code>obj.__repr__()</code> and should return a developer-friendly representation of <code>obj</code>. If possible, this should be code that can recreate <code>obj</code>. Data classes do this.</p>
</li>
<li>
<p><code>str(obj)</code> is defined by <code>obj.__str__()</code> and should return a user-friendly representation of <code>obj</code>. Data classes do not implement a <code>.__str__()</code> method, so Python will fall back to the <code>.__repr__()</code> method.</p>
</li>
</ul>

<p>Let us implement a user-friendly representation of a <code>PlayingCard</code>:</p>

<div class="highlight python"><pre><span/><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">dataclass</span>

<span class="nd">@dataclass</span>
<span class="k">class</span> <span class="nc">PlayingCard</span><span class="p">:</span>
<span class="n">rank</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">suit</span><span class="p">:</span> <span class="nb">str</span>

    <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="n">f</span><span class="s1">'{self.suit}{self.rank}'</span>

</pre></div>

<p>The cards now look much nicer, but the deck is still as verbose as ever:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">ace_of_spades</span> <span class="o">=</span> <span class="n">PlayingCard</span><span class="p">(</span><span class="s1">'A'</span><span class="p">,</span> <span class="s1">'♠'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ace_of_spades</span>
<span class="go">PlayingCard(rank='A', suit='♠')</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">ace_of_spades</span><span class="p">)</span>
<span class="go">♠A</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">Deck</span><span class="p">())</span>
<span class="go">Deck(cards=[PlayingCard(rank='2', suit='♣'), PlayingCard(rank='3', suit='♣'), ...</span>
<span class="go">            PlayingCard(rank='K', suit='♠'), PlayingCard(rank='A', suit='♠')])</span>
</pre></div>

<p>To show that it is possible to add your own <code>.__repr__()</code> method as well, we will violate the principle that it should return code that can recreate an object. <a href="https://www.python.org/dev/peps/pep-0020/">Practicality beats purity</a> after all. The following code adds a more concise representation of the <code>Deck</code>:</p>

<div class="highlight python"><pre><span/><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">dataclass</span><span class="p">,</span> <span class="n">field</span>
<span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">List</span>

<span class="nd">@dataclass</span>
<span class="k">class</span> <span class="nc">Deck</span><span class="p">:</span>
<span class="n">cards</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="n">PlayingCard</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="n">make_french_deck</span><span class="p">)</span>

    <span class="k">def</span> <span class="fm">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="n">cards</span> <span class="o">=</span> <span class="s1">', '</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">f</span><span class="s1">'{c!s}'</span> <span class="k">for</span> <span class="n">c</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">cards</span><span class="p">)</span>
        <span class="k">return</span> <span class="n">f</span><span class="s1">'{self.__class__.__name__}({cards})'</span>

</pre></div>

<p>Note the <code>!s</code> specifier in the <code>{c!s}</code> format string. It means that we explicitly want to use the <code>str()</code> representation of <code>PlayingCard</code>s. With the new <code>.__repr__()</code>, the representation of <code>Deck</code> is easier on the eyes:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">Deck</span><span class="p">()</span>
<span class="go">Deck(♣2, ♣3, ♣4, ♣5, ♣6, ♣7, ♣8, ♣9, ♣10, ♣J, ♣Q, ♣K, ♣A,</span>
<span class="go">     ♢2, ♢3, ♢4, ♢5, ♢6, ♢7, ♢8, ♢9, ♢10, ♢J, ♢Q, ♢K, ♢A,</span>
<span class="go">     ♡2, ♡3, ♡4, ♡5, ♡6, ♡7, ♡8, ♡9, ♡10, ♡J, ♡Q, ♡K, ♡A,</span>
<span class="go">     ♠2, ♠3, ♠4, ♠5, ♠6, ♠7, ♠8, ♠9, ♠10, ♠J, ♠Q, ♠K, ♠A)</span>
</pre></div>

<h3 id="comparing-cards">Comparing Cards</h3>

<p>In many card games, cards are compared to each other. For instance in a typical trick taking game, the highest card takes the trick. As it is currently implemented, the <code>PlayingCard</code> class does not support this kind of comparison:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts</span> <span class="o">=</span> <span class="n">PlayingCard</span><span class="p">(</span><span class="s1">'Q'</span><span class="p">,</span> <span class="s1">'♡'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ace_of_spades</span> <span class="o">=</span> <span class="n">PlayingCard</span><span class="p">(</span><span class="s1">'A'</span><span class="p">,</span> <span class="s1">'♠'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ace_of_spades</span> <span class="o">&gt;</span> <span class="n">queen_of_hearts</span>
<span class="go">TypeError: '&gt;' not supported between instances of 'Card' and 'Card'</span>
</pre></div>

<p>This is, however, (seemingly) easy to rectify:</p>

<div class="highlight python"><pre><span/><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">dataclass</span>

<span class="nd">@dataclass</span><span class="p">(</span><span class="n">order</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">PlayingCard</span><span class="p">:</span>
<span class="n">rank</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">suit</span><span class="p">:</span> <span class="nb">str</span>

    <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="n">f</span><span class="s1">'{self.suit}{self.rank}'</span>

</pre></div>

<p>The <code>@dataclass</code> decorator has two forms. So far you have seen the simple form where <code>@dataclass</code> is specified without any parentheses and parameters. However, you can also give parameters to the <code>@dataclass()</code> decorator in parentheses. The following parameters are supported:</p>

<ul>
<li><code>init</code>: Add <code>.__init__()</code> method? (Default is <code>True</code>.)</li>
<li><code>repr</code>: Add <code>.__repr__()</code> method? (Default is <code>True</code>.)</li>
<li><code>eq</code>: Add <code>.__eq__()</code> method? (Default is <code>True</code>.)</li>
<li><code>order</code>: Add ordering methods? (Default is <code>False</code>.)</li>
<li><code>unsafe_hash</code>: Force the addition of a <code>.__hash__()</code> method? (Default is <code>False</code>.)</li>
<li><code>frozen</code>: If <code>True</code>, assigning to fields raise an exception. (Default is <code>False</code>.)</li>
</ul>

<p>See <a href="https://www.python.org/dev/peps/pep-0557/#id7">the original PEP</a> for more information about each parameter. After setting <code>order=True</code>, instances of <code>PlayingCard</code> can be compared:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts</span> <span class="o">=</span> <span class="n">PlayingCard</span><span class="p">(</span><span class="s1">'Q'</span><span class="p">,</span> <span class="s1">'♡'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ace_of_spades</span> <span class="o">=</span> <span class="n">PlayingCard</span><span class="p">(</span><span class="s1">'A'</span><span class="p">,</span> <span class="s1">'♠'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ace_of_spades</span> <span class="o">&gt;</span> <span class="n">queen_of_hearts</span>
<span class="go">False</span>
</pre></div>

<p>How are the two cards compared though? You have not specified how the ordering should be done, and for some reason Python seems to believe that a Queen is higher than an Ace…</p>

<p>It turns out that data classes compare objects as if they were tuples of their fields. In other words, a Queen is higher than an Ace because <code>'Q'</code> comes after <code>'A'</code> in the alphabet:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="p">(</span><span class="s1">'A'</span><span class="p">,</span> <span class="s1">'♠'</span><span class="p">)</span> <span class="o">&gt;</span> <span class="p">(</span><span class="s1">'Q'</span><span class="p">,</span> <span class="s1">'♡'</span><span class="p">)</span>
<span class="go">False</span>
</pre></div>

<p>That does not really work for us. Instead, we need to define some kind of sort index that uses the order of <code>RANKS</code> and <code>SUITS</code>. Something like this:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">RANKS</span> <span class="o">=</span> <span class="s1">'2 3 4 5 6 7 8 9 10 J Q K A'</span><span class="o">.</span><span class="n">split</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">SUITS</span> <span class="o">=</span> <span class="s1">'♣ ♢ ♡ ♠'</span><span class="o">.</span><span class="n">split</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">card</span> <span class="o">=</span> <span class="n">PlayingCard</span><span class="p">(</span><span class="s1">'Q'</span><span class="p">,</span> <span class="s1">'♡'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">RANKS</span><span class="o">.</span><span class="n">index</span><span class="p">(</span><span class="n">card</span><span class="o">.</span><span class="n">rank</span><span class="p">)</span> <span class="o">*</span> <span class="nb">len</span><span class="p">(</span><span class="n">SUITS</span><span class="p">)</span> <span class="o">+</span> <span class="n">SUITS</span><span class="o">.</span><span class="n">index</span><span class="p">(</span><span class="n">card</span><span class="o">.</span><span class="n">suit</span><span class="p">)</span>
<span class="go">42</span>
</pre></div>

<p>For <code>PlayingCard</code> to use this sort index for comparisons, we need to add a field <code>.sort_index</code> to the class. However, this field should be calculated from the other fields <code>.rank</code> and <code>.suit</code> automatically. This is exactly what the special method <code>.__post_init__()</code> is for. It allows for special processing after the regular <code>.__init__()</code> method is called:</p>

<div class="highlight python"><pre><span/><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">dataclass</span><span class="p">,</span> <span class="n">field</span>

<span class="n">RANKS</span> <span class="o">=</span> <span class="s1">'2 3 4 5 6 7 8 9 10 J Q K A'</span><span class="o">.</span><span class="n">split</span><span class="p">()</span>
<span class="n">SUITS</span> <span class="o">=</span> <span class="s1">'♣ ♢ ♡ ♠'</span><span class="o">.</span><span class="n">split</span><span class="p">()</span>

<span class="nd">@dataclass</span><span class="p">(</span><span class="n">order</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">PlayingCard</span><span class="p">:</span>
<span class="n">sort_index</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">init</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span> <span class="nb">repr</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="n">rank</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">suit</span><span class="p">:</span> <span class="nb">str</span>

    <span class="k">def</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">sort_index</span> <span class="o">=</span> <span class="p">(</span><span class="n">RANKS</span><span class="o">.</span><span class="n">index</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">rank</span><span class="p">)</span> <span class="o">*</span> <span class="nb">len</span><span class="p">(</span><span class="n">SUITS</span><span class="p">)</span>
                           <span class="o">+</span> <span class="n">SUITS</span><span class="o">.</span><span class="n">index</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">suit</span><span class="p">))</span>

    <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="n">f</span><span class="s1">'{self.suit}{self.rank}'</span>

</pre></div>

<p>Note that <code>.sort_index</code> is added as the first field of the class. That way, the comparison is first done using <code>.sort_index</code> and only if there are ties are the other fields used. Using <code>field()</code>, you must also specify that <code>.sort_index</code> should not be included as a parameter in the <code>.__init__()</code> method (because it is calculated from the <code>.rank</code> and <code>.suit</code> fields). To avoid confusing the user about this implementation detail, it is probably also a good idea to remove <code>.sort_index</code> from the <code>repr</code> of the class.</p>

<p>Finally, aces are high:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts</span> <span class="o">=</span> <span class="n">PlayingCard</span><span class="p">(</span><span class="s1">'Q'</span><span class="p">,</span> <span class="s1">'♡'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ace_of_spades</span> <span class="o">=</span> <span class="n">PlayingCard</span><span class="p">(</span><span class="s1">'A'</span><span class="p">,</span> <span class="s1">'♠'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ace_of_spades</span> <span class="o">&gt;</span> <span class="n">queen_of_hearts</span>
<span class="go">True</span>
</pre></div>

<p>You can now easily create a sorted deck:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">Deck</span><span class="p">(</span><span class="nb">sorted</span><span class="p">(</span><span class="n">make_french_deck</span><span class="p">()))</span>
<span class="go">Deck(♣2, ♢2, ♡2, ♠2, ♣3, ♢3, ♡3, ♠3, ♣4, ♢4, ♡4, ♠4, ♣5,</span>
<span class="go">     ♢5, ♡5, ♠5, ♣6, ♢6, ♡6, ♠6, ♣7, ♢7, ♡7, ♠7, ♣8, ♢8,</span>
<span class="go">     ♡8, ♠8, ♣9, ♢9, ♡9, ♠9, ♣10, ♢10, ♡10, ♠10, ♣J, ♢J, ♡J,</span>
<span class="go">     ♠J, ♣Q, ♢Q, ♡Q, ♠Q, ♣K, ♢K, ♡K, ♠K, ♣A, ♢A, ♡A, ♠A)</span>
</pre></div>

<p>Or, if you don’t care about sorting, this is how you draw a random hand of 10 cards:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">random</span> <span class="kn">import</span> <span class="n">sample</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Deck</span><span class="p">(</span><span class="n">sample</span><span class="p">(</span><span class="n">make_french_deck</span><span class="p">(),</span> <span class="n">k</span><span class="o">=</span><span class="mi">10</span><span class="p">))</span>
<span class="go">Deck(♢2, ♡A, ♢10, ♣2, ♢3, ♠3, ♢A, ♠8, ♠9, ♠2)</span>
</pre></div>

<p>Of course, you don’t need <code>order=True</code> for that…</p>

<h2 id="immutable-data-classes">Immutable Data Classes</h2>

<p>One of the defining features of the <code>namedtuple</code> you saw earlier is that it is <a href="https://medium.com/@meghamohan/mutable-and-immutable-side-of-python-c2145cf72747">immutable</a>. That is, the value of its fields may never change. For many types of data classes, this is a great idea! To make a data class immutable, set <code>frozen=True</code> when you create it. For example, the following is an immutable version of the <code>Position</code> class <a href="#basic-data-classes">you saw earlier</a>:</p>

<div class="highlight python"><pre><span/><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">dataclass</span>

<span class="nd">@dataclass</span><span class="p">(</span><span class="n">frozen</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">Position</span><span class="p">:</span>
<span class="n">name</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">lon</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span>
<span class="n">lat</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span>

</pre></div>

<p>In a frozen data class, you can not assign values to the fields after creation:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">pos</span> <span class="o">=</span> <span class="n">Position</span><span class="p">(</span><span class="s1">'Oslo'</span><span class="p">,</span> <span class="mf">10.8</span><span class="p">,</span> <span class="mf">59.9</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pos</span><span class="o">.</span><span class="n">name</span>
<span class="go">'Oslo'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pos</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="s1">'Stockholm'</span>
<span class="go">dataclasses.FrozenInstanceError: cannot assign to field 'name'</span>
</pre></div>

<p>Be aware though that if your data class contains mutable fields, those might still change. This is true for all nested data structures in Python (see <a href="https://www.youtube.com/watch?v=p9ppfvHv2Us">this video for further info</a>):</p>

<div class="highlight python"><pre><span/><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">dataclass</span>
<span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">List</span>

<span class="nd">@dataclass</span><span class="p">(</span><span class="n">frozen</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">ImmutableCard</span><span class="p">:</span>
<span class="n">rank</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">suit</span><span class="p">:</span> <span class="nb">str</span>

<span class="nd">@dataclass</span><span class="p">(</span><span class="n">frozen</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">ImmutableDeck</span><span class="p">:</span>
<span class="n">cards</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="n">PlayingCard</span><span class="p">]</span>

</pre></div>

<p>Even though both <code>ImmutableCard</code> and <code>ImmutableDeck</code> are immutable, the list holding <code>cards</code> is not. You can therefore still change the cards in the deck:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">queen_of_hearts</span> <span class="o">=</span> <span class="n">ImmutableCard</span><span class="p">(</span><span class="s1">'Q'</span><span class="p">,</span> <span class="s1">'♡'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ace_of_spades</span> <span class="o">=</span> <span class="n">ImmutableCard</span><span class="p">(</span><span class="s1">'A'</span><span class="p">,</span> <span class="s1">'♠'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">deck</span> <span class="o">=</span> <span class="n">ImmutableDeck</span><span class="p">([</span><span class="n">queen_of_hearts</span><span class="p">,</span> <span class="n">ace_of_spades</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">deck</span>
<span class="go">ImmutableDeck(cards=[ImmutableCard(rank='Q', suit='♡'), ImmutableCard(rank='A', suit='♠')])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">deck</span><span class="o">.</span><span class="n">cards</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="n">ImmutableCard</span><span class="p">(</span><span class="s1">'7'</span><span class="p">,</span> <span class="s1">'♢'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">deck</span>
<span class="go">ImmutableDeck(cards=[ImmutableCard(rank='7', suit='♢'), ImmutableCard(rank='A', suit='♠')])</span>
</pre></div>

<p>To avoid this, make sure all fields of an immutable data class use immutable types (but remember that types are not enforced at runtime). The <code>ImmutableDeck</code> should be implemented using a tuple instead of a list.</p>

<h2 id="inheritance">Inheritance</h2>

<p>You can <a href="https://realpython.com/python3-object-oriented-programming/">subclass</a> data classes quite freely. As an example, we will extend our <code>Position</code> example with a <code>country</code> field and use it to record capitals:</p>

<div class="highlight python"><pre><span/><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">dataclass</span>

<span class="nd">@dataclass</span>
<span class="k">class</span> <span class="nc">Position</span><span class="p">:</span>
<span class="n">name</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">lon</span><span class="p">:</span> <span class="nb">float</span>
<span class="n">lat</span><span class="p">:</span> <span class="nb">float</span>

<span class="nd">@dataclass</span>
<span class="k">class</span> <span class="nc">Capital</span><span class="p">(</span><span class="n">Position</span><span class="p">):</span>
<span class="n">country</span><span class="p">:</span> <span class="nb">str</span>

</pre></div>

<p>In this simple example, everything works without a hitch:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">Capital</span><span class="p">(</span><span class="s1">'Oslo'</span><span class="p">,</span> <span class="mf">10.8</span><span class="p">,</span> <span class="mf">59.9</span><span class="p">,</span> <span class="s1">'Norway'</span><span class="p">)</span>
<span class="go">Capital(name='Oslo', lon=10.8, lat=59.9, country='Norway')</span>
</pre></div>

<p>The <code>country</code> field of <code>Capital</code> is added after the three original fields in <code>Position</code>. Things get a little more complicated if any fields in the base class have default values:</p>

<div class="highlight python"><pre><span/><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">dataclass</span>

<span class="nd">@dataclass</span>
<span class="k">class</span> <span class="nc">Position</span><span class="p">:</span>
<span class="n">name</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">lon</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span>
<span class="n">lat</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span>

<span class="nd">@dataclass</span>
<span class="k">class</span> <span class="nc">Capital</span><span class="p">(</span><span class="n">Position</span><span class="p">):</span>
<span class="n">country</span><span class="p">:</span> <span class="nb">str</span> <span class="c1"># Does NOT work</span>

</pre></div>

<p>This code will immediately crash with a <code>TypeError</code> complaining that “non-default argument ‘country’ follows default argument.” The problem is that our new <code>country</code> field has no default value, while the <code>lon</code> and <code>lat</code> fields have default values. The data class will try to write an <code>.__init__()</code> method with the following signature:</p>

<div class="highlight python"><pre><span/><span class="k">def</span> <span class="fm">__init__</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">lon</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span><span class="p">,</span> <span class="n">lat</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span><span class="p">,</span> <span class="n">country</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
    <span class="o">...</span>
</pre></div>

<p>However, this is not valid Python. <a href="https://docs.python.org/reference/compound_stmts.html#function-definitions">If a parameter has a default value, all following parameters must also have a default value</a>. In other words, if a field in a base class has a default value, then all new fields added in a subclass must have default values as well.</p>

<p>Another thing to be aware of is how fields are ordered in a subclass. Starting with the base class, fields are ordered in the order in which they are first defined. If a field is redefined in a subclass, its order does not change. For example, if you define <code>Position</code> and <code>Capital</code> as follows:</p>

<div class="highlight python"><pre><span/><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">dataclass</span>

<span class="nd">@dataclass</span>
<span class="k">class</span> <span class="nc">Position</span><span class="p">:</span>
<span class="n">name</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">lon</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span>
<span class="n">lat</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span>

<span class="nd">@dataclass</span>
<span class="k">class</span> <span class="nc">Capital</span><span class="p">(</span><span class="n">Position</span><span class="p">):</span>
<span class="n">country</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s1">'Unknown'</span>
<span class="n">lat</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">40.0</span>

</pre></div>

<p>Then the order of the fields in <code>Capital</code> will still be <code>name</code>, <code>lon</code>, <code>lat</code>, <code>country</code>. However, the default value of <code>lat</code> will be <code>40.0</code>.</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="n">Capital</span><span class="p">(</span><span class="s1">'Madrid'</span><span class="p">,</span> <span class="n">country</span><span class="o">=</span><span class="s1">'Spain'</span><span class="p">)</span>
<span class="go">Capital(name='Madrid', lon=0.0, lat=40.0, country='Spain')</span>
</pre></div>

<h2 id="optimizing-data-classes">Optimizing Data Classes</h2>

<p>I’m going to end this tutorial with a few words about <a href="https://docs.python.org/reference/datamodel.html#slots">slots</a>. Slots can be used to make classes faster and use less memory. Data classes have no explicit syntax for working with slots, but the normal way of creating slots works for data classes as well. (They really are just regular classes!)</p>

<div class="highlight python"><pre><span/><span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">dataclass</span>

<span class="nd">@dataclass</span>
<span class="k">class</span> <span class="nc">SimplePosition</span><span class="p">:</span>
<span class="n">name</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">lon</span><span class="p">:</span> <span class="nb">float</span>
<span class="n">lat</span><span class="p">:</span> <span class="nb">float</span>

<span class="nd">@dataclass</span>
<span class="k">class</span> <span class="nc">SlotPosition</span><span class="p">:</span>
<span class="vm">**slots**</span> <span class="o">=</span> <span class="p">[</span><span class="s1">'name'</span><span class="p">,</span> <span class="s1">'lon'</span><span class="p">,</span> <span class="s1">'lat'</span><span class="p">]</span>
<span class="n">name</span><span class="p">:</span> <span class="nb">str</span>
<span class="n">lon</span><span class="p">:</span> <span class="nb">float</span>
<span class="n">lat</span><span class="p">:</span> <span class="nb">float</span>

</pre></div>

<p>Essentially, slots are defined using <code>.__slots__</code> to list the variables on a class. Variables or attributes not present in <code>.__slots__</code> may not be defined. Furthermore, a slots class may not have default values.</p>

<p>The benefit of adding such restrictions is that certain optimizations may be done. For instance, slots classes take up less memory, as can be measured using <a href="https://pythonhosted.org/Pympler/">Pympler</a>:</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">pympler</span> <span class="kn">import</span> <span class="n">asizeof</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">simple</span> <span class="o">=</span> <span class="n">SimplePosition</span><span class="p">(</span><span class="s1">'London'</span><span class="p">,</span> <span class="o">-</span><span class="mf">0.1</span><span class="p">,</span> <span class="mf">51.5</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">slot</span> <span class="o">=</span> <span class="n">SlotPosition</span><span class="p">(</span><span class="s1">'Madrid'</span><span class="p">,</span> <span class="o">-</span><span class="mf">3.7</span><span class="p">,</span> <span class="mf">40.4</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">asizeof</span><span class="o">.</span><span class="n">asizesof</span><span class="p">(</span><span class="n">simple</span><span class="p">,</span> <span class="n">slot</span><span class="p">)</span>
<span class="go">(440, 248)</span>
</pre></div>

<p>Similarly, slots classes are typically faster to work with. The following example measures the speed of attribute access on a slots data class and a regular data class using <a href="https://docs.python.org/library/timeit.html">timeit</a> from the standard library.</p>

<div class="highlight python"><pre><span/><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">timeit</span> <span class="kn">import</span> <span class="n">timeit</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">timeit</span><span class="p">(</span><span class="s1">'slot.name'</span><span class="p">,</span> <span class="n">setup</span><span class="o">=</span><span class="s2">"from position import SlotPosition; slot=SlotPosition('Oslo', 10.8, 59.9)"</span><span class="p">)</span>
<span class="go">0.05882283499886398</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">timeit</span><span class="p">(</span><span class="s1">'simple.name'</span><span class="p">,</span> <span class="n">setup</span><span class="o">=</span><span class="s2">"from position import SimplePosition; simple=SimplePosition('Oslo', 10.8, 59.9)"</span><span class="p">)</span>
<span class="go">0.09207444800267695</span>
</pre></div>

<p>In this particular example, the slot class is about 35% faster.</p>

<h2 id="conclusion-further-reading">Conclusion &amp; Further Reading</h2>

<p>Data classes are one of the new features of Python 3.7. With data classes, you do not have to write boilerplate code to get proper initialization, representation, and comparisons for your objects. </p>

<p>You have seen how to define your own data classes, as well as:</p>

<ul>
<li>How to add default values to the fields in your data class</li>
<li>How to customize the ordering of data class objects</li>
<li>How to work with immutable data classes</li>
<li>How inheritance works for data classes</li>
</ul>

<p>If you want to dive into all the details of data classes, have a look at <a href="https://www.python.org/dev/peps/pep-0557/">PEP 557</a> as well as the discussions in the original <a href="https://github.com/ericvsmith/dataclasses/issues?utf8=%E2%9C%93&amp;q=">GitHub repo</a>.</p>

<p>In addition, Raymond Hettinger’s PyCon 2018 talk <a href="https://www.youtube.com/watch?v=T-TwcmT6Rcw">Dataclasses: The code generator to end all code generators</a> is well worth watching.</p>

<p>If you do not yet have Python 3.7, there is also a <a href="https://github.com/ericvsmith/dataclasses">data classes backport for Python 3.6</a>. And now, go forth and write less code!</p>
  </article>
</section>


<nav id="jumpto">
  <p>
    <a href="/david/blog/">Accueil du blog</a> |
    <a href="https://realpython.com/python-data-classes/">Source originale</a> |
    <a href="/david/stream/2019/">Accueil du flux</a>
  </p>
</nav>

<footer>
  <div>
    <img src="/static/david/david-larlet-avatar.jpg" loading="lazy" class="avatar" width="200" height="200">
    <p>
      Bonjour/Hi!
      Je suis <a href="/david/" title="Profil public">David&nbsp;Larlet</a>, je vis actuellement à Montréal et j’alimente cet espace depuis 15 ans. <br>
      Si tu as apprécié cette lecture, n’hésite pas à poursuivre ton exploration. Par exemple via les <a href="/david/blog/" title="Expériences bienveillantes">réflexions bimestrielles</a>, la <a href="/david/stream/2019/" title="Pensées (dés)articulées">veille hebdomadaire</a> ou en t’abonnant au <a href="/david/log/" title="S’abonner aux publications via RSS">flux RSS</a> (<a href="/david/blog/2019/flux-rss/" title="Tiens c’est quoi un flux RSS ?">so 2005</a>).
    </p>
    <p>
      Je m’intéresse à la place que je peux avoir dans ce monde. En tant qu’humain, en tant que membre d’une famille et en tant qu’associé d’une coopérative. De temps en temps, je fais aussi des <a href="https://github.com/davidbgk" title="Principalement sur Github mais aussi ailleurs">trucs techniques</a>. Et encore plus rarement, <a href="/david/talks/" title="En ce moment je laisse plutôt la place aux autres">j’en parle</a>.
    </p>
    
    <p>
      Voici quelques articles choisis :
      <a href="/david/blog/2019/faire-equipe/" title="Accéder à l’article complet">Faire équipe</a>,
      <a href="/david/blog/2018/bivouac-automnal/" title="Accéder à l’article complet">Bivouac automnal</a>,
      <a href="/david/blog/2018/commodite-effondrement/" title="Accéder à l’article complet">Commodité et effondrement</a>,
      <a href="/david/blog/2017/donnees-communs/" title="Accéder à l’article complet">Des données aux communs</a>,
      <a href="/david/blog/2016/accompagner-enfant/" title="Accéder à l’article complet">Accompagner un enfant</a>,
      <a href="/david/blog/2016/senior-developer/" title="Accéder à l’article complet">Senior developer</a>,
      <a href="/david/blog/2016/illusion-sociale/" title="Accéder à l’article complet">L’illusion sociale</a>,
      <a href="/david/blog/2016/instantane-scopyleft/" title="Accéder à l’article complet">Instantané Scopyleft</a>,
      <a href="/david/blog/2016/enseigner-web/" title="Accéder à l’article complet">Enseigner le Web</a>,
      <a href="/david/blog/2016/simplicite-defaut/" title="Accéder à l’article complet">Simplicité par défaut</a>,
      <a href="/david/blog/2016/minimalisme-esthetique/" title="Accéder à l’article complet">Minimalisme et esthétique</a>,
      <a href="/david/blog/2014/un-web-omni-present/" title="Accéder à l’article complet">Un web omni-présent</a>,
      <a href="/david/blog/2014/manifeste-developpeur/" title="Accéder à l’article complet">Manifeste de développeur</a>,
      <a href="/david/blog/2013/confort-convivialite/" title="Accéder à l’article complet">Confort et convivialité</a>,
      <a href="/david/blog/2013/testament-numerique/" title="Accéder à l’article complet">Testament numérique</a>,
      et <a href="/david/blog/" title="Accéder aux archives">bien d’autres…</a>
    </p>
    <p>
      On peut <a href="mailto:david%40larlet.fr" title="Envoyer un courriel">échanger par courriel</a>. Si éventuellement tu souhaites que l’on travaille ensemble, tu devrais commencer par consulter le <a href="http://larlet.com">profil dédié à mon activité professionnelle</a> et/ou contacter directement <a href="http://scopyleft.fr/">scopyleft</a>, la <abbr title="Société coopérative et participative">SCOP</abbr> dont je fais partie depuis six ans. Je recommande au préalable de lire <a href="/david/blog/2018/cout-site/" title="Attention ce qui va suivre peut vous choquer">combien coûte un site</a> et pourquoi je suis plutôt favorable à une <a href="/david/pro/devis/" title="Discutons-en !">non-demande de devis</a>.
    </p>
    <p>
      Je ne traque pas ta navigation mais mon
      <abbr title="Alwaysdata, 62 rue Tiquetonne 75002 Paris, +33.184162340">hébergeur</abbr>
      conserve des logs d’accès.
    </p>
  </div>
</footer>
<script type="text/javascript">
  ;(_ => {
    const jumper = document.getElementById('jumper')
    jumper.addEventListener('click', e => {
      e.preventDefault()
      const anchor = e.target.getAttribute('href')
      const targetEl = document.getElementById(anchor.substring(1))
      targetEl.scrollIntoView({behavior: 'smooth'})
    })
  })()
</script>