1Cerberus |latest-version|
2=========================
3|build-status| |python-support| |black|
4
5Cerberus is a lightweight and extensible data validation library for Python.
6
7.. code-block:: python
8
9    >>> v = Validator({'name': {'type': 'string'}})
10    >>> v.validate({'name': 'john doe'})
11    True
12
13
14Features
15--------
16
17Cerberus provides type checking and other base functionality out of the box and
18is designed to be non-blocking and easily and widely extensible, allowing for
19custom validation. It has no dependencies, but has the potential to become
20yours.
21
22
23Versioning & Interpreter support
24--------------------------------
25
26The Cerberus `1.x` versions can be used with Python 2 while version `2.0` and
27later rely on Python 3 features.
28
29Starting with Cerberus 1.2, it is maintained according to
30`semantic versioning`_. So, a major release sheds off the old and defines a
31space for the new, minor releases ship further new features and improvements
32(you now the drill, new bugs are inevitable too), and micro releases polish a
33definite amount of features to glory.
34
35We intend to test Cerberus against all CPython interpreters at least until half
36a year after their `end of life`_ and against the most recent PyPy interpreter
37as a requirement for a release. If you still need to use it with a potential
38security hole in your setup, it should most probably work with the latest
39minor version branch from the time when the interpreter was still tested.
40Subsequent minor versions have good chances as well. In any case, you are
41advised to run the contributed test suite on your target system.
42
43
44Funding
45-------
46
47Cerberus is an open source, collaboratively funded project. If you run a
48business and are using Cerberus in a revenue-generating product, it would
49make business sense to sponsor its development: it ensures the project that
50your product relies on stays healthy and actively maintained. Individual users
51are also welcome to make a recurring pledge or a one time donation if Cerberus
52has helped you in your work or personal projects.
53
54Every single sign-up makes a significant impact towards making Eve possible. To
55learn more, check out our `funding page`_.
56
57
58Documentation
59-------------
60
61Complete documentation is available at http://docs.python-cerberus.org
62
63
64Installation
65------------
66
67Cerberus is on PyPI_, so all you need to do is:
68
69.. code-block:: console
70
71    $ pip install cerberus
72
73
74Testing
75-------
76
77Just run:
78
79.. code-block:: console
80
81    $ python setup.py test
82
83Or you can use tox to run the tests under all supported Python versions. Make
84sure the required python versions are installed and run:
85
86.. code-block:: console
87
88    $ pip install tox  # first time only
89    $ tox
90
91
92Contributing
93------------
94
95Please see the `Contribution Guidelines`_.
96
97
98Copyright
99---------
100
101Cerberus is an open source project by `Nicola Iarocci`_. See the license_ file
102for more information.
103
104
105.. _Contribution Guidelines: https://github.com/pyeve/cerberus/blob/master/CONTRIBUTING.rst
106.. _end of life: https://devguide.python.org/#status-of-python-branches
107.. _funding page: http://docs.python-cerberus.org/en/latest/funding.html
108.. _license: https://github.com/pyeve/cerberus/blob/master/LICENSE
109.. _Nicola Iarocci: https://nicolaiarocci.com/
110.. _PyPI: https://pypi.python.org/
111.. _semantic versioning: https://semver.org/
112
113.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
114   :alt: Black code style
115   :target: https://black.readthedocs.io/
116.. |build-status| image:: https://travis-ci.org/pyeve/cerberus.svg?branch=master
117   :alt: Build status
118   :target: https://travis-ci.org/pyeve/cerberus
119.. |latest-version| image:: https://img.shields.io/pypi/v/cerberus.svg
120   :alt: Latest version on PyPI
121   :target: https://pypi.org/project/cerberus
122.. |license| image:: https://img.shields.io/pypi/l/cerberus.svg
123   :alt: Software license
124   :target: https://github.com/pyeve/cerberus/blob/master/LICENSE
125.. |python-support| image:: https://img.shields.io/pypi/pyversions/cerberus.svg
126   :target: https://pypi.python.org/pypi/cerberus
127   :alt: Python versions
128