/usr/share/doc/python-attr/html/extending.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 | <!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>Extending — 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="How Does It Work?" href="how-does-it-work.html" />
<link rel="prev" title="API Reference" href="api.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="extending">
<span id="id1"></span><h1>Extending<a class="headerlink" href="#extending" title="Permalink to this headline">¶</a></h1>
<p>Each <code class="docutils literal"><span class="pre">attrs</span></code>-decorated class has a <code class="docutils literal"><span class="pre">__attrs_attrs__</span></code> class attribute.
It is a tuple of <a class="reference internal" href="api.html#attr.Attribute" title="attr.Attribute"><code class="xref py py-class docutils literal"><span class="pre">attr.Attribute</span></code></a> carrying meta-data about each attribute.</p>
<p>So it is fairly simple to build your own decorators on top of <code class="docutils literal"><span class="pre">attrs</span></code>:</p>
<div class="highlight-default"><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="k">def</span> <span class="nf">print_attrs</span><span class="p">(</span><span class="bp">cls</span><span class="p">):</span>
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="bp">cls</span><span class="o">.</span><span class="n">__attrs_attrs__</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nd">@print_attrs</span>
<span class="gp">... </span><span class="nd">@attr</span><span class="o">.</span><span class="n">s</span>
<span class="gp">... </span><span class="k">class</span> <span class="nc">C</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">a</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="go">(Attribute(name='a', default=NOTHING, validator=None, repr=True, cmp=True, hash=None, init=True, metadata=mappingproxy({}), type=None, converter=None),)</span>
</pre></div>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p>The <a class="reference internal" href="api.html#attr.s" title="attr.s"><code class="xref py py-func docutils literal"><span class="pre">attr.s()</span></code></a> decorator <strong>must</strong> be applied first because it puts <code class="docutils literal"><span class="pre">__attrs_attrs__</span></code> in place!
That means that is has to come <em>after</em> your decorator because:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="nd">@a</span>
<span class="nd">@b</span>
<span class="k">def</span> <span class="nf">f</span><span class="p">():</span>
<span class="k">pass</span>
</pre></div>
</div>
<p>is just <a class="reference external" href="https://en.wikipedia.org/wiki/Syntactic_sugar">syntactic sugar</a> for:</p>
<div class="last highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">original_f</span><span class="p">():</span>
<span class="k">pass</span>
<span class="n">f</span> <span class="o">=</span> <span class="n">a</span><span class="p">(</span><span class="n">b</span><span class="p">(</span><span class="n">original_f</span><span class="p">))</span>
</pre></div>
</div>
</div>
<div class="section" id="wrapping-the-decorator">
<h2>Wrapping the Decorator<a class="headerlink" href="#wrapping-the-decorator" title="Permalink to this headline">¶</a></h2>
<p>A more elegant way can be to wrap <code class="docutils literal"><span class="pre">attrs</span></code> altogether and build a class <a class="reference external" href="https://en.wikipedia.org/wiki/Domain-specific_language">DSL</a> on top of it.</p>
<p>An example for that is the package <a class="reference external" href="https://github.com/hynek/environ_config">environ_config</a> that uses <code class="docutils literal"><span class="pre">attrs</span></code> under the hood to define environment-based configurations declaratively without exposing <code class="docutils literal"><span class="pre">attrs</span></code> APIs at all.</p>
</div>
<div class="section" id="types">
<h2>Types<a class="headerlink" href="#types" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal"><span class="pre">attrs</span></code> offers two ways of attaching type information to attributes:</p>
<ul class="simple">
<li><a class="reference external" href="https://www.python.org/dev/peps/pep-0526/">PEP 526</a> annotations on Python 3.6 and later,</li>
<li>and the <em>type</em> argument to <a class="reference internal" href="api.html#attr.ib" title="attr.ib"><code class="xref py py-func docutils literal"><span class="pre">attr.ib()</span></code></a>.</li>
</ul>
<p>This information is available to you:</p>
<div class="highlight-default"><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</span><span class="o">.</span><span class="n">s</span>
<span class="gp">... </span><span class="k">class</span> <span class="nc">C</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">x</span><span class="p">:</span> <span class="nb">int</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="gp">... </span> <span class="n">y</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="nb">type</span><span class="o">=</span><span class="nb">str</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">attr</span><span class="o">.</span><span class="n">fields</span><span class="p">(</span><span class="n">C</span><span class="p">)</span><span class="o">.</span><span class="n">x</span><span class="o">.</span><span class="n">type</span>
<span class="go"><class 'int'></span>
<span class="gp">>>> </span><span class="n">attr</span><span class="o">.</span><span class="n">fields</span><span class="p">(</span><span class="n">C</span><span class="p">)</span><span class="o">.</span><span class="n">y</span><span class="o">.</span><span class="n">type</span>
<span class="go"><class 'str'></span>
</pre></div>
</div>
<p>Currently, <code class="docutils literal"><span class="pre">attrs</span></code> doesn’t do anything with this information but it’s very useful if you’d like to write your own validators or serializers!</p>
</div>
<div class="section" id="metadata">
<span id="extending-metadata"></span><h2>Metadata<a class="headerlink" href="#metadata" title="Permalink to this headline">¶</a></h2>
<p>If you’re the author of a third-party library with <code class="docutils literal"><span class="pre">attrs</span></code> integration, you may want to take advantage of attribute metadata.</p>
<p>Here are some tips for effective use of metadata:</p>
<ul>
<li><p class="first">Try making your metadata keys and values immutable.
This keeps the entire <code class="docutils literal"><span class="pre">Attribute</span></code> instances immutable too.</p>
</li>
<li><p class="first">To avoid metadata key collisions, consider exposing your metadata keys from your modules.:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">mylib</span> <span class="k">import</span> <span class="n">MY_METADATA_KEY</span>
<span class="nd">@attr</span><span class="o">.</span><span class="n">s</span>
<span class="k">class</span> <span class="nc">C</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="n">x</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">metadata</span><span class="o">=</span><span class="p">{</span><span class="n">MY_METADATA_KEY</span><span class="p">:</span> <span class="mi">1</span><span class="p">})</span>
</pre></div>
</div>
<p>Metadata should be composable, so consider supporting this approach even if you decide implementing your metadata in one of the following ways.</p>
</li>
<li><p class="first">Expose <code class="docutils literal"><span class="pre">attr.ib</span></code> wrappers for your specific metadata.
This is a more graceful approach if your users don’t require metadata from other libraries.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">MY_TYPE_METADATA</span> <span class="o">=</span> <span class="s1">'__my_type_metadata'</span>
<span class="go">>>></span>
<span class="gp">>>> </span><span class="k">def</span> <span class="nf">typed</span><span class="p">(</span><span class="bp">cls</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">NOTHING</span><span class="p">,</span> <span class="n">validator</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="nb">repr</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="nb">cmp</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="nb">hash</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">init</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">convert</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">metadata</span><span class="o">=</span><span class="p">{}):</span>
<span class="gp">... </span> <span class="n">metadata</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">()</span> <span class="k">if</span> <span class="ow">not</span> <span class="n">metadata</span> <span class="k">else</span> <span class="n">metadata</span>
<span class="gp">... </span> <span class="n">metadata</span><span class="p">[</span><span class="n">MY_TYPE_METADATA</span><span class="p">]</span> <span class="o">=</span> <span class="bp">cls</span>
<span class="gp">... </span> <span class="k">return</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="p">,</span> <span class="n">validator</span><span class="p">,</span> <span class="nb">repr</span><span class="p">,</span> <span class="nb">cmp</span><span class="p">,</span> <span class="nb">hash</span><span class="p">,</span> <span class="n">init</span><span class="p">,</span> <span class="n">convert</span><span class="p">,</span> <span class="n">metadata</span><span class="p">)</span>
<span class="go">>>></span>
<span class="gp">>>> </span><span class="nd">@attr</span><span class="o">.</span><span class="n">s</span>
<span class="gp">... </span><span class="k">class</span> <span class="nc">C</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">x</span> <span class="o">=</span> <span class="n">typed</span><span class="p">(</span><span class="nb">int</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">init</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">attr</span><span class="o">.</span><span class="n">fields</span><span class="p">(</span><span class="n">C</span><span class="p">)</span><span class="o">.</span><span class="n">x</span><span class="o">.</span><span class="n">metadata</span><span class="p">[</span><span class="n">MY_TYPE_METADATA</span><span class="p">]</span>
<span class="go"><class 'int'></span>
</pre></div>
</div>
</li>
</ul>
</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="#">Extending</a><ul>
<li><a class="reference internal" href="#wrapping-the-decorator">Wrapping the Decorator</a></li>
<li><a class="reference internal" href="#types">Types</a></li>
<li><a class="reference internal" href="#metadata">Metadata</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="api.html" title="previous chapter">API Reference</a></li>
<li>Next: <a href="how-does-it-work.html" title="next chapter">How Does It Work?</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>
|