.. image:: https://circleci.com/gh/AndreaCensi/contracts.svg?style=svg
:target: https://circleci.com/gh/AndreaCensi/contracts
PyContracts is a Python package that allows to declare constraints on function parameters and
return values. It supports a basic type system, variables binding, arithmetic constraints, and
has several specialized contracts (notably for Numpy arrays).
As a quick intro, please see `this presentation about PyContracts`_.
.. _`this presentation about PyContracts`: http://censi.mit.edu/pub/research/201410-pycontracts/201410-pycontracts.pdf
.. image:: http://censi.mit.edu/pub/research/201410-pycontracts/201410-pycontracts.border.png
:height: 100px
:target: http://censi.mit.edu/pub/research/201410-pycontracts/201410-pycontracts.pdf
:alt: A presentation about PyContracts
.. container:: brief_summary
A brief summary follows. See the full documentation at: <http://andreacensi.github.com/contracts/>
**Why**: The purpose of PyContracts is **not** to turn Python into a statically-typed language
(albeit you can be as strict as you wish), but, rather, to avoid the time-consuming and
obfuscating checking of various preconditions. In fact, more than the type constraints, I found
useful the ability to impose value and size constraints. For example, "I need a list of at least
3 positive numbers" can be expressed as ``list[>=3](number, >0))``. If you find that
PyContracts is overkill for you, you might want to try a simpler alternative, such as
typecheck_. If you find that PyContracts is not *enough* for you, you probably want to be
using Haskell_ instead of Python.
**Specifying contracts**: Contracts can be specified in three ways:
1. **Using the ``@contract`` decorator**: ::
@contract(a='int,>0', b='list[N],N>0', returns='list[N]')
def my_function(a, b):
...
2. **Using annotations** (for Python 3): ::
@contract
def my_function(a : 'int,>0', b : 'list[N],N>0') -> 'list[N]':
# Requires b to be a nonempty list, and the return
# value to have the same length.
...
3. **Using docstrings**, with the ``:type:`` and ``:rtype:`` tags: ::
@contract
def my_function(a, b):
""" Function description.
:type a: int,>0
:type b: list[N],N>0
:rtype: list[N]
"""
...
..
In any case, PyContracts will include the spec in the ``__doc__`` attribute.
**Deployment**: In production, all checks can be disabled using the function ``contracts.disable_all()``, so the performance hit is 0.
**Extensions:** You can extend PyContracts with new contracts types: ::
new_contract('valid_name', lambda s: isinstance(s, str) and len(s)>0)
@contract(names='dict(int: (valid_name, int))')
def process_accounting(records):
...
Any Python type is a contract: ::
@contract(a=int, # simple contract
b='int,>0' # more complicated
)
def f(a, b):
...
**Enforcing interfaces**: ``ContractsMeta`` is a metaclass,
like ABCMeta, which propagates contracts to the subclasses: ::
from contracts import contract, ContractsMeta, with_metaclass
class Base(with_metaclass(ContractsMeta, object)):
@abstractmethod
@contract(probability='float,>=0,<=1')
def sample(self, probability):
pass
class Derived(Base):
# The contract above is automatically enforced,
# without this class having to know about PyContracts at all!
def sample(self, probability):
....
**Numpy**: There is special support for Numpy: ::
@contract(image='array[HxWx3](uint8),H>10,W>10')
def recolor(image):
...
**Status:** The syntax is stable and it won't be changed. PyContracts is very well tested on Python 2.x.
**Status on Python 3.x:** We reached feature parity! Everything works on Python 3 now.
**Contributors**:
- `Chris Beaumont`_ (Harvard-Smithsonian Center for Astrophysics): ``$var`` syntax; kwargs/args for extensions.
- `Brett Graham`_ (Rowland Institute at Harvard University): ``attr(name:type)`` syntax for checking types of attributes.
- `William Furr`_: bug reports and performance improvements
- `Karol Kuczmarski`_ (Google Zurich): implementation of "string" and "unicode" contracts
- `Maarten Derickx`_ (Leiden U.): documentation fixes
- `Calen Pennington`_ (EdX): disabling checks inside check() function.
- `Adam Palay`_ (EdX): implementation of environment variable enabling/disabling override.
- `Ryan Heimbuch`_: bug reports
- Bernhard Biskup: bug reports
- `asharp`_: bug fixes
- `Dennis Kempin`_ (Google mothership): Sphinx-style constraints specs
- `Andy Hayden`_: Python 3 support, more efficient Numpy checks
- `Jonathan Sharpe`_: contracts for file-like objects, not operator
(Please let me know if I forgot anybody.)
.. _`Jonathan Sharpe`: http://jonathansharpe.me.uk/
.. _`Chris Beaumont`: http://chrisbeaumont.org/
.. _`asharp`: https://github.com/asharp
.. _`Maarten Derickx`: http://mderickx.nl/
.. _`Ryan Heimbuch`: https://github.com/ryanheimbuch-wf
.. _`Calen Pennington`: https://github.com/cpennington
.. _`Adam Palay`: https://github.com/adampalay
.. _`William Furr`: http://www.ccs.neu.edu/home/furrwf/
.. _`Karol Kuczmarski`: http://xion.org.pl/
.. _`Brett Graham`: https://github.com/braingram
.. _`Dennis Kempin`: https://github.com/denniskempin
.. _`Andy Hayden`: http://careers.stackoverflow.com/hayd
.. _typecheck: http://oakwinter.com/code/typecheck/
.. _Haskell: http://www.haskell.org/
Raw data
{
"_id": null,
"home_page": "http://andreacensi.github.com/contracts/",
"name": "PyContracts3",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "type checking,value checking,contracts",
"author": "Andrea Censi",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/cf/79/4784b017f7ab3310f8a2360264688a0b12f974bda503550ed581b40976e6/PyContracts3-3.0.2.tar.gz",
"platform": "",
"description": ".. image:: https://circleci.com/gh/AndreaCensi/contracts.svg?style=svg\n :target: https://circleci.com/gh/AndreaCensi/contracts\n\nPyContracts is a Python package that allows to declare constraints on function parameters and\nreturn values. It supports a basic type system, variables binding, arithmetic constraints, and\nhas several specialized contracts (notably for Numpy arrays). \n\n\nAs a quick intro, please see `this presentation about PyContracts`_.\n\n.. _`this presentation about PyContracts`: http://censi.mit.edu/pub/research/201410-pycontracts/201410-pycontracts.pdf \n\n.. image:: http://censi.mit.edu/pub/research/201410-pycontracts/201410-pycontracts.border.png\n :height: 100px\n :target: http://censi.mit.edu/pub/research/201410-pycontracts/201410-pycontracts.pdf \n :alt: A presentation about PyContracts\n\n\n\n.. container:: brief_summary\n \n A brief summary follows. See the full documentation at: <http://andreacensi.github.com/contracts/>\n\n\n**Why**: The purpose of PyContracts is **not** to turn Python into a statically-typed language\n(albeit you can be as strict as you wish), but, rather, to avoid the time-consuming and\nobfuscating checking of various preconditions. In fact, more than the type constraints, I found\nuseful the ability to impose value and size constraints. For example, \"I need a list of at least\n3 positive numbers\" can be expressed as ``list[>=3](number, >0))``. If you find that\nPyContracts is overkill for you, you might want to try a simpler alternative, such as\ntypecheck_. If you find that PyContracts is not *enough* for you, you probably want to be\nusing Haskell_ instead of Python.\n\n**Specifying contracts**: Contracts can be specified in three ways:\n\n1. **Using the ``@contract`` decorator**: ::\n \n @contract(a='int,>0', b='list[N],N>0', returns='list[N]')\n def my_function(a, b):\n ...\n\n2. **Using annotations** (for Python 3): :: \n \n @contract\n def my_function(a : 'int,>0', b : 'list[N],N>0') -> 'list[N]': \n # Requires b to be a nonempty list, and the return \n # value to have the same length.\n ...\n \n3. **Using docstrings**, with the ``:type:`` and ``:rtype:`` tags: ::\n \n @contract\n def my_function(a, b): \n \"\"\" Function description.\n :type a: int,>0\n :type b: list[N],N>0\n :rtype: list[N]\n \"\"\"\n ...\n \n..\n In any case, PyContracts will include the spec in the ``__doc__`` attribute.\n\n**Deployment**: In production, all checks can be disabled using the function ``contracts.disable_all()``, so the performance hit is 0.\n\n**Extensions:** You can extend PyContracts with new contracts types: ::\n\n new_contract('valid_name', lambda s: isinstance(s, str) and len(s)>0)\n @contract(names='dict(int: (valid_name, int))')\n def process_accounting(records):\n ...\n\nAny Python type is a contract: ::\n\n @contract(a=int, # simple contract\n b='int,>0' # more complicated\n )\n def f(a, b):\n ...\n\n**Enforcing interfaces**: ``ContractsMeta`` is a metaclass,\nlike ABCMeta, which propagates contracts to the subclasses: ::\n\n from contracts import contract, ContractsMeta, with_metaclass\n \n class Base(with_metaclass(ContractsMeta, object)):\n\n @abstractmethod\n @contract(probability='float,>=0,<=1')\n def sample(self, probability):\n pass\n\n class Derived(Base):\n # The contract above is automatically enforced, \n # without this class having to know about PyContracts at all!\n def sample(self, probability):\n ....\n\n**Numpy**: There is special support for Numpy: ::\n\n @contract(image='array[HxWx3](uint8),H>10,W>10')\n def recolor(image):\n ...\n\n**Status:** The syntax is stable and it won't be changed. PyContracts is very well tested on Python 2.x. \n\n**Status on Python 3.x:** We reached feature parity! Everything works on Python 3 now.\n\n**Contributors**:\n\n- `Chris Beaumont`_ (Harvard-Smithsonian Center for Astrophysics): ``$var`` syntax; kwargs/args for extensions.\n- `Brett Graham`_ (Rowland Institute at Harvard University): ``attr(name:type)`` syntax for checking types of attributes.\n- `William Furr`_: bug reports and performance improvements\n- `Karol Kuczmarski`_ (Google Zurich): implementation of \"string\" and \"unicode\" contracts\n- `Maarten Derickx`_ (Leiden U.): documentation fixes\n- `Calen Pennington`_ (EdX): disabling checks inside check() function.\n- `Adam Palay`_ (EdX): implementation of environment variable enabling/disabling override.\n- `Ryan Heimbuch`_: bug reports \n- Bernhard Biskup: bug reports\n- `asharp`_: bug fixes\n- `Dennis Kempin`_ (Google mothership): Sphinx-style constraints specs\n- `Andy Hayden`_: Python 3 support, more efficient Numpy checks\n- `Jonathan Sharpe`_: contracts for file-like objects, not operator\n\n(Please let me know if I forgot anybody.)\n\n.. _`Jonathan Sharpe`: http://jonathansharpe.me.uk/\n\n.. _`Chris Beaumont`: http://chrisbeaumont.org/\n.. _`asharp`: https://github.com/asharp\n.. _`Maarten Derickx`: http://mderickx.nl/\n.. _`Ryan Heimbuch`: https://github.com/ryanheimbuch-wf\n.. _`Calen Pennington`: https://github.com/cpennington\n.. _`Adam Palay`: https://github.com/adampalay\n.. _`William Furr`: http://www.ccs.neu.edu/home/furrwf/\n.. _`Karol Kuczmarski`: http://xion.org.pl/\n.. _`Brett Graham`: https://github.com/braingram\n.. _`Dennis Kempin`: https://github.com/denniskempin\n.. _`Andy Hayden`: http://careers.stackoverflow.com/hayd\n\n.. _typecheck: http://oakwinter.com/code/typecheck/\n.. _Haskell: http://www.haskell.org/",
"bugtrack_url": null,
"license": "LGPL",
"summary": "PyContracts is a Python package that allows to declare constraints on function parameters and return values. Contracts can be specified using Python3 annotations, in a decorator, or inside a docstring :type: and :rtype: tags. PyContracts supports a basic type system, variables binding, arithmetic constraints, and has several specialized contracts (notably for Numpy arrays), as well as an extension API.",
"version": "3.0.2",
"project_urls": {
"Download": "http://github.com/AndreaCensi/contracts/tarball/3.0.2",
"Homepage": "http://andreacensi.github.com/contracts/"
},
"split_keywords": [
"type checking",
"value checking",
"contracts"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cf794784b017f7ab3310f8a2360264688a0b12f974bda503550ed581b40976e6",
"md5": "ccdf2005de48f0a83ec66f3c3334346d",
"sha256": "9badfdfd71c9eb7e68ced138e612163564af440be961951f2535e0a0454b49ef"
},
"downloads": -1,
"filename": "PyContracts3-3.0.2.tar.gz",
"has_sig": false,
"md5_digest": "ccdf2005de48f0a83ec66f3c3334346d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 63931,
"upload_time": "2020-07-13T07:49:38",
"upload_time_iso_8601": "2020-07-13T07:49:38.416275Z",
"url": "https://files.pythonhosted.org/packages/cf/79/4784b017f7ab3310f8a2360264688a0b12f974bda503550ed581b40976e6/PyContracts3-3.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-07-13 07:49:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AndreaCensi",
"github_project": "contracts",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"circle": true,
"requirements": [
{
"name": "pyparsing",
"specs": [
[
"==",
"2.2.2"
]
]
},
{
"name": "decorator",
"specs": [
[
"==",
"4.0.10"
]
]
},
{
"name": "six",
"specs": [
[
"==",
"1.10.0"
]
]
},
{
"name": "future",
"specs": []
},
{
"name": "numpy",
"specs": [
[
"<",
"1.16"
]
]
}
],
"lcname": "pycontracts3"
}
JSON
