typing-validation

typing-validation: Validation using Type Hints

.. image:: https://img.shields.io/badge/python-3.7+-green.svg :target: https://docs.python.org/3.7/ :alt: Python versions

.. image:: https://img.shields.io/pypi/v/typing-validation.svg :target: https://pypi.python.org/pypi/typing-validation/ :alt: PyPI version

.. image:: https://img.shields.io/pypi/status/typing-validation.svg :target: https://pypi.python.org/pypi/typing-validation/ :alt: PyPI status

.. image:: http://www.mypy-lang.org/static/mypy_badge.svg :target: https://github.com/python/mypy :alt: Checked with Mypy

.. image:: https://readthedocs.org/projects/typing-validation/badge/?version=latest :target: https://typing-validation.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status

.. image:: https://github.com/hashberg-io/typing-validation/actions/workflows/python-pytest.yml/badge.svg :target: https://github.com/hashberg-io/typing-validation/actions/workflows/python-pytest.yml :alt: Python package status

.. image:: https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square :target: https://github.com/RichardLitt/standard-readme :alt: standard-readme compliant

Typing-validation is a small library to perform runtime validation of Python objects using PEP 484 type hints <https://www.python.org/dev/peps/pep-0484/>_.

.. contents::

Install

You can install the latest release from PyPI <https://pypi.org/project/typing-validation/>_ as follows:

.. code-block::

pip install --upgrade typing-validation

Usage

The core functionality of this library is provided by the validate <https://typing-validation.readthedocs.io/en/latest/api/typing_validation.validation.html#typing_validation.validation.validate>_ function:

from typing_validation import validate

The validate <https://typing-validation.readthedocs.io/en/latest/api/typing_validation.validation.html#typing_validation.validation.validate>_ function is invoked with a value and a type as its arguments and it returns nothing when the given value is valid for the given type:

validate(12, int) True # no error raised => 12 is a valid int

If the value is invalid for the given type, the validate <https://typing-validation.readthedocs.io/en/latest/api/typing_validation.validation.html#typing_validation.validation.validate>_ function raises a TypeError <https://docs.python.org/3/library/exceptions.html#TypeError>_:

validate(12, str) TypeError: Runtime validation error raised by validate(val, t), details below. For type <class 'str'>, invalid value: 12

For nested types (e.g. parametric collection/mapping types), the full chain of validation failures is shown by the type error:

validate([0, 1, "hi"], list[int]) TypeError: Runtime validation error raised by validate(val, t), details below. For type list[int], invalid value at idx: 2 For type <class 'int'>, invalid value: 'hi'

The function is_valid is a variant of the validate <https://typing-validation.readthedocs.io/en/latest/api/typing_validation.validation.html#typing_validation.validation.validate>_ function which returns False in case of validation failure, instead of raising TypeError <https://docs.python.org/3/library/exceptions.html#TypeError>_:

from typing_validation import is_valid is_valid([0, 1, "hi"], list[int]) False

The function latest_validation_failure <https://typing-validation.readthedocs.io/en/latest/api/typing_validation.validation.html#typing_validation.validation_failure.latest_validation_failure>_ can be used to access detailed information immediately after a failure:

from typing_validation import latest_validation_failure is_valid([0, 1, "hi"], list[int]) False failure = latest_validation_failure() print(failure) Runtime validation error raised by validate(val, t), details below. For type list[int], invalid value at idx: 2 For type <class 'int'>, invalid value: 'hi'

Please note that latest_validation_failure <https://typing-validation.readthedocs.io/en/latest/api/typing_validation.validation.html#typing_validation.validation_failure.latest_validation_failure>_ clears the internal failure logs after returning the latest failure, so the latter must be manually stored if it needs to be accessed multiple times.

API

For the full API documentation, see https://typing-validation.readthedocs.io/

Contributing

Please see <CONTRIBUTING.md>_.

License

MIT © Hashberg Ltd. <LICENSE>_