Document Python 2 annotation syntax

Author: JukkaL

docs/source/basics.rst

@@ -10,10 +10,10 @@ Function signatures
 
 A function without a type signature is dynamically typed. You can
 declare the signature of a function using the Python 3 annotation
-syntax. This makes the function statically typed (the type checker
-reports type errors within the function). A function without a
-type annotation is dynamically typed, and identical to ordinary
-Python:
+syntax (Python 2 is discussed later in :ref:`python2`.) This makes the
+function statically typed (the type checker reports type errors within
+the function). A function without a type annotation is dynamically
+typed, and identical to ordinary Python:
 
 .. code-block:: python
 

docs/source/conf.py

@@ -46,7 +46,7 @@
 
 # General information about the project.
 project = u'Mypy'
-copyright = u'2014, Jukka Lehtosalo'
+copyright = u'2016, Jukka Lehtosalo'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

docs/source/index.rst

@@ -12,6 +12,7 @@ Welcome to Mypy documentation!
    introduction
    basics
    builtin_types
+   python2
    type_inference_and_annotations
    kinds_of_types
    class_basics

docs/source/introduction.rst

@@ -3,11 +3,12 @@ Introduction
 
 Mypy is a static type checker for Python. If you sprinkle your code
 with type annotations using the Python 3 function annotation syntax
-(using the PEP 484 notation), mypy can type check you code and find
-common bugs. Mypy is a static analyzer, or a lint-like tool: type
-annotations are just hints and are not enforced when running your
-program. You run your program with a standard Python interpreter, and
-the annotations are treated basically as comments.
+(using the PEP 484 notation) or a comment-based annotation syntax for
+Python 2 code, mypy can type check you code and find common bugs. Mypy
+is a static analyzer, or a lint-like tool: type annotations are just
+hints and are not enforced when running your program. You run your
+program with a standard Python interpreter, and the annotations are
+treated basically as comments.
 
 Mypy has a powerful but easy-to-use type system with modern features
 such as type inference, generics, function types, tuple types and
@@ -17,9 +18,8 @@ programs, but it will make your programs easier to debug, maintain and
 understand.
 
 This document is a short introduction to mypy. It will get you started
-writing statically typed code. Knowledge of Python 3.x and some kind
-of a statically typed object-oriented language such as Java are
-assumed.
+writing statically typed code. Knowledge of Python and some kind of a
+statically typed object-oriented language such as Java are assumed.
 
 .. note::
    Mypy is still experimental. There will be changes

docs/source/python2.rst

@@ -0,0 +1,65 @@
+.. _python2:
+
+Type checking Python 2 code
+===========================
+
+For code that needs to be Python 2.7 compatible, function type
+annotations are given in comments, since the function annotation
+syntax was introduced in Python 3. The comment-based syntax is
+specified in `PEP 484 <https://www.python.org/dev/peps/pep-0484>`_.
+
+Run mypy in Python 2 mode by using the ``--py2`` option::
+
+    $ mypy --py2 program.py
+
+To run your program, you must have the ``typing`` module in your module
+search path. Use ``pip install typing`` to install the module (this also
+works for Python 3).
+
+The example below illustrates Python 2 function type annotation
+syntax. This is also valid in Python 3 mode:
+
+.. code-block:: python
+
+    from typing import List
+
+    def hello(): # type: () -> None
+        print 'hello'
+
+    class Example:
+        def method(self, lst, opt=0, *args, **kwargs):
+            # type: (List[str], int, *str, **bool) -> int
+            ...
+
+Here are more specifics:
+
+- You should include types for arguments with default values in the
+  annotation. The ``opt`` argument of ``method`` above is an example
+  of this.
+
+- For ``*args`` and ``**kwargs`` the type should be prefixed with
+  ``*`` or ``**``, respectively. Again, the above example illustrates
+  this.
+
+- The type syntax for variables is the same as for Python 3.
+
+- Things like ``Any`` must be imported from ``typing``, even if they
+  are only used in comments.
+
+- You don't provide an annotation for the ``self``/``cls`` variable of
+  methods.
+
+- The annotation can be on the same line as the function header or on
+  the following line.
+
+- You don't need to use string literal escapes for forward references
+  within comments.
+
+- Mypy uses a separate set of library stub files in `typeshed
+  <http://github.com/python/typeshed>`_ for Python 2. Library support
+  may vary between Python 2 and Python 3.
+
+.. note::
+
+    Currently there's no support for splitting an annotation to multiple
+    lines. This will likely change in the future.