Metadata-Version: 2.4
Name: aiohttp_validate
Version: 2.0
Summary: Simple library that helps you validate your API endpoints requests/responses with json schema
Author-email: Dmitry Chaplinsky <chaplinsky.dmitry@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/dchaplinsky/aiohttp_validate
Project-URL: Issues, https://github.com/dchaplinsky/aiohttp_validate/issues
Keywords: aiohttp,jsonschema,validation,api
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Framework :: aiohttp
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: AUTHORS.rst
Requires-Dist: aiohttp>=3.8
Requires-Dist: jsonschema>=3.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-aiohttp; extra == "test"
Dynamic: license-file

===============================
aiohttp_validate
===============================


.. image:: https://img.shields.io/pypi/v/aiohttp_validate.svg
        :target: https://pypi.python.org/pypi/aiohttp_validate

.. image:: https://github.com/dchaplinsky/aiohttp_validate/actions/workflows/tests.yml/badge.svg
        :target: https://github.com/dchaplinsky/aiohttp_validate/actions/workflows/tests.yml


Simple library that helps you validate your API endpoints requests/responses with jsonschema_. Requires Python 3.9+ and aiohttp 3.8+.



Installation
------------
Install from PyPI::

    pip install aiohttp_validate

Usage
-----
Complete example of validation for `text tokenization microservice`_::

    from aiohttp_validate import validate

    @validate(
        request_schema={
            "type": "object",
            "properties": {
                "text": {"type": "string"},
            },
            "required": ["text"],
            "additionalProperties": False
        },
        response_schema={
            "type": "array",
            "items": {
                "type": "array",
                "items": {
                    "type": "array",
                    "items": {"type": "string"}
                }
            }
        }
    )
    async def tokenize_text_handler(request, *args):
        return tokenize_text(request["text"])

The wrapped handler receives the parsed and validated JSON body as its
first argument and the original aiohttp request object as the second::

    async def handler(data, request):
        pool = request.app["redis_pool"]  # the real request is right here
        ...

To respond with a status code other than 200, return a ``(data, status)``
tuple::

    async def create_handler(data, request):
        return {"id": new_id}, 201

The tuple form is detected by shape (a 2-tuple ending in an int), so if
your response data is itself such a tuple, return it as a list instead —
JSON has no tuples, the wire format is identical — or return a ready
``web.json_response``.

To also validate string formats (``date``, ``email``, ...), pass a format
checker (extra format support follows `jsonschema's rules`_)::

    @validate(request_schema=..., format_checker=jsonschema.FormatChecker())

.. _jsonschema's rules: https://python-jsonschema.readthedocs.io/en/stable/validate/#validating-formats

Features
--------
* The decorator to (optionally) validate the request to your aiohttp endpoint and it's response.
* Easily integrates with aiohttp_swaggerify_ to automatically document your endpoints with swagger.
* Validation errors are standardized and can be easily parsed by the clients of your service and also human-readable.


Developing
----------

Install with test dependencies and launch tests::

    pip install -e .[test]
    pytest


Credits
-------
That package is influenced by Tornado-JSON_ written by Hamza Faran 
Code to parse errors is written by `Ruslan Karalkin`_

Versioning
----------
This software follows `Semantic Versioning`_

.. _Semantic Versioning: http://semver.org/

License
-------

* Free software: MIT license

.. _jsonschema: http://json-schema.org/
.. _aiohttp_swaggerify: https://github.com/dchaplinsky/aiohttp_swaggerify
.. _Tornado-JSON: https://github.com/hfaran/Tornado-JSON/
.. _`Ruslan Karalkin`: https://github.com/rkaralkin
.. _`text tokenization microservice`: https://github.com/lang-uk/tokenize-ms
