.. Copyright 2017, 2018, 2021 Stefan Richthofer

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

.. image:: https://travis-ci.org/Stewori/pytypes.svg?branch=master :target: https://travis-ci.org/Stewori/pytypes :alt: Build Status

.. image:: https://raw.githubusercontent.com/Stewori/pytypes/master/pytypes_logo_text.png :scale: 70% :align: left :alt: pytypes

Welcome to the pytypes project

pytypes is a typing toolbox w.r.t. PEP 484 <https://www.python.org/dev/peps/pep-0484/>__ (PEP 526 <https://www.python.org/dev/peps/pep-0526/>__ on the road map, later also 544 <https://www.python.org/dev/peps/pep-0544/>__ if it gets accepted).

Its main features are currently

• @typechecked decorator for runtime typechecking with support for stubfiles <https://www.python.org/dev/peps/pep-0484/#stub-files>__ and type comments <https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code>__
• @override decorator that asserts existence of a type-compatible parent method
• @annotations decorator to turn type info from stubfiles or from type comments into __annotations__
• @typelogged decorator observes function and method calls at runtime and generates stubfiles from acquired type info
• service functions to apply these decorators module wide or even globally, i.e. runtime wide
• typechecking can alternatively be done in decorator-free manner (friendlier for debuggers)
• all the above decorators work smoothly with OOP, i.e. with methods, static methods, class methods and properties, even if classes are nested
• converter for stubfiles to Python 2.7 compliant form
• lots of utility functions regarding types, e.g. a Python 2.7 compliant and actually functional implementation of get_type_hints
• full Python 2.7 support for all these features

An additional future goal will be integration with the Java typing system when running on Jython. Along with this, some generator utilities to produce type-safe Java bindings for Python frameworks are planned.

In wider sense, PEP 484-style type annotations can be used to build type safe interfaces to allow also other programming languages to call into Python code (kind of reverse FFI). In this sense the project name refers to 'ctypes', which provides Python-bindings of C.

Python 2.7, 3.5-3.8

All described features of pytypes were carefully implemented such that they are equally workable on CPython 3.5, 3.6, 2.7 and on Jython 2.7.1 (other interpreters might work as well, but were not yet tested). For Python 2.7, pytypes fully supports type-annotations via type comments <https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code>__. It also supports Python 2.7-style type annotations in Python 3.5-code to allow easier 2.7/3.5 multi-version development. Python 3.7 and 3.8 are mostly supported, but some bugs still need to be fixed.

Why write another runtime typecheck decorator?

There have been earlier approaches for runtime-typechecking. However, most of them predate PEP 484 or lack some crucial features like support of Python 2.7 or support of stubfiles. Also, none of them features a typechecking override decorator. There were separate approaches for override decorators, but these usually don't consider PEP 484 at all. So we decided that it's time for a new runtime typechecking framework, designed to support PEP 484 from the roots, including its extensive features like (Python 2.7-style-)type comments and stub files.

Quick manual

Typechecking

pytypes provides a rich set of utilities for runtime typechecking.

@typechecked decorator

Decorator applicable to functions, methods, properties and classes.
Asserts compatibility of runtime argument and return values of all targeted functions and methods w.r.t. `PEP 484 <https://www.python.org/dev/peps/pep-0484/>`__-style type annotations of these functions and methods.
This supports `stubfiles <https://www.python.org/dev/peps/pep-0484/#stub-files>`__ and `type comments <https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code>`__ and is thus workable on Python 2.7.


Disabling typechecking

Running Python with the '-O' flag, which also disables assert statements, turns off typechecking completely. Alternatively, one can modify the flag pytypes.checking_enabled.

Note that this must be done right after import of pytypes, because it affects the way how @typechecked decorator works. For modules that were imported with this flag disabled, typechecking cannot be turned on later on within the same runtime.

Usage Python 2

.. code:: python

    from pytypes import typechecked

    @typechecked
    def some_function(a, b, c):
        # type: (int, str, List[Union[str, float]]) -> int
        return a+len(b)+len(c)


Usage Python 3

.. code:: python

from pytypes import typechecked

@typechecked
def some_function(a: int, b: str, c: List[Union[str, float]]) -> int:
    return a+len(b)+len(c)

Overriding methods in type-safe manner

The decorators in this section allow type-safe method overriding.

@override decorator

Decorator applicable to methods only.
For a version applicable also to classes or modules use ``auto_override``.
Asserts that for the decorated method a parent method exists in its mro.
If both the decorated method and its parent method are type annotated, the decorator additionally asserts compatibility of the annotated types.
Note that the return type is checked in contravariant manner. A successful check guarantees that the child method can always be used in places that support the parent method's signature.
Use ``pytypes.check_override_at_runtime`` and ``pytypes.check_override_at_class_definition_time`` to control whether checks happen at class definition time or at "actual runtime".

The following rules apply for override checking:

- a parent method must exist
- the parent method must have call-compatible signature (e.g. same number of args)
- arg types of parent method must be more or equal specific than arg types of child
- return type behaves contravariant - parent method must have less or equal specific return type than child


Usage Example
~~~~~~~~~~~~~

.. code:: python

    from pytypes import override

    class some_baseclass():
        def some_method1(self, a: int) -> None: ...
        def some_method2(self, a: int) -> None: ...
        def some_method3(self, a: int) -> None: ...
        def some_method4(self) -> int: ...

    class some_subclass(some_baseclass):
        @override
        def some_method1(self, a: float) -> None: ...

        @override
        def some_method2(self, a: str) -> None: ...

        @override
        def some_metd3(self, a: int) -> None: ...

        @override
        def some_method4(self) -> float: ...

- ``some_method1``: override check passes
- ``some_method2``: override check fails because type is not compatible
- ``some_method3``: override check fails because of typo in method name
- ``some_method4``: override check fails because return type must be more or equal specific than parent


@auto_override decorator

Decorator applicable to methods and classes. Works like override decorator on type annotated methods that actually have a type annotated parent method. Has no effect on methods that do not override anything. In contrast to plain override decorator, auto_override can be applied easily on every method in a class or module. In contrast to explicit override decorator, auto_override is not suitable to detect typos in spelling of a child method's name. It is only useful to assert compatibility of type information (note that return type is contravariant). Use pytypes.check_override_at_runtime and pytypes.check_override_at_class_definition_time to control whether checks happen at class definition time or at "actual runtime".

The following rules apply, if a parent method exists:

• the parent method must have call-compatible signature (e.g. same number of args)
• arg types of parent method must be more or equal specific than arg types of child
• return type behaves contravariant - parent method must have less or equal specific return type than child

Compared to ordinary override decorator, the rule “a parent method must exist” is not applied here. If no parent method exists, auto_override silently passes.

Provide info from type comments and stubfiles as __annotations__ for other tools

@annotations decorator

Decorator applicable to functions, methods, properties and classes.
Methods with type comment will have type hints parsed from that string and get them attached as ``__annotations__`` attribute. Methods with either a type comment or ordinary type annotations in a stubfile will get that information attached as ``__annotations__`` attribute (also a relevant use case in Python 3).
Behavior in case of collision with previously (manually) attached ``__annotations__`` can be controlled using the flags ``pytypes.annotations_override_typestring`` and ``pytypes.annotations_from_t