/usr/share/doc/python-attr/html/overview.html is in python-attr-doc 17.4.0-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Overview — attrs 17.4.0 documentation</title>
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '17.4.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Why not…" href="why.html" />
<link rel="prev" title="Changelog" href="changelog.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head>
<body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="overview">
<h1>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h1>
<p>In order to fulfill its ambitious goal of bringing back the joy to writing classes, it gives you a class decorator and a way to declaratively define the attributes on that class:</p>
<div class="highlight-pycon"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">attr</span>
<span class="gp">>>> </span><span class="nd">@attr.s</span>
<span class="gp">... </span><span class="k">class</span> <span class="nc">SomeClass</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">a_number</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">default</span><span class="o">=</span><span class="mi">42</span><span class="p">)</span>
<span class="gp">... </span> <span class="n">list_of_numbers</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">default</span><span class="o">=</span><span class="n">attr</span><span class="o">.</span><span class="n">Factory</span><span class="p">(</span><span class="nb">list</span><span class="p">))</span>
<span class="gp">...</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">hard_math</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">another_number</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">a_number</span> <span class="o">+</span> <span class="nb">sum</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">list_of_numbers</span><span class="p">)</span> <span class="o">*</span> <span class="n">another_number</span>
<span class="gp">>>> </span><span class="n">sc</span> <span class="o">=</span> <span class="n">SomeClass</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">])</span>
<span class="gp">>>> </span><span class="n">sc</span>
<span class="go">SomeClass(a_number=1, list_of_numbers=[1, 2, 3])</span>
<span class="gp">>>> </span><span class="n">sc</span><span class="o">.</span><span class="n">hard_math</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
<span class="go">19</span>
<span class="gp">>>> </span><span class="n">sc</span> <span class="o">==</span> <span class="n">SomeClass</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">])</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">sc</span> <span class="o">!=</span> <span class="n">SomeClass</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="p">[</span><span class="mi">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">])</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">attr</span><span class="o">.</span><span class="n">asdict</span><span class="p">(</span><span class="n">sc</span><span class="p">)</span>
<span class="go">{'a_number': 1, 'list_of_numbers': [1, 2, 3]}</span>
<span class="gp">>>> </span><span class="n">SomeClass</span><span class="p">()</span>
<span class="go">SomeClass(a_number=42, list_of_numbers=[])</span>
<span class="gp">>>> </span><span class="n">C</span> <span class="o">=</span> <span class="n">attr</span><span class="o">.</span><span class="n">make_class</span><span class="p">(</span><span class="s2">"C"</span><span class="p">,</span> <span class="p">[</span><span class="s2">"a"</span><span class="p">,</span> <span class="s2">"b"</span><span class="p">])</span>
<span class="gp">>>> </span><span class="n">C</span><span class="p">(</span><span class="s2">"foo"</span><span class="p">,</span> <span class="s2">"bar"</span><span class="p">)</span>
<span class="go">C(a='foo', b='bar')</span>
</pre></div>
</div>
<p>After <em>declaring</em> your attributes <code class="docutils literal"><span class="pre">attrs</span></code> gives you:</p>
<ul class="simple">
<li>a concise and explicit overview of the class’s attributes,</li>
<li>a nice human-readable <code class="docutils literal"><span class="pre">__repr__</span></code>,</li>
<li>a complete set of comparison methods,</li>
<li>an initializer,</li>
<li>and much more,</li>
</ul>
<p><em>without</em> writing dull boilerplate code again and again and <em>without</em> runtime performance penalties.</p>
<p>This gives you the power to use actual classes with actual types in your code instead of confusing <code class="docutils literal"><span class="pre">tuple</span></code>s or <a class="reference external" href="http://www.attrs.org/en/stable/why.html#namedtuples">confusingly behaving</a> <code class="docutils literal"><span class="pre">namedtuple</span></code>s.
Which in turn encourages you to write <em>small classes</em> that do <a class="reference external" href="https://www.destroyallsoftware.com/talks/boundaries">one thing well</a>.
Never again violate the <a class="reference external" href="https://en.wikipedia.org/wiki/Single_responsibility_principle">single responsibility principle</a> just because implementing <code class="docutils literal"><span class="pre">__init__</span></code> et al is a painful drag.</p>
<div class="section" id="philosophy">
<span id="id1"></span><h2>Philosophy<a class="headerlink" href="#philosophy" title="Permalink to this headline">¶</a></h2>
<dl class="docutils">
<dt><strong>It’s about regular classes.</strong></dt>
<dd><code class="docutils literal"><span class="pre">attrs</span></code> is for creating well-behaved classes with a type, attributes, methods, and everything that comes with a class.
It can be used for data-only containers like <code class="docutils literal"><span class="pre">namedtuple</span></code>s or <code class="docutils literal"><span class="pre">types.SimpleNamespace</span></code> but they’re just a sub-genre of what <code class="docutils literal"><span class="pre">attrs</span></code> is good for.</dd>
<dt><strong>The class belongs to the users.</strong></dt>
<dd>You define a class and <code class="docutils literal"><span class="pre">attrs</span></code> adds static methods to that class based on the attributes you declare.
The end.
It doesn’t add metaclasses.
It doesn’t add classes you’ve never heard of to your inheritance tree.
An <code class="docutils literal"><span class="pre">attrs</span></code> class in runtime is indistiguishable from a regular class: because it <em>is</em> a regular class with a few boilerplate-y methods attached.</dd>
<dt><strong>Be light on API impact.</strong></dt>
<dd>As convenient as it seems at first, <code class="docutils literal"><span class="pre">attrs</span></code> will <em>not</em> tack on any methods to your classes save the dunder ones.
Hence all the useful <a class="reference internal" href="api.html#helpers"><span class="std std-ref">tools</span></a> that come with <code class="docutils literal"><span class="pre">attrs</span></code> live in functions that operate on top of instances.
Since they take an <code class="docutils literal"><span class="pre">attrs</span></code> instance as their first argument, you can attach them to your classes with one line of code.</dd>
<dt><strong>Performance matters.</strong></dt>
<dd><code class="docutils literal"><span class="pre">attrs</span></code> runtime impact is very close to zero because all the work is done when the class is defined.
Once you’re instantiating it, <code class="docutils literal"><span class="pre">attrs</span></code> is out of the picture completely.</dd>
<dt><strong>No surprises.</strong></dt>
<dd><code class="docutils literal"><span class="pre">attrs</span></code> creates classes that arguably work the way a Python beginner would reasonably expect them to work.
It doesn’t try to guess what you mean because explicit is better than implicit.
It doesn’t try to be clever because software shouldn’t be clever.</dd>
</dl>
<p>Check out <a class="reference internal" href="how-does-it-work.html"><span class="doc">How Does It Work?</span></a> if you’d like to know how it achieves all of the above.</p>
</div>
<div class="section" id="what-attrs-is-not">
<h2>What <code class="docutils literal"><span class="pre">attrs</span></code> Is Not<a class="headerlink" href="#what-attrs-is-not" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal"><span class="pre">attrs</span></code> does <em>not</em> invent some kind of magic system that pulls classes out of its hat using meta classes, runtime introspection, and shaky interdependencies.</p>
<p>All <code class="docutils literal"><span class="pre">attrs</span></code> does is:</p>
<ol class="arabic simple">
<li>take your declaration,</li>
<li>write dunder methods based on that information,</li>
<li>and attach them to your class.</li>
</ol>
<p>It does <em>nothing</em> dynamic at runtime, hence zero runtime overhead.
It’s still <em>your</em> class.
Do with it as you please.</p>
</div>
<div class="section" id="on-the-attr-s-and-attr-ib-names">
<h2>On the <code class="docutils literal"><span class="pre">attr.s</span></code> and <code class="docutils literal"><span class="pre">attr.ib</span></code> Names<a class="headerlink" href="#on-the-attr-s-and-attr-ib-names" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal"><span class="pre">attr.s</span></code> decorator and the <code class="docutils literal"><span class="pre">attr.ib</span></code> function aren’t any obscure abbreviations.
They are a <em>concise</em> and highly <em>readable</em> way to write <code class="docutils literal"><span class="pre">attrs</span></code> and <code class="docutils literal"><span class="pre">attrib</span></code> with an <em>explicit namespace</em>.</p>
<p>At first, some people have a negative gut reaction to that; resembling the reactions to Python’s significant whitespace.
And as with that, once one gets used to it, the readability and explicitness of that API prevails and delights.</p>
<p>For those who can’t swallow that API at all, <code class="docutils literal"><span class="pre">attrs</span></code> comes with serious business aliases: <code class="docutils literal"><span class="pre">attr.attrs</span></code> and <code class="docutils literal"><span class="pre">attr.attrib</span></code>.</p>
<p>Therefore, the following class definition is identical to the previous one:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">attr</span> <span class="k">import</span> <span class="n">attrs</span><span class="p">,</span> <span class="n">attrib</span><span class="p">,</span> <span class="n">Factory</span>
<span class="gp">>>> </span><span class="nd">@attrs</span>
<span class="gp">... </span><span class="k">class</span> <span class="nc">SomeClass</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">a_number</span> <span class="o">=</span> <span class="n">attrib</span><span class="p">(</span><span class="n">default</span><span class="o">=</span><span class="mi">42</span><span class="p">)</span>
<span class="gp">... </span> <span class="n">list_of_numbers</span> <span class="o">=</span> <span class="n">attrib</span><span class="p">(</span><span class="n">default</span><span class="o">=</span><span class="n">Factory</span><span class="p">(</span><span class="nb">list</span><span class="p">))</span>
<span class="gp">...</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">hard_math</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">another_number</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">a_number</span> <span class="o">+</span> <span class="nb">sum</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">list_of_numbers</span><span class="p">)</span> <span class="o">*</span> <span class="n">another_number</span>
<span class="gp">>>> </span><span class="n">SomeClass</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">])</span>
<span class="go">SomeClass(a_number=1, list_of_numbers=[1, 2, 3])</span>
</pre></div>
</div>
<p>Use whichever variant fits your taste better.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="index.html">
<img class="logo" src="_static/attrs_logo.svg" alt="Logo"/>
</a></p>
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Overview</a><ul>
<li><a class="reference internal" href="#philosophy">Philosophy</a></li>
<li><a class="reference internal" href="#what-attrs-is-not">What <code class="docutils literal"><span class="pre">attrs</span></code> Is Not</a></li>
<li><a class="reference internal" href="#on-the-attr-s-and-attr-ib-names">On the <code class="docutils literal"><span class="pre">attr.s</span></code> and <code class="docutils literal"><span class="pre">attr.ib</span></code> Names</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation overview</a><ul>
<li>Previous: <a href="changelog.html" title="previous chapter">Changelog</a></li>
<li>Next: <a href="why.html" title="next chapter">Why not…</a></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©2018, Hynek Schlawack.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
</div>
</body>
</html>
|