typedframes 0.10.0__tar.gz → 0.12.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. typedframes-0.12.0/LICENSE +21 -0
  2. {typedframes-0.10.0 → typedframes-0.12.0}/PKG-INFO +42 -15
  3. {typedframes-0.10.0 → typedframes-0.12.0}/README.md +39 -14
  4. {typedframes-0.10.0 → typedframes-0.12.0}/pyproject.toml +11 -21
  5. {typedframes-0.10.0 → typedframes-0.12.0}/rust/Cargo.lock +1 -1
  6. {typedframes-0.10.0 → typedframes-0.12.0}/rust/Cargo.toml +1 -1
  7. {typedframes-0.10.0 → typedframes-0.12.0}/rust/src/apply.rs +4 -2
  8. {typedframes-0.10.0 → typedframes-0.12.0}/rust/src/column_consuming_methods.rs +5 -0
  9. {typedframes-0.10.0 → typedframes-0.12.0}/rust/src/constants.rs +3 -1
  10. {typedframes-0.10.0 → typedframes-0.12.0}/rust/src/errors.rs +2 -0
  11. {typedframes-0.10.0 → typedframes-0.12.0}/rust/src/index.rs +66 -1
  12. {typedframes-0.10.0 → typedframes-0.12.0}/rust/src/lib.rs +4 -0
  13. {typedframes-0.10.0 → typedframes-0.12.0}/rust/src/linter.rs +106 -6
  14. {typedframes-0.10.0 → typedframes-0.12.0}/rust/src/notebook.rs +3 -0
  15. typedframes-0.12.0/rust/src/phrase.rs +233 -0
  16. {typedframes-0.10.0 → typedframes-0.12.0}/rust/src/pyapi.rs +33 -0
  17. typedframes-0.12.0/rust/src/report.rs +1229 -0
  18. typedframes-0.12.0/rust/src/report_names.rs +631 -0
  19. {typedframes-0.10.0 → typedframes-0.12.0}/rust/src/suggest.rs +290 -64
  20. typedframes-0.12.0/rust/src/words.txt +2048 -0
  21. {typedframes-0.10.0 → typedframes-0.12.0}/src/typedframes/__init__.py +1 -5
  22. {typedframes-0.10.0 → typedframes-0.12.0}/src/typedframes/_rust_checker.pyi +4 -0
  23. {typedframes-0.10.0 → typedframes-0.12.0}/src/typedframes/base_schema.py +0 -82
  24. typedframes-0.10.0/src/typedframes/_cache.py → typedframes-0.12.0/src/typedframes/cache.py +25 -0
  25. {typedframes-0.10.0 → typedframes-0.12.0}/src/typedframes/cli.py +297 -66
  26. {typedframes-0.10.0 → typedframes-0.12.0}/src/typedframes/column.py +1 -1
  27. {typedframes-0.10.0 → typedframes-0.12.0}/src/typedframes/column_group.py +5 -44
  28. {typedframes-0.10.0 → typedframes-0.12.0}/src/typedframes/column_set.py +2 -8
  29. typedframes-0.12.0/src/typedframes/compat.py +28 -0
  30. typedframes-0.12.0/src/typedframes/python315.py +13 -0
  31. typedframes-0.10.0/src/typedframes/pandas.py +0 -284
  32. typedframes-0.10.0/src/typedframes/polars.py +0 -234
  33. {typedframes-0.10.0 → typedframes-0.12.0}/rust/.cargo/config.toml +0 -0
  34. {typedframes-0.10.0 → typedframes-0.12.0}/rust/README.md +0 -0
  35. {typedframes-0.10.0 → typedframes-0.12.0}/rust/benches/parser_bench.rs +0 -0
  36. {typedframes-0.10.0 → typedframes-0.12.0}/rust/build.rs +0 -0
  37. {typedframes-0.10.0 → typedframes-0.12.0}/rust/src/ast_extract.rs +0 -0
  38. {typedframes-0.10.0 → typedframes-0.12.0}/rust/src/column_usage.rs +0 -0
  39. {typedframes-0.10.0 → typedframes-0.12.0}/rust/src/config.rs +0 -0
  40. {typedframes-0.10.0 → typedframes-0.12.0}/rust/src/contract.rs +0 -0
  41. {typedframes-0.10.0 → typedframes-0.12.0}/rust/src/frame_ops.rs +0 -0
  42. {typedframes-0.10.0 → typedframes-0.12.0}/rust/src/helpers.rs +0 -0
  43. {typedframes-0.10.0 → typedframes-0.12.0}/rust/src/main.rs +0 -0
  44. {typedframes-0.10.0 → typedframes-0.12.0}/rust/src/parallel.rs +0 -0
  45. {typedframes-0.10.0 → typedframes-0.12.0}/rust/src/sql.rs +0 -0
  46. {typedframes-0.10.0 → typedframes-0.12.0}/rust/src/static_eval.rs +0 -0
  47. {typedframes-0.10.0 → typedframes-0.12.0}/rust/src/typo.rs +0 -0
  48. {typedframes-0.10.0 → typedframes-0.12.0}/rust/tests/integration_test.rs +0 -0
  49. {typedframes-0.10.0 → typedframes-0.12.0}/src/typedframes/column_group_error.py +0 -0
  50. {typedframes-0.10.0 → typedframes-0.12.0}/src/typedframes/missing_dependency_error.py +0 -0
  51. {typedframes-0.10.0 → typedframes-0.12.0}/src/typedframes/mypy.py +0 -0
  52. {typedframes-0.10.0 → typedframes-0.12.0}/src/typedframes/pandera.py +0 -0
  53. {typedframes-0.10.0 → typedframes-0.12.0}/src/typedframes/py.typed +0 -0
  54. {typedframes-0.10.0 → typedframes-0.12.0}/src/typedframes/schema_algebra.py +0 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 William Martin
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: typedframes
3
- Version: 0.10.0
3
+ Version: 0.12.0
4
4
  Classifier: Development Status :: 3 - Alpha
