typedframes 0.2.2__tar.gz → 0.3.0__tar.gz

{typedframes-0.2.2 → typedframes-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typedframes
-Version: 0.2.2
+Version: 0.3.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -42,7 +42,7 @@ Project-URL: Repository, https://github.com/w-martin/typedframes
 
 > ⚠️ **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.
 >
@@ -140,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)
 ```
 
@@ -297,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.
 
@@ -327,6 +354,8 @@ 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
 - Significantly faster than mypy (see benchmarks below)
 
@@ -409,15 +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 (488 files) |
+| Tool | Version | What it does | typedframes (13 files) | great_expectations (485 files) |
 |------|---------|--------------|------------------------|--------------------------------|
-| typedframes | 0.2.1 | DataFrame column checker | 43ms ±531µs | 285ms ±4ms |
-| ruff | 0.15.4 | Linter (no type checking) | 27ms ±932µs | 251ms ±2ms |
-| ty | 0.0.19 | Type checker | 67ms ±1ms | 793ms ±14ms |
-| pyrefly | 0.54.0 | Type checker | 120ms ±2ms | 1.11s ±13ms |
-| mypy | 1.19.1 | Type checker (no plugin) | 3.47s ±15ms | 4.43s ±66ms |
-| mypy + typedframes | 1.19.1 | Type checker + column checker | 3.52s ±40ms | 4.79s ±113ms |
-| pyright | 1.1.408 | Type checker | 822ms ±55ms | 3.43s ±54ms |
+| 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.*
 
@@ -630,7 +659,7 @@ Comprehensive comparison of pandas/DataFrame typing and validation tools. **type
 
 | Feature                         | typedframes            | Pandera     | Great Expectations | strictly_typed_pandas | pandas-stubs | dataenforce | pandas-type-checks | StaticFrame      | narwhals | dataframely      | patito           |
 |---------------------------------|------------------------|-------------|--------------------|-----------------------|--------------|-------------|--------------------|------------------|----------|------------------|------------------|
-| **Version tested**              | 0.2.1                  | 0.29.0      | 1.18.0             | 0.3.7                 | 3.0.3        | 0.1.2       | 1.1.3              | 4.1.0            | 2.22.1   | 2.10.1           | 0.8.6            |
+| **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            | Runtime               | Static       | Runtime     | Runtime            | Runtime          | Runtime  | Runtime          | Runtime          |
 | **Static Analysis (our focus)** |
@@ -656,7 +685,7 @@ Comprehensive comparison of pandas/DataFrame typing and validation tools. **type
 
 ### 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.
 
@@ -664,30 +693,30 @@ Comprehensive comparison of pandas/DataFrame typing and validation tools. **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)** (v4.1.0): Alternative immutable DataFrame library.
+- **[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.22.1): 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.18.0): 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.10.1): Polars-only runtime validation library from Quantco.
+- **[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
@@ -992,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:**
 

{typedframes-0.2.2 → typedframes-0.3.0}/README.md

@@ -8,7 +8,7 @@
 
 > ⚠️ **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 +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)
 ```
 
@@ -263,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.
 
@@ -293,6 +320,8 @@ 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
 - Significantly faster than mypy (see benchmarks below)
 
@@ -375,15 +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 (488 files) |
+| Tool | Version | What it does | typedframes (13 files) | great_expectations (485 files) |
 |------|---------|--------------|------------------------|--------------------------------|
-| typedframes | 0.2.1 | DataFrame column checker | 43ms ±531µs | 285ms ±4ms |
-| ruff | 0.15.4 | Linter (no type checking) | 27ms ±932µs | 251ms ±2ms |
-| ty | 0.0.19 | Type checker | 67ms ±1ms | 793ms ±14ms |
-| pyrefly | 0.54.0 | Type checker | 120ms ±2ms | 1.11s ±13ms |
-| mypy | 1.19.1 | Type checker (no plugin) | 3.47s ±15ms | 4.43s ±66ms |
-| mypy + typedframes | 1.19.1 | Type checker + column checker | 3.52s ±40ms | 4.79s ±113ms |
-| pyright | 1.1.408 | Type checker | 822ms ±55ms | 3.43s ±54ms |
+| 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,7 +625,7 @@ Comprehensive comparison of pandas/DataFrame typing and validation tools. **type
 
 | Feature                         | typedframes            | Pandera     | Great Expectations | strictly_typed_pandas | pandas-stubs | dataenforce | pandas-type-checks | StaticFrame      | narwhals | dataframely      | patito           |
 |---------------------------------|------------------------|-------------|--------------------|-----------------------|--------------|-------------|--------------------|------------------|----------|------------------|------------------|
-| **Version tested**              | 0.2.1                  | 0.29.0      | 1.18.0             | 0.3.7                 | 3.0.3        | 0.1.2       | 1.1.3              | 4.1.0            | 2.22.1   | 2.10.1           | 0.8.6            |
+| **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            | Runtime               | Static       | Runtime     | Runtime            | Runtime          | Runtime  | Runtime          | Runtime          |
 | **Static Analysis (our focus)** |
@@ -622,7 +651,7 @@ Comprehensive comparison of pandas/DataFrame typing and validation tools. **type
 
 ### 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.
 
@@ -630,30 +659,30 @@ Comprehensive comparison of pandas/DataFrame typing and validation tools. **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)** (v4.1.0): Alternative immutable DataFrame library.
+- **[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.22.1): 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.18.0): 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.10.1): Polars-only runtime validation library from Quantco.
+- **[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
@@ -958,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:**
 

{typedframes-0.2.2 → typedframes-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "typedframes"
-version = "0.2.2"
+version = "0.3.0"
 description = "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"]
 readme = "README.md"

{typedframes-0.2.2 → typedframes-0.3.0}/rust/Cargo.lock

@@ -229,9 +229,9 @@ dependencies = [
 
 [[package]]
 name = "crossbeam-epoch"
-version = "0.9.18"
+version = "0.9.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5b82ac4a3c2ca9c3460964f020e1402edd5753411d7737aa39c3714ad1b5420e"
+checksum = "2d6914041f254d6e9176c01941b21115dcfb7089e55135a35411081bd106ef3f"
 dependencies = [
  "crossbeam-utils",
 ]
@@ -1109,7 +1109,7 @@ checksum = "5d99f8c9a7727884afe522e9bd5edbfc91a3312b36a77b5fb8926e4c31a41801"
 
 [[package]]
 name = "typedframes_checker"
-version = "0.2.2"
+version = "0.3.0"
 dependencies = [
  "anyhow",
  "criterion",

{typedframes-0.2.2 → typedframes-0.3.0}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "typedframes_checker"
-version = "0.2.2"
+version = "0.3.0"
 edition = "2021"
 description = "A high-performance Rust-based checker for typedframes DataFrame column schemas"
 license = "MIT"