What are variable annotations in Python 3.6?
<p>Python 3.6 is about to be released. <a href="https://www.python.org/dev/peps/pep-0494/">PEP 494 -- Python 3.6 Release Schedule</a> mentions the end of December, so I went through <a href="https://docs.python.org/3.6/whatsnew/3.6.html">What's New in Python 3.6</a> to see they mention the <em>variable annotations</em>:</p>

<blockquote>
  <p><a href="https://www.python.org/dev/peps/pep-0484">PEP 484</a> introduced standard for type annotations of function parameters, a.k.a. type hints. This PEP adds syntax to Python for annotating the types of variables including class variables and instance variables:</p>

<pre><code>  primes: List[int] = []

  captain: str  # Note: no initial value!

  class Starship:
     stats: Dict[str, int] = {}
</code></pre>
  
  <p>Just as for function annotations, the Python interpreter does not attach any particular meaning to variable annotations and only stores them in a special attribute <code>__annotations__</code> of a class or module. In contrast to variable declarations in statically typed languages, the goal of annotation syntax is to provide an easy way to specify structured type metadata for third party tools and libraries via the abstract syntax tree and the <code>__annotations__</code> attribute.</p>
</blockquote>

<p>So from what I read they are part of the type hints coming from Python 3.5, described in <a href="http://stackoverflow.com/q/32557920/1983854">What are Type hints in Python 3.5</a>.</p>

<p>I follow the <code>captain: str</code> and <code>class Starship</code> example, but not sure about the last one: How does <code>primes: List[int] = []</code> explain? Is it defining an empty list that will just allow integers?</p>

<p>Everything between <code>:</code> and the <code>=</code> is a type hint, so <code>primes</code> is indeed defined as <code>List[int]</code>, and initially set to an empty list (and <code>stats</code> is an empty dictionary initially, defined as <code>Dict[str, int]</code>).</p>

<p><code>List[int]</code> and <code>Dict[str, int]</code> are not part of the next syntax however, these were already defined in the Python 3.5 typing hints PEP. The 3.6 <a href="https://www.python.org/dev/peps/pep-0526/">PEP 526 â <em>Syntax for Variable Annotations</em></a> proposal <em>only</em> defines the syntax to attach the same hints to variables; before you could only attach type hints to variables with comments (e.g. <code>primes = []  # List[int]</code>).</p>

<p>Both <code>List</code> and <code>Dict</code> are <em>Generic</em> types, indicating that you have a list or dictionary mapping with specific (concrete) contents. </p>

<p>For <code>List</code>, there is only one 'argument' (the elements in the <code>[...]</code> syntax), the type of every element in the list. For <code>Dict</code>, the first argument is the key type, and the second the value type. So <em>all</em> values in the <code>primes</code> list are integers, and <em>all</em> key-value pairs in the <code>stats</code> dictionary are <code>(str, int)</code> pairs, mapping strings to integers.</p>

<p>See the <a href="https://docs.python.org/3/library/typing.html#typing.List"><code>typing.List</code></a> and <a href="https://docs.python.org/3/library/typing.html#typing.Dict"><code>typing.Dict</code></a> definitions, the <a href="https://docs.python.org/3/library/typing.html#generics">section on <em>Generics</em></a>, as well as <a href="https://www.python.org/dev/peps/pep-0483">PEP 483 â <em>The Theory of Type Hints</em></a>.</p>

<p>Like type hints on functions, their use is optional and are also considered <em>annotations</em> (provided there is an object to attach these to, so globals in modules and attributes on classes, but not locals in functions) which you could introspect via the <code>__annotations__</code> attribute. You can attach arbitrary info to these annotations, you are not strictly limited to type hint information.</p>

<p>You may want to read the <a href="https://www.python.org/dev/peps/pep-0526/">full proposal</a>; it contains some additional functionality above and beyond the new syntax; it specifies when such annotations are evaluated, how to introspect them and how to declare something as a class attribute vs. instance attribute, for example.</p>

python python-3.x annotations type-hinting python-3.6