Python type hints and migration to Python 3

Migration to Python 3

See these Google Slides for our plan overview for migrating to Python 3 and adding mypy type hints to help catch problems in the migration and elsewhere (esp. with the string to unicode vs. bytes change).

It looks like this:

def emphasize(message):
  # type: (str) -> str
  """Construct an emphatic message."""
  return message + '!'

Type hints

A few type hints -- esp. one per function definition -- can go a long way to catching problems and documenting types.

PyCharm checks types interactively, while you edit. You don't need any other tools to check types. See Python Type Checking (Guide).

Batch programs mypy and pytest are other ways to check types, particularly in Continuous Integration builds.

Typeshed is a repository for "stub" files that associate type definitions with existing libraries. It's bundled with PyCharm, mypy, and pytype. It does not have types for Numpy.

Types for Numpy

1. There are experimental type stubs in the numpy repo that define types for dtype and ndarray.

def array(
    object: object,
    dtype: _DtypeLike = ...,
    copy: bool = ...,
    subok: bool = ...,
    ndmin: int = ...,
) -> ndarray: ...

2. There's an older but a bit more ambitious numpy stub numpy-mypy. It provides types for class ndarray that supports an element type parameter (that is, ndarray is a generic type), and functions such as np.array:

def array(object: Any, dtype: Any=None, copy: bool=True,
          order: str=None, subok: bool=False,
          ndmin: int=0) -> ndarray[Any]: ...

To install stub files:

1. Copy them into a stubs/ directory in the project.
2. Mark a directory as a source root by choosing Mark Directory as | Sources Root from the context menu of the directory.

(We can check in the stub files and the project setting.)