No description, website, or topics provided.
Python
Permalink
Failed to load latest commit information.
builtins Small fixes to some builtin tests. Feb 11, 2015
examples Replace examples/pytree.py with canonical version. Feb 11, 2015
parse
tests
.gitignore add .gitignore Dec 6, 2013
LICENSE import into git Dec 6, 2013
README.md pytd optimizations, AST tweaking. Apr 12, 2014
__init__.py
abc_hierarchy.py
all_tests.py Some clean-up. Feb 11, 2015
booleq.py Change tests of builtin operators to be "only has result" from "has r… Feb 11, 2015
booleq_test.py Change tests of builtin operators to be "only has result" from "has r… Feb 11, 2015
checker.py
checker_classes_test.py
checker_generics_test.py
checker_interface_test.py Merge ast.py and typing.py. Call the result "pytd.py". Mar 26, 2014
checker_overloading_test.py fix import paths for all_tests.py Dec 9, 2013
checker_test.py
checker_union_test.py
demo.py cleanups, optional parameters, homogeneous types, add prettyprinting Mar 26, 2014
inference_test.py Log output tweak. Aug 27, 2014
optimize.py Slightly nicer output for call with wrong args.. Feb 11, 2015
optimize_test.py
pytd.py Don't allow empty UnionTypes. Feb 11, 2015
pytd_test.py
setup.py Fix pylint complaints. Feb 11, 2015
slots.py Additional operator tests (mostly not working yet). Feb 11, 2015
slots_test.py
type_match.py Change tests of builtin operators to be "only has result" from "has r… Feb 11, 2015
type_match_test.py
utils.py
utils_test.py Rename UnknownType to AnythingType to avoid confusion with "unknown" … Feb 11, 2015

README.md

Pytypedecl - https://github.com/google/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.

License

Apache 2.0

Motivation

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.

Status

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 "application.py", 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 https://github.com/google/pytypedecl.git
python setup.py install

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

$ python -B demo.py

The -B flag prevents the generation of pyc file.

You can also run the tests:

$ python -B all_tests.py

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 email.py)

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