Install & Compatibility
Where this runs
tested against v3.0.9 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
601MB installed
● package 601MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
discover_df
✓ from tdda.constraints import discover_df
Used for automatically inferring constraints from a Pandas DataFrame.
verify_df
✓ from tdda.constraints import verify_df
Used for verifying a Pandas DataFrame against a set of constraints.
ReferenceTestCase
✓ from tdda.referencetest import ReferenceTestCase
✗ from tdda.referencetest import WritableTestCase
WritableTestCase was superseded by ReferenceTest in a past update.
This quickstart demonstrates how to use `tdda.constraints` to automatically discover constraints from a Pandas DataFrame and then verify another DataFrame against these discovered constraints. It highlights the `discover_df` and `verify_df` functions, showing how to save and load constraints from a `.tdda` JSON file.
import pandas as pd
from tdda.constraints import discover_df, verify_df
import os
# Create a sample DataFrame
data = {
'col1': [1, 2, 3, 4, 5, None],
'col2': ['A', 'B', 'A', 'C', 'B', 'D'],
'col3': [10.1, 11.2, 10.1, 13.4, 15.5, 12.3]
}
df = pd.DataFrame(data)
# 1. Discover constraints from the DataFrame
constraints = discover_df(df)
# Constraints object has a to_json() method to save them
constraints_filename = 'my_dataframe_constraints.tdda'
with open(constraints_filename, 'w') as f:
f.write(constraints.to_json())
print(f"Constraints discovered and saved to {constraints_filename}")
# 2. Verify a (potentially new or modified) DataFrame against the constraints
# Let's create a slightly different DataFrame for verification
df_to_verify = pd.DataFrame({
'col1': [1, 2, 3, 6, 5, 7],
'col2': ['A', 'B', 'A', 'C', 'B', 'E'],
'col3': [10.1, 11.2, 10.1, 13.0, 15.5, 12.0]
})
verification_result = verify_df(df_to_verify, constraints_filename)
print("\nVerification Results:")
print(f"Passed constraints: {verification_result.passes}")
print(f"Failed constraints: {verification_result.failures}")
if verification_result.failures > 0:
print("Details of failed constraints:")
print(verification_result.to_frame())
# Clean up the generated constraints file
os.remove(constraints_filename)
tdda --version
Debug
Known issues
breakingPython 2.7 support has been dropped. The library previously supported Python 2.7, but current versions (>=2.0) explicitly require Python >=3.8. Older codebases targeting Python 2.7 will break if upgrading `tdda` without migrating their Python environment.fixUpgrade your Python environment to 3.8 or newer before updating tdda.
affects: <2.0 (supported Python 2.7), >=2.0 (requires Python >=3.8)
deprecatedThe `WritableTestCase` class for reference testing has been superseded by `ReferenceTest`. While `WritableTestCase` might still exist for backward compatibility in some older versions, new development should use `ReferenceTest` for improved features and maintainability.fixMigrate your reference tests from `WritableTestCase` to `ReferenceTest`.
affects: All versions where `ReferenceTest` is available (from at least 2017-01-26 onwards).
gotchaMany features, particularly for constraint generation and verification against various data sources (databases, Feather files), rely on optional external dependencies (e.g., `pandas`, `feather-format`, database drivers). These packages are not installed by default with `pip install tdda` and must be installed separately if their corresponding functionality is required.fixInstall necessary optional dependencies (e.g., `pip install pandas feather-format pygresql`) based on the data sources you intend to use.
affects: All versions
gotchaWhen installing `feather-format` on Windows, you may encounter issues requiring `cython` and the Microsoft Visual C++ compiler for Python. This is a common prerequisite for many Python packages with C extensions on Windows.fixInstall `cython` (`pip install cython`) and the appropriate Microsoft Visual C++ compiler (e.g., through Visual Studio Build Tools) if you plan to use Feather files on Windows.
affects: All versions (on Windows when using feather files)
gotchaThe acronym "TDDA" is used by several unrelated projects (e.g., Java Thread Dump Analyzer, The Drug Detection Agency, Topological Data Analysis). This can lead to confusion when searching for documentation, examples, or discussing the Python `tdda` library. Ensure you are referencing the correct project.fixBe specific in searches (e.g., "Python tdda data analysis") and context when discussing the library.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'tdda'
The tdda package is not installed in the current Python environment.
tdda: command not found
The tdda command-line executable scripts are not in your system's PATH, or the package was not installed with console scripts enabled for your environment.
fixEnsure tdda is installed and its scripts directory is in your PATH, or run commands using `python -m tdda.cmd_line_app <subcommand>` (e.g., `python -m tdda.cmd_line_app infer my_data.csv`).
FileNotFoundError: [Errno 2] No such file or directory: 'my_data.csv'
The specified data file, reference file, or constraint file does not exist at the given path relative to where the command or script is executed.
fixProvide the correct absolute or relative path to the file, or ensure the file is present in the specified location.
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
A tdda constraints file (which uses JSON format) or another JSON-based configuration file is malformed and cannot be parsed.
fixReview and correct the JSON syntax in the specified file, paying attention to the reported line and column number.
AttributeError: 'Series' object has no attribute 'columns'
You are passing a Pandas Series object to a tdda function (like `infer_df`) that expects a Pandas DataFrame, which possesses a `columns` attribute.
fixEnsure you pass a Pandas DataFrame to the function; for a single column, use `df[['column_name']]` instead of `df['column_name']`.
Upgrade
Version history
3.0.9latest on PyPI · released Jun 5, 2026
Audit
Dependencies
pandasoptionalRequired for CSV files and feather files, and for working with DataFrames in constraint discovery/verification.
feather-formatoptionalRequired for reading and writing Feather files.
pmmifoptionalMakes feather file reading and writing more robust.
pygresqloptionalRequired for PostgreSQL database tables.
mysqlclient / MySQL-python / mysql-connector-pythonoptionalOne of these is required for MySQL database tables.
pymongooptionalRequired for MongoDB document collections.