Python API

This reference explains how to use the Soda Core Python API to generate, test, publish, and verify data contracts using local execution (Soda Core) or remote execution (Soda Agent).

---

Installation

Install the Soda package for your data source:

pip install -i https://pypi.dev.sodadata.io/simple -U soda-postgres

Replace soda-postgres with the appropriate package for your data source. See the Data source reference for Soda Corefor supported packages and configurations.

---

Configure Logging

To enable logging for contract operations, use:

from soda_core import configure_logging

# Enable or disable verbose logging
configure_logging(verbose=True)

To access logs after a verification run:

from soda_core.contracts import verify_contracts_on_agent

result = verify_contracts_on_agent(
    contract_file_paths="path/to/contract.yaml", 
    soda_cloud_file_path="path/to/soda_cloud.yml",
)

result.get_logs()

---

Verify a local Contract with Soda Core

Use verify_contracts_locally to run the verification using local configuration and execution:

from soda_core.contracts import verify_contracts_locally

result = verify_contracts_locally(
    data_source_file_path="path/to/data_source.yml",
    contract_file_paths=["contract1.yaml", "contract2.yaml"],
    soda_cloud_file_path="path/to/soda_cloud.yml",
    variables={"START_DATE": "2024-01-01"},
    publish=False,
)

Parameter	Required	Type	Description
data_source_file_path	Yes	str	Path(s) to data source file Data source reference for Soda Core
contract_file_paths	Yes (or is dataset_identifiers required)	str or list[str]	Path(s) to local contract file(s)
dataset_identifiers	Yes (or is contract_file_paths required)	list[str]	Dataset identifiers to fetch contracts from Soda Cloud
variables	No	dict	Variables to override in contract
publish	No	bool	Push results to Soda Cloud
soda_cloud_file_path	No (unless publish is True)	str	Path to Soda Cloud config file

---

Verify Contract with Soda Agent

Use verify_contracts_on_agent to run verification remotely via Soda Agent.

from soda_core.contracts import verify_contracts_on_agent

result = verify_contracts_on_agent(
    contract_file_paths="path/to/contract.yaml",  # or list of paths
    soda_cloud_file_path="path/to/soda_cloud.yml",
    variables={"COUNTRY": "US"},
    publish=True,
)

Parameter	Required	Type	Description
contract_file_paths	Yes (or is dataset_identifiers required)	str or list[str]	Path(s) to local contract file(s)
dataset_identifiers	Yes (or is contract_file_paths required)	list[str]	Dataset identifiers to fetch contracts from Soda Cloud
variables	No	dict	Variables to override in contract
publish	No	bool	Push results to Soda Cloud
soda_cloud_file_path	Yes	str	Path to Soda Cloud config file
blocking_timeout_in_minutes	No	int	How long to wait for the agent to return results (default: 60 minutes)

---

Result Object

Both verify_contracts_on_agent and verify_contracts_locally return a result object with the following methods:

result.is_failed()     # Returns True if any check failed
result.get_logs()      # Returns log output (only if logging was enabled)