.. Statham Schema documentation master file, created by
   sphinx-quickstart on Fri Apr 17 19:10:24 2020.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Statham's documentation!
==========================================


``statham`` is a tool for generating Python models from `JSON Schema`_ documents.

This project aims to simplify the experience of integrating with external sources, by providing:

1. **External validation**: Ensure that incoming data matches what you expect.
2. **Internal validation**: Ensure your application logic is consistent with the schema. Static type checking (see `mypy`_) can do this job for you.
3. **Extensibility**: Extend the generated models with properties and methods useful to you.
4. **Visibility**: Update the model layer against schema changes automatically, and let static tools identify any issues.

The models generated by this tool are declared using a JSON Schema DSL. This DSL can easily be used to write schemas by hand.

Example DSL Definition
----------------------

.. code:: python

   from typing import List

   from statham.dsl.elements import Array, Integer, Object, String
   from statham.dsl.property import Property


   class Choice(Object):
       choice_text: str = Property(String(maxLength=200), required=True)
       votes: int = Property(Integer(default=0))


   class Poll(Object):
       question: str = Property(String(), required=True)
       choices: List[Choice] = Property(Array(Choice), required=True)

Development currently targets compatibility with JSONSchema Draft 6.

Requirements
============

This package is currently tested for Python 3.6.

Installation
============

This project may be installed using `pip`_:

.. code-block:: bash

   $ pip install statham-schema

Generating python classes
=========================

Class definitions may be generated with the following command:

.. code-block:: bash

   $ statham --input /path/to/schema.json

This will write generated python classes to stdout. Optionally specify
an ``--output`` path to write to file.

Command-line arguments
----------------------

::

   Required arguments:
     --input INPUT    Specify the path to the JSON Schema to be generated.

                      If the target schema is not at the root of a document, specify the
                      JSON Pointer in the same format as a JSONSchema `$ref`, e.g.
                      `--input path/to/document.json#/definitions/schema`


   Optional arguments:
     --output OUTPUT  Output directory or file in which to write the output.

                      If the provided path is a directory, the command will derive the name
                      from the input argument. If not passed, the command will write to
                      stdout.

     -h, --help       Display this help message and exit.


.. toctree::
  :maxdepth: 2

  quickstart
  advanced
  dsl
  api



Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`


.. _JSON Schema: https://json-schema.org/
.. _mypy: http://mypy-lang.org/
.. _pip: https://pip.pypa.io/en/stable/
.. _here: https://json-schema.org/draft/2019-09/json-schema-validation.html#rfc.section.7.2.3