Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Failed to load latest commit information.
builtins Small fixes to some builtin tests.
examples Replace examples/ with canonical version.
parse Remove unneeded AdjustInit visitor
tests Fix pylint complaints.
.gitignore add .gitignore
LICENSE import into git pytd optimizations, AST tweaking. import into git Add optimization: merge types into common base type. Some clean-up. Change tests of builtin operators to be "only has result" from "has r… Change tests of builtin operators to be "only has result" from "has r… Add mandatory 'name' attribute to pytd.TypeDeclUnit. Some clean-up. Some clean-up. Merge and Call the result "". fix import paths for fix import paths for Fix pylint complaints. cleanups, optional parameters, homogeneous types, add prettyprinting Log output tweak. Slightly nicer output for call with wrong args.. Rename UnknownType to AnythingType to avoid confusion with "unknown" … Don't allow empty UnionTypes. Make pytd AST nodes sortable. (This helps with some determinism issues.) Fix pylint complaints. Additional operator tests (mostly not working yet). Add support for comparison operators. Change tests of builtin operators to be "only has result" from "has r… Fix matching against builtin functions. Rename UnknownType to AnythingType to avoid confusion with "unknown" … Rename UnknownType to AnythingType to avoid confusion with "unknown" …

Pytypedecl -

Pytypedecl consists of a type declaration language for Python and an optional run-time type checker. This project was started by Raoul-Gabriel Urma under the supervision of Peter Ludemann and Gregory P. Smith during a summer 2013 internship at Google.


Apache 2.0


Why types declarations?

Type declarations are useful to document your code. This proposal starts a conversation with the community to reach a standard for a type declaration language for Python.

Why runtime type-checking?

Runtime type-checking of optional type declarations is useful for code maintenance and debugging. Our type-checker is available as a Python package. You therefore do not need to run external tools to benefit from the type-checking.


This project is in its infancy -- we intend to make many updates in the next couple of months. We currently support Python 2.7. Support for Python 3 coming soon.

Type declaration language

Types declarations are specified in an external file with the extension "pytd". For example if you want to provide types for "", you define the type inside the file "application.pytd". Examples of type declarations files can be found in the /tests/ folder.

Here’s an example of a type declaration file that mixes several features:

class Logger:
  def log(messages: list<str>, buffer: Readable or Writeable) raises IOException
  def log(messages: list<str>) -> None
  def setStatus(status: int or str)

The type declaration language currently supports the following features:

  • Function signatures: Functions can be given a signature following the Python 3 function annotation convention. However, we extended it in a number of ways that would be difficult or clumsy using Python 3's annotations.

  • Exceptions: In addition to the return type, you can specify the exceptions that the function might raise. There is no runtime checking for this, but exceptions can be useful documentation and an automated type inferencer could deduce the possible exceptions that a function might throw.

  • Overloading: A function is allowed to have multiple different signatures. This is not supported in the Python 3 function annotation syntax but is supported by pytypedecl.

  • Union types: It is sometime convenient to indicate that a type can hold values from a number of different types. Union types allow to express this idea. For example int or float indicates that a value may be an int or a float. There is no limit to the number of types in a union. A none-able type can be seen as the union of a type and None. (Note: None is a unit type and is a subtype of NoneType. Because there's only one subtype of NoneType, for type-specification purposes, None and NoneType are the same.)

  • Generics: A type can be parameterised with a set of type arguments, similarly to Java generics. For example, generator<str> describes a generator that only produces strs, dict<str, int> describes a dictionary of keys of type str and values of type int.

Coming soon:

  • Declaration of type parameters for methods and classes.
  • Bounded type parameters
  • Support for tags: @classmethod, @staticmethod...

How to get started

git clone
python install

The package is now installed. You can run an example:

$ python -B

The -B flag prevents the generation of pyc file.

You can also run the tests:

$ python -B

Look into the /examples/ directory to see how the emailer example works. You need to do two things to type-check your program:

1. Create a type declaration file

Create a type declaration file that has the name of the Python file you want to type-check but with the extension .pytd (e.g. email.pytd for

2. Import the checker package

Include the following two imports in the Python file that you want to type-check:

import sys
import checker

And the following line after your function and class declarations (before they are used)

checker.CheckFromFile(sys.modules[__name__], __file__ + "td")

That’s it! You can now run your python program and it will be type-checked at runtime using the type declarations you defined in the pytd file.

How to contribute to the project

Something went wrong with that request. Please try again.