Skip to main content

type checking at test time

Project description

typist is a test time tool that uses your Sphinx docstrings (you do document your code right?) to ensure that your callables:

  • are only called with the types they expect

  • only return types they advertise

  • only raise exceptions they advertise


Right now you have to import typist and install it. The argument to install is the top level package for the code you are interested in testing. In the future I plan on creating plugins for test frameworks.

import typist

typist implements an import hook that will use Python’s AST to add a decorator to all of your callables. The decorator ensures the callable is properly used based on its docstring type declarations. If your callable doesn’t have :param:, :returns or :raises: then it works just fine, it’s just not checked.

Type language

Types will be pulled from the following formats:

param {type} varname:

some descriptive text

rtype avarname:


returns {types}:

some descriptive text

{type} can be any valid Python type. Some examples:

  • int

  • list

  • :py:class:typist._import_hook.Finder

  • typist._import_hook.Finder

{types} can be a list of types separated by commas that includes an optional ‘or’. All the same types as above can be used in the list. Some examples:

  • list or None

  • int, float or long

  • int, float, long

  • typist._py.PY2 or typist._py.PY3

  • list or callable

callable above is a special case. While technically it’s not a type it does describe the way an object should behave. Another special cases that doesn’t work yet, but may soon is iterable.

This languasge for specifying a type will grow a bit more rich for collections. It would be really handy to allow the developer to specify parameterized types like:

  • list<int> - a list of int

  • dict<str,package.module.Class> - a dict where the keys are strings and the values are instances of package.module.Class


The idea to write to this came to me when I was working on Python 3 support for Keystone. I wanted to ensure that the code was actually getting the binary or text types that it expected. I was sick of the bullshit practice of .encode(‘utf8’).decode(‘utf8’) (maybe I got that backwards) that made the exceptions go away, but does nothing to solve the problem.

I didn’t bother looking for something that was already implemented because I wanted to learn a bit about import hooks. If you know of something better then please let me know. If this is the best thing since sliced bread I’d also like to know.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

typist-0.0.1.tar.gz (6.5 kB view hashes)

Uploaded Source

Built Distributions

typist-0.0.1-py3-none-any.whl (11.7 kB view hashes)

Uploaded Python 3

typist-0.0.1-py2-none-any.whl (11.7 kB view hashes)

Uploaded Python 2

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page