type_enforced

Type Enforced

A pure python (no special compiler required) type enforcer for type annotations. Enforce types in python functions and methods.

Setup

Make sure you have Python 3.10.x (or higher) installed on your system. You can download it here.

Unsupported python versions can be used, however newer features will not be available.
- For 3.7: use type_enforced==0.0.16 (only very basic type checking is supported)
- For 3.8: use type_enforced==0.0.16 (only very basic type checking is supported)
- For 3.9: use type_enforced<=1.9.0 (staticmethod, union with | and from __future__ import annotations typechecking are not supported)
Other notes:
- For python 3.10: from __future__ import annotations may cause errors (EG: when using staticmethods and classmethods)

Installation

pip install type_enforced

Basic Usage

import type_enforced

@type_enforced.Enforcer(enabled=True)
def my_fn(a: int , b: [int, str] =2, c: int =3) -> None:
    pass

Note: enabled=True by default if not specified. You can set enabled=False to disable type checking for a specific function, method, or class. This is useful for a production vs debugging environment or for undecorating a single method in a larger wrapped class.

Getting Started

type_enforcer contains a basic Enforcer wrapper that can be used to enforce many basic python typing hints. Technical Docs Here.

type_enforcer currently supports many single and multi level python types. This includes class instances and classes themselves. For example, you can force an input to be an int, a number [int, float], an instance of the self defined MyClass, or a even a vector with list[int]. Items like typing.List, typing.Dict, typing.Union and typing.Optional are supported.

You can pass union types to validate one of multiple types. For example, you could validate an input was an int or a float with [int, float], [int | float] or even typing.Union[int, float].

Nesting is allowed as long as the nested items are iterables (e.g. typing.List, dict, ...). For example, you could validate that a list is a vector with list[int] or possibly typing.List[int].

Variables without an annotation for type are not enforced.

Supported Type Checking Features:

Function/Method Input Typing
Function/Method Return Typing
Dataclass Typing
All standard python types (str, list, int, dict, ...)
Union types
- typing.Union
- , separated list (e.g. [int, float])
- | separated list (e.g. [int | float])
- | separated items (e.g. int | float)
Nested types (e.g. dict[str] or list[int, float])
- Note: Each parent level must be an iterable
  - Specifically a variant of list, set, tuple or dict
- Note: dict keys are not validated, only values
- Deeply nested types are supported too:
  - dict[dict[int]]
  - list[set[str]]
Many of the typing (package) functions and methods including:
- Standard typing functions:
  - List, Set, Dict, Tuple
- Union
- Optional
- Sized
  - Essentially creates a union of:
    - list, tuple, dict, set, str, bytes, bytearray, memoryview, range
  - Note: Can not have a nested type
    - Because this does not always meet the criteria for Nested types above
- Literal
  - Only allow certain values to be passed. Operates slightly differently than other checks.
  - e.g. Literal['a', 'b'] will require any passed values that are equal (==) to 'a' or 'b'.
    - This compares the value of the passed input and not the type of the passed input.
  - Note: Multiple types can be passed in the same Literal.
  - Note: Literals are evaluated after type checking occurs.
- Callable
  - Essentially creates a union of:
    - staticmethod, classmethod, types.FunctionType, types.BuiltinFunctionType, types.MethodType, types.BuiltinMethodType, types.GeneratorType
- Note: Other functions might have support, but there are not currently tests to validate them
  - Feel free to create an issue (or better yet a PR) if you want to add tests/support
Constraint validation.
- This is a special type of validation that allows passed input to be validated.
  - Standard and custom constraints are supported.
