typedframes 0.6.0__tar.gz → 0.8.0__tar.gz

{typedframes-0.6.0 → typedframes-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typedframes
-Version: 0.6.0
+Version: 0.8.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.5.0) is currently an experimental proof-of-concept. The core static analysis and mypy/Rust
+> `typedframes` (v0.8.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
 > column checking over production-grade stability.
 >
@@ -504,7 +504,7 @@ repos:
         name: typedframes check
         entry: typedframes check . --strict
         language: python
-        additional_dependencies: ["typedframes==0.5.0"]
+        additional_dependencies: ["typedframes==0.8.0"]
         types_or: [python, jupyter]
         pass_filenames: false
 ```
@@ -553,10 +553,10 @@ The action installs the PyPI wheel into a throwaway virtualenv and runs the chec
 | Input | Default | |
 |-------|---------|-|
 | `path` | `.` | File or directory to check |
-| `version` | `latest` | PyPI version to install, e.g. `"0.5.0"` |
+| `version` | `latest` | PyPI version to install, e.g. `"0.8.0"` |
 | `strict` | `true` | Fail the step on errors — `typedframes check` exits 0 without it |
 | `coverage-fail-under` | *(unset)* | Minimum DataFrame schema coverage, e.g. `"90"` |
-| `coverage-detail` | `summary` | Or `term-missing` for the per-file breakdown |
+| `coverage-detail` | `summary` | Or `term-missing` for the per-file breakdown, `explain` to diagnose a lower-than-expected total |
 | `no-warnings` | `false` | Suppress warning-level diagnostics |
 | `args` | *(empty)* | Escape hatch for `--no-index`, `--lenient-ingest`, `--no-info` |
 
@@ -667,17 +667,17 @@ plus the requested features, so both halves get checked normally. See
 Fast feedback reduces development time. The typedframes Rust binary provides near-instant column checking.
 
 **Benchmark results** (20 runs, 3 warmup, caches cleared between runs):
-*2026-08-18 · Darwin 25.6.0 · arm · CPython 3.14.4 · 64GiB RAM · Great Expectations pinned @ 1.20.0*
+*2026-09-28 · Darwin 27.0.0 · arm · CPython 3.14.4 · 64GiB RAM · Great Expectations pinned @ 1.20.0*
 
 | Tool | Version | What it does | typedframes (13 files) | great_expectations (485 files) |
 |------|---------|--------------|------------------------|--------------------------------|
-| typedframes | 0.4.1 | DataFrame column checker | 51ms ±918µs (IQR 1ms) | 219ms ±2ms (IQR 4ms) |
-| ruff | 0.16.3 | Linter (no type checking) | 30ms ±764µs (IQR 922µs) | 233ms ±3ms (IQR 4ms) |
-| ty | 0.0.72 | Type checker | 73ms ±1ms (IQR 2ms) | 810ms ±10ms (IQR 13ms) |
-| pyrefly | 1.2.0 | Type checker | 104ms ±2ms (IQR 2ms) | 276ms ±9ms (IQR 14ms) |
-| mypy | 2.3.1 | Type checker (no plugin) | 3.07s ±17ms (IQR 25ms) | 4.56s ±29ms (IQR 57ms) |
-| mypy + typedframes | 2.3.1 | Type checker + column checker | 3.07s ±13ms (IQR 17ms) | 4.84s ±20ms (IQR 23ms) |
-| pyright | 1.1.411 | Type checker | 781ms ±5ms (IQR 6ms) | 3.46s ±25ms (IQR 41ms) |
+| typedframes | 0.8.0 | DataFrame column checker | 49ms ±349µs (IQR 513µs) | 258ms ±2ms (IQR 2ms) |
+| ruff | 0.16.3 | Linter (no type checking) | 30ms ±981µs (IQR 1ms) | 236ms ±4ms (IQR 6ms) |
+| ty | 0.0.72 | Type checker | 72ms ±1ms (IQR 959µs) | 773ms ±8ms (IQR 14ms) |
+| pyrefly | 1.2.0 | Type checker | 98ms ±1ms (IQR 1ms) | 273ms ±8ms (IQR 11ms) |
+| mypy | 2.3.1 | Type checker (no plugin) | 2.79s ±93ms (IQR 61ms) | 4.14s ±41ms (IQR 52ms) |
+| mypy + typedframes | 2.3.1 | Type checker + column checker | 2.78s ±13ms (IQR 14ms) | 4.50s ±26ms (IQR 33ms) |
+| pyright | 1.1.411 | Type checker | 841ms ±35ms (IQR 46ms) | 3.30s ±24ms (IQR 32ms) |
 
 *Run `uv run python benchmarks/benchmark_checkers.py` to reproduce.*
 

{typedframes-0.6.0 → typedframes-0.8.0}/README.md

@@ -8,7 +8,7 @@
 
 > ⚠️ **Project Status: Proof of Concept**
 >
-> `typedframes` (v0.5.0) is currently an experimental proof-of-concept. The core static analysis and mypy/Rust
+> `typedframes` (v0.8.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
 > column checking over production-grade stability.
 >
@@ -470,7 +470,7 @@ repos:
         name: typedframes check
         entry: typedframes check . --strict
         language: python
-        additional_dependencies: ["typedframes==0.5.0"]
+        additional_dependencies: ["typedframes==0.8.0"]
         types_or: [python, jupyter]
         pass_filenames: false
 ```
@@ -519,10 +519,10 @@ The action installs the PyPI wheel into a throwaway virtualenv and runs the chec
 | Input | Default | |
 |-------|---------|-|
 | `path` | `.` | File or directory to check |
-| `version` | `latest` | PyPI version to install, e.g. `"0.5.0"` |
+| `version` | `latest` | PyPI version to install, e.g. `"0.8.0"` |
 | `strict` | `true` | Fail the step on errors — `typedframes check` exits 0 without it |
 | `coverage-fail-under` | *(unset)* | Minimum DataFrame schema coverage, e.g. `"90"` |
-| `coverage-detail` | `summary` | Or `term-missing` for the per-file breakdown |
+| `coverage-detail` | `summary` | Or `term-missing` for the per-file breakdown, `explain` to diagnose a lower-than-expected total |
 | `no-warnings` | `false` | Suppress warning-level diagnostics |
 | `args` | *(empty)* | Escape hatch for `--no-index`, `--lenient-ingest`, `--no-info` |
 
@@ -633,17 +633,17 @@ plus the requested features, so both halves get checked normally. See
 Fast feedback reduces development time. The typedframes Rust binary provides near-instant column checking.
 
 **Benchmark results** (20 runs, 3 warmup, caches cleared between runs):
-*2026-08-18 · Darwin 25.6.0 · arm · CPython 3.14.4 · 64GiB RAM · Great Expectations pinned @ 1.20.0*
+*2026-09-28 · Darwin 27.0.0 · arm · CPython 3.14.4 · 64GiB RAM · Great Expectations pinned @ 1.20.0*
 
 | Tool | Version | What it does | typedframes (13 files) | great_expectations (485 files) |
 |------|---------|--------------|------------------------|--------------------------------|
-| typedframes | 0.4.1 | DataFrame column checker | 51ms ±918µs (IQR 1ms) | 219ms ±2ms (IQR 4ms) |
-| ruff | 0.16.3 | Linter (no type checking) | 30ms ±764µs (IQR 922µs) | 233ms ±3ms (IQR 4ms) |
-| ty | 0.0.72 | Type checker | 73ms ±1ms (IQR 2ms) | 810ms ±10ms (IQR 13ms) |
-| pyrefly | 1.2.0 | Type checker | 104ms ±2ms (IQR 2ms) | 276ms ±9ms (IQR 14ms) |
-| mypy | 2.3.1 | Type checker (no plugin) | 3.07s ±17ms (IQR 25ms) | 4.56s ±29ms (IQR 57ms) |
-| mypy + typedframes | 2.3.1 | Type checker + column checker | 3.07s ±13ms (IQR 17ms) | 4.84s ±20ms (IQR 23ms) |
-| pyright | 1.1.411 | Type checker | 781ms ±5ms (IQR 6ms) | 3.46s ±25ms (IQR 41ms) |
+| typedframes | 0.8.0 | DataFrame column checker | 49ms ±349µs (IQR 513µs) | 258ms ±2ms (IQR 2ms) |
+| ruff | 0.16.3 | Linter (no type checking) | 30ms ±981µs (IQR 1ms) | 236ms ±4ms (IQR 6ms) |
+| ty | 0.0.72 | Type checker | 72ms ±1ms (IQR 959µs) | 773ms ±8ms (IQR 14ms) |
+| pyrefly | 1.2.0 | Type checker | 98ms ±1ms (IQR 1ms) | 273ms ±8ms (IQR 11ms) |
+| mypy | 2.3.1 | Type checker (no plugin) | 2.79s ±93ms (IQR 61ms) | 4.14s ±41ms (IQR 52ms) |
+| mypy + typedframes | 2.3.1 | Type checker + column checker | 2.78s ±13ms (IQR 14ms) | 4.50s ±26ms (IQR 33ms) |
+| pyright | 1.1.411 | Type checker | 841ms ±35ms (IQR 46ms) | 3.30s ±24ms (IQR 32ms) |
 
 *Run `uv run python benchmarks/benchmark_checkers.py` to reproduce.*
 

{typedframes-0.6.0 → typedframes-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "typedframes"
-version = "0.6.0"
+version = "0.8.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.6.0 → typedframes-0.8.0}/rust/Cargo.lock

@@ -1347,7 +1347,7 @@ checksum = "7d56353a2a665ad0f41a421187180aab746c8c325620617ad883a99a1cbe66d2"
 
 [[package]]
 name = "typedframes_checker"
-version = "0.6.0"
+version = "0.8.0"
 dependencies = [
  "anyhow",
  "criterion",

{typedframes-0.6.0 → typedframes-0.8.0}/rust/Cargo.toml

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

{typedframes-0.6.0 → typedframes-0.8.0}/rust/src/ast_extract.rs

@@ -16,6 +16,19 @@ pub(crate) fn is_schema_base(name: &str) -> bool {
     )
 }
 
+// The bare name of a decorator expression: `staticmethod` for `@staticmethod`,
+// `wraps` for both `@wraps(f)` and `@functools.wraps(f)`. `None` for anything else
+// (an attribute chain deeper than one level, a subscript, a call with no simple
+// name, ...) -- callers treat that the same as an unrecognized name.
+pub(crate) fn decorator_name(expr: &Expr) -> Option<&str> {
+    match expr {
+        Expr::Name(name) => Some(name.id.as_str()),
+        Expr::Attribute(attr) => Some(attr.attr.as_str()),
+        Expr::Call(call) => decorator_name(&call.func),
+        _ => None,
+    }
+}
+
 pub(crate) fn extract_string_literal(expr: &Expr) -> Option<&str> {
     if let Expr::StringLiteral(s) = expr {
         Some(s.value.to_str())

{typedframes-0.6.0 → typedframes-0.8.0}/rust/src/constants.rs

@@ -182,6 +182,9 @@ pub(crate) const LOAD_FUNCTIONS: &[&str] = &[
     "read_database",
     "read_database_uri",
     "read_gbq",
+    // Not an I/O read, but shares the same usecols=/columns=/dtype=/schema= recognition
+    // and bare-load-without-a-hint fallback as every function above it.
+    "DataFrame",
 ];
 
 pub(crate) const LOAD_MODULES: &[&str] = &["pd", "pandas", "pl", "polars"];
@@ -241,6 +244,90 @@ pub(crate) const SQL_PRODUCING_METHODS: &[&str] = &["query", "sql"];
 // checker's existing "empty string = none" sentinel convention for the same fields.
 pub(crate) const OPEN_FRAME_MARKER: &str = "__typedframes_open_frame__";
 
+// Methods that return a frame with the same columns as their receiver, beyond
+// `ROW_PASSTHROUGH_METHODS` (which the assignment dispatch already propagates
+// into a new binding). Consulted only by `frame_ops::classify_rhs`, to tell a
+// reassignment that leaves a tracked frame's schema intact (`df = df.copy()`)
+// apart from one that may change it. Deliberately conservative: anything not
+// listed here is treated as possibly schema-changing.
+pub(crate) const SCHEMA_PRESERVING_METHODS: &[&str] = &[
+    "copy",
+    "drop_duplicates",
+    "astype",
+    "replace",
+    "round",
+    "abs",
+    "clip",
+    "where",
+    "mask",
+    "sort_index",
+    "interpolate",
+    "shift",
+    "convert_dtypes",
+    "infer_objects",
+    "explode",
+    "isna",
+    "isnull",
+    "notna",
+    "notnull",
+    "clone",
+    "unique",
+    "drop_nulls",
+    "fill_null",
+    "fill_nan",
+    "slice",
+    "limit",
+    "reverse",
+    "lazy",
+    "collect",
+    "to_pandas",
+    "to_polars",
+];
+
+// Methods whose result is a Series, scalar, list, dict, or a serialisation --
+// never a frame -- so a name reassigned from one is no longer the tracked frame.
+pub(crate) const NON_FRAME_METHODS: &[&str] = &[
+    "sum",
+    "mean",
+    "median",
+    "std",
+    "var",
+    "min",
+    "max",
+    "count",
+    "nunique",
+    "idxmax",
+    "idxmin",
+    "any",
+    "all",
+    "prod",
+    "value_counts",
+    "to_dict",
+    "to_list",
+    "tolist",
+    "to_numpy",
+    "to_csv",
+    "to_parquet",
+    "to_json",
+    "to_string",
+    "to_html",
+    "to_markdown",
+    "to_latex",
+    "to_excel",
+    "to_sql",
+    "to_records",
+    "memory_usage",
+    "iterrows",
+    "itertuples",
+    "items",
+    "pop",
+    "get",
+    "squeeze",
+    "item",
+    "keys",
+    "insert",
+];
+
 pub(crate) const ROW_PASSTHROUGH_METHODS: &[&str] = &[
     "filter",
     "query",

{typedframes-0.6.0 → typedframes-0.8.0}/rust/src/errors.rs

@@ -63,6 +63,17 @@ pub struct FileStats {
     pub dataframes_total: usize,
     pub dataframes_typed: usize,
     pub untyped_sites: Vec<UntypedSite>,
+    pub typed_sites: Vec<TypedSite>,
+    /// Every `<load module>.<load function>(...)`-shaped call found anywhere in the
+    /// file by an unconditional, position-independent scan (see
+    /// `linter::LoadCallSiteCollector`) -- populated regardless of whether the site
+    /// was actually recognized as an origin by the targeted (`Assign`/`AnnAssign`-only)
+    /// counting logic. Powers `--coverage-detail=explain`: cross-referencing this list
+    /// against `typed_sites`/`untyped_sites` by line is what tells a reader whether a
+    /// given call was counted at all, not just whether it was typed.
+    pub all_dataframe_calls: Vec<DataFrameCallSite>,
+    /// Every place a tracked frame stopped carrying its column set -- see [`LegEvent`].
+    pub leg_events: Vec<LegEvent>,
 }
 
 /// One DataFrame origin the linter recognized but could not resolve columns for.
@@ -85,6 +96,58 @@ pub struct UntypedSite {
     pub var: String,
 }
 
+/// A recognized DataFrame origin that DID resolve to a concrete column set --
+/// the `dataframes_typed` counterpart of [`UntypedSite`]. Line and column are
+/// 1-indexed, matching [`LintError`].
+#[derive(Debug, Serialize)]
+pub struct TypedSite {
+    pub line: usize,
+    pub col: usize,
+    /// The assigned variable name where one was available, else a generic stand-in.
+    pub var: String,
+    /// A human-readable rendering of the resolved schema, from
+    /// `Linter::schema_display`: the schema's class name and column set for a named
+    /// `BaseSchema`, or `inferred column set {...}` (plus an origin, where known)
+    /// for one inferred from `usecols=`/a dict literal/etc.
+    pub schema: String,
+}
+
+/// A statement after which a tracked DataFrame no longer has a column set the checker
+/// can vouch for. Powers `--coverage-detail=explain`'s "tracking ended" listing, so a
+/// run can say exactly which line lost a frame and why.
+///
+/// `outcome` is `"unresolved"` (the frame is still a DataFrame, but its columns are
+/// unknown from here) or `"untracked"` (the name no longer holds that frame, or the
+/// checker can make no claim about it). Line and column are 1-indexed, matching
+/// [`LintError`].
+#[derive(Debug, Serialize)]
+pub struct LegEvent {
+    pub line: usize,
+    pub col: usize,
+    pub var: String,
+    pub outcome: String,
+    pub reason: String,
+}
+
+/// One `<load module>.<load function>(...)`-shaped call site found anywhere in a
+/// file by [`crate::linter::LoadCallSiteCollector`]'s unconditional scan -- see
+/// [`FileStats::all_dataframe_calls`]. Line and column are 1-indexed and point at
+/// the call expression itself (e.g. the `pd` in `pd.DataFrame(...)`), NOT at an
+/// enclosing assignment statement the way [`UntypedSite`]/[`TypedSite`] do -- the two
+/// coordinate systems are cross-referenced by LINE only (see
+/// `--coverage-detail=explain` in the CLI), not by column.
+#[derive(Debug, Serialize)]
+pub struct DataFrameCallSite {
+    pub line: usize,
+    pub col: usize,
+    /// E.g. `"pd.DataFrame"`, `"pl.read_csv"`.
+    pub label: String,
+    /// Human-readable description of the syntactic position this call was found in
+    /// (direct assignment, return value, call argument, collection element, ...) --
+    /// see `linter::CallContext::describe`.
+    pub context: String,
+}
+
 /// The JSON payload returned by the `check_file` entry point: the diagnostics plus
 /// coverage stats.
 #[derive(Debug, Serialize)]