pandas-contract

Provide decorators to check functions arguments and return values using pandas DataFrame.

The decorators utilize the pandera.io library to validate data types and constraints of the input arguments and output values of functions.

Documentation

Documentation on pandas-contract.readthedocs.io

Installation

pip install pandas-contract

Setup

See Setup for first-time setup information.

Usage

ℹ️ Info: Generally, the standard abbreviations for the package imports are
import pandas as pd
import pandas_contract as pc
import pandera.pandas as pa

Check Dataframe structure

The following defines a function that takes a DataFrame with a column 'x' of type integer as input and returns a DataFrame with the column 'x' of type string as output.

The Pandera.io documentation provides a full overview of the DataFrame/DataSeries checks.

@pc.argument("df", pa.DataFrameSchema({"x": pa.Int}))
@pc.result(pa.DataFrameSchema({"x": pa.String}))
def col_x_to_string(df: pd.DataFrame) -> pd.DataFrame:
    """Convert column x to string"""
    return df.assign(x=df["x"].astype(str))

Dynamic Arguments and return values

Required columns and arguments can also be specified dynamically using a function that returns a schema.

@pc.argument("df", pa.DataFrameSchema({pc.from_arg("col"): pa.Column()}))
@pc.result(pa.DataFrameSchema({pc.from_arg("col"): pa.String}))
def col_to_string(df: pd.DataFrame, col: str) -> pd.DataFrame:
    return df.assign(**{col: df[col].astype(str)})

Multiple columns in function argument

The decorator also supports multiple columns from the function argument.

@pc.argument("df", pa.DataFrameSchema({pc.from_arg("cols"): pa.Column()}))
@pc.result(pa.DataFrameSchema({pc.from_arg("cols"): pa.String}))
def cols_to_string(df: pd.DataFrame, cols: list[str]) -> pd.DataFrame:
    return df.assign(**{col: df[col].astype(str) for col in cols})

Retrieve dataframes from a more complex argument

Sometimes the dataframe is not a direct argument of the function, but is part of a more complex argument. In this case, the decorator argument key can be used to specify the key of the dataframe in the argument.

If key is a callable, it will be called with the argument and the result will be used as the dataframe. Otherwise, it will be used as a key to retrieve the dataframe from the argument, i.e. arg[key].

Dataframe result is wrapped within another object

@pc.result(key="data")
def into_dict():
    """Dataframe wrapped in a dict"""
    return dict(data=pd.DataFrame())

See Key Type for more information and examples.

Download files

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

Source Distribution

pandas_contract-0.11.5.tar.gz (151.8 kB view details)

Uploaded Aug 12, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

pandas_contract-0.11.5-py3-none-any.whl (17.5 kB view details)

Uploaded Aug 12, 2026 Python 3

File details

Details for the file pandas_contract-0.11.5.tar.gz.

File metadata

Download URL: pandas_contract-0.11.5.tar.gz
Upload date: Aug 12, 2026
Size: 151.8 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pandas_contract-0.11.5.tar.gz
Algorithm	Hash digest
SHA256	`7c03344b0a416d856ab45e2c81864e51479b8b705c645108d08a37bac1beb3a4`
MD5	`5ffae7b9c7d9501d9668bc186475a7a8`
BLAKE2b-256	`dbe4b7c5af122149c0392ddb09262e620130570e5fb57755cbad1f2d30cc67d8`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pandas_contract-0.11.5.tar.gz:

Publisher: python.yml on schollm/pandas-contract

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: pandas_contract-0.11.5.tar.gz
- Subject digest: 7c03344b0a416d856ab45e2c81864e51479b8b705c645108d08a37bac1beb3a4
- Sigstore transparency entry: 2441612852
- Sigstore integration time: Aug 12, 2026
Source repository:
- Permalink: schollm/pandas-contract@55bf7b0889dfb2e4255f59e52edfda5b9a0a4035
- Branch / Tag: refs/tags/v0.11.5
- Owner: https://github.com/schollm
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: python.yml@55bf7b0889dfb2e4255f59e52edfda5b9a0a4035
- Trigger Event: push