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>Indeed, variable annotations are just the next step from <code># type</code> comments as they where defined in <code>PEP 484</code>; the rationale behind this change is highlighted in the <a href="https://www.python.org/dev/peps/pep-0526/#rationale">respective PEP section</a>. So, instead of hinting the type with:</p>

<pre><code>primes = []  # type: List[int]
</code></pre>

<p>New syntax was introduced to allow for directly annotating the type with an assignment of the form:</p>

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

<p>which, as @Martijn pointed out, denotes a list of integers by using types available in <a href="https://docs.python.org/3/library/typing.html"><code>typing</code></a> and initializing it to an empty list.</p>

<hr>

<p>In short, the <a href="https://docs.python.org/3.6/reference/simple_stmts.html#annotated-assignment-statements">new syntax introduced</a> simply allows you to annotate with a type after the colon <code>:</code> character and, optionally allows you to assign a value to it:</p>

<pre><code>annotated_assignment_stmt ::=  augtarget ":" expression ["=" expression]
</code></pre>

<hr>

<p>Additional changes were also introduced along with the new syntax; modules and classes now have an <code>__annotations__</code> attribute, as functions have had for some time, in which the type metadata is attached:</p>

<pre><code>from typing import get_type_hints  # grabs __annotations__
</code></pre>

<p>Now <code>__main__.__annotations__</code> holds the declared types:</p>

<pre><code>&gt;&gt;&gt; from typing import List, get_type_hints
&gt;&gt;&gt; primes: List[int] = []
&gt;&gt;&gt; captain: str
&gt;&gt;&gt; import __main__
&gt;&gt;&gt; get_type_hints(__main__)
{'primes': typing.List&lt;~T&gt;[int]}
</code></pre>

<p><code>captain</code> won't currently show up through <a href="https://docs.python.org/3.6/library/typing.html#typing.get_type_hints"><code>get_type_hints</code></a> because <code>get_type_hints</code> only returns types that can also be accessed on a module; i.e it needs a value first:</p>

<pre><code>&gt;&gt;&gt; captain = "Picard"
&gt;&gt;&gt; get_type_hints(__main__)
{'primes': typing.List&lt;~T&gt;[int], 'captain': &lt;class 'str'&gt;}
</code></pre>

<p><sub> Using <code>print(__annotations__)</code> will show <code>'captain': &lt;class 'str'&gt;</code> but you really shouldn't be accessing <code>__annotations__</code> directly.</sub></p>

<p>Similarly, for classes:</p>

<pre><code>&gt;&gt;&gt; get_type_hints(Starship)
ChainMap({'stats': typing.Dict&lt;~KT, ~VT&gt;[str, int]}, {})
</code></pre>

<p>Where a <code>ChainMap</code> is used to grab the annotations for a given class (located in the first mapping) and all annotations defined in the base classes found in its <code>mro</code> (consequent mappings, <code>{}</code> for object).</p>

<p>Along with the new syntax, a new <a href="https://docs.python.org/3.6/library/typing.html#typing.ClassVar"><code>ClassVar</code></a> type has been added to denote class variables. Yup, <code>stats</code> in your example is actually an <em>instance variable</em>, not a <code>ClassVar</code>.</p>

<hr>

<p>As with type hints from <code>PEP 484</code>, these are completely optional and are of main use for type checking tools (and whatever else you can build based on this information). It is to be provisional when the stable version of Py 3.6 is released so small tweaks might be added in the future.</p>

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