Skip to main content

Extend sphinx to include icontracts.

Project description

sphinx-icontract

Continuous integration Coverage PyPi PyPI - Python Version

Sphinx-icontract extends Sphinx to include icontracts of classes and functions in the documentation.

Usage

Sphinx-icontract is based on the sphinx.ext.autodoc module. You need to specify both modules in extensions of your Sphinx configuration file (conf.py).

Here is an example excerpt:

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.autodoc',
    'sphinx_icontract'
]

Implications

Sphinx-icontract tries to infer the implications from the conditions and render them as implication (... ⇒ ...). We implemented a rule-based matching that covers most of the practical use cases:

  • not A or B is translated to A ⇒ B.

  • Expressions are negated, so x < y or B is translated to x >= y ⇒ B. More general expressions are negated with not: from x.y() or B to not x.y() ⇒ B.

  • If-Expressions are translated from B if A else True to A ⇒ B.

We found implications in form of if-expressions to be confusing when read in source code and encourage programmers to use disjunction form instead.

Custom Errors

If you specify custom errors in the contract, sphinx-icontract will try to include the error in the documentation.

The error type will be inferred from the contract’s error argument. If the error message is given as a string literal and there is no contract description, the error message will be used to describe the contract so that you do not have to specify the description twice (once in the description of the contract and once in the error message).

For example:

@icontract.require(
    lambda x: x > 0,
    error=lambda: ValueError("x positive"))
def some_func(x: int) -> None:
    pass

will be documented as:

:requires:
                        * :code:`x > 0` (x positive; raise :py:class:`ValueError`)

If both the description and the error message are given, only the description will be included:

@icontract.require(
    lambda x: x > 0,
    description="x must be positive",
    error=lambda: ValueError("x positive"))
def some_func(x: int) -> None:
    pass

will be rendered as:

:requires:
    * :code:`x > 0` (x must be positive; raise :py:class:`ValueError`)

Installation

  • Install sphinx-icontract with pip:

pip3 install sphinx-icontract

Development

  • Check out the repository.

  • In the repository root, create the virtual environment:

python3 -m venv venv3
  • Activate the virtual environment:

source venv3/bin/activate
  • Install the development dependencies:

pip3 install -e .[dev]

We use tox for testing and packaging the distribution:

tox

Pre-commit Checks

We provide a set of pre-commit checks that lint and check code for formatting.

Namely, we use:

  • yapf to check the formatting.

  • The style of the docstrings is checked with pydocstyle.

  • Static type analysis is performed with mypy.

  • Various linter checks are done with pylint.

  • Contracts are linted with pyicontract-lint.

  • Doctests are executed using the Python doctest module.

Run the pre-commit checks locally from an activated virtual environment with development dependencies:

./precommit.py
  • The pre-commit script can also automatically format the code:

./precommit.py  --overwrite

Versioning

We follow Semantic Versioning. The version X.Y.Z indicates:

  • X is the major version (backward-incompatible),

  • Y is the minor version (backward-compatible), and

  • Z is the patch version (backward-compatible bug fix).

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx-icontract-2.0.3.tar.gz (12.5 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page