Contract violation handling

Module for handling errors.

Functions to set up handling of contract violation. By default, the contract violation will be silenced.

Important

By default, the decorators will be attached to the functions, but they will not run. This ensures that production code is not affected.

The method set_mode() can be used to set the global mode.

>>> import pandas_contract as pc
>>> # print warn messages on standard log.
>>> pc.set_mode("warn")

Alternatively, the environment variable PANDAS_CONTRACT_MODE can be set to one of the values of ModesT.

It is recommended to set the mode once in the main module of your application. For tests, this can be overwritten in the test-setup.

For specific runs, the context generators as_mode() and the short-cuts pc.raises() and pc.silent() can be used to set the mode. Note, that these are not thread-safe, so they should not be used in parallel.

>>> import pandas_contract as pc
>>> # print warn messages on standard log.
>>> pc.set_mode("warn") #
>>> with pc.as_mode("raise"): # Within the context, raise a ValueError on violation.
...     pass

class pandas_contract.mode.Modes(*values)

Bases: Enum

Modes for handling errors.

The possible modes are

• silent Register the function at import, but do not run check during runtime.

• skip Do not register the function at import, and do not run check during runtime. When this is set, it’s not possible to change the mode later on since we don’t even register the function at all.

• trace, debug, info, warn, error, critical Log the error message at the specified level.

• raise Raise an exception with the error message.

Environment

The environment variable PANDAS_CONTRACT_MODE can be used to set the initial mode

handle(msgs: Iterable[str], prefix: str) → None

Handle the error messages.

no_handling() → bool

Check if the mode does not handle errors.

pandas_contract.mode.ModesT

List of valid modes for the pandas-contract library.

alias of Modes | Literal[‘skip’, ‘silent’, ‘trace’, ‘debug’, ‘info’, ‘warn’, ‘error’, ‘critical’, ‘raise’]

pandas_contract.mode.PANDAS_CONTRACT_MODE_ENV = 'PANDAS_CONTRACT_MODE'

Environment variable to set the mode for the pandas-contract library. Can be one of the literal values of ModesT.

pandas_contract.mode.as_mode(mode: ModesT) → Iterator[None]

Context manager to temporarily set the global mode for handling errors.

>>> import pandas as pd
>>> import pandas_contract as pc
>>> @pc.result(pc.checks.same_index_as("df"))
... def problematic_call(df):
...    return df.reset_index()
...
>>> with as_mode("warn"):
...     problematic_call(pd.DataFrame({"a": [1]}, index=[10]))
   index  a
0     10  1

pandas_contract.mode.get_mode() → Modes

Get the global mode for handling errors.

pandas_contract.mode.raises() → Iterator[None]

Context decorator to raise errors on failed dataframe tests.

>>> import pandas_contract as pc
>>> import pandas as pd
>>> @pc.result(pc.checks.same_index_as("df"))
... def foo(df):
...    return df.reset_index(drop=True)
>>>
>>> with raises():
...    foo(pd.DataFrame({"a": [1]}, index=[10]))
Traceback (most recent call last):
ValueError: foo: Output: Index not equal to index of df.

pandas_contract.mode.set_mode(mode: Modes | Literal['skip', 'silent', 'trace', 'debug', 'info', 'warn', 'error', 'critical', 'raise']) → Modes

Set the global mode for handling errors. This function should be set at initialization of the application.

Note that if mode equals "skip" / Modes.SKIP, then once a module has been imported, the decorator cannot be activated anymore.

Example to set the mode to raise an exception on error

>>> set_mode("raise")
<Modes.RAISE: 'raise'>

pandas_contract.mode.silent() → Iterator[None]

Context decorator to silence errors on failed dataframe tests.

>>> import pandas as pd
>>> import pandas_contract as pc
>>> @pc.result(pc.checks.same_index_as("df"))
... def foo(df):
...    return df.reset_index(drop=True)
>>>
>>> with silent():  # silence errors
...     foo(pd.DataFrame({"a": [1]}, index=[10]))
   a
0  1