Metadata-Version: 2.1
Name: quart-schema
Version: 0.15.0
Summary: A Quart extension to provide schema validation
Home-page: https://gitlab.com/pgjones/quart-schema/
License: MIT
Author: pgjones
Author-email: philip.graham.jones@googlemail.com
Requires-Python: >=3.7
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: docs
Requires-Dist: pydantic (>=1.10)
Requires-Dist: pydata_sphinx_theme ; extra == "docs"
Requires-Dist: pyhumps (>=1.6.1)
Requires-Dist: quart (>=0.18.1)
Requires-Dist: sphinx (<6) ; extra == "docs"
Requires-Dist: typing_extensions ; python_version < "3.8"
Project-URL: Repository, https://gitlab.com/pgjones/quart-schema/
Description-Content-Type: text/x-rst

Quart-Schema
============

|Build Status| |docs| |pypi| |python| |license|

Quart-Schema is a Quart extension that provides schema validation and
auto-generated API documentation. This is particularly useful when
writing RESTful APIs.

Quickstart
----------

Quart-Schema can validate an existing Quart route by decorating it
with ``validate_querystring``, ``validate_request``, or
``validate_response``. It can also validate the JSON data sent and
received over websockets using the ``send_as`` and ``receive_as``
methods.

.. code-block:: python

    from dataclasses import dataclass
    from datetime import datetime

    from quart import Quart, websocket
    from quart_schema import QuartSchema, validate_request, validate_response

    app = Quart(__name__)
    QuartSchema(app)

    @dataclass
    class Todo:
        task: str
        due: datetime | None

    @app.post("/")
    @validate_request(Todo)
    @validate_response(Todo, 201)
    async def create_todo(data: Todo) -> tuple[Todo, int]:
        ... # Do something with data, e.g. save to the DB
        return data, 201

    @app.websocket("/ws")
    async def ws() -> None:
        while True:
            data = await websocket.receive_as(Todo)
            ... # Do something with data, e.g. save to the DB
            await websocket.send_as(data, Todo)

The documentation is served by default at ``/openapi.json`` according
to the OpenAPI standard, or at ``/docs`` for a `SwaggerUI
<https://swagger.io/tools/swagger-ui/>`_ interface, or ``/redocs`` for
a `redoc <https://github.com/Redocly/redoc>`_ interface. Note that
there is currently no documentation standard for WebSockets.

Contributing
------------

Quart-Schema is developed on `GitHub
<https://github.com/pgjones/quart-schema>`_. If you come across an
issue, or have a feature request please open an `issue
<https://github.com/pgjones/quart-schema/issues>`_. If you want to
contribute a fix or the feature-implementation please do (typo fixes
welcome), by proposing a `merge request
<https://github.com/pgjones/quart-schema/merge_requests>`_.

Testing
~~~~~~~

The best way to test Quart-Schema is with `Tox
<https://tox.readthedocs.io>`_,

.. code-block:: console

    $ pip install tox
    $ tox

this will check the code style and run the tests.

Help
----

The Quart-Schema `documentation
<https://quart-schema.readthedocs.io>`_ is the best places to
start, after that try searching `stack overflow
<https://stackoverflow.com/questions/tagged/quart>`_ or ask for help
`on gitter <https://gitter.im/python-quart/lobby>`_. If you still
can't find an answer please `open an issue
<https://github.com/pgjones/quart-schema/issues>`_.


.. |Build Status| image:: https://github.com/pgjones/quart-schema/actions/workflows/ci.yml/badge.svg
   :target: https://github.com/pgjones/quart-schema/commits/main

.. |docs| image:: https://img.shields.io/badge/docs-passing-brightgreen.svg
   :target: https://quart-schema.readthedocs.io

.. |pypi| image:: https://img.shields.io/pypi/v/quart-schema.svg
   :target: https://pypi.python.org/pypi/Quart-Schema/

.. |python| image:: https://img.shields.io/pypi/pyversions/quart-schema.svg
   :target: https://pypi.python.org/pypi/Quart-Schema/

.. |license| image:: https://img.shields.io/badge/license-MIT-blue.svg
   :target: https://github.com/pgjones/quart-schema/blob/main/LICENSE

