typedframes 0.2.1__tar.gz → 0.3.0__tar.gz

typedframes-0.2.1/README.md → typedframes-0.3.0/PKG-INFO

@@ -1,14 +1,48 @@
+Metadata-Version: 2.4
+Name: typedframes
+Version: 0.3.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: mypy ; extra == 'mypy'
+Requires-Dist: pandas>=2.0 ; extra == 'pandas'
+Requires-Dist: pandera>=0.20.0 ; extra == 'pandera'
+Requires-Dist: polars>=1.0 ; extra == 'polars'
+Provides-Extra: mypy
+Provides-Extra: pandas
+Provides-Extra: pandera
+Provides-Extra: polars
+Summary: Static analysis for pandas and polars DataFrames. Catch column errors at lint-time, not runtime.
+Keywords: pandas,polars,type-checking,static-analysis,dataframe,linter,mypy-plugin
+Home-Page: https://github.com/w-martin/typedframes
+Author: William Martin
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Documentation, https://typedframes.readthedocs.io/en/latest/
+Project-URL: Homepage, https://github.com/w-martin/typedframes
+Project-URL: Issue Tracker, https://github.com/w-martin/typedframes/issues
+Project-URL: Repository, https://github.com/w-martin/typedframes
+
 # typedframes
 
 [![CI](https://github.com/w-martin/typedframes/actions/workflows/publish.yml/badge.svg)](https://github.com/w-martin/typedframes/actions/workflows/publish.yml)
 [![PyPI version](https://img.shields.io/pypi/v/typedframes.svg)](https://pypi.org/project/typedframes/)
 [![Python versions](https://img.shields.io/pypi/pyversions/typedframes.svg)](https://pypi.org/project/typedframes/)
-[![Coverage](https://codecov.io/gh/w-martin/typedframes/branch/main/graph/badge.svg)](https://codecov.io/gh/w-martin/typedframes)
+[![Coverage](https://coveralls.io/repos/github/w-martin/typedframes/badge.svg?branch=main)](https://coveralls.io/github/w-martin/typedframes?branch=main)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 > ⚠️ **Project Status: Proof of Concept**
 >
-> `typedframes` (v0.2.1) is currently an experimental proof-of-concept. The core static analysis and mypy/Rust
+> `typedframes` (v0.3.0) is currently an experimental proof-of-concept. The core static analysis and mypy/Rust
 > integrations work, but expect rough edges. The codebase prioritizes demonstrating the viability of static DataFrame
 > schema validation over production-grade stability.
 >
@@ -106,7 +140,7 @@ print(orders["revenue"])  # ✗ unknown-column — 'revenue' not in inferred set
 
 ```shell
 typedframes check src/
-# src/pipeline.py:7:8: error[unknown-column] Column 'revenue' not in inferred set {order_id, amount, status}
+# src/pipeline.py:7:8: error[unknown-column] Column 'revenue' does not exist in inferred column set (defined at line 6)
 # ✗ Found 1 error in 12 files (0.0s)
 ```
 
@@ -263,12 +297,39 @@ trimmed = df.drop(columns=["nonexistent"])
 # ⚠ dropped-unknown-column: Dropped column 'nonexistent' does not exist in UserData
 ```
 
+### Function Parameter Contracts
+
+Beyond validating access at the point it happens, the checker infers a *contract* for any function's
+first parameter: every column the function needs, drawn from what its body accesses or — taking priority —
+from a schema annotation on the parameter itself. Calling that function with a DataFrame that doesn't
+satisfy the contract is caught at the **call site**, across files:
+
+```python
+# transforms.py
+def contact_label(customers):
+    return customers["name"] + customers["email"]
+```
+
+```python
+# pipeline.py
+customers = load_customers(path)  # inferred columns: {customer_id, name, region}
+contact_label(customers)
+# ✗ missing-column: 'customers' passed to contact_label (transforms.py:2) is missing
+#   column(s) {email} — available: {customer_id, name, region}, required: {email, name}
+```
+
+The contract is resolved *transitively*: if a function only forwards its parameter to other functions
+(`step1 = preprocess(df); step2 = enrich(step1)`), the checker follows the chain and unions their
+requirements, catching a missing column even when no single function in the chain touches it directly.
+Column-list slices (`df[["a", "b"]]`) contribute to the contract too.
+
 ### See Also
 
 - [`examples/inference_example.py`](examples/inference_example.py) — single-file walkthrough of all four inference
   scenarios with annotated ✓/✗ comments.
 - [`examples/multi_file_inference/`](examples/multi_file_inference/) — multi-file project checked with
-  `typedframes check examples/multi_file_inference/`; no `BaseSchema` anywhere.
+  `typedframes check examples/multi_file_inference/`; no `BaseSchema` anywhere. Includes a function
+  parameter contract violation caught at the call site (`missing-column`).
 - [`examples/multi_file_with_schema/`](examples/multi_file_with_schema/) — same scenario with `BaseSchema`
   classes; the checker follows schemas across module boundaries via the project index.
 
@@ -293,8 +354,10 @@ typedframes check src/
 **Features:**
 - Catches column name errors
 - Validates schema mismatches between functions
+- Validates function parameter contracts across files, including transitively through chains of
+  helper functions (`missing-column`)
 - Checks both pandas and polars code
-- 10-100x faster than mypy
+- Significantly faster than mypy (see benchmarks below)
 
 **Use this for:**
 - Fast feedback during development
@@ -375,17 +438,15 @@ Fast feedback reduces development time. The typedframes Rust binary provides nea
 
 **Benchmark results** (10 runs, 3 warmup, caches cleared between runs):
 
-| Tool               | Version | What it does                  | typedframes (13 files) | great_expectations (490 files)† |
-|--------------------|---------|-------------------------------|------------------------|---------------------------------|
-| typedframes        | 0.2.0   | DataFrame column checker      | 9ms ±2ms               | 930µs ±89µs                     |
-| ruff               | 0.15.4  | Linter (no type checking)     | 64ms ±16ms             | 360ms ±18ms                     |
-| ty                 | 0.0.19  | Type checker                  | 115ms ±22ms            | 1.65s ±26ms                     |
-| pyrefly            | 0.54.0  | Type checker                  | 3.78s ±7.53s           | 693ms ±33ms                     |
-| mypy               | 1.19.1  | Type checker (no plugin)      | 13.85s ±1.08s          | 12.13s ±400ms                   |
-| mypy + typedframes | 1.19.1  | Type checker + column checker | 13.51s ±273ms          | 13.89s ±491ms                   |
-| pyright            | 1.1.408 | Type checker                  | 2.10s ±422ms           | 8.37s ±253ms                    |
-
-*† great_expectations column from previous benchmark run.*
+| Tool | Version | What it does | typedframes (13 files) | great_expectations (485 files) |
+|------|---------|--------------|------------------------|--------------------------------|
+| typedframes | 0.3.0 | DataFrame column checker | 81ms ±6ms | 3.64s ±9ms |
+| ruff | 0.15.21 | Linter (no type checking) | 48ms ±13ms | 237ms ±31ms |
+| ty | 0.0.58 | Type checker | 119ms ±14ms | 287ms ±33ms |
+| pyrefly | 1.1.1 | Type checker | 162ms ±18ms | 390ms ±21ms |
+| mypy | 2.2.0 | Type checker (no plugin) | 4.56s ±22ms | 7.31s ±35ms |
+| mypy + typedframes | 2.2.0 | Type checker + column checker | 4.69s ±61ms | 10.89s ±356ms |
+| pyright | 1.1.411 | Type checker | 1.39s ±17ms | 8.06s ±193ms |
 
 *Run `uv run python benchmarks/benchmark_checkers.py` to reproduce.*
 
@@ -596,63 +657,77 @@ See [`examples/schema_algebra_example.py`](examples/schema_algebra_example.py) f
 Comprehensive comparison of pandas/DataFrame typing and validation tools. **typedframes focuses on static analysis**
 —catching errors at lint-time before your code runs.
 
-| Feature                         | typedframes            | Pandera     | Great Expectations | strictly_typed_pandas | pandas-stubs | dataenforce | pandas-type-checks | StaticFrame      | narwhals |
-|---------------------------------|------------------------|-------------|--------------------|-----------------------|--------------|-------------|--------------------|------------------|----------|
-| **Version tested**              | 0.2.0                  | 0.29.0      | 1.4.3              | 0.3.6                 | 3.0.0        | 0.1.2       | 1.1.3              | 3.7.0            | 2.16.0   |
+| Feature                         | typedframes            | Pandera     | Great Expectations | strictly_typed_pandas | pandas-stubs | dataenforce | pandas-type-checks | StaticFrame      | narwhals | dataframely      | patito           |
+|---------------------------------|------------------------|-------------|--------------------|-----------------------|--------------|-------------|--------------------|------------------|----------|------------------|------------------|
+| **Version tested**              | 0.3.0                  | 0.32.1      | 1.18.2             | 0.3.7                 | 3.0.3        | 0.1.2       | 1.1.3              | 5.0.0            | 2.23.0   | 2.13.0           | 0.8.6            |
 | **Analysis Type**               |
-| When errors are caught          | **Static (lint-time)** | Runtime     | Runtime            | Static + Runtime      | Static       | Runtime     | Runtime            | Static + Runtime | Runtime  |
+| When errors are caught          | **Static (lint-time)** | Runtime     | Runtime            | Runtime               | Static       | Runtime     | Runtime            | Runtime          | Runtime  | Runtime          | Runtime          |
 | **Static Analysis (our focus)** |
-| Mypy plugin                     | ✅ Yes                  | ⚠️ Limited  | ❌ No               | ✅ Yes                 | ✅ Yes        | ❌ No        | ❌ No               | ⚠️ Basic         | ❌ No     |
-| Standalone checker              | ✅ Rust (~1ms)          | ❌ No        | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ❌ No     |
-| Column name checking            | ✅ Yes                  | ⚠️ Limited  | ❌ No               | ✅ Yes                 | ❌ No         | ❌ No        | ❌ No               | ✅ Yes            | ❌ No     |
-| Column type checking            | ✅ Yes                  | ⚠️ Limited  | ❌ No               | ✅ Yes                 | ❌ No         | ❌ No        | ❌ No               | ✅ Yes            | ❌ No     |
-| Typo suggestions                | ✅ Yes                  | ❌ No        | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ❌ No     |
+| Mypy plugin                     | ✅ Yes                  | ⚠️ Limited  | ❌ No               | ❌ No                  | ✅ Yes        | ❌ No        | ❌ No               | ⚠️ Basic         | ❌ No     | ❌ No             | ❌ No             |
+| Standalone checker              | ✅ Rust (~1ms)          | ❌ No        | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ❌ No     | ❌ No             | ❌ No             |
+| Column name checking            | ✅ Yes                  | ⚠️ Limited  | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ❌ No     | ❌ No             | ❌ No             |
+| Column type checking            | ✅ Yes                  | ⚠️ Limited  | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ❌ No     | ❌ No             | ❌ No             |
+| Typo suggestions                | ✅ Yes                  | ❌ No        | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ❌ No     | ❌ No             | ❌ No             |
 | **Runtime Validation**          |
-| Data validation                 | ❌ No                   | ✅ Excellent | ✅ Excellent        | ✅ typeguard           | ❌ No         | ✅ Yes       | ✅ Yes              | ✅ Yes            | ❌ No     |
-| Value constraints               | ❌ No                   | ✅ Yes       | ✅ Excellent        | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ✅ Yes            | ❌ No     |
+| Data validation                 | ❌ No                   | ✅ Excellent | ✅ Excellent        | ✅ typeguard           | ❌ No         | ✅ Yes       | ✅ Yes              | ✅ Yes            | ❌ No     | ✅ Yes            | ✅ Yes            |
+| Value constraints               | ❌ No                   | ✅ Yes       | ✅ Excellent        | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ✅ Yes            | ❌ No     | ✅ Yes            | ✅ Yes            |
 | **Schema Features**             |
-| Column grouping                 | ✅ ColumnGroup          | ❌ No        | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ❌ No     |
-| Regex column matching           | ✅ Yes                  | ❌ No        | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ❌ No     |
+| Column grouping                 | ✅ ColumnGroup          | ❌ No        | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ❌ No     | ❌ No             | ❌ No             |
+| Regex column matching           | ✅ Yes                  | ❌ No        | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ❌ No     | ❌ No             | ❌ No             |
 | **Backend Support**             |
-| Pandas                          | ✅ Yes                  | ✅ Yes       | ✅ Yes              | ✅ Yes                 | ✅ Yes        | ✅ Yes       | ✅ Yes              | ❌ Own            | ✅ Yes    |
-| Polars                          | ✅ Yes                  | ✅ Yes       | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ Own            | ✅ Yes    |
-| DuckDB, cuDF, etc.              | ❌ No                   | ❌ No        | ✅ Spark, SQL       | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ✅ Yes    |
+| Pandas                          | ✅ Yes                  | ✅ Yes       | ✅ Yes              | ✅ Yes                 | ✅ Yes        | ✅ Yes       | ✅ Yes              | ❌ Own            | ✅ Yes    | ❌ No             | ⚠️ Limited        |
+| Polars                          | ✅ Yes                  | ✅ Yes       | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ Own            | ✅ Yes    | ✅ Yes (only)     | ✅ Yes            |
+| DuckDB, cuDF, etc.              | ❌ No                   | ❌ No        | ✅ Spark, SQL       | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ✅ Yes    | ❌ No             | ❌ No             |
 | **Project Status (Feb 2026)**   |
-| Active development              | ✅ Yes                  | ✅ Yes       | ✅ Yes              | ⚠️ Low                | ✅ Yes        | ❌ Inactive  | ⚠️ Low             | ✅ Yes            | ✅ Yes    |
+| Active development              | ✅ Yes                  | ✅ Yes       | ✅ Yes              | ⚠️ Low                | ✅ Yes        | ❌ Inactive  | ⚠️ Low             | ✅ Yes            | ✅ Yes    | ✅ Yes            | ✅ Yes            |
 
 **Legend:** ✅ Full support | ⚠️ Limited/Partial | ❌ Not supported
 
 ### Tool Descriptions
 
-- **[Pandera](https://pandera.readthedocs.io/)** (v0.29.0): Excellent runtime validation. Static analysis support exists
+- **[Pandera](https://pandera.readthedocs.io/)** (v0.32.1): Excellent runtime validation. Static analysis support exists
   but has limitations—column access via `df["column"]` is not validated, and schema mismatches between functions may not
   be caught.
 
-- **[strictly_typed_pandas](https://strictly-typed-pandas.readthedocs.io/)** (v0.3.6): Provides `DataSet[Schema]` type
-  hints with mypy support. No standalone checker. No polars support. Runtime validation via typeguard.
+- **[strictly_typed_pandas](https://strictly-typed-pandas.readthedocs.io/)** (v0.3.7): Provides `DataSet[Schema]` type
+  hints for runtime validation via typeguard. Despite documentation implying mypy support, there is no mypy plugin —
+  column access errors are not caught statically. No standalone checker. No polars support.
 
-- **[pandas-stubs](https://github.com/pandas-dev/pandas-stubs)** (v3.0.0): Official pandas type stubs. Provides
+- **[pandas-stubs](https://github.com/pandas-dev/pandas-stubs)** (v3.0.3): Official pandas type stubs. Provides
   API-level types but no column-level checking.
 
 - **[dataenforce](https://github.com/CedricFR/dataenforce)** (v0.1.2): Runtime validation via decorator. Marked as
-  experimental/not production-ready. Appears inactive.
+  experimental/not production-ready. Appears inactive. Broken on Python 3.13+ due to removal of internal typing APIs.
 
 - **[pandas-type-checks](https://pypi.org/project/pandas-type-checks/)** (v1.1.3): Runtime validation decorator. No
   static analysis.
 
-- **[StaticFrame](https://github.com/static-frame/static-frame)** (v3.7.0): Alternative immutable DataFrame library with
-  built-in static typing. Not compatible with pandas/polars—requires using StaticFrame's own DataFrame implementation.
+- **[StaticFrame](https://github.com/static-frame/static-frame)** (v5.0.0): Alternative immutable DataFrame library.
+  Not compatible with pandas/polars — requires a full rewrite to StaticFrame's own API. Column access is still
+  string-based; mypy does not catch column name typos. Type safety comes from immutability guarantees, not schema checking.
 
-- **[narwhals](https://narwhals-dev.github.io/narwhals/)** (v2.16.0): Compatibility layer that provides a unified API
+- **[narwhals](https://narwhals-dev.github.io/narwhals/)** (v2.23.0): Compatibility layer that provides a unified API
   across pandas, polars, DuckDB, cuDF, and more. Solves a different problem—write-once-run-anywhere portability, not
   type safety. See [Why Abstraction Layers Don't Solve Type Safety](#why-abstraction-layers-dont-solve-type-safety)
   below.
 
-- **[Great Expectations](https://greatexpectations.io/)** (v1.4.3): Comprehensive data quality framework. Defines
+- **[Great Expectations](https://greatexpectations.io/)** (v1.18.2): Comprehensive data quality framework. Defines
   "expectations" (assertions) about data values, distributions, and schema properties. Excellent for runtime
   validation, data documentation, and data quality monitoring. No static analysis or column-level type checking in
   code. Supports pandas, Spark, and SQL backends.
 
+- **[dataframely](https://github.com/Quantco/dataframely)** (v2.13.0): Polars-only runtime validation library from Quantco.
+  Schemas are defined as classes inheriting `dy.Schema` with typed descriptor fields (`dy.String()`, `dy.Float64()`)
+  and `@dy.rule()` decorators for cross-column and group-level constraints. Returns `dy.DataFrame[Schema]` generic
+  types that give call-site narrowing to type checkers, but does not validate column subscript access inside function
+  bodies. No lint-time or static analysis capability. Supports nullability, string constraints, numeric bounds,
+  cross-column rules, soft validation, test data generation, and SQLAlchemy/PyArrow export.
+
+- **[patito](https://github.com/JakobGM/patito)** (v0.8.6): Runtime validation library using a Pydantic-style `patito.Model`
+  class. Polars is the primary backend; pandas is supported but works by converting to Polars via PyArrow (an
+  undeclared dependency). DuckDB is not supported despite appearing in some documentation—validation crashes immediately
+  on DuckDB relations. No static analysis or standalone checker.
+
 ### Type Checkers (Not DataFrame-Specific)
 
 These are general Python type checkers. They don't validate DataFrame column names, but they can be used alongside
@@ -946,6 +1021,8 @@ MIT License - see [LICENSE](LICENSE)
 - [x] Pandera integration (`to_pandera_schema()`)
 - [x] Cross-file schema inference (project-level index, `--no-index` flag)
 - [x] Aggressive column inference (untracked-dataframe/dropped-unknown-column warnings, method chain propagation)
+- [x] Function parameter contracts (`missing-column`), resolved transitively across chains of helper
+  functions and cross-file calls; schema-annotated parameters take priority over body-scanning
 
 **Planned:**
 
@@ -1002,6 +1079,7 @@ Inspired by the needs of ML/data science teams working with complex data pipelin
 
 ---
 
-**Questions? Issues? Ideas?** [Open an issue](https://github.com/yourusername/typedframes/issues)
+**Questions? Issues? Ideas?** [Open an issue](https://github.com/w-martin/typedframes/issues)
 
 **Ready to catch DataFrame bugs before runtime?** `pip install typedframes`
+

typedframes-0.2.1/PKG-INFO → typedframes-0.3.0/README.md

@@ -1,37 +1,14 @@
-Metadata-Version: 2.4
-Name: typedframes
-Version: 0.2.1
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Requires-Dist: mypy ; extra == 'mypy'
-Requires-Dist: pandas>=2.3.3 ; extra == 'pandas'
-Requires-Dist: pandera>=0.29.0 ; extra == 'pandera'
-Requires-Dist: polars>=1.38.1 ; extra == 'polars'
-Provides-Extra: mypy
-Provides-Extra: pandas
-Provides-Extra: pandera
-Provides-Extra: polars
-Summary: Static analysis for pandas and polars DataFrames. Catch column errors at lint-time, not runtime.
-Home-Page: https://github.com/w-martin/typedframes
-Author: William Martin
-License: MIT
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
-
 # typedframes
 
 [![CI](https://github.com/w-martin/typedframes/actions/workflows/publish.yml/badge.svg)](https://github.com/w-martin/typedframes/actions/workflows/publish.yml)
 [![PyPI version](https://img.shields.io/pypi/v/typedframes.svg)](https://pypi.org/project/typedframes/)
 [![Python versions](https://img.shields.io/pypi/pyversions/typedframes.svg)](https://pypi.org/project/typedframes/)
-[![Coverage](https://codecov.io/gh/w-martin/typedframes/branch/main/graph/badge.svg)](https://codecov.io/gh/w-martin/typedframes)
+[![Coverage](https://coveralls.io/repos/github/w-martin/typedframes/badge.svg?branch=main)](https://coveralls.io/github/w-martin/typedframes?branch=main)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 > ⚠️ **Project Status: Proof of Concept**
 >
-> `typedframes` (v0.2.1) is currently an experimental proof-of-concept. The core static analysis and mypy/Rust
+> `typedframes` (v0.3.0) is currently an experimental proof-of-concept. The core static analysis and mypy/Rust
 > integrations work, but expect rough edges. The codebase prioritizes demonstrating the viability of static DataFrame
 > schema validation over production-grade stability.
 >
@@ -129,7 +106,7 @@ print(orders["revenue"])  # ✗ unknown-column — 'revenue' not in inferred set
 
 ```shell
 typedframes check src/
-# src/pipeline.py:7:8: error[unknown-column] Column 'revenue' not in inferred set {order_id, amount, status}
+# src/pipeline.py:7:8: error[unknown-column] Column 'revenue' does not exist in inferred column set (defined at line 6)
 # ✗ Found 1 error in 12 files (0.0s)
 ```
 
@@ -286,12 +263,39 @@ trimmed = df.drop(columns=["nonexistent"])
 # ⚠ dropped-unknown-column: Dropped column 'nonexistent' does not exist in UserData
 ```
 
+### Function Parameter Contracts
+
+Beyond validating access at the point it happens, the checker infers a *contract* for any function's
+first parameter: every column the function needs, drawn from what its body accesses or — taking priority —
+from a schema annotation on the parameter itself. Calling that function with a DataFrame that doesn't
+satisfy the contract is caught at the **call site**, across files:
+
+```python
+# transforms.py
+def contact_label(customers):
+    return customers["name"] + customers["email"]
+```
+
+```python
+# pipeline.py
+customers = load_customers(path)  # inferred columns: {customer_id, name, region}
+contact_label(customers)
+# ✗ missing-column: 'customers' passed to contact_label (transforms.py:2) is missing
+#   column(s) {email} — available: {customer_id, name, region}, required: {email, name}
+```
+
+The contract is resolved *transitively*: if a function only forwards its parameter to other functions
+(`step1 = preprocess(df); step2 = enrich(step1)`), the checker follows the chain and unions their
+requirements, catching a missing column even when no single function in the chain touches it directly.
+Column-list slices (`df[["a", "b"]]`) contribute to the contract too.
+
 ### See Also
 
 - [`examples/inference_example.py`](examples/inference_example.py) — single-file walkthrough of all four inference
   scenarios with annotated ✓/✗ comments.
 - [`examples/multi_file_inference/`](examples/multi_file_inference/) — multi-file project checked with
-  `typedframes check examples/multi_file_inference/`; no `BaseSchema` anywhere.
+  `typedframes check examples/multi_file_inference/`; no `BaseSchema` anywhere. Includes a function
+  parameter contract violation caught at the call site (`missing-column`).
 - [`examples/multi_file_with_schema/`](examples/multi_file_with_schema/) — same scenario with `BaseSchema`
   classes; the checker follows schemas across module boundaries via the project index.
 
@@ -316,8 +320,10 @@ typedframes check src/
 **Features:**
 - Catches column name errors
 - Validates schema mismatches between functions
+- Validates function parameter contracts across files, including transitively through chains of
+  helper functions (`missing-column`)
 - Checks both pandas and polars code
-- 10-100x faster than mypy
+- Significantly faster than mypy (see benchmarks below)
 
 **Use this for:**
 - Fast feedback during development
@@ -398,17 +404,15 @@ Fast feedback reduces development time. The typedframes Rust binary provides nea
 
 **Benchmark results** (10 runs, 3 warmup, caches cleared between runs):
 
-| Tool               | Version | What it does                  | typedframes (13 files) | great_expectations (490 files)† |
-|--------------------|---------|-------------------------------|------------------------|---------------------------------|
-| typedframes        | 0.2.0   | DataFrame column checker      | 9ms ±2ms               | 930µs ±89µs                     |
-| ruff               | 0.15.4  | Linter (no type checking)     | 64ms ±16ms             | 360ms ±18ms                     |
-| ty                 | 0.0.19  | Type checker                  | 115ms ±22ms            | 1.65s ±26ms                     |
-| pyrefly            | 0.54.0  | Type checker                  | 3.78s ±7.53s           | 693ms ±33ms                     |
-| mypy               | 1.19.1  | Type checker (no plugin)      | 13.85s ±1.08s          | 12.13s ±400ms                   |
-| mypy + typedframes | 1.19.1  | Type checker + column checker | 13.51s ±273ms          | 13.89s ±491ms                   |
-| pyright            | 1.1.408 | Type checker                  | 2.10s ±422ms           | 8.37s ±253ms                    |
-
-*† great_expectations column from previous benchmark run.*
+| Tool | Version | What it does | typedframes (13 files) | great_expectations (485 files) |
+|------|---------|--------------|------------------------|--------------------------------|
+| typedframes | 0.3.0 | DataFrame column checker | 81ms ±6ms | 3.64s ±9ms |
+| ruff | 0.15.21 | Linter (no type checking) | 48ms ±13ms | 237ms ±31ms |
+| ty | 0.0.58 | Type checker | 119ms ±14ms | 287ms ±33ms |
+| pyrefly | 1.1.1 | Type checker | 162ms ±18ms | 390ms ±21ms |
+| mypy | 2.2.0 | Type checker (no plugin) | 4.56s ±22ms | 7.31s ±35ms |
+| mypy + typedframes | 2.2.0 | Type checker + column checker | 4.69s ±61ms | 10.89s ±356ms |
+| pyright | 1.1.411 | Type checker | 1.39s ±17ms | 8.06s ±193ms |
 
 *Run `uv run python benchmarks/benchmark_checkers.py` to reproduce.*
 
@@ -619,63 +623,77 @@ See [`examples/schema_algebra_example.py`](examples/schema_algebra_example.py) f
 Comprehensive comparison of pandas/DataFrame typing and validation tools. **typedframes focuses on static analysis**
 —catching errors at lint-time before your code runs.
 
-| Feature                         | typedframes            | Pandera     | Great Expectations | strictly_typed_pandas | pandas-stubs | dataenforce | pandas-type-checks | StaticFrame      | narwhals |
-|---------------------------------|------------------------|-------------|--------------------|-----------------------|--------------|-------------|--------------------|------------------|----------|
-| **Version tested**              | 0.2.0                  | 0.29.0      | 1.4.3              | 0.3.6                 | 3.0.0        | 0.1.2       | 1.1.3              | 3.7.0            | 2.16.0   |
+| Feature                         | typedframes            | Pandera     | Great Expectations | strictly_typed_pandas | pandas-stubs | dataenforce | pandas-type-checks | StaticFrame      | narwhals | dataframely      | patito           |
+|---------------------------------|------------------------|-------------|--------------------|-----------------------|--------------|-------------|--------------------|------------------|----------|------------------|------------------|
+| **Version tested**              | 0.3.0                  | 0.32.1      | 1.18.2             | 0.3.7                 | 3.0.3        | 0.1.2       | 1.1.3              | 5.0.0            | 2.23.0   | 2.13.0           | 0.8.6            |
 | **Analysis Type**               |
-| When errors are caught          | **Static (lint-time)** | Runtime     | Runtime            | Static + Runtime      | Static       | Runtime     | Runtime            | Static + Runtime | Runtime  |
+| When errors are caught          | **Static (lint-time)** | Runtime     | Runtime            | Runtime               | Static       | Runtime     | Runtime            | Runtime          | Runtime  | Runtime          | Runtime          |
 | **Static Analysis (our focus)** |
-| Mypy plugin                     | ✅ Yes                  | ⚠️ Limited  | ❌ No               | ✅ Yes                 | ✅ Yes        | ❌ No        | ❌ No               | ⚠️ Basic         | ❌ No     |
-| Standalone checker              | ✅ Rust (~1ms)          | ❌ No        | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ❌ No     |
-| Column name checking            | ✅ Yes                  | ⚠️ Limited  | ❌ No               | ✅ Yes                 | ❌ No         | ❌ No        | ❌ No               | ✅ Yes            | ❌ No     |
-| Column type checking            | ✅ Yes                  | ⚠️ Limited  | ❌ No               | ✅ Yes                 | ❌ No         | ❌ No        | ❌ No               | ✅ Yes            | ❌ No     |
-| Typo suggestions                | ✅ Yes                  | ❌ No        | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ❌ No     |
+| Mypy plugin                     | ✅ Yes                  | ⚠️ Limited  | ❌ No               | ❌ No                  | ✅ Yes        | ❌ No        | ❌ No               | ⚠️ Basic         | ❌ No     | ❌ No             | ❌ No             |
+| Standalone checker              | ✅ Rust (~1ms)          | ❌ No        | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ❌ No     | ❌ No             | ❌ No             |
+| Column name checking            | ✅ Yes                  | ⚠️ Limited  | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ❌ No     | ❌ No             | ❌ No             |
+| Column type checking            | ✅ Yes                  | ⚠️ Limited  | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ❌ No     | ❌ No             | ❌ No             |
+| Typo suggestions                | ✅ Yes                  | ❌ No        | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ❌ No     | ❌ No             | ❌ No             |
 | **Runtime Validation**          |
-| Data validation                 | ❌ No                   | ✅ Excellent | ✅ Excellent        | ✅ typeguard           | ❌ No         | ✅ Yes       | ✅ Yes              | ✅ Yes            | ❌ No     |
-| Value constraints               | ❌ No                   | ✅ Yes       | ✅ Excellent        | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ✅ Yes            | ❌ No     |
+| Data validation                 | ❌ No                   | ✅ Excellent | ✅ Excellent        | ✅ typeguard           | ❌ No         | ✅ Yes       | ✅ Yes              | ✅ Yes            | ❌ No     | ✅ Yes            | ✅ Yes            |
+| Value constraints               | ❌ No                   | ✅ Yes       | ✅ Excellent        | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ✅ Yes            | ❌ No     | ✅ Yes            | ✅ Yes            |
 | **Schema Features**             |
-| Column grouping                 | ✅ ColumnGroup          | ❌ No        | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ❌ No     |
-| Regex column matching           | ✅ Yes                  | ❌ No        | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ❌ No     |
+| Column grouping                 | ✅ ColumnGroup          | ❌ No        | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ❌ No     | ❌ No             | ❌ No             |
+| Regex column matching           | ✅ Yes                  | ❌ No        | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ❌ No     | ❌ No             | ❌ No             |
 | **Backend Support**             |
-| Pandas                          | ✅ Yes                  | ✅ Yes       | ✅ Yes              | ✅ Yes                 | ✅ Yes        | ✅ Yes       | ✅ Yes              | ❌ Own            | ✅ Yes    |
-| Polars                          | ✅ Yes                  | ✅ Yes       | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ Own            | ✅ Yes    |
-| DuckDB, cuDF, etc.              | ❌ No                   | ❌ No        | ✅ Spark, SQL       | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ✅ Yes    |
+| Pandas                          | ✅ Yes                  | ✅ Yes       | ✅ Yes              | ✅ Yes                 | ✅ Yes        | ✅ Yes       | ✅ Yes              | ❌ Own            | ✅ Yes    | ❌ No             | ⚠️ Limited        |
+| Polars                          | ✅ Yes                  | ✅ Yes       | ❌ No               | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ Own            | ✅ Yes    | ✅ Yes (only)     | ✅ Yes            |
+| DuckDB, cuDF, etc.              | ❌ No                   | ❌ No        | ✅ Spark, SQL       | ❌ No                  | ❌ No         | ❌ No        | ❌ No               | ❌ No             | ✅ Yes    | ❌ No             | ❌ No             |
 | **Project Status (Feb 2026)**   |
-| Active development              | ✅ Yes                  | ✅ Yes       | ✅ Yes              | ⚠️ Low                | ✅ Yes        | ❌ Inactive  | ⚠️ Low             | ✅ Yes            | ✅ Yes    |
+| Active development              | ✅ Yes                  | ✅ Yes       | ✅ Yes              | ⚠️ Low                | ✅ Yes        | ❌ Inactive  | ⚠️ Low             | ✅ Yes            | ✅ Yes    | ✅ Yes            | ✅ Yes            |
 
 **Legend:** ✅ Full support | ⚠️ Limited/Partial | ❌ Not supported
 
 ### Tool Descriptions
 
-- **[Pandera](https://pandera.readthedocs.io/)** (v0.29.0): Excellent runtime validation. Static analysis support exists
+- **[Pandera](https://pandera.readthedocs.io/)** (v0.32.1): Excellent runtime validation. Static analysis support exists
   but has limitations—column access via `df["column"]` is not validated, and schema mismatches between functions may not
   be caught.
 
-- **[strictly_typed_pandas](https://strictly-typed-pandas.readthedocs.io/)** (v0.3.6): Provides `DataSet[Schema]` type
-  hints with mypy support. No standalone checker. No polars support. Runtime validation via typeguard.
+- **[strictly_typed_pandas](https://strictly-typed-pandas.readthedocs.io/)** (v0.3.7): Provides `DataSet[Schema]` type
+  hints for runtime validation via typeguard. Despite documentation implying mypy support, there is no mypy plugin —
+  column access errors are not caught statically. No standalone checker. No polars support.
 
-- **[pandas-stubs](https://github.com/pandas-dev/pandas-stubs)** (v3.0.0): Official pandas type stubs. Provides
+- **[pandas-stubs](https://github.com/pandas-dev/pandas-stubs)** (v3.0.3): Official pandas type stubs. Provides
   API-level types but no column-level checking.
 
 - **[dataenforce](https://github.com/CedricFR/dataenforce)** (v0.1.2): Runtime validation via decorator. Marked as
-  experimental/not production-ready. Appears inactive.
+  experimental/not production-ready. Appears inactive. Broken on Python 3.13+ due to removal of internal typing APIs.
 
 - **[pandas-type-checks](https://pypi.org/project/pandas-type-checks/)** (v1.1.3): Runtime validation decorator. No
   static analysis.
 
-- **[StaticFrame](https://github.com/static-frame/static-frame)** (v3.7.0): Alternative immutable DataFrame library with
-  built-in static typing. Not compatible with pandas/polars—requires using StaticFrame's own DataFrame implementation.
+- **[StaticFrame](https://github.com/static-frame/static-frame)** (v5.0.0): Alternative immutable DataFrame library.
+  Not compatible with pandas/polars — requires a full rewrite to StaticFrame's own API. Column access is still
+  string-based; mypy does not catch column name typos. Type safety comes from immutability guarantees, not schema checking.
 
-- **[narwhals](https://narwhals-dev.github.io/narwhals/)** (v2.16.0): Compatibility layer that provides a unified API
+- **[narwhals](https://narwhals-dev.github.io/narwhals/)** (v2.23.0): Compatibility layer that provides a unified API
   across pandas, polars, DuckDB, cuDF, and more. Solves a different problem—write-once-run-anywhere portability, not
   type safety. See [Why Abstraction Layers Don't Solve Type Safety](#why-abstraction-layers-dont-solve-type-safety)
   below.
 
-- **[Great Expectations](https://greatexpectations.io/)** (v1.4.3): Comprehensive data quality framework. Defines
+- **[Great Expectations](https://greatexpectations.io/)** (v1.18.2): Comprehensive data quality framework. Defines
   "expectations" (assertions) about data values, distributions, and schema properties. Excellent for runtime
   validation, data documentation, and data quality monitoring. No static analysis or column-level type checking in
   code. Supports pandas, Spark, and SQL backends.
 
+- **[dataframely](https://github.com/Quantco/dataframely)** (v2.13.0): Polars-only runtime validation library from Quantco.
+  Schemas are defined as classes inheriting `dy.Schema` with typed descriptor fields (`dy.String()`, `dy.Float64()`)
+  and `@dy.rule()` decorators for cross-column and group-level constraints. Returns `dy.DataFrame[Schema]` generic
+  types that give call-site narrowing to type checkers, but does not validate column subscript access inside function
+  bodies. No lint-time or static analysis capability. Supports nullability, string constraints, numeric bounds,
+  cross-column rules, soft validation, test data generation, and SQLAlchemy/PyArrow export.
+
+- **[patito](https://github.com/JakobGM/patito)** (v0.8.6): Runtime validation library using a Pydantic-style `patito.Model`
+  class. Polars is the primary backend; pandas is supported but works by converting to Polars via PyArrow (an
+  undeclared dependency). DuckDB is not supported despite appearing in some documentation—validation crashes immediately
+  on DuckDB relations. No static analysis or standalone checker.
+
 ### Type Checkers (Not DataFrame-Specific)
 
 These are general Python type checkers. They don't validate DataFrame column names, but they can be used alongside
@@ -969,6 +987,8 @@ MIT License - see [LICENSE](LICENSE)
 - [x] Pandera integration (`to_pandera_schema()`)
 - [x] Cross-file schema inference (project-level index, `--no-index` flag)
 - [x] Aggressive column inference (untracked-dataframe/dropped-unknown-column warnings, method chain propagation)
+- [x] Function parameter contracts (`missing-column`), resolved transitively across chains of helper
+  functions and cross-file calls; schema-annotated parameters take priority over body-scanning
 
 **Planned:**
 
@@ -1025,7 +1045,6 @@ Inspired by the needs of ML/data science teams working with complex data pipelin
 
 ---
 
-**Questions? Issues? Ideas?** [Open an issue](https://github.com/yourusername/typedframes/issues)
+**Questions? Issues? Ideas?** [Open an issue](https://github.com/w-martin/typedframes/issues)
 
 **Ready to catch DataFrame bugs before runtime?** `pip install typedframes`
-