- This is useful for validating that a passed input is within a certain range or meets a certain criteria.
- Note: The constraint is checked after type checking occurs.
- Note: See the example below or technical constraint and generic constraint docs for more information. ```

Interactive Example

>>> import type_enforced
>>> @type_enforced.Enforcer
... def my_fn(a: int , b: [int, str] =2, c: int =3) -> None:
...     pass
...
>>> my_fn(a=1, b=2, c=3)
>>> my_fn(a=1, b='2', c=3)
>>> my_fn(a='a', b=2, c=3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/conmak/development/personal/type_enforced/type_enforced/enforcer.py", line 85, in __call__
    self.__check_type__(assigned_vars.get(key), value, key)
  File "/home/conmak/development/personal/type_enforced/type_enforced/enforcer.py", line 107, in __check_type__
    self.__exception__(
  File "/home/conmak/development/personal/type_enforced/type_enforced/enforcer.py", line 34, in __exception__
    raise TypeError(f"({self.__fn__.__qualname__}): {message}")
TypeError: (my_fn): Type mismatch for typed variable `a`. Expected one of the following `[<class 'int'>]` but got `<class 'str'>` instead.

Nested Examples

import type_enforced
import typing

@type_enforced.Enforcer
def my_fn(
    a: dict[dict[int, float]], # Note: dict keys are not validated, only values
    b: list[typing.Set[str]] # Could also just use set
) -> None:
    return None

my_fn(a={'i':{'j':1}}, b=[{'x'}]) # Success

my_fn(a={'i':{'j':'k'}}, b=[{'x'}]) # Error:
# TypeError: (my_fn): Type mismatch for typed variable `a[i][j]`. Expected one of the following `[<class 'int'>]` but got `<class 'str'>` instead.

Class and Method Use

Type enforcer can be applied to methods individually:

import type_enforced

class my_class:
    @type_enforced.Enforcer
    def my_fn(self, b:int):
        pass

You can also enforce all typing for all methods in a class by decorating the class itself.

import type_enforced

@type_enforced.Enforcer
class my_class:
    def my_fn(self, b:int):
        pass

    def my_other_fn(self, a: int, b: int | str):
      pass

You can also enforce types on staticmethods and classmethods if you are using python >= 3.10. If you are using a python version less than this, classmethods and staticmethods methods will not have their types enforced.

import type_enforced

@type_enforced.Enforcer
class my_class:
    @classmethod
    def my_fn(self, b:int):
        pass

    @staticmethod
    def my_other_fn(a: int, b: int | str):
      pass

Dataclasses are suported too.

import type_enforced
from dataclasses import dataclass

@type_enforced.Enforcer
@dataclass
class my_class:
    foo: int
    bar: str

You can skip enforcement if you add the argument enabled=False in the Enforcer call.

This is useful for a production vs debugging environment.
This is also useful for undecorating a single method in a larger wrapped class.
Note: You can set enabled=False for an entire class or simply disable a specific method in a larger wrapped class.
Note: Method level wrapper enabled values take precedence over class level wrappers.

import type_enforced
@type_enforced.Enforcer
class my_class:
    def my_fn(self, a: int) -> None:
        pass

    @type_enforced.Enforcer(enabled=False)
    def my_other_fn(self, a: int) -> None:
        pass

Validate with Constraints

Type enforcer can enforce constraints for passed variables. These constraints are validated after any type checks are made.

To enforce basic input values are integers greater than or equal to zero, you can use the Constraint class like so:

import type_enforced
from type_enforced.utils import Constraint

@type_enforced.Enforcer()
def positive_int_test(value: [int, Constraint(ge=0)]) -> bool:
    return True

positive_int_test(1) # Passes
positive_int_test(-1) # Fails
positive_int_test(1.0) # Fails

To enforce a GenericConstraint:

import type_enforced
from type_enforced.utils import GenericConstraint

CustomConstraint = GenericConstraint(
    {
        'in_rgb': lambda x: x in ['red', 'green', 'blue'],
    }
)

@type_enforced.Enforcer()
def rgb_test(value: [str, CustomConstraint]) -> bool:
    return True

rgb_test('red') # Passes
rgb_test('yellow') # Fails

Validate class instances and classes

Type enforcer can enforce class instances and classes. There are a few caveats between the two.

To enforce a class instance, simply pass the class itself as a type hint:

import type_enforced

class Foo():
    def __init__(self) -> None:
        pass

@type_enforced.Enforcer
class my_class():
    def __init__(self, object: Foo) -> None:
        self.object = object

x=my_class(Foo()) # Works great!
y=my_class(Foo) # Fails!

Notice how an initialized class instance Foo() must be passed for the enforcer to not raise an exception.

To enforce an uninitialized class object use typing.Type[classHere] on the class to enforce inputs to be an uninitialized class:

import type_enforced
import typing

class Foo():
    def __init__(self) -> None:
        pass

@type_enforced.Enforcer
class my_class():
    def __init__(self, object_class: typing.Type[Foo]) -> None:
        self.object = object_class()

y=my_class(Foo) # Works great!
x=my_class(Foo()) # Fails

Validate classes with inheritance

import type_enforced
from type_enforced.utils import WithSubclasses

class Foo:
    pass

class Bar(Foo):
    pass

class Baz:
    pass

@type_enforced.Enforcer
def my_fn(custom_class: WithSubclasses(Foo)):
    pass

print(WithSubclasses.get_subclasses(Foo)) # Prints: [<class '__main__.Foo'>, <class '__main__.Bar'>]
my_fn(Foo()) # Passes as expected
my_fn(Bar()) # Passes as expected
my_fn(Baz()) # Raises TypeError as expected

Development

Running Tests, Prettifying Code, and Updating Docs

Make sure Docker is installed and running.

Create a docker container and drop into a shell
- ./run.sh
Run all tests (see ./utils/test.sh)
- ./run.sh test
Prettify the code (see ./utils/prettify.sh)
- ./run.sh prettify
Update the docs (see ./utils/docs.sh)
- ./run.sh docs
Note: You can and should modify the Dockerfile to test different python versions.

View Source

  1"""
  2# Type Enforced
  3[![PyPI version](https://badge.fury.io/py/type_enforced.svg)](https://badge.fury.io/py/type_enforced)
  4[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  5[![PyPI Downloads](https://img.shields.io/pypi/dm/type_enforced.svg?label=PyPI%20downloads)](https://pypi.org/project/type_enforced/)
  6
  7A pure python (no special compiler required) type enforcer for type annotations. Enforce types in python functions and methods.
  8
  9# Setup
 10
 11Make sure you have Python 3.10.x (or higher) installed on your system. You can download it [here](https://www.python.org/downloads/).
 12
 13- Unsupported python versions can be used, however newer features will not be available.
 14    - For 3.7: use type_enforced==0.0.16 (only very basic type checking is supported)
 15    - For 3.8: use type_enforced==0.0.16 (only very basic type checking is supported)
 16    - For 3.9: use type_enforced<=1.9.0 (`staticmethod`, union with `|` and `from __future__ import annotations` typechecking are not supported)
 17- Other notes:
 18    - For python 3.10: `from __future__ import annotations` may cause errors (EG: when using staticmethods and classmethods)
 19
 20### Installation
 21
 22```
 23pip install type_enforced
 24```
 25
 26## Basic Usage
 27```py
 28import type_enforced
 29
 30@type_enforced.Enforcer(enabled=True)
 31def my_fn(a: int , b: [int, str] =2, c: int =3) -> None:
 32    pass
 33```
 34- Note: `enabled=True` by default if not specified. You can set `enabled=False` to disable type checking for a specific function, method, or class. This is useful for a production vs debugging environment or for undecorating a single method in a larger wrapped class.
 35
 36# Getting Started
 37
 38`type_enforcer` contains a basic `Enforcer` wrapper that can be used to enforce many basic python typing hints. [Technical Docs Here](https://connor-makowski.github.io/type_enforced/type_enforced/enforcer.html).
 39
 40`type_enforcer` currently supports many single and multi level python types. This includes class instances and classes themselves. For example, you can force an input to be an `int`, a number `[int, float]`, an instance of the self defined `MyClass`, or a even a vector with `list[int]`. Items like `typing.List`, `typing.Dict`, `typing.Union` and `typing.Optional` are supported.
 41
 42You can pass union types to validate one of multiple types. For example, you could validate an input was an int or a float with `[int, float]`, `[int | float]` or even `typing.Union[int, float]`.
 43
 44Nesting is allowed as long as the nested items are iterables (e.g. `typing.List`, `dict`, ...). For example, you could validate that a list is a vector with `list[int]` or possibly `typing.List[int]`.
 45
 46Variables without an annotation for type are not enforced.
 47
 48## Supported Type Checking Features:
 49
 50- Function/Method Input Typing
 51- Function/Method Return Typing
 52- Dataclass Typing
 53- All standard python types (`str`, `list`, `int`, `dict`, ...)
 54- Union types
 55    - typing.Union
 56    - `,` separated list (e.g. `[int, float]`)
 57    - `|` separated list (e.g. `[int | float]`)
 58    - `|` separated items (e.g. `int | float`)
 59- Nested types (e.g. `dict[str]` or `list[int, float]`)
 60    - Note: Each parent level must be an iterable
 61        - Specifically a variant of `list`, `set`, `tuple` or `dict`
 62    - Note: `dict` keys are not validated, only values
 63    - Deeply nested types are supported too:
 64        - `dict[dict[int]]`
 65        - `list[set[str]]`
 66- Many of the `typing` (package) functions and methods including:
 67    - Standard typing functions:
 68        - `List`, `Set`, `Dict`, `Tuple`
 69    - `Union`
 70    - `Optional`
 71    - `Sized`
 72        - Essentially creates a union of:
 73            - `list`, `tuple`, `dict`, `set`, `str`, `bytes`, `bytearray`, `memoryview`, `range`
 74        - Note: Can not have a nested type
 75            - Because this does not always meet the criteria for `Nested types` above
 76    - `Literal`
 77        - Only allow certain values to be passed. Operates slightly differently than other checks.
 78        - e.g. `Literal['a', 'b']` will require any passed values that are equal (`==`) to `'a'` or `'b'`.
 79            - This compares the value of the passed input and not the type of the passed input.
 80        - Note: Multiple types can be passed in the same `Literal`.
 81        - Note: Literals are evaluated after type checking occurs.
 82    - `Callable`
 83        - Essentially creates a union of:
 84            - `staticmethod`, `classmethod`, `types.FunctionType`, `types.BuiltinFunctionType`, `types.MethodType`, `types.BuiltinMethodType`, `types.GeneratorType`
 85    - Note: Other functions might have support, but there are not currently tests to validate them
 86        - Feel free to create an issue (or better yet a PR) if you want to add tests/support
 87- `Constraint` validation.
 88    - This is a special type of validation that allows passed input to be validated.
 89        - Standard and custom constraints are supported.
 90    - This is useful for validating that a passed input is within a certain range or meets a certain criteria.
 91    - Note: The constraint is checked after type checking occurs.
 92    - Note: See the example below or technical [constraint](https://connor-makowski.github.io/type_enforced/type_enforced/utils.html#Constraint) and [generic constraint](https://connor-makowski.github.io/type_enforced/type_enforced/utils.html#GenericConstraint) docs for more information.
 93    ```
 94
 95## Interactive Example
 96
 97```py
 98>>> import type_enforced
 99>>> @type_enforced.Enforcer
100... def my_fn(a: int , b: [int, str] =2, c: int =3) -> None:
101...     pass
102...
103>>> my_fn(a=1, b=2, c=3)
104>>> my_fn(a=1, b='2', c=3)
105>>> my_fn(a='a', b=2, c=3)
106Traceback (most recent call last):
107  File "<stdin>", line 1, in <module>
108  File "/home/conmak/development/personal/type_enforced/type_enforced/enforcer.py", line 85, in __call__
109    self.__check_type__(assigned_vars.get(key), value, key)
110  File "/home/conmak/development/personal/type_enforced/type_enforced/enforcer.py", line 107, in __check_type__
111    self.__exception__(
112  File "/home/conmak/development/personal/type_enforced/type_enforced/enforcer.py", line 34, in __exception__
113    raise TypeError(f"({self.__fn__.__qualname__}): {message}")
114TypeError: (my_fn): Type mismatch for typed variable `a`. Expected one of the following `[<class 'int'>]` but got `<class 'str'>` instead.
115```
116
117## Nested Examples
118```py
119import type_enforced
120import typing
121
122@type_enforced.Enforcer
123def my_fn(
124    a: dict[dict[int, float]], # Note: dict keys are not validated, only values
125    b: list[typing.Set[str]] # Could also just use set
126) -> None:
127    return None
128
129my_fn(a={'i':{'j':1}}, b=[{'x'}]) # Success
130
131my_fn(a={'i':{'j':'k'}}, b=[{'x'}]) # Error:
132# TypeError: (my_fn): Type mismatch for typed variable `a[i][j]`. Expected one of the following `[<class 'int'>]` but got `<class 'str'>` instead. 
133```
134
135## Class and Method Use
136
137Type enforcer can be applied to methods individually:
138
139```py
140import type_enforced
141
142class my_class:
143    @type_enforced.Enforcer
144    def my_fn(self, b:int):
145        pass
146```
147
148You can also enforce all typing for all methods in a class by decorating the class itself.
149
150```py
151import type_enforced
152
153@type_enforced.Enforcer
154class my_class:
155    def my_fn(self, b:int):
156        pass
157
158    def my_other_fn(self, a: int, b: int | str):
159      pass
160```
161
162You can also enforce types on `staticmethod`s and `classmethod`s if you are using `python >= 3.10`. If you are using a python version less than this, `classmethod`s and `staticmethod`s methods will not have their types enforced.
163
164```py
165import type_enforced
166
167@type_enforced.Enforcer
168class my_class:
169    @classmethod
170    def my_fn(self, b:int):
171        pass
172
173    @staticmethod
174    def my_other_fn(a: int, b: int | str):
175      pass
176```
177
178Dataclasses are suported too.
179
180```py
181import type_enforced
182from dataclasses import dataclass
183
184@type_enforced.Enforcer
185@dataclass
186class my_class:
187    foo: int
188    bar: str
189```
190
191You can skip enforcement if you add the argument `enabled=False` in the `Enforcer` call.
192- This is useful for a production vs debugging environment.
193- This is also useful for undecorating a single method in a larger wrapped class.
194- Note: You can set `enabled=False` for an entire class or simply disable a specific method in a larger wrapped class.
195- Note: Method level wrapper `enabled` values take precedence over class level wrappers.
196```py
197import type_enforced
198@type_enforced.Enforcer
199class my_class:
200    def my_fn(self, a: int) -> None:
201        pass
202
203    @type_enforced.Enforcer(enabled=False)
204    def my_other_fn(self, a: int) -> None:
205        pass
206```
207
208## Validate with Constraints
209Type enforcer can enforce constraints for passed variables. These constraints are validated after any type checks are made.
210
211To enforce basic input values are integers greater than or equal to zero, you can use the [Constraint](https://connor-makowski.github.io/type_enforced/type_enforced/utils.html#Constraint) class like so:
212```py
213import type_enforced
214from type_enforced.utils import Constraint
215
216@type_enforced.Enforcer()
217def positive_int_test(value: [int, Constraint(ge=0)]) -> bool:
218    return True
219
220positive_int_test(1) # Passes
221positive_int_test(-1) # Fails
222positive_int_test(1.0) # Fails
223```
224
225To enforce a [GenericConstraint](https://connor-makowski.github.io/type_enforced/type_enforced/utils.html#GenericConstraint):
226```py
227import type_enforced
228from type_enforced.utils import GenericConstraint
229
230CustomConstraint = GenericConstraint(
231    {
232        'in_rgb': lambda x: x in ['red', 'green', 'blue'],
233    }
234)
235
236@type_enforced.Enforcer()
237def rgb_test(value: [str, CustomConstraint]) -> bool:
238    return True
239
240rgb_test('red') # Passes
241rgb_test('yellow') # Fails
242```
243
244
245
246## Validate class instances and classes
247
248Type enforcer can enforce class instances and classes. There are a few caveats between the two.
249
250To enforce a class instance, simply pass the class itself as a type hint:
251```py
252import type_enforced
253
254class Foo():
255    def __init__(self) -> None:
256        pass
257
258@type_enforced.Enforcer
259class my_class():
260    def __init__(self, object: Foo) -> None:
261        self.object = object
262
263x=my_class(Foo()) # Works great!
264y=my_class(Foo) # Fails!
265```
266
267Notice how an initialized class instance `Foo()` must be passed for the enforcer to not raise an exception.
268
269To enforce an uninitialized class object use `typing.Type[classHere]` on the class to enforce inputs to be an uninitialized class:
270```py
271import type_enforced
272import typing
273
274class Foo():
275    def __init__(self) -> None:
276        pass
277
278@type_enforced.Enforcer
279class my_class():
280    def __init__(self, object_class: typing.Type[Foo]) -> None:
281        self.object = object_class()
282
283y=my_class(Foo) # Works great!
284x=my_class(Foo()) # Fails
285```
286
287## Validate classes with inheritance
288
289```py
290import type_enforced
291from type_enforced.utils import WithSubclasses
292
293class Foo:
294    pass
295
296class Bar(Foo):
297    pass
298
299class Baz:
300    pass
301
302@type_enforced.Enforcer
303def my_fn(custom_class: WithSubclasses(Foo)):
304    pass
305
306print(WithSubclasses.get_subclasses(Foo)) # Prints: [<class '__main__.Foo'>, <class '__main__.Bar'>]
307my_fn(Foo()) # Passes as expected
308my_fn(Bar()) # Passes as expected
309my_fn(Baz()) # Raises TypeError as expected
310```
311
312# Development
313## Running Tests, Prettifying Code, and Updating Docs
314
315Make sure Docker is installed and running.
316
317- Create a docker container and drop into a shell
318    - `./run.sh`
319- Run all tests (see ./utils/test.sh)
320    - `./run.sh test`
321- Prettify the code (see ./utils/prettify.sh)
322    - `./run.sh prettify`
323- Update the docs (see ./utils/docs.sh)
324    - `./run.sh docs`
325
326- Note: You can and should modify the `Dockerfile` to test different python versions.
327"""
328from .enforcer import Enforcer, FunctionMethodEnforcer