# typesafety **Repository Path**: mirrors_balabit/typesafety ## Basic Information - **Project Name**: typesafety - **Description**: Type safety checker for Python3 - **Primary Language**: Unknown - **License**: LGPL-2.1 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2020-09-24 - **Last Updated**: 2026-04-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README ============================ 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 `_ and `pytest `_ (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)``.