5
5
  Classifier: Intended Audience :: Developers
6
6
  Classifier: License :: OSI Approved :: MIT License
@@ -10,6 +10,7 @@ Classifier: Programming Language :: Python :: 3.11
10
10
  Classifier: Programming Language :: Python :: 3.12
11
11
  Classifier: Programming Language :: Python :: 3.13
12
12
  Classifier: Programming Language :: Python :: 3.14
13
+ Classifier: Programming Language :: Python :: 3.15
13
14
  Classifier: Topic :: Software Development :: Quality Assurance
14
15
  Classifier: Topic :: Software Development :: Libraries :: Python Modules
15
16
  Requires-Dist: mypy ; extra == 'mypy'
@@ -20,6 +21,7 @@ Provides-Extra: mypy
20
21
  Provides-Extra: pandas
21
22
  Provides-Extra: pandera
22
23
  Provides-Extra: polars
24
+ License-File: LICENSE
23
25
  Summary: Static analysis for pandas and polars DataFrames. Catch column errors at lint-time, not runtime.
24
26
  Keywords: pandas,polars,type-checking,static-analysis,dataframe,linter,mypy-plugin
25
27
  Home-Page: https://github.com/w-martin/typedframes
@@ -42,7 +44,7 @@ Project-URL: Repository, https://github.com/w-martin/typedframes
42
44
 
43
45
  > ⚠️ **Project Status: Proof of Concept**
44
46
  >
45
- > `typedframes` (v0.10.0) is currently an experimental proof-of-concept. The core static analysis and mypy/Rust
47
+ > `typedframes` (v0.12.0) is currently an experimental proof-of-concept. The core static analysis and mypy/Rust
46
48
  > integrations work, but expect rough edges. The codebase prioritizes demonstrating the viability of static DataFrame
47
49
  > column checking over production-grade stability.
48
50
  >
@@ -504,7 +506,7 @@ repos:
504
506
  name: typedframes check
505
507
  entry: typedframes check . --strict
506
508
  language: python
507
- additional_dependencies: ["typedframes==0.10.0"]
509
+ additional_dependencies: ["typedframes==0.12.0"]
508
510
  types_or: [python, jupyter]
509
511
  pass_filenames: false
