/usr/share/doc/mypy-doc/html/basics.html is in mypy-doc 0.560-1.
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 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 | <!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Basics — Mypy 0.560 documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="index" title="Index"
href="genindex.html"/>
<link rel="search" title="Search" href="search.html"/>
<link rel="top" title="Mypy 0.560 documentation" href="index.html"/>
<link rel="next" title="Getting started" href="getting_started.html"/>
<link rel="prev" title="Introduction" href="introduction.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="index.html" class="icon icon-home"> Mypy
</a>
<div class="version">
0.560
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="introduction.html">Introduction</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Basics</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#function-signatures">Function signatures</a></li>
<li class="toctree-l2"><a class="reference internal" href="#mixing-dynamic-and-static-typing">Mixing dynamic and static typing</a></li>
<li class="toctree-l2"><a class="reference internal" href="#the-typing-module">The typing module</a></li>
<li class="toctree-l2"><a class="reference internal" href="#type-checking-programs">Type checking programs</a></li>
<li class="toctree-l2"><a class="reference internal" href="#library-stubs-and-the-typeshed-repo">Library stubs and the Typeshed repo</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="getting_started.html">Getting started</a></li>
<li class="toctree-l1"><a class="reference internal" href="builtin_types.html">Built-in types</a></li>
<li class="toctree-l1"><a class="reference internal" href="python2.html">Type checking Python 2 code</a></li>
<li class="toctree-l1"><a class="reference internal" href="type_inference_and_annotations.html">Type inference and type annotations</a></li>
<li class="toctree-l1"><a class="reference internal" href="kinds_of_types.html">Kinds of types</a></li>
<li class="toctree-l1"><a class="reference internal" href="class_basics.html">Class basics</a></li>
<li class="toctree-l1"><a class="reference internal" href="dynamic_typing.html">Dynamically typed code</a></li>
<li class="toctree-l1"><a class="reference internal" href="function_overloading.html">Function Overloading</a></li>
<li class="toctree-l1"><a class="reference internal" href="casts.html">Casts</a></li>
<li class="toctree-l1"><a class="reference internal" href="duck_type_compatibility.html">Duck type compatibility</a></li>
<li class="toctree-l1"><a class="reference internal" href="common_issues.html">Common issues</a></li>
<li class="toctree-l1"><a class="reference internal" href="generics.html">Generics</a></li>
<li class="toctree-l1"><a class="reference internal" href="supported_python_features.html">Supported Python features and modules</a></li>
<li class="toctree-l1"><a class="reference internal" href="additional_features.html">Additional features</a></li>
<li class="toctree-l1"><a class="reference internal" href="command_line.html">The mypy command line</a></li>
<li class="toctree-l1"><a class="reference internal" href="config_file.html">The mypy configuration file</a></li>
<li class="toctree-l1"><a class="reference internal" href="python36.html">New features in Python 3.6</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
<li class="toctree-l1"><a class="reference internal" href="cheat_sheet.html">Mypy syntax cheat sheet (Python 2)</a></li>
<li class="toctree-l1"><a class="reference internal" href="cheat_sheet_py3.html">Mypy syntax cheat sheet (Python 3)</a></li>
<li class="toctree-l1"><a class="reference internal" href="revision_history.html">Revision history</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">Mypy</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> »</li>
<li>Basics</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/basics.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="basics">
<h1>Basics<a class="headerlink" href="#basics" title="Permalink to this headline">¶</a></h1>
<p>This chapter introduces some core concepts of mypy, including function
annotations, the <code class="docutils literal"><span class="pre">typing</span></code> module and library stubs. Read it carefully,
as the rest of documentation may not make much sense otherwise.</p>
<div class="section" id="function-signatures">
<h2>Function signatures<a class="headerlink" href="#function-signatures" title="Permalink to this headline">¶</a></h2>
<p>A function without a type annotation is considered dynamically typed:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">greeting</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>
<span class="k">return</span> <span class="s1">'Hello, {}'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">name</span><span class="p">)</span>
</pre></div>
</div>
<p>You can declare the signature of a function using the Python 3
annotation syntax (Python 2 is discussed later in <a class="reference internal" href="python2.html#python2"><span class="std std-ref">Type checking Python 2 code</span></a>).
This makes the function statically typed, and that causes type
checker report type errors within the function.</p>
<p>Here’s a version of the above function that is statically typed and
will be type checked:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">greeting</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="o">-></span> <span class="nb">str</span><span class="p">:</span>
<span class="k">return</span> <span class="s1">'Hello, {}'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">name</span><span class="p">)</span>
</pre></div>
</div>
<p>If a function does not explicitly return a value we give the return
type as <code class="docutils literal"><span class="pre">None</span></code>. Using a <code class="docutils literal"><span class="pre">None</span></code> result in a statically typed
context results in a type check error:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">p</span><span class="p">()</span> <span class="o">-></span> <span class="bp">None</span><span class="p">:</span>
<span class="k">print</span><span class="p">(</span><span class="s1">'hello'</span><span class="p">)</span>
<span class="n">a</span> <span class="o">=</span> <span class="n">p</span><span class="p">()</span> <span class="c1"># Type check error: p has None return value</span>
</pre></div>
</div>
<p>Arguments with default values can be annotated as follows:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">greeting</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">prefix</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s1">'Mr.'</span><span class="p">)</span> <span class="o">-></span> <span class="nb">str</span><span class="p">:</span>
<span class="k">return</span> <span class="s1">'Hello, {} {}'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">prefix</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="mixing-dynamic-and-static-typing">
<h2>Mixing dynamic and static typing<a class="headerlink" href="#mixing-dynamic-and-static-typing" title="Permalink to this headline">¶</a></h2>
<p>Mixing dynamic and static typing within a single file is often
useful. For example, if you are migrating existing Python code to
static typing, it may be easiest to do this incrementally, such as by
migrating a few functions at a time. Also, when prototyping a new
feature, you may decide to first implement the relevant code using
dynamic typing and only add type signatures later, when the code is
more stable.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">f</span><span class="p">():</span>
<span class="mi">1</span> <span class="o">+</span> <span class="s1">'x'</span> <span class="c1"># No static type error (dynamically typed)</span>
<span class="k">def</span> <span class="nf">g</span><span class="p">()</span> <span class="o">-></span> <span class="bp">None</span><span class="p">:</span>
<span class="mi">1</span> <span class="o">+</span> <span class="s1">'x'</span> <span class="c1"># Type check error (statically typed)</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The earlier stages of mypy, known as the semantic analysis, may
report errors even for dynamically typed functions. However, you
should not rely on this, as this may change in the future.</p>
</div>
</div>
<div class="section" id="the-typing-module">
<h2>The typing module<a class="headerlink" href="#the-typing-module" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal"><span class="pre">typing</span></code> module contains many definitions that are useful in
statically typed code. You typically use <code class="docutils literal"><span class="pre">from</span> <span class="pre">...</span> <span class="pre">import</span></code> to import
them (we’ll explain <code class="docutils literal"><span class="pre">Iterable</span></code> later in this document):</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">Iterable</span>
<span class="k">def</span> <span class="nf">greet_all</span><span class="p">(</span><span class="n">names</span><span class="p">:</span> <span class="n">Iterable</span><span class="p">[</span><span class="nb">str</span><span class="p">])</span> <span class="o">-></span> <span class="bp">None</span><span class="p">:</span>
<span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">names</span><span class="p">:</span>
<span class="k">print</span><span class="p">(</span><span class="s1">'Hello, {}'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">name</span><span class="p">))</span>
</pre></div>
</div>
<p>For brevity, we often omit the <code class="docutils literal"><span class="pre">typing</span></code> import in code examples, but
you should always include it in modules that contain statically typed
code.</p>
<p>The presence or absence of the <code class="docutils literal"><span class="pre">typing</span></code> module does not affect
whether your code is type checked; it is only required when you use
one or more special features it defines.</p>
</div>
<div class="section" id="type-checking-programs">
<h2>Type checking programs<a class="headerlink" href="#type-checking-programs" title="Permalink to this headline">¶</a></h2>
<p>You can type check a program by using the <code class="docutils literal"><span class="pre">mypy</span></code> tool, which is
basically a linter – it checks your program for errors without actually
running it:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ mypy program.py
</pre></div>
</div>
<p>All errors reported by mypy are essentially warnings that you are free
to ignore, if you so wish.</p>
<p>The next chapter explains how to download and install mypy:
<a class="reference internal" href="getting_started.html#getting-started"><span class="std std-ref">Getting started</span></a>.</p>
<p>More command line options are documented in <a class="reference internal" href="command_line.html#command-line"><span class="std std-ref">The mypy command line</span></a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Depending on how mypy is configured, you may have to explicitly use
the Python 3 interpreter to run mypy. The mypy tool is an ordinary
mypy (and so also Python) program. For example:</p>
<div class="last highlight-default"><div class="highlight"><pre><span></span>$ python3 -m mypy program.py
</pre></div>
</div>
</div>
</div>
<div class="section" id="library-stubs-and-the-typeshed-repo">
<span id="library-stubs"></span><h2>Library stubs and the Typeshed repo<a class="headerlink" href="#library-stubs-and-the-typeshed-repo" title="Permalink to this headline">¶</a></h2>
<p>In order to type check code that uses library modules such as those
included in the Python standard library, you need to have library
<em>stubs</em>. A library stub defines a skeleton of the public interface
of the library, including classes, variables and functions and
their types, but dummy function bodies.</p>
<p>For example, consider this code:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">x</span> <span class="o">=</span> <span class="nb">chr</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span>
</pre></div>
</div>
<p>Without a library stub, the type checker would have no way of
inferring the type of <code class="docutils literal"><span class="pre">x</span></code> and checking that the argument to <code class="docutils literal"><span class="pre">chr</span></code>
has a valid type. Mypy incorporates the <a class="reference external" href="https://github.com/python/typeshed">typeshed</a> project, which contains library
stubs for the Python builtins and the standard library. The stub for
the builtins contains a definition like this for <code class="docutils literal"><span class="pre">chr</span></code>:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">chr</span><span class="p">(</span><span class="n">code</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-></span> <span class="nb">str</span><span class="p">:</span> <span class="o">...</span>
</pre></div>
</div>
<p>In stub files we don’t care about the function bodies, so we use
an ellipsis instead. That <code class="docutils literal"><span class="pre">...</span></code> is three literal dots!</p>
<p>Mypy complains if it can’t find a stub (or a real module) for a
library module that you import. You can create a stub easily; here is
an overview:</p>
<ul>
<li><p class="first">Write a stub file for the library and store it as a <code class="docutils literal"><span class="pre">.pyi</span></code> file in
the same directory as the library module.</p>
</li>
<li><p class="first">Alternatively, put your stubs (<code class="docutils literal"><span class="pre">.pyi</span></code> files) in a directory
reserved for stubs (e.g., <code class="docutils literal"><span class="pre">myproject/stubs</span></code>). In this case you
have to set the environment variable <code class="docutils literal"><span class="pre">MYPYPATH</span></code> to refer to the
directory. For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ export MYPYPATH=~/work/myproject/stubs
</pre></div>
</div>
</li>
</ul>
<p>Use the normal Python file name conventions for modules, e.g. <code class="docutils literal"><span class="pre">csv.pyi</span></code>
for module <code class="docutils literal"><span class="pre">csv</span></code>. Use a subdirectory with <code class="docutils literal"><span class="pre">__init__.pyi</span></code> for packages.</p>
<p>If a directory contains both a <code class="docutils literal"><span class="pre">.py</span></code> and a <code class="docutils literal"><span class="pre">.pyi</span></code> file for the
same module, the <code class="docutils literal"><span class="pre">.pyi</span></code> file takes precedence. This way you can
easily add annotations for a module even if you don’t want to modify
the source code. This can be useful, for example, if you use 3rd party
open source libraries in your program (and there are no stubs in
typeshed yet).</p>
<p>That’s it! Now you can access the module in mypy programs and type check
code that uses the library. If you write a stub for a library module,
consider making it available for other programmers that use mypy
by contributing it back to the typeshed repo.</p>
<p>There is more information about creating stubs in the
<a class="reference external" href="https://github.com/python/mypy/wiki/Creating-Stubs-For-Python-Modules">mypy wiki</a>.
The following sections explain the kinds of type annotations you can use
in your programs and stub files.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You may be tempted to point <code class="docutils literal"><span class="pre">MYPYPATH</span></code> to the standard library or
to the <code class="docutils literal"><span class="pre">site-packages</span></code> directory where your 3rd party packages
are installed. This is almost always a bad idea – you will likely
get tons of error messages about code you didn’t write and that
mypy can’t analyze all that well yet, and in the worst case
scenario mypy may crash due to some construct in a 3rd party
package that it didn’t expect.</p>
</div>
</div>
</div>
</div>
<div class="articleComments">
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="getting_started.html" class="btn btn-neutral float-right" title="Getting started" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="introduction.html" class="btn btn-neutral" title="Introduction" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
© Copyright 2017, Jukka Lehtosalo.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'0.560',
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>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
|