{"id":13467950,"url":"https://github.com/AndreaCensi/contracts","last_synced_at":"2025-03-26T03:31:19.805Z","repository":{"id":1225966,"uuid":"1154119","full_name":"AndreaCensi/contracts","owner":"AndreaCensi","description":"PyContracts is a Python package that allows to declare  constraints on function parameters and return values.  Contracts can be specified using Python3 annotations, or inside a docstring. PyContracts supports a basic type system, variables binding,  arithmetic constraints, and has several specialized contracts and an extension API.","archived":false,"fork":false,"pushed_at":"2024-12-17T23:24:38.000Z","size":12782,"stargazers_count":405,"open_issues_count":54,"forks_count":61,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-19T19:01:42.876Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://andreacensi.github.io/contracts/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AndreaCensi.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2010-12-09T19:17:10.000Z","updated_at":"2025-02-23T17:05:31.000Z","dependencies_parsed_at":"2025-01-08T10:00:43.818Z","dependency_job_id":null,"html_url":"https://github.com/AndreaCensi/contracts","commit_stats":{"total_commits":422,"total_committers":19,"mean_commits":"22.210526315789473","dds":0.3815165876777251,"last_synced_commit":"bf6dac0a2867214d66f560257c773ba30d4a3136"},"previous_names":[],"tags_count":191,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndreaCensi%2Fcontracts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndreaCensi%2Fcontracts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndreaCensi%2Fcontracts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndreaCensi%2Fcontracts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AndreaCensi","download_url":"https://codeload.github.com/AndreaCensi/contracts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245584750,"owners_count":20639622,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T15:01:03.041Z","updated_at":"2025-03-26T03:31:19.143Z","avatar_url":"https://github.com/AndreaCensi.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":".. 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: \u003chttp://andreacensi.github.com/contracts/\u003e\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[\u003e=3](number, \u003e0))``. 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,\u003e0', b='list[N],N\u003e0', 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,\u003e0', b : 'list[N],N\u003e0') -\u003e '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,\u003e0\n              :type b: list[N],N\u003e0\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)\u003e0)\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,\u003e0' # 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,\u003e=0,\u003c=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\u003e10,W\u003e10')\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/\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAndreaCensi%2Fcontracts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAndreaCensi%2Fcontracts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAndreaCensi%2Fcontracts/lists"}