Metadata-Version: 2.3
Name: typing-validation
Version: 2.0.0
Summary: A library to perform runtime validation of Python objects using type hints.
Project-URL: Documentation, https://typing-validation.readthedocs.io
Project-URL: Repository, https://github.com/hashberg-io/typing-validation
Project-URL: Issues, https://github.com/hashberg-io/typing-validation/issues
Author: Hashberg
License: LGPL-3.0
Classifier: Development Status :: 4 - Beta
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.14
Requires-Dist: optmanage>=1.1.1
Description-Content-Type: text/x-rst

=================
Typing Validation
=================

.. image:: https://img.shields.io/badge/python-3.14+-green.svg
    :target: https://docs.python.org/3.14/
    :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

.. contents::

`typing-validation <https://typing-validation.readthedocs.io/en/latest/api/typing_validation.html>`_ is a library to perform runtime validation of Python objects using type hints.


.. 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

Please note that v2.0.0 introduces breaking changes to the API, with support restricted to Python 3.14+.

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[...], invalid value at idx: 2
  For type <class 'int'>, invalid value: 'hi'

The function `is_instance <https://typing-validation.readthedocs.io/en/latest/api/typing_validation.va;idation.html#typing_validation.validation.is_instance>`_ 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_instance
>>> is_instance([0, 1, "hi"], list[int])
False

API
===

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

License
=======

`LGPLv3 © Hashberg. <LICENSE>`_
