typing-validation 1.2.12
A simple library for runtime type-checking.
Requires Python: >=3.7


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>`_