510
512
  ```
@@ -553,13 +555,38 @@ The action installs the PyPI wheel into a throwaway virtualenv and runs the chec
553
555
  | Input | Default | |
554
556
  |-------|---------|-|
555
557
  | `path` | `.` | File or directory to check |
556
- | `version` | `latest` | PyPI version to install, e.g. `"0.10.0"` |
558
+ | `version` | `latest` | PyPI version to install, e.g. `"0.12.0"` |
557
559
  | `strict` | `true` | Fail the step on errors — `typedframes check` exits 0 without it |
558
560
  | `coverage-fail-under` | *(unset)* | Minimum DataFrame schema coverage, e.g. `"90"` |
559
561
  | `coverage-detail` | `summary` | Or `term-missing` for the per-file breakdown, `explain` to diagnose a lower-than-expected total |
560
562
  | `no-warnings` | `false` | Suppress warning-level diagnostics |
561
563
  | `args` | *(empty)* | Escape hatch for `--no-index`, `--lenient-ingest`, `--no-info` |
562
564
 
565
+ ### Fixing Untyped DataFrames (`suggest`)
566
+
567
+ For a DataFrame the checker can't resolve columns for, `typedframes suggest` works out a fix from the columns the rest
568
+ of its scope reads: a `usecols=`/`columns=` added to a plain `read_csv` or `read_parquet`, or else a column selection on
569
+ the line after the load. It is a dry run that prints diffs. Each site has a two-word name (`quiet-amber`) shown next to it.
570
+
571
+ ```shell
572
+ typedframes suggest src/ # dry run: prints diffs, changes nothing
573
+ typedframes suggest src/ --apply # write the safe suggestions
574
+ typedframes suggest src/ --apply --only quiet-amber # act on just that site
575
+ typedframes suggest src/ --interactive # ask about each suggestion
576
+ ```
577
+
578
+ Edits need a clean git work tree and tracked files, each edited file is re-checked in memory before anything is written,
579
+ and the files are written together or not at all. See the
580
+ [full guide](docs/usage.md#suggesting-fixes-suggest).
581
+
582
+ ### Reporting a Problem (`report`)
583
+
584
+ If `check` or `suggest` gets a site wrong and the code can't be shared, `typedframes report quiet-amber src/` prints a
585
+ bug-report body with a redacted copy of the code around that site, checked against the checker so it reproduces the same
586
+ result. Redacted is not anonymous: read it before posting, and don't use it on code you aren't allowed to share. See
587
+ [Reporting a problem](docs/usage.md#reporting-a-problem-report), and
588
+ [Security and data handling](docs/security.md) for what the tool reads, writes and connects to.
589
+
563
590
  ---
564
591
 
565
592
  ## Jupyter Notebooks
@@ -666,18 +693,18 @@ plus the requested features, so both halves get checked normally. See
666
693
 
667
694
  Fast feedback reduces development time. The typedframes Rust binary provides near-instant column checking.
668
695
 
669
- **Benchmark results** (20 runs, 3 warmup, caches cleared between runs):
670
- *2026-10-06 · Darwin 27.0.0 · arm · CPython 3.14.4 · 64GiB RAM · Great Expectations pinned @ 1.23.2*
696
+ **Benchmark results** (median of 5 runs ± one standard deviation, 3 warmup, caches cleared between runs):
697
+ *2026-10-11 · Darwin 27.0.0 · arm · CPython 3.15.0 · 64GiB RAM · Great Expectations pinned @ 1.23.2*
671
698
 
672
699
  | Tool | Version | What it does | typedframes (14 files) | great_expectations (494 files) |
673
700
  |------|---------|--------------|------------------------|--------------------------------|
674
- | typedframes | 0.10.0 | DataFrame column checker | 49ms ±618µs (IQR 609µs) | 134ms ±1ms (IQR 2ms) |
675
- | ruff | 0.16.10 | Linter (no type checking) | 22ms ±940µs (IQR 2ms) | 225ms ±3ms (IQR 5ms) |
676
- | ty | 0.0.84 | Type checker | 70ms ±1ms (IQR 2ms) | 788ms ±9ms (IQR 9ms) |
677
- | pyrefly | 1.3.2 | Type checker | 91ms ±863µs (IQR 1ms) | 261ms ±7ms (IQR 11ms) |
678
- | mypy | 2.4.0 | Type checker (no plugin) | 1.96s ±10ms (IQR 13ms) | 3.27s ±19ms (IQR 20ms) |
679
- | mypy + typedframes | 2.4.0 | Type checker + column checker | 1.99s ±29ms (IQR 31ms) | 3.67s ±15ms (IQR 15ms) |
680
- | pyright | 1.1.414 | Type checker | 940ms ±4ms (IQR 6ms) | 4.21s ±35ms (IQR 52ms) |
701
+ | typedframes | 0.12.0 | DataFrame column checker | 41.1 ± 0.7 ms | 122.1 ± 0.6 ms |
702
+ | ruff | 0.17.0 | Linter (no type checking) | 21.5 ± 0.6 ms | 212.9 ± 1.5 ms |
703
+ | ty | 0.0.84 | Type checker | 50.2 ± 0.3 ms | 751.7 ± 7.6 ms |
704
+ | pyrefly | 1.3.2 | Type checker | 91.5 ± 2.5 ms | 268.9 ± 3.8 ms |
705
+ | mypy | 2.4.0 | Type checker (no plugin) | 1.82 ± 0.03 s | 3.04 ± 0.02 s |
706
+ | mypy + typedframes | 2.4.0 | Type checker + column checker | 1.84 ± 0.02 s | 3.46 ± 0.02 s |
707
+ | pyright | 1.1.414 | Type checker | 794.2 ± 13.8 ms | 3.90 ± 0.03 s |
681
708
 
682
709
  *Run `uv run python benchmarks/benchmark_checkers.py` to reproduce.*
683
710
 
@@ -922,7 +949,7 @@ Comprehensive comparison of pandas/DataFrame typing and validation tools. **type
922
949
 
923
950
  | Feature | typedframes | Pandera | Great Expectations | strictly_typed_pandas | pandas-stubs | dataenforce | pandas-type-checks | StaticFrame | narwhals | dataframely | patito |
924
951
  |---------------------------------|------------------------|-------------|--------------------|-----------------------|--------------|-------------|--------------------|------------------|----------|------------------|------------------|
925
- | **Version tested** | 0.10.0 | 0.34.1 | 1.23.2 | 0.3.7 | 3.0.5.260914 | 0.1.2 | 1.1.3 | 5.1.1 | 2.26.0 | 3.1.2 | 0.8.6 |
952
+ | **Version tested** | 0.12.0 | 0.34.1 | 1.23.2 | 0.3.7 | 3.0.5.260914 | 0.1.2 | 1.1.3 | 5.1.1 | 2.26.0 | 3.1.2 | 0.8.6 |
926
953
  | **Analysis Type** |
927
954
  | When errors are caught | **Static (lint-time)** | Runtime | Runtime | Runtime | Static | Runtime | Runtime | Runtime | Runtime | Runtime | Runtime |
928
955
  | **Static Analysis (our focus)** |
@@ -963,7 +990,7 @@ Comprehensive comparison of pandas/DataFrame typing and validation tools. **type
963
990
 
964
991
  - **[dataenforce](https://github.com/CedricFR/dataenforce)** (v0.1.2, the only release ever published): Runtime
965
992
  validation via decorator. Appears inactive/abandoned. Broken on every currently-supported Python version
966
- (3.11 through 3.14) due to removal of internal typing APIs (`typing._TypingEmpty`) it depends on — confirmed
993
+ (3.11 through 3.15) due to removal of internal typing APIs (`typing._TypingEmpty`) it depends on — confirmed
967
994
  working only as far back as Python 3.9.
968
995
 
969
996
  - **[pandas-type-checks](https://pypi.org/project/pandas-type-checks/)** (v1.1.3): Runtime validation decorator. No
@@ -8,7 +8,7 @@
8
8
 
9
9
  > ⚠️ **Project Status: Proof of Concept**
10
10
  >
11
- > `typedframes` (v0.10.0) is currently an experimental proof-of-concept. The core static analysis and mypy/Rust
11
+ > `typedframes` (v0.12.0) is currently an experimental proof-of-concept. The core static analysis and mypy/Rust
12
12
  > integrations work, but expect rough edges. The codebase prioritizes demonstrating the viability of static DataFrame
13
13
  > column checking over production-grade stability.
14
14
  >
@@ -470,7 +470,7 @@ repos:
470
470
  name: typedframes check
471
471
  entry: typedframes check . --strict
472
472
  language: python
473
- additional_dependencies: ["typedframes==0.10.0"]
473
+ additional_dependencies: ["typedframes==0.12.0"]
474
474
  types_or: [python, jupyter]
475
475
  pass_filenames: false
476
476
  ```
