============================ Usage of the typesafety tool

.. image:: https://travis-ci.org/balabit/typesafety.svg?branch=master :target: https://travis-ci.org/balabit/typesafety

Typesafety is a tool for Python (3.2 or newer) that - using annotations - checks if the arguments for function calls are valid. For example, consider the following piece of code:

.. code-block:: python

def sign(x): if not isinstance(x, int): raise TypeError('Invalid type {!r}, expected int'.format(x))

   if x < 0:
       return -1

   if x > 0:
       return 1

   return 0

The manual type check can become cumbersome really fast, especially when there are multiple arguments, complex checks, etc. Wouldn't it be cool if for internal (i.e. not API) code the checks could be done more concisely? If you could write:

.. code-block:: python

def sign(x: int):
    # ...

Testing with typesafety

Typesafety is meant to be used during testing. True, the checker can be turned on in production code but the performance slowdown can make this undesirable.

Typesafety comes with builtin plugins for two popular testing frameworks, nosetests <https://nose.readthedocs.org> and pytest <http://pytest.org/> (our preferred tool at Balabit is nosetests), and using it is very simple.

For nose:

::

$ nosetests --enable-typesafety mymodule

And similarly for pytest:

::

$ py.test --enable-typesafety mymodule

And voila! Type checking is enabled for the module mymodule during tests.

Enabling typesafety manually

The typesafety tool can also be enabled "manually," using the typesafety.activate function. Consider the module testmod:

.. code-block:: python

def my_function(x: int) -> int:
    return x + 1

Before importing testmod, we need to enable typesafety:

.. code-block:: python

import typesafety
import imp
import testmod

testmod.my_function(1.0)      # No error, since typesafety is not enabled

# Note that the filter_func optional argument can be used to filter
# which modules will be type checked.
typesafety.activate(filter_func=lambda name: name.startswith('testmod.'))
testmod = imp.reload(testmod)
testmod.my_function(1.0)      # Will throw a TypesafetyError

NOTE: We use the exception TypesafetyError instead of the more appropriate, built-in TypeError since raising a TypeError would cause tests asserting for TypeError to pass if the arguments are wrong.

Disabling typesafety checks for certain functions .................................................

If you are using typesafety with another lib that uses annotations, it might cause some interference. In this case, you should be able to disable typesafety checking for certain functions. But how to do this?

The preferred way is simply to mark the function for skipping:

.. code-block:: python

def dont_check(x: (int, 'This annotation has another meaning')) -> (float, 'As does this'):
    return 'Definitely not a float'

dont_check.typesafety_skip = True

When the typesafety_skip attribute is set for a function, it will not check the calls to that function.

Specifying typesafety checks

A function with argument or return value annotations will be used to implement the type safety check mechanism. For further information on how annotations work, see the Python documentation.

Type annotations ................

The simplest type safety check is when a singular type is specified for an argument or return value:

.. code-block:: python

def my_function(x: int) -> float:
    return float(x) + 1.0

my_function(1)      # Will return 2.0
my_function(1.0)    # Will throw a TypesafetyError

In this case on each call the type safety checker will validate that the argument is an int and the return value is a float.

Callable annotations ....................

Some conditions cannot be checked by isinstance. If the parameter needs to be a callable object (i.e. function, object with __call__ implemented, etc.) we can annotate the argument or return value with a callable:

.. code-block:: python

def decorator(func: callable) -> callable:
    # ...
    return res

@decorator
def my_function(x):
    pass

decorator(1)    # Will throw a TypesafetyError

Multiple annotations ....................

If a tuple is specified in the annotation, then at least one of the specified conditions must apply to the argument.

.. code-block:: python

def multiple_argument_types(number: (int, float)) -> (int, float):
    return number + 1

multiple_argument_types(1)          # Will return 2
multiple_argument_types(1.0)        # Will return 2.0
multiple_argument_types('string')   # Will throw a TypesafetyError

Generating documentation using annotations with Sphinx autodoc

To avoid having to write parameter documentation manually, the typesafety.sphinxautodoc Sphinx extension is provided. It will automatically add the typesafety annotations to the signatures that Sphinx autodoc puts into the documentation.

Usage

In your Sphinx config file, simply add typesafety.sphinxautodoc to the extension list:

.. code-block:: python

extensions.append('typesafety.sphinxautodoc')

Decorator functions

Custom decorator functions often work like the following:

.. code-block:: python

from functools import wraps

def some_decorator(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        # Do some additional stuff, and then...
        return func(*args, **kwargs)

    return wrapper

@some_decorator
def my_annotated_function(x: int):
    pass

This way the documentation for my_annotated_function will use the signature of the decorated function, ie. it will be just *args, **kwargs which is not very helpful. Sadly, there is no out-of-the-box solution for this problem, however, if the decorator is extended with setting the decorated_function attribute of the wrapper function it returns, then typesafety.sphinxautodoc will use that attribute to read the signature from:

.. code-block:: python

def some_decorator(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        # Do some additional stuff, and then...
        return func(*args, **kwargs)

    wrapper.decorated_function = func

    return wrapper

Using the above version of @some_decorator will enable typesafety.sphinxautodoc to generate the proper signature documentation for my_annotated_function(), ie. (x: int).