kprzybyla/prototypes

Prototypes

Summary

Prototypes allow you to define signatures for your functions and verify those signatures during both static type checking and runtime.

Installation

$ pip install prototypes

Requirements

typing-extensions >= 3.10 when using Python < 3.10

Basic usage

To validate your function against prototype, decorate your function with the prototype decorator and pass the prototype function as a parameter.

from prototypes import prototype

def add(x: int, y: int) -> int:
    ...

@prototype(add)
def custom_add(x: int, y: int) -> int:
    return x + y

Static type checking is fully supported thanks to usage of both typing.TypeVar (PEP 484) and typing.ParamSpec (PEP 612) under the hood.

from prototypes import prototype

def add(x: int, y: int) -> int:
    ...

# This will report type error by static type checkers like `mypy` in the future
@prototype(add)
def compute() -> None:
    pass

Advanced usage

Prototype functions does not have to be empty. They can be regular functions that already contain specific implementation. The prototype function act more like a signature template for the function, rather than an empty shell to be filled with the implementation.

from prototypes import prototype

def add(x: int, y: int) -> int:
    return x + y

@prototype(add)
def custom_add(x: int, y: int) -> int:
    ...
    return add(x, y)

By default, the prototype decorator verifies the signatures during runtime. Since decorators are executed during the function definition, this validation is performed right away, even if function is never called.

>>> from prototypes import prototype
>>>
>>> def add(x: int, y: int) -> int: ...
...
>>> @prototype(add)
... def compute() -> None:
...     pass
...
Traceback (most recent call last):
    ...
prototypes.PrototypeError: Incompatible function implementation for given prototype

Function:
def compute() -> None @ compute

Prototype:
def add(x: int, y: int) -> int @ add

However, since closures (inner functions) are defined on function execution, using prototype decorator in the closure will have no effect until the outer function is called.

>>> from prototypes import prototype
>>>
>>> def add(x: int, y: int) -> int: ...
...
>>> def func() -> None:
...     @prototype(add)
...     def compute() -> None:
...         ...
...
>>> # No exception is raised at that point
>>> func()
Traceback (most recent call last):
    ...
prototypes.PrototypeError: Incompatible function implementation for given prototype

Function:
def compute() -> None @ func.<locals>.compute

Prototype:
def add(x: int, y: int) -> int @ add

The runtime validation can be turned off when static type checking is performed to increase the code performance during runtime.

>>> from prototypes import prototype
>>>
>>> def add(x: int, y: int) -> int: ...
...
>>> @prototype(add, runtime=False)
... def compute() -> None:
...     pass
...
>>> # No exception is raised during runtime

Bugs/Requests

Please use the GitHub issue tracker to submit bugs or request features.

License

Distributed under the terms of the MIT license.

kprzybyla / prototypes