@@ -519,13 +519,38 @@ The action installs the PyPI wheel into a throwaway virtualenv and runs the chec
519
519
  | Input | Default | |
520
520
  |-------|---------|-|
521
521
  | `path` | `.` | File or directory to check |
522
- | `version` | `latest` | PyPI version to install, e.g. `"0.10.0"` |
522
+ | `version` | `latest` | PyPI version to install, e.g. `"0.12.0"` |
523
523
  | `strict` | `true` | Fail the step on errors — `typedframes check` exits 0 without it |
524
524
  | `coverage-fail-under` | *(unset)* | Minimum DataFrame schema coverage, e.g. `"90"` |
525
525
  | `coverage-detail` | `summary` | Or `term-missing` for the per-file breakdown, `explain` to diagnose a lower-than-expected total |
526
526
  | `no-warnings` | `false` | Suppress warning-level diagnostics |
527
527
  | `args` | *(empty)* | Escape hatch for `--no-index`, `--lenient-ingest`, `--no-info` |
528
528
 
529
+ ### Fixing Untyped DataFrames (`suggest`)
530
+
531
+ For a DataFrame the checker can't resolve columns for, `typedframes suggest` works out a fix from the columns the rest
532
+ of its scope reads: a `usecols=`/`columns=` added to a plain `read_csv` or `read_parquet`, or else a column selection on
533
+ the line after the load. It is a dry run that prints diffs. Each site has a two-word name (`quiet-amber`) shown next to it.
534
+
535
+ ```shell
536
+ typedframes suggest src/ # dry run: prints diffs, changes nothing
537
+ typedframes suggest src/ --apply # write the safe suggestions
538
+ typedframes suggest src/ --apply --only quiet-amber # act on just that site
539
+ typedframes suggest src/ --interactive # ask about each suggestion
540
+ ```
541
+
542
+ Edits need a clean git work tree and tracked files, each edited file is re-checked in memory before anything is written,
543
+ and the files are written together or not at all. See the
544
+ [full guide](docs/usage.md#suggesting-fixes-suggest).
545
+
546
+ ### Reporting a Problem (`report`)
547
+
548
+ If `check` or `suggest` gets a site wrong and the code can't be shared, `typedframes report quiet-amber src/` prints a
549
+ bug-report body with a redacted copy of the code around that site, checked against the checker so it reproduces the same
550
+ result. Redacted is not anonymous: read it before posting, and don't use it on code you aren't allowed to share. See
551
+ [Reporting a problem](docs/usage.md#reporting-a-problem-report), and
552
+ [Security and data handling](docs/security.md) for what the tool reads, writes and connects to.
553
+
529
554
  ---
530
555
 
531
556
  ## Jupyter Notebooks
@@ -632,18 +657,18 @@ plus the requested features, so both halves get checked normally. See
632
657
 
633
658
  Fast feedback reduces development time. The typedframes Rust binary provides near-instant column checking.
634
659
 
635
- **Benchmark results** (20 runs, 3 warmup, caches cleared between runs):
636
- *2026-10-06 · Darwin 27.0.0 · arm · CPython 3.14.4 · 64GiB RAM · Great Expectations pinned @ 1.23.2*
660
+ **Benchmark results** (median of 5 runs ± one standard deviation, 3 warmup, caches cleared between runs):
661
+ *2026-10-11 · Darwin 27.0.0 · arm · CPython 3.15.0 · 64GiB RAM · Great Expectations pinned @ 1.23.2*
637
662
 
638
663
  | Tool | Version | What it does | typedframes (14 files) | great_expectations (494 files) |
639
664
  |------|---------|--------------|------------------------|--------------------------------|
640
- | typedframes | 0.10.0 | DataFrame column checker | 49ms ±618µs (IQR 609µs) | 134ms ±1ms (IQR 2ms) |
641
- | ruff | 0.16.10 | Linter (no type checking) | 22ms ±940µs (IQR 2ms) | 225ms ±3ms (IQR 5ms) |
642
- | ty | 0.0.84 | Type checker | 70ms ±1ms (IQR 2ms) | 788ms ±9ms (IQR 9ms) |
643
- | pyrefly | 1.3.2 | Type checker | 91ms ±863µs (IQR 1ms) | 261ms ±7ms (IQR 11ms) |
644
- | mypy | 2.4.0 | Type checker (no plugin) | 1.96s ±10ms (IQR 13ms) | 3.27s ±19ms (IQR 20ms) |
645
- | mypy + typedframes | 2.4.0 | Type checker + column checker | 1.99s ±29ms (IQR 31ms) | 3.67s ±15ms (IQR 15ms) |
646
- | pyright | 1.1.414 | Type checker | 940ms ±4ms (IQR 6ms) | 4.21s ±35ms (IQR 52ms) |
665
+ | typedframes | 0.12.0 | DataFrame column checker | 41.1 ± 0.7 ms | 122.1 ± 0.6 ms |
666
+ | ruff | 0.17.0 | Linter (no type checking) | 21.5 ± 0.6 ms | 212.9 ± 1.5 ms |
667
+ | ty | 0.0.84 | Type checker | 50.2 ± 0.3 ms | 751.7 ± 7.6 ms |
668
+ | pyrefly | 1.3.2 | Type checker | 91.5 ± 2.5 ms | 268.9 ± 3.8 ms |
669
+ | mypy | 2.4.0 | Type checker (no plugin) | 1.82 ± 0.03 s | 3.04 ± 0.02 s |
670
+ | mypy + typedframes | 2.4.0 | Type checker + column checker | 1.84 ± 0.02 s | 3.46 ± 0.02 s |
671
+ | pyright | 1.1.414 | Type checker | 794.2 ± 13.8 ms | 3.90 ± 0.03 s |
647
672
 
648
673
  *Run `uv run python benchmarks/benchmark_checkers.py` to reproduce.*
649
674
 
@@ -888,7 +913,7 @@ Comprehensive comparison of pandas/DataFrame typing and validation tools. **type
888
913
 
889
914
  | Feature | typedframes | Pandera | Great Expectations | strictly_typed_pandas | pandas-stubs | dataenforce | pandas-type-checks | StaticFrame | narwhals | dataframely | patito |
890
915
  |---------------------------------|------------------------|-------------|--------------------|-----------------------|--------------|-------------|--------------------|------------------|----------|------------------|------------------|
891
- | **Version tested** | 0.10.0 | 0.34.1 | 1.23.2 | 0.3.7 | 3.0.5.260914 | 0.1.2 | 1.1.3 | 5.1.1 | 2.26.0 | 3.1.2 | 0.8.6 |
916
+ | **Version tested** | 0.12.0 | 0.34.1 | 1.23.2 | 0.3.7 | 3.0.5.260914 | 0.1.2 | 1.1.3 | 5.1.1 | 2.26.0 | 3.1.2 | 0.8.6 |
892
917
  | **Analysis Type** |
893
918
  | When errors are caught | **Static (lint-time)** | Runtime | Runtime | Runtime | Static | Runtime | Runtime | Runtime | Runtime | Runtime | Runtime |
894
919
  | **Static Analysis (our focus)** |
@@ -929,7 +954,7 @@ Comprehensive comparison of pandas/DataFrame typing and validation tools. **type
929
954
 
930
955
  - **[dataenforce](https://github.com/CedricFR/dataenforce)** (v0.1.2, the only release ever published): Runtime
931
956
  validation via decorator. Appears inactive/abandoned. Broken on every currently-supported Python version
932
- (3.11 through 3.14) due to removal of internal typing APIs (`typing._TypingEmpty`) it depends on — confirmed
957
+ (3.11 through 3.15) due to removal of internal typing APIs (`typing._TypingEmpty`) it depends on — confirmed
933
958
  working only as far back as Python 3.9.
934
959
 
935
960
  - **[pandas-type-checks](https://pypi.org/project/pandas-type-checks/)** (v1.1.3): Runtime validation decorator. No
@@ -4,7 +4,7 @@ build-backend = "maturin"
4
4
 
5
5
  [project]
6
6
  name = "typedframes"
7
- version = "0.10.0"
7
+ version = "0.12.0"
8
8
  description = "Static analysis for pandas and polars DataFrames. Catch column errors at lint-time, not runtime."
9
9
  keywords = ["pandas", "polars", "type-checking", "static-analysis", "dataframe", "linter", "mypy-plugin"]
10
10
  readme = "README.md"
@@ -23,6 +23,7 @@ classifiers = [
23
23
  "Programming Language :: Python :: 3.12",
24
24
  "Programming Language :: Python :: 3.13",
25
25
  "Programming Language :: Python :: 3.14",
26
+ "Programming Language :: Python :: 3.15",
26
27
  "Topic :: Software Development :: Quality Assurance",
27
28
  "Topic :: Software Development :: Libraries :: Python Modules",
28
29
  ]
@@ -48,6 +49,7 @@ manifest-path = "rust/Cargo.toml"
48
49
  python-source = "src"
49
50
  module-name = "typedframes._rust_checker"
50
51
  features = ["pyo3/extension-module"]
52
+ include = [{ path = "LICENSE", format = "sdist" }]
51
53
 
52
54
  [tool.pytest.ini_options]
53
55
  addopts = "--cov=. --cov-report=term-missing --cov-report=json --cov-report=lcov --cov-branch -n auto"
@@ -56,6 +58,7 @@ testpaths = ["tests"]
56
58
  [tool.coverage.run]
57
59
  branch = true
58
60
  omit = [
61
+ "src/typedframes/python315.py", # needs 3.15; tests/unit/test_compat.py covers it there
59
62
  "benchmarks/*",
60
63
  "examples/*",
61
64
  "tests/*",
@@ -71,6 +74,8 @@ ignore_missing_imports = true
71
74
  line-length = 120
72
75
  target-version = "py311"
73
76
  fix = true
77
+ # Files that use syntax newer than the oldest supported Python (see typedframes/compat.py).
78
+ per-file-target-version = { "src/typedframes/python315.py" = "py315" }
74
79
 
75
80
  [tool.ruff.format]
76
81
  # Ensure the formatter respects the limit
@@ -109,11 +114,6 @@ ignore = [
109
114
  "tasks.py" = ["T201"]
110
115
  "src/typedframes/cli.py" = ["T201"]
111
116
  "benchmarks/*" = ["T201", "S603", "S607", "PLR2004", "PLR0912", "PLR0913", "TRY300"]
112
- # Deprecated PolarsFrame classmethod stubs (read_csv/read_parquet/read_json/read_excel)
113
- # intentionally don't use `source`/`schema` -- they exist only to raise a deprecation
114
- # warning and forward to the real pandas/polars call, matching the real signatures
115
- # they stand in for.
116
- "src/typedframes/polars.py" = ["ARG003"]
117
117
 
118
118
  [tool.ruff.lint.mccabe]
119
119
  max-complexity = 10
@@ -142,7 +142,7 @@ dev = [
142
142
  "pytest>=9.1.1",
143
143
  "pytest-cov>=7.1.0",
144
144
  "pytest-xdist>=3.8.0",
145
- "ruff>=0.16.10",
145
+ "ruff>=0.17.0",
146
146
  "ty>=0.0.84",
147
147
  "openpyxl>=3.1.5",
148
148
  "pyarrow>=25.0.1",
@@ -172,6 +172,10 @@ branch_coverage_min = 100
172
172
  file_line_coverage_min = 100
173
173
  file_branch_coverage_min = 100
174
174
 
175
+ [tool.ty.src]
176
+ # Uses syntax newer than requires-python (see typedframes/compat.py); ruff still checks it.
177
+ exclude = ["src/typedframes/python315.py"]
178
+
175
179
  [tool.ty.terminal]
176
180
  output-format = "concise"
177
181
 
@@ -222,20 +226,6 @@ include = ["benchmarks/**/*.py"]
222
226
  [tool.ty.overrides.rules]
223
227
  no-matching-overload = "ignore"
224
228
 
225
- # PandasFrame is deprecated (see its module docstring): it subclasses pd.DataFrame to
226
- # attach schema-aware __getitem__/groupby overrides, which structurally can't satisfy
227
- # pd.DataFrame's own signatures -- that mismatch is the reason the class is deprecated
228
- # in favor of Annotated[pd.DataFrame, Schema], not a bug to work around case-by-case.
229
- [[tool.ty.overrides]]
230
- include = ["src/typedframes/pandas.py"]
231
-
232
- [tool.ty.overrides.rules]
233
- invalid-method-override = "ignore"
234
- no-matching-overload = "ignore"
235
- invalid-argument-type = "ignore"
236
- too-many-positional-arguments = "ignore"
237
- invalid-return-type = "ignore"
238
-
239
229
  [tool.typedframes]
240
230
  enabled = true
241
231
  warnings = true
@@ -1347,7 +1347,7 @@ checksum = "7d56353a2a665ad0f41a421187180aab746c8c325620617ad883a99a1cbe66d2"
1347
1347
 
1348
1348
  [[package]]
1349
1349
  name = "typedframes_checker"
1350
- version = "0.10.0"
1350
+ version = "0.12.0"
1351
1351
  dependencies = [
1352
1352
  "anyhow",
1353
1353
  "criterion",
@@ -1,6 +1,6 @@
1
1
  [package]
2
2
  name = "typedframes_checker"
3
- version = "0.10.0"
3
+ version = "0.12.0"
4
4
  edition = "2021"
5
5
  description = "A high-performance Rust-based checker for typedframes DataFrame column schemas"
6
6
  license = "MIT"
@@ -110,6 +110,7 @@ pub(crate) fn analyze(
110
110
 
111
111
  #[derive(Serialize, Clone, Debug)]
112
112
  pub struct AppliedSuggestion {
113
+ pub phrase: String,
113
114
  pub line: usize,
114
115
  pub col: usize,
115
116
  pub var: String,
@@ -269,6 +270,7 @@ pub(crate) fn plan_file(
269
270
  outcome.applied = chosen
270
271
  .iter()
271
272
  .map(|s| AppliedSuggestion {
273
+ phrase: s.phrase.clone(),
272
274
  line: s.line,
273
275
  col: s.col,
274
276
  var: s.var.clone(),
@@ -468,9 +470,9 @@ pub(crate) fn apply_all(
468
470
  mod tests {
469
471
  use super::*;
470
472
 
471
- const SAFE: &str = "import pandas as pd\n\n\ndef run():\n df = pd.read_csv(\"x.csv\")\n return df[\"a\"] + df[\"b\"]\n";
473
+ const SAFE: &str = "import pandas as pd\n\n\ndef run():\n df = pd.read_json(\"x.json\")\n return df[\"a\"] + df[\"b\"]\n";
472
474
  // read only on one path, so a review-tier suggestion
473
- const REVIEW: &str = "import pandas as pd\n\n\ndef run(flag):\n df = pd.read_csv(\"x.csv\")\n if flag:\n return df[\"b\"]\n return df[\"a\"]\n";
475
+ const REVIEW: &str = "import pandas as pd\n\n\ndef run(flag):\n df = pd.read_json(\"x.json\")\n if flag:\n return df[\"b\"]\n return df[\"a\"]\n";
474
476
 
475
477
  fn project(files: &[(&str, &str)]) -> tempfile::TempDir {
476
478
  let dir = tempfile::tempdir().unwrap();
@@ -50,6 +50,11 @@ pub(crate) fn classify_name(name: &str) -> Consumption {
50
50
  }
51
51
  }
52
52
 
53
+ /// Every method name this module classifies, for callers that need the set (not a verdict).
54
+ pub(crate) fn names() -> impl Iterator<Item = &'static str> {
55
+ WHOLE_FRAME_CONSUMERS.iter().chain(NON_CONSUMERS).copied()
56
+ }
57
+
53
58
  #[cfg(test)]
54
59
  mod tests {
55
60
  use super::*;
@@ -4,7 +4,8 @@
4
4
 
5
5
  // Directories that should never be descended into when collecting `.py` files by
6
6
  // default: VCS metadata, virtualenvs, caches, editor/tool state, and vendored/build
7
- // trees. Mirrors ruff's default exclude list (and cli.py's own `_EXCLUDED_DIRS`,
7
+ // trees. Mirrors ruff's default exclude list, plus `target` (the Rust/maturin build
8
+ // output), and cli.py's own `_EXCLUDED_DIRS`,
8
9
  // which MUST be kept in sync with this) -- including ruff's own override semantics:
9
10
  // `[tool.typedframes] exclude` in pyproject.toml REPLACES this set entirely rather
10
11
  // than adding to it (see `collect_py_files`).
@@ -35,6 +36,7 @@ pub(crate) const DEFAULT_EXCLUDED_DIRS: &[&str] = &[
35
36
  "dist",
36
37
  "node_modules",
37
38
  "site-packages",
39
+ "target",
38
40
  "venv",
39
41
  ];
40
42
 
@@ -99,6 +99,8 @@ pub struct UntypedSite {
99
99
  pub col: usize,
100
100
  /// The assigned variable name where one was available, else a generic stand-in.
101
101
  pub var: String,
102
+ /// A stable two-word name for the site (see `phrase`); empty until assigned.
103
+ pub phrase: String,
102
104
  }
103
105
 
104
106
  /// Downstream usage the checker observed for one [`UntypedSite`] -- what a schema for
@@ -436,12 +436,26 @@ impl<'a> FileIndexer<'a> {
436
436
  }
437
437
  // Renamed into place so a reader or a crash never sees a half-written file.
438
438
  let temporary = cache_path.with_extension(format!("tmp{}", std::process::id()));
439
- if fs::write(&temporary, bytes).is_err() || fs::rename(&temporary, cache_path).is_err() {
439
+ if write_private(&temporary, &bytes).is_err() || fs::rename(&temporary, cache_path).is_err()
440
+ {
440
441
  let _ = fs::remove_file(&temporary);
441
442
  }
442
443
  }
443
444
  }
444
445
 
446
+ // Cache files hold source paths and identifiers, so only the user may read them.
447
+ fn write_private(path: &Path, bytes: &[u8]) -> std::io::Result<()> {
448
+ use std::io::Write;
449
+ let mut options = fs::OpenOptions::new();
450
+ options.write(true).create(true).truncate(true);
451
+ #[cfg(unix)]
452
+ {
453
+ use std::os::unix::fs::OpenOptionsExt;
454
+ options.mode(0o600);
455
+ }
456
+ options.open(path)?.write_all(bytes)
457
+ }
458
+
445
459
  // A directory made for the cache is private to the user; an existing one is left alone.
446
460
  fn create_private_dir(dir: &Path) -> std::io::Result<()> {
447
461
  if let Some(parent) = dir.parent() {
@@ -2639,6 +2653,36 @@ class VendoredSchema(BaseSchema):
2639
2653
  assert!(!index.all_schemas.contains_key("VendoredSchema"));
2640
2654
  }
2641
2655
 
2656
+ #[test]
2657
+ fn test_should_prune_a_rust_target_directory_by_default() {
2658
+ let dir = tempfile::tempdir().unwrap();
2659
+ let root = dir.path();
2660
+ fs::create_dir_all(root.join("rust").join("target").join("debug")).unwrap();
2661
+ fs::write(
2662
+ root.join("rust")
2663
+ .join("target")
2664
+ .join("debug")
2665
+ .join("generated.py"),
2666
+ "x = 1\n",
2667
+ )
2668
+ .unwrap();
2669
+ fs::write(root.join("app.py"), "x = 1\n").unwrap();
2670
+
2671
+ // act
2672
+ let index = build_index_internal(root);
2673
+
2674
+ // assert
2675
+ let indexed: Vec<&String> = index.files.keys().collect();
2676
+ assert!(
2677
+ indexed.iter().any(|p| p.ends_with("app.py")),
2678
+ "{indexed:#?}"
2679
+ );
2680
+ assert!(
2681
+ !indexed.iter().any(|p| p.ends_with("generated.py")),
2682
+ "{indexed:#?}"
2683
+ );
2684
+ }
2685
+
2642
2686
  #[test]
2643
2687
  fn test_should_prune_dot_claude_by_default_with_no_config_at_all() {
2644
2688
  // .claude is in DEFAULT_EXCLUDED_DIRS -- pruned automatically with no
@@ -3763,6 +3807,27 @@ def load_{i}(path: str) -> pd.DataFrame:
3763
3807
  assert_eq!(mode & 0o777, 0o700);
3764
3808
  }
3765
3809
 
3810
+ #[cfg(unix)]
3811
+ #[test]
3812
+ fn test_should_write_cache_files_readable_by_the_user_alone() {
3813
+ use std::os::unix::fs::PermissionsExt;
3814
+ let project = project_with(&[("a.py", LOADER)]);
3815
+ let cache = tempfile::tempdir().unwrap();
3816
+
3817
+ build_index_cached(project.path(), Some(cache.path()));
3818
+
3819
+ let files: Vec<_> = fs::read_dir(cache.path()).unwrap().collect();
3820
+ assert_eq!(files.len(), 1);
3821
+ let mode = files[0]
3822
+ .as_ref()
3823
+ .unwrap()
3824
+ .metadata()
3825
+ .unwrap()
3826
+ .permissions()
3827
+ .mode();
3828
+ assert_eq!(mode & 0o777, 0o600);
3829
+ }
3830
+
3766
3831
  #[test]
3767
3832
  fn test_should_survive_a_cache_dir_that_cannot_be_created() {
3768
3833
  let project = project_with(&[("a.py", LOADER)]);
@@ -47,7 +47,10 @@ mod index;
47
47
  mod linter;
48
48
  mod notebook;
49
49
  mod parallel;
50
+ mod phrase;
50
51
  mod pyapi;
52
+ mod report;
53
+ mod report_names;
51
54
  mod sql;
52
55
  mod static_eval;
53
56
  mod suggest;
@@ -65,6 +68,7 @@ fn _rust_checker(m: &Bound<'_, PyModule>) -> PyResult<()> {
65
68
  m.add_function(wrap_pyfunction!(pyapi::check_notebook, m)?)?;
66
69
  m.add_function(wrap_pyfunction!(pyapi::check_files, m)?)?;
67
70
  m.add_function(wrap_pyfunction!(pyapi::suggest_file, m)?)?;
71
+ m.add_function(wrap_pyfunction!(pyapi::report_file, m)?)?;
68
72
  m.add_function(wrap_pyfunction!(pyapi::apply_suggestions, m)?)?;
69
73
  m.add_function(wrap_pyfunction!(pyapi::vcs_problem, m)?)?;
70
74
  m.add_function(wrap_pyfunction!(pyapi::build_project_index, m)?)?;