/usr/share/doc/python-pint-doc/html/wrapping.html is in python-pint-doc 0.7.2-3.
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 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 | <!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>Wrapping and checking functions — pint 0.7.2 documentation</title>
<link rel="stylesheet" href="_static/flasky.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '0.7.2',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</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="top" title="pint 0.7.2 documentation" href="index.html" />
<link rel="next" title="Serialization" href="serialization.html" />
<link rel="prev" title="Temperature conversion" href="nonmult.html" />
<link media="only screen and (max-device-width: 480px)" href="_static/small_flask.css" type= "text/css" rel="stylesheet" />
</head>
<body role="document">
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="serialization.html" title="Serialization"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="nonmult.html" title="Temperature conversion"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">pint 0.7.2 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="wrapping-and-checking-functions">
<span id="wrapping"></span><h1>Wrapping and checking functions<a class="headerlink" href="#wrapping-and-checking-functions" title="Permalink to this headline">¶</a></h1>
<p>In some cases you might want to use pint with a pre-existing web service or library
which is not units aware. Or you might want to write a fast implementation of a
numerical algorithm that requires the input values in some specific units.</p>
<p>For example, consider a function to return the period of the pendulum within
a hypothetical physics library. The library does not use units, but instead
requires you to provide numerical values in certain units:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">simple_physics</span> <span class="k">import</span> <span class="n">pendulum_period</span>
<span class="gp">>>> </span><span class="n">help</span><span class="p">(</span><span class="n">pendulum_period</span><span class="p">)</span>
<span class="go">Help on function pendulum_period in module simple_physics:</span>
<span class="go">pendulum_period(length)</span>
<span class="go">Return the pendulum period in seconds. The length of the pendulum</span>
<span class="go">must be provided in meters.</span>
<span class="gp">>>> </span><span class="n">pendulum_period</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="go">2.0064092925890407</span>
</pre></div>
</div>
<p>This behaviour is very error prone, in particular when combining multiple libraries.
You could wrap this function to use Quantities instead:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">pint</span> <span class="k">import</span> <span class="n">UnitRegistry</span>
<span class="gp">>>> </span><span class="n">ureg</span> <span class="o">=</span> <span class="n">UnitRegistry</span><span class="p">()</span>
<span class="gp">>>> </span><span class="k">def</span> <span class="nf">mypp_caveman</span><span class="p">(</span><span class="n">length</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">return</span> <span class="n">pendulum_period</span><span class="p">(</span><span class="n">length</span><span class="o">.</span><span class="n">to</span><span class="p">(</span><span class="n">ureg</span><span class="o">.</span><span class="n">meter</span><span class="p">)</span><span class="o">.</span><span class="n">magnitude</span><span class="p">)</span> <span class="o">*</span> <span class="n">ureg</span><span class="o">.</span><span class="n">second</span>
</pre></div>
</div>
<p>and:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mypp_caveman</span><span class="p">(</span><span class="mi">100</span> <span class="o">*</span> <span class="n">ureg</span><span class="o">.</span><span class="n">centimeter</span><span class="p">)</span>
<span class="go"><Quantity(2.0064092925890407, 'second')></span>
</pre></div>
</div>
<p>Pint provides a more convenient way to do this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mypp</span> <span class="o">=</span> <span class="n">ureg</span><span class="o">.</span><span class="n">wraps</span><span class="p">(</span><span class="n">ureg</span><span class="o">.</span><span class="n">second</span><span class="p">,</span> <span class="n">ureg</span><span class="o">.</span><span class="n">meter</span><span class="p">)(</span><span class="n">pendulum_period</span><span class="p">)</span>
</pre></div>
</div>
<p>Or in the decorator format:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nd">@ureg</span><span class="o">.</span><span class="n">wraps</span><span class="p">(</span><span class="n">ureg</span><span class="o">.</span><span class="n">second</span><span class="p">,</span> <span class="n">ureg</span><span class="o">.</span><span class="n">meter</span><span class="p">)</span>
<span class="gp">... </span><span class="k">def</span> <span class="nf">mypp</span><span class="p">(</span><span class="n">length</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">return</span> <span class="n">pendulum_period</span><span class="p">(</span><span class="n">length</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">mypp</span><span class="p">(</span><span class="mi">100</span> <span class="o">*</span> <span class="n">ureg</span><span class="o">.</span><span class="n">centimeter</span><span class="p">)</span>
<span class="go"><Quantity(2.0064092925890407, 'second')></span>
</pre></div>
</div>
<p><cite>wraps</cite> takes 3 input arguments:</p>
<blockquote>
<div><ul>
<li><dl class="first docutils">
<dt><strong>ret</strong>: the return units.</dt>
<dd><p class="first last">Use None to skip conversion.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt><strong>args</strong>: the inputs units for each argument, as an iterable.</dt>
<dd><p class="first last">Use None to skip conversion of any given element.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt><strong>strict</strong>: if <cite>True</cite> all convertible arguments must be a Quantity</dt>
<dd><p class="first last">and others will raise a ValueError (True by default)</p>
</dd>
</dl>
</li>
</ul>
</div></blockquote>
<div class="section" id="strict-mode">
<h2>Strict Mode<a class="headerlink" href="#strict-mode" title="Permalink to this headline">¶</a></h2>
<p>By default, the function is wrapped in <cite>strict</cite> mode. In this mode,
the input arguments assigned to units must be a Quantities.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mypp</span><span class="p">(</span><span class="mf">1.</span> <span class="o">*</span> <span class="n">ureg</span><span class="o">.</span><span class="n">meter</span><span class="p">)</span>
<span class="go"><Quantity(2.0064092925890407, 'second')></span>
<span class="gp">>>> </span><span class="n">mypp</span><span class="p">(</span><span class="mf">1.</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">ValueError</span>: <span class="n">A wrapped function using strict=True requires quantity for all arguments with not None units. (error found for meter, 1.0)</span>
</pre></div>
</div>
<p>To enable using non-Quantity numerical values, set strict to False`.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mypp_ns</span> <span class="o">=</span> <span class="n">ureg</span><span class="o">.</span><span class="n">wraps</span><span class="p">(</span><span class="n">ureg</span><span class="o">.</span><span class="n">second</span><span class="p">,</span> <span class="n">ureg</span><span class="o">.</span><span class="n">meter</span><span class="p">,</span> <span class="kc">False</span><span class="p">)(</span><span class="n">pendulum_period</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">mypp_ns</span><span class="p">(</span><span class="mf">1.</span> <span class="o">*</span> <span class="n">ureg</span><span class="o">.</span><span class="n">meter</span><span class="p">)</span>
<span class="go"><Quantity(2.0064092925890407, 'second')></span>
<span class="gp">>>> </span><span class="n">mypp_ns</span><span class="p">(</span><span class="mf">1.</span><span class="p">)</span>
<span class="go"><Quantity(2.0064092925890407, 'second')></span>
</pre></div>
</div>
<p>In this mode, the value is assumed to have the correct units.</p>
</div>
<div class="section" id="multiple-arguments-or-return-values">
<h2>Multiple arguments or return values<a class="headerlink" href="#multiple-arguments-or-return-values" title="Permalink to this headline">¶</a></h2>
<p>For a function with more arguments, use a tuple:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">simple_physics</span> <span class="k">import</span> <span class="n">pendulum_period2</span>
<span class="gp">>>> </span><span class="n">help</span><span class="p">(</span><span class="n">pendulum_period2</span><span class="p">)</span>
<span class="go">Help on function pendulum_period2 in module simple_physics:</span>
<span class="go">pendulum_period2(length, swing_amplitude)</span>
<span class="go">Return the pendulum period in seconds. The length of the pendulum</span>
<span class="go">must be provided in meters. The swing_amplitude must be in radians.</span>
<span class="gp">>>> </span><span class="n">mypp2</span> <span class="o">=</span> <span class="n">ureg</span><span class="o">.</span><span class="n">wraps</span><span class="p">(</span><span class="n">ureg</span><span class="o">.</span><span class="n">second</span><span class="p">,</span> <span class="p">(</span><span class="n">ureg</span><span class="o">.</span><span class="n">meter</span><span class="p">,</span> <span class="n">ureg</span><span class="o">.</span><span class="n">radians</span><span class="p">))(</span><span class="n">pendulum_period2</span><span class="p">)</span>
<span class="gp">...</span>
</pre></div>
</div>
<p>Or if the function has multiple outputs:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mypp3</span> <span class="o">=</span> <span class="n">ureg</span><span class="o">.</span><span class="n">wraps</span><span class="p">((</span><span class="n">ureg</span><span class="o">.</span><span class="n">second</span><span class="p">,</span> <span class="n">ureg</span><span class="o">.</span><span class="n">meter</span> <span class="o">/</span> <span class="n">ureg</span><span class="o">.</span><span class="n">second</span><span class="p">),</span>
<span class="gp">... </span> <span class="p">(</span><span class="n">ureg</span><span class="o">.</span><span class="n">meter</span><span class="p">,</span> <span class="n">ureg</span><span class="o">.</span><span class="n">radians</span><span class="p">))(</span><span class="n">pendulum_period_maxspeed</span><span class="p">)</span>
<span class="gp">...</span>
</pre></div>
</div>
</div>
<div class="section" id="specifying-relations-between-arguments">
<h2>Specifying relations between arguments<a class="headerlink" href="#specifying-relations-between-arguments" title="Permalink to this headline">¶</a></h2>
<p>In certain cases the actual units but just their relation. This is done using string
starting with the equal sign <cite>=</cite>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nd">@ureg</span><span class="o">.</span><span class="n">wraps</span><span class="p">(</span><span class="s1">'=A**2'</span><span class="p">,</span> <span class="p">(</span><span class="s1">'=A'</span><span class="p">,</span> <span class="s1">'=A'</span><span class="p">))</span>
<span class="gp">... </span><span class="k">def</span> <span class="nf">sqsum</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">return</span> <span class="n">x</span> <span class="o">*</span> <span class="n">x</span> <span class="o">+</span> <span class="mi">2</span> <span class="o">*</span> <span class="n">x</span> <span class="o">*</span> <span class="n">y</span> <span class="o">+</span> <span class="n">y</span> <span class="o">*</span> <span class="n">y</span>
</pre></div>
</div>
<p>which can be read as the first argument (<cite>x</cite>) has certain units (we labeled them <cite>A</cite>),
the second argument (<cite>y</cite>) has the same units as the first (<cite>A</cite> again). The return value
has the unit of <cite>x</cite> squared (<cite>A**2</cite>)</p>
<p>You can use more than one label:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nd">@ureg</span><span class="o">.</span><span class="n">wraps</span><span class="p">(</span><span class="s1">'=A**2*B'</span><span class="p">,</span> <span class="p">(</span><span class="s1">'=A'</span><span class="p">,</span> <span class="s1">'=A*B'</span><span class="p">,</span> <span class="s1">'=B'</span><span class="p">))</span>
<span class="gp">... </span><span class="k">def</span> <span class="nf">some_function</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">z</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">pass</span>
</pre></div>
</div>
</div>
<div class="section" id="ignoring-an-argument-or-return-value">
<h2>Ignoring an argument or return value<a class="headerlink" href="#ignoring-an-argument-or-return-value" title="Permalink to this headline">¶</a></h2>
<p>To avoid the conversion of an argument or return value, use None</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mypp3</span> <span class="o">=</span> <span class="n">ureg</span><span class="o">.</span><span class="n">wraps</span><span class="p">((</span><span class="n">ureg</span><span class="o">.</span><span class="n">second</span><span class="p">,</span> <span class="kc">None</span><span class="p">),</span> <span class="n">ureg</span><span class="o">.</span><span class="n">meter</span><span class="p">)(</span><span class="n">pendulum_period_error</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="checking-units">
<h1>Checking units<a class="headerlink" href="#checking-units" title="Permalink to this headline">¶</a></h1>
<p>When you want pint quantities to be used as inputs to your functions, pint provides a wrapper to ensure units are of
correct type - or more precisely, they match the expected dimensionality of the physical quantity.</p>
<p>Similar to wraps(), you can pass None to skip checking of some parameters, but the return parameter type is not checked.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mypp</span> <span class="o">=</span> <span class="n">ureg</span><span class="o">.</span><span class="n">check</span><span class="p">(</span><span class="s1">'[length]'</span><span class="p">)(</span><span class="n">pendulum_period</span><span class="p">)</span>
</pre></div>
</div>
<p>In the decorator format:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nd">@ureg</span><span class="o">.</span><span class="n">check</span><span class="p">(</span><span class="s1">'[length]'</span><span class="p">)</span>
<span class="gp">... </span><span class="k">def</span> <span class="nf">pendulum_period</span><span class="p">(</span><span class="n">length</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">return</span> <span class="mi">2</span><span class="o">*</span><span class="n">math</span><span class="o">.</span><span class="n">pi</span><span class="o">*</span><span class="n">math</span><span class="o">.</span><span class="n">sqrt</span><span class="p">(</span><span class="n">length</span><span class="o">/</span><span class="n">G</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper"><p><a href="index.html">
<img src="_images/logo-full.jpg" alt="Logo" style="width:80%;height:80%"/>
</a></p>
<h3>About Pint</h3>
Units in Python.
You are currently looking at the documentation of version 0.7.2.
<h3>Other Formats</h3>
<p>
You can download the documentation in other formats as well:
</p>
<ul>
<li><a href="https://media.readthedocs.org/pdf/pint/latest/pint.pdf">as PDF</a>
<li><a href="https://media.readthedocs.org/htmlzip/pint/latest/pint.zip">as zipped HTML</a>
<li><a href="https://media.readthedocs.org/epub/pint/latest/pint.epub">as ePub</a>
</ul>
<h3>Useful Links</h3>
<ul>
<li><a href="https://pypi.python.org/pypi/Pint/">Pint @ PyPI</a></li>
<li><a href="https://github.com/hgrecco/pint">Code in GitHub</a></li>
<li><a href="https://github.com/hgrecco/pint/issues">Issue Tracker</a></li>
</ul>
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Wrapping and checking functions</a><ul>
<li><a class="reference internal" href="#strict-mode">Strict Mode</a></li>
<li><a class="reference internal" href="#multiple-arguments-or-return-values">Multiple arguments or return values</a></li>
<li><a class="reference internal" href="#specifying-relations-between-arguments">Specifying relations between arguments</a></li>
<li><a class="reference internal" href="#ignoring-an-argument-or-return-value">Ignoring an argument or return value</a></li>
</ul>
</li>
<li><a class="reference internal" href="#checking-units">Checking units</a></li>
</ul>
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation overview</a></li>
<p>
<b>Previous</b><br/>
<a href="nonmult.html" title="previous chapter">Temperature conversion</a>
</p>
<p>
<b>Next</b><br/>
<a href="serialization.html" title="next chapter">Serialization</a>
</p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/wrapping.txt"
rel="nofollow">Show Source</a></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>
<a href="http://github.com/hgrecco/pint"><img style="position: fixed; top: 0; right: 0; border: 0;"
src="" alt="Fork me on GitHub" /></a>
<div class="footer">
© Copyright 2016, Hernan E. Grecco. Pint 0.7.2.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
</div>
</body>
</html>
|