Skip to main content

Type checking @typesafe employing Sphinx docstrings

Project description

sphinx_typesafe is a decorator which enables dynamic type checking on Python method and function calls. It works in conjunction with Sphinx-style docstrings, which makes it particularly convenient for keeping the code documentation up-to-date with the code actually being executed.

Features is a Nutshell

  • The decorator can be attached to any function or method.

  • Raises TypeError if types of arguments do not match the specification.

  • Raises TypeError if type of return value does not match the specification.

  • Performs dynamic type checking.


Since function annotations are not available in Python2 the way type checking for Python2 is a documentation convention for parameters based on the info field lists of sphinx. So even when you don’t use type checking you can use it to generate documentation.

Syntax for Python2 using sphinx style docstrings

This is the preferred way since you will be also documenting your code.

from sphinx_typesafe.typesafe import typesafe

def foo(param_a, param_b, param_c):
        :type param_a:  types.StringType
        :type param_b:  types.IntType
        :type param_c:  types.NotImplementedType
        :rtype:         types.BooleanType
        # Do Something
        return True

Syntax for Python2 using decorator arguments

This is an alternative approach, useful in circunstances where Sphinx-style documentation is not allowed or desired, for whatever reason.

from sphinx_typesafe.typesafe import typesafe

@typesafe( { 'param_a' : 'str',
             'param_b' : 'types.IntType',
             'param_c' : 'own_module.OwnType',
             'return'  : 'bool' } )
def foo(param_a, param_b, param_c):
        """ Some Docstring Info          """
        # Do Something
        return True

You can use any Python type

So if you have defined a Point class in module mod1 like below:

# File:

class Point(object):
    def __init__(self, x = None, y = None):
        """ Initialize the Point. Can be used to give x,y directly."""
        self.x = x
        self.y = y

then you can employ this type in your code like this:

from mod1 import Point
from sphinx_typesafe.typesafe import typesafe

def foo(afunc):
    :type afunc:     mod1.Point
    :rtype:          types.BooleanType
    return True


The base technique is the Function Annotations proposed in PEP-3107 which is documented in Python3 What’s New (see section New Syntax).

Syntax for Python3

from sphinx_typesafe.typesafe import typesafe

def foo(param_a: str, param_b: int) -> bool:
        # Do Something
        return True
  • The @typesafe decorator will then check all arguments dynamically whenever the foo is called for valid types.

  • As a quoting remark from the PEP 3107: “All annotated parameter types can be any python expression.”, but for typechecking only types make sense, though.

The idea and parts of the implementation were inspired by the book: Pro Python (Expert’s Voice in Open Source)

Building from source

Start from a clean and minimalist virtual environment, for example:

$ pip list
pip (1.4)
setuptools (2.1)
wsgiref (0.1.2)

Download sources and run test cases

$ git clone
$ cd sphinx_typesafe
$ python devtest && py.test


Why it was called IcanHasTypeCheck ?

IcanHasTypeCheck (ICHTC), refers to the famous lolcats.

Why is now called sphinx_typesafe ?

Because typesafe tells immediatelly what it is about. Unfortunately, typesafe was already taken on PyPI, so sphinx_typesafe seemed to be a good alternative name which also relates to the documentation standard adopted.


Please find links on the top of this page.



0.3 (13-feb-2014)

  • Several bugfixes and enhancements

    • better resolution of type names

    • fix support for methods

    • fix documentation

    • test suite now has 60 test cases

    • support for types.NoneType

    • more restrictive matching of documenation against parameters

    • support for ignoring type checking: types.NotImplementeType

    • exposing function get_class_type

0.2 (03-dec-2013)

  • Full code rewiew and rewrite by Richard Gomes <>

    • @typesafe is now a class

    • Code reorganization and some optimization

    • Preparing code for porting to Python3

  • New features

    • Added verification of return type of decorated functions

  • Bugfixes

    • Type resolver now finds types involving multiple nested modules

    • Type resolver assumes module ‘__builtin__’ for simple names, such as ‘bool’

  • Renamed to sphinx_typesafe

  • Documentation rewriten in reStructuredText

  • Added docs directory required by

  • First version deployed onto PyPI


Original version of IcanHasTypeCheck (ICHTC) by Klaas <>

Project details

Download files

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

Source Distributions (30.0 kB view hashes)

Uploaded source

sphinx_typesafe-0.3.tar.gz (17.6 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page