PyPI - python-constricter - Versions diffs - 0.2.5__tar.gz → 0.3.6__tar.gz - Mend

python-constricter 0.2.5tar.gz → 0.3.6tar.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 (170) hide show

python_constricter-0.3.6/.gitignore ADDED Viewed

@@ -0,0 +1,48 @@
+# Everything generated locally (the dev venv, tool caches, coverage data, build output) lives under local/.
+local/
+# Written next to the sources by Python.
+__pycache__/
+# Generated by a build (hatch_build.py, or `python -m stdlib_tables`): the standard-library tables, and
+# the tests' list of what only some platforms and Pythons have.
+constricter/fix/tables/
+stdlib_tables/partial.json
+# npm installs of the pinned CI Markdown tools (.github/package.json)
+.github/node_modules/
+.hypothesis
+# Claude Code's agent worktrees: other checkouts of this repository.
+.claude/worktrees/
+# Claude Code's sandbox bind-mounts /dev/null over these denied paths while a
+# session runs; none is a file of this repo
+/.bash_profile
+/.bashrc
+/.gitconfig
+/.gitmodules
+/.idea
+/.mcp.json
+/.profile
+/.ripgreprc
+/.zprofile
+/.zshrc
+/.claude/agents
+/.claude/commands
+/.claude/hooks
+/.claude/launch.json
+/.claude/loop.md
+/.claude/output-styles
+/.claude/routines
+/.claude/scheduled_tasks.json
+/.claude/settings.json
+/.claude/settings.local.json
+/.claude/skills
+/.claude/workflows
+/.claude/.cc-writes
+/.vscode
+# Backups merge tools leave next to a conflicted file.
+*.orig

{python_constricter-0.2.5 → python_constricter-0.3.6}/PKG-INFO RENAMED Viewed

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: python-constricter
-Version: 0.2.5
+Version: 0.3.6
+Import-Name: constricter
 Summary: Lint rules: every local variable is typed where it's first bound. A flake8 plugin, a pylint plugin and a standalone CLI.
 Author: Ivy Duggan
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
 License-Expression: MIT
+License-File: LICENSE.md
 Classifier: Framework :: Flake8
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
@@ -18,12 +18,12 @@ Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Typing :: Typed
-License-File: LICENSE.md
-Requires-Dist: flake8>=7 ; extra == "flake8"
-Requires-Dist: pylint>=3 ; extra == "pylint"
+Requires-Python: >=3.11
 Provides-Extra: flake8
+Requires-Dist: flake8>=7; extra == 'flake8'
 Provides-Extra: pylint
-Import-Name: constricter
+Requires-Dist: pylint>=3; extra == 'pylint'
+Description-Content-Type: text/markdown
 # python-con`strict`er
@@ -97,7 +97,7 @@ class bodies too. Statements are read in source order, and only a name's first b
 | `LVA002` | an untyped `for` target or `match` capture                                                | `name: T` first (or a type comment)            |
 | `LVA003` | a `for` target typed only by `# type: T`                                                  | `name: T` first                                |
 | `LVA004` | with `all-scopes`: the same as `LVA001`, in a module or class body                        | `name: T = ...` (`ClassVar[T]` in a dataclass) |
-| `LVA005` | an annotation with `Any`, `object` or a generic without its parameters                    | name the real type                             |
+| `LVA005` | an annotation with `Any`, `object` or a generic without its parameters, past `vague`      | name the real type                             |
 | `LVA006` | an annotation nested `nesting` deep (3 by default)                                        | a `type` alias for a part of it                |
 | `LVA007` | a name annotated again with the type it already has, in the same block                    | drop the second annotation                     |
 | `LVA008` | with every value the name ever holds known: an annotation that could narrow to them       | narrow it (`total: int`)                       |
@@ -109,7 +109,10 @@ class bodies too. Statements are read in source order, and only a name's first b
 Exempt: comprehensions, `except ... as`, imports, `def`/`class`, `type` aliases, parameters,
 `global`/`nonlocal`, and `_`; in module and class bodies, dunder names (`__all__`, `__slots__`) and
 enum members (a base imported from `enum`, however it's aliased, or else whose name ends in `Enum`
-or `Flag`).
+or `Flag`). And what makes a type, not a value, which an annotation would turn into a variable to a
+type checker: `T = TypeVar("T")`, a `ParamSpec`, a `TypeVarTuple`, a `NewType`, and a functional
+`NamedTuple`, `TypedDict`, `Enum` or `collections.namedtuple`, however `typing`,
+`typing_extensions`, `enum` or `collections` is imported.
 A `# type:` comment (`x = 1  # type: int`, `with f() as x:  # type: T`) counts as an annotation with
 `type-comments`, or automatically in a module written to run on Python 2: one that imports
@@ -170,32 +173,39 @@ enabled).
 Options:
-| Option           | CLI                                                                                                                                                                          | `[tool.constricter]`                            | flake8 (CLI or config)          | pylint                            |
-| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------- | --------------------------------- |
-| level            | `--level`                                                                                                                                                                    | `level`                                         | `--constricter-level`           | `constricter-level`               |
-| type comments    | `--type-comments`                                                                                                                                                            | `type-comments`                                 | `--constricter-type-comments`   | `constricter-type-comments = yes` |
-| all scopes       | `--all-scopes`                                                                                                                                                               | `all-scopes`                                    | `--constricter-all-scopes`      | `constricter-all-scopes = yes`    |
-| nesting          | `--nesting N`                                                                                                                                                                | `nesting`                                       | `--constricter-nesting`         | `constricter-nesting`             |
-| max length       | `--max-length N` (LVA011)                                                                                                                                                    | `max-length`                                    | `--constricter-max-length`      | `constricter-max-length`          |
-| type hierarchy   | -                                                                                                                                                                            | `narrower` (a table)                            | `--constricter-narrower`        | `constricter-narrower`            |
-| fix              | `--fix` (`--unsafe-fixes` for guesses), `--diff` to preview                                                                                                                  | -                                               | -                               | -                                 |
-| infer with       | `--infer-with CHECKERS` (`basedpyright`, `ty`, both: inferred types, as guesses)                                                                                             | `infer-with`                                    | -                               | -                                 |
-| show fixes       | `--show-fixes` (each fix and how it was decided, text)                                                                                                                       | -                                               | -                               | -                                 |
-| fix levels       | `--fix-select`, `--fix-ignore`, `--unsafe-fix-select` (mechanisms: [docs/FIXES.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/FIXES.md#fix-levels)) | `fix-select`, `fix-ignore`, `unsafe-fix-select` | -                               | -                                 |
-| select           | `--select CODES` (codes or prefixes)                                                                                                                                         | `select`                                        | flake8's own `select`           | pylint's own `enable`             |
-| extend select    | `--extend-select CODES` (also report these; an opt-in code by its full code)                                                                                                 | `extend-select`                                 | flake8's own `extend-select`    | pylint's own `enable`             |
-| ignore           | `--ignore CODES`                                                                                                                                                             | `ignore`                                        | flake8's own `extend-ignore`    | pylint's own `disable`            |
-| exclude          | `--exclude GLOB` (repeatable)                                                                                                                                                | `exclude`                                       | flake8's own `exclude`          | pylint's own `ignore-paths`       |
-| format           | `--format`: `text`, `full` (with source), `json`, `github`, `sarif`, `gitlab`, `junit`, `rdjson`                                                                             | -                                               | -                               | -                                 |
-| statistics       | `--statistics` (counts per code, text format)                                                                                                                                | -                                               | -                               | -                                 |
-| jobs             | `--jobs N` (`-j`; 0: one per CPU)                                                                                                                                            | `jobs`                                          | flake8's own `--jobs`           | pylint's own `--jobs`             |
-| baseline         | `--baseline FILE`; `--write-baseline` records it                                                                                                                             | `baseline`                                      | -                               | -                                 |
-| coverage         | `--coverage`, `--fail-under PCT`                                                                                                                                             | -                                               | -                               | -                                 |
-| per-path levels  | -                                                                                                                                                                            | `per-path-levels`                               | -                               | -                                 |
-| per-file ignores | -                                                                                                                                                                            | `per-file-ignores`                              | flake8's own `per-file-ignores` | -                                 |
-| stdin            | `-` as the path, `--stdin-filename PATH`                                                                                                                                     | -                                               | flake8's own `-`                | -                                 |
-| exit status      | `--exit-zero`                                                                                                                                                                | -                                               | flake8's own `--exit-zero`      | pylint's own `--exit-zero`        |
-| output file      | `--output-file FILE`                                                                                                                                                         | -                                               | flake8's own `--output-file`    | pylint's own `--output`           |
+| Option           | CLI                                                                                                                                                                                                                                                                                                                        | `[tool.constricter]`                            | flake8 (CLI or config)          | pylint                            |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------- | --------------------------------- |
+| level            | `--level`                                                                                                                                                                                                                                                                                                                  | `level`                                         | `--constricter-level`           | `constricter-level`               |
+| strictest        | `--max`: `--level=suffocate` for every path, `--all-scopes`, and the opt-in `LVA012`                                                                                                                                                                                                                                       | —                                               | —                               | —                                 |
+| every fix        | `--max-fix`: `--max`, `--fix --unsafe-fixes`, and `--infer-with` each of basedpyright, ty and pyrefly that's installed and runs                                                                                                                                                                                            | —                                               | —                               | —                                 |
+| type comments    | `--type-comments`                                                                                                                                                                                                                                                                                                          | `type-comments`                                 | `--constricter-type-comments`   | `constricter-type-comments = yes` |
+| all scopes       | `--all-scopes`                                                                                                                                                                                                                                                                                                             | `all-scopes`                                    | `--constricter-all-scopes`      | `constricter-all-scopes = yes`    |
+| nesting          | `--nesting N`                                                                                                                                                                                                                                                                                                              | `nesting`                                       | `--constricter-nesting`         | `constricter-nesting`             |
+| max length       | `--max-length N` (LVA011)                                                                                                                                                                                                                                                                                                  | `max-length`                                    | `--constricter-max-length`      | `constricter-max-length`          |
+| vague            | `--vague LEVEL` (LVA005, and the fixes offered): -1 none (the default), 0 one `Any` inside a type that says the rest (`tuple[str, Any]`), N from 1 N + 1, or one alone                                                                                                                                                     | `vague`                                         | `--constricter-vague`           | `constricter-vague`               |
+| min python       | `--min-python VERSION` (the oldest Python the code runs on, whose syntax `--fix` writes; default: `requires-python`'s)                                                                                                                                                                                                     | `min-python`                                    | -                               | -                                 |
+| type hierarchy   | -                                                                                                                                                                                                                                                                                                                          | `narrower` (a table)                            | `--constricter-narrower`        | `constricter-narrower`            |
+| fix              | `--fix` (`--unsafe-fixes` for guesses, `--likely` for those measured to hold), `--diff` to preview                                                                                                                                                                                                                         | -                                               | -                               | -                                 |
+| infer with       | `--infer-with CHECKERS` (`basedpyright`, `ty`, `pyrefly`, several: inferred types, as guesses)                                                                                                                                                                                                                             | `infer-with`                                    | -                               | -                                 |
+| infer from       | `--infer-from FILE` (the types `python -m constricter.trace -m pytest` recorded from a run, as guesses)                                                                                                                                                                                                                    | `infer-from`                                    | -                               | -                                 |
+| show fixes       | `--show-fixes` (each fix and how it was decided; with `--fix`, those made too)                                                                                                                                                                                                                                             | -                                               | -                               | -                                 |
+| fix levels       | `--fix-select`, `--fix-ignore`, `--unsafe-fix-select` (mechanisms: [docs/FIXES.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/FIXES.md#fix-levels))                                                                                                                                               | `fix-select`, `fix-ignore`, `unsafe-fix-select` | -                               | -                                 |
+| fix plain bases  | `--fix-plain-bases BASES` (frameworks' classes whose subclasses' bodies `--fix` annotates; django's are built in)                                                                                                                                                                                                          | `fix-plain-bases`                               | -                               | -                                 |
+| fix widen        | `--fix-widen KINDS` (wider types `--fix` may write, each marked: `untyped-parameters`, `empty-containers`, `mixed-containers`, `unions`, `vague`, `untyped-calls`, `unknown-calls`; `all`: every one; [docs/FIXES.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/FIXES.md#wider-types-fix-widen)) | `fix-widen`                                     | -                               | -                                 |
+| select           | `--select CODES` (codes or prefixes)                                                                                                                                                                                                                                                                                       | `select`                                        | flake8's own `select`           | pylint's own `enable`             |
+| extend select    | `--extend-select CODES` (also report these; an opt-in code by its full code)                                                                                                                                                                                                                                               | `extend-select`                                 | flake8's own `extend-select`    | pylint's own `enable`             |
+| ignore           | `--ignore CODES`                                                                                                                                                                                                                                                                                                           | `ignore`                                        | flake8's own `extend-ignore`    | pylint's own `disable`            |
+| exclude          | `--exclude GLOB` (repeatable)                                                                                                                                                                                                                                                                                              | `exclude`                                       | flake8's own `exclude`          | pylint's own `ignore-paths`       |
+| format           | `--format`: `text`, `full` (with source), `json`, `github`, `sarif`, `gitlab`, `junit`, `rdjson`                                                                                                                                                                                                                           | -                                               | -                               | -                                 |
+| statistics       | `--statistics` (counts per code, text format)                                                                                                                                                                                                                                                                              | -                                               | -                               | -                                 |
+| jobs             | `--jobs N` (`-j`; 0: one per CPU)                                                                                                                                                                                                                                                                                          | `jobs`                                          | flake8's own `--jobs`           | pylint's own `--jobs`             |
+| baseline         | `--baseline FILE`; `--write-baseline` records it                                                                                                                                                                                                                                                                           | `baseline`                                      | -                               | -                                 |
+| coverage         | `--coverage`, `--fail-under PCT`                                                                                                                                                                                                                                                                                           | -                                               | -                               | -                                 |
+| per-path levels  | -                                                                                                                                                                                                                                                                                                                          | `per-path-levels`                               | -                               | -                                 |
+| per-file ignores | -                                                                                                                                                                                                                                                                                                                          | `per-file-ignores`                              | flake8's own `per-file-ignores` | -                                 |
+| stdin            | `-` as the path, `--stdin-filename PATH`                                                                                                                                                                                                                                                                                   | -                                               | flake8's own `-`                | -                                 |
+| exit status      | `--exit-zero`                                                                                                                                                                                                                                                                                                              | -                                               | flake8's own `--exit-zero`      | pylint's own `--exit-zero`        |
+| output file      | `--output-file FILE`                                                                                                                                                                                                                                                                                                       | -                                               | flake8's own `--output-file`    | pylint's own `--output`           |
 `constricter --explain LVA002` prints a code's rationale, its fix, and the levels that report it.
@@ -210,6 +220,8 @@ type-comments = false
 all-scopes = true
 nesting = 3
 max-length = 4
+vague = -1 # the default: no `Any`; 0 lets `dict[str, Any]` through, 1 `Any` itself
+min-python = "3.11" # the default: your `requires-python`'s lower bound
 jobs = 0
 baseline = "constricter-baseline.json" # the default; relative to this pyproject.toml
@@ -231,12 +243,17 @@ ignore = ["LVA003"]
 `--fix` adds the annotation where the value decides it: a literal (`count = 0` becomes
 `count: int = 0`), a container whose elements agree, a constructor or a function that declares its
-return type (in another checked file too), a copy, subscript, attribute or method call of a local
-whose type is known, and values computed from those; a loop's target or an unpacking's names get a
-declaration on the line before. `--unsafe-fixes` adds guesses, and `--show-fixes` lists each fix and
-how its value decided it. `--infer-with basedpyright` (or `ty`, or `basedpyright,ty`, installed
-alongside) asks those type checkers for what `--fix` can't type itself, as guesses. The full list is
-in [docs/FIXES.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/FIXES.md).
+return type or whose `return`s agree (in another checked file too), a copy, subscript, attribute or
+method call of a local whose type is known, and values computed from those; a loop's target or an
+unpacking's names get a declaration on the line before. `--unsafe-fixes` adds guesses, `--likely`
+only those measured to hold as often as a certain fix
+([docs/LIKELY.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/LIKELY.md)),
+and `--show-fixes` lists each fix and how its value decided it, and after `--fix` each one made.
+`--infer-with basedpyright` (or `ty`, or `pyrefly`, or several: `basedpyright,ty`; each installed
+alongside) asks those type checkers for what `--fix` can't type itself, as guesses;
+`--infer-from FILE` takes the types a run bound each name to, recorded by
+`python -m constricter.trace -m pytest`, the same way. The full list is in
+[docs/FIXES.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/FIXES.md).
 ### Installing and running
@@ -261,7 +278,7 @@ pre-commit, after ruff's hooks (or `constricter-fix`, which runs `--fix` first):
 ```yaml
 - repo: https://github.com/ivylikethevine/python-constricter
-  rev: v0.2.3
+  rev: v0.3.6
   hooks:
     - id: constricter
 ```
@@ -294,8 +311,8 @@ default one is used only if it exists.
 total; the bindings are the ones the rules cover (with `--all-scopes`, module and class bodies too),
 and `# noqa` doesn't make one typed. `--fail-under PCT` (which implies `--coverage`) exits 1 below
 PCT, so CI can hold a codebase to a share. With `--format=json` it prints
-`{"typed", "total", "percent", "files"}`, which a badge can read: publish that JSON somewhere (a
-gist, a release asset) and point
+`{"typed", "total", "widened", "percent", "files"}`, which a badge can read: publish that JSON
+somewhere (a gist, a release asset) and point
 [shields.io's dynamic JSON badge](https://shields.io/badges/dynamic-json-badge) at it with the query
 `$.percent`. This project keeps its own share at 100% in CI, so its badge is static.
@@ -375,4 +392,3 @@ I have used generative AI to write large parts of this code. All of the code her
 _responsibility_ regardless: AI is a tool, not an owner of a project. I have personally understood,
 reviewed, and approved all of the AI-generated code in this repository, and **mainline releases**
 carry the same accountability to me as anything I write and publish myself.

{python_constricter-0.2.5 → python_constricter-0.3.6}/README.md RENAMED Viewed

@@ -70,7 +70,7 @@ class bodies too. Statements are read in source order, and only a name's first b
 | `LVA002` | an untyped `for` target or `match` capture                                                | `name: T` first (or a type comment)            |
 | `LVA003` | a `for` target typed only by `# type: T`                                                  | `name: T` first                                |
 | `LVA004` | with `all-scopes`: the same as `LVA001`, in a module or class body                        | `name: T = ...` (`ClassVar[T]` in a dataclass) |
-| `LVA005` | an annotation with `Any`, `object` or a generic without its parameters                    | name the real type                             |
+| `LVA005` | an annotation with `Any`, `object` or a generic without its parameters, past `vague`      | name the real type                             |
 | `LVA006` | an annotation nested `nesting` deep (3 by default)                                        | a `type` alias for a part of it                |
 | `LVA007` | a name annotated again with the type it already has, in the same block                    | drop the second annotation                     |
 | `LVA008` | with every value the name ever holds known: an annotation that could narrow to them       | narrow it (`total: int`)                       |
@@ -82,7 +82,10 @@ class bodies too. Statements are read in source order, and only a name's first b
 Exempt: comprehensions, `except ... as`, imports, `def`/`class`, `type` aliases, parameters,
 `global`/`nonlocal`, and `_`; in module and class bodies, dunder names (`__all__`, `__slots__`) and
 enum members (a base imported from `enum`, however it's aliased, or else whose name ends in `Enum`
-or `Flag`).
+or `Flag`). And what makes a type, not a value, which an annotation would turn into a variable to a
+type checker: `T = TypeVar("T")`, a `ParamSpec`, a `TypeVarTuple`, a `NewType`, and a functional
+`NamedTuple`, `TypedDict`, `Enum` or `collections.namedtuple`, however `typing`,
+`typing_extensions`, `enum` or `collections` is imported.
 A `# type:` comment (`x = 1  # type: int`, `with f() as x:  # type: T`) counts as an annotation with
 `type-comments`, or automatically in a module written to run on Python 2: one that imports
@@ -143,32 +146,39 @@ enabled).
 Options:
-| Option           | CLI                                                                                                                                                                          | `[tool.constricter]`                            | flake8 (CLI or config)          | pylint                            |
-| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------- | --------------------------------- |
-| level            | `--level`                                                                                                                                                                    | `level`                                         | `--constricter-level`           | `constricter-level`               |
-| type comments    | `--type-comments`                                                                                                                                                            | `type-comments`                                 | `--constricter-type-comments`   | `constricter-type-comments = yes` |
-| all scopes       | `--all-scopes`                                                                                                                                                               | `all-scopes`                                    | `--constricter-all-scopes`      | `constricter-all-scopes = yes`    |
-| nesting          | `--nesting N`                                                                                                                                                                | `nesting`                                       | `--constricter-nesting`         | `constricter-nesting`             |
-| max length       | `--max-length N` (LVA011)                                                                                                                                                    | `max-length`                                    | `--constricter-max-length`      | `constricter-max-length`          |
-| type hierarchy   | -                                                                                                                                                                            | `narrower` (a table)                            | `--constricter-narrower`        | `constricter-narrower`            |
-| fix              | `--fix` (`--unsafe-fixes` for guesses), `--diff` to preview                                                                                                                  | -                                               | -                               | -                                 |
-| infer with       | `--infer-with CHECKERS` (`basedpyright`, `ty`, both: inferred types, as guesses)                                                                                             | `infer-with`                                    | -                               | -                                 |
-| show fixes       | `--show-fixes` (each fix and how it was decided, text)                                                                                                                       | -                                               | -                               | -                                 |
-| fix levels       | `--fix-select`, `--fix-ignore`, `--unsafe-fix-select` (mechanisms: [docs/FIXES.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/FIXES.md#fix-levels)) | `fix-select`, `fix-ignore`, `unsafe-fix-select` | -                               | -                                 |
-| select           | `--select CODES` (codes or prefixes)                                                                                                                                         | `select`                                        | flake8's own `select`           | pylint's own `enable`             |
-| extend select    | `--extend-select CODES` (also report these; an opt-in code by its full code)                                                                                                 | `extend-select`                                 | flake8's own `extend-select`    | pylint's own `enable`             |
-| ignore           | `--ignore CODES`                                                                                                                                                             | `ignore`                                        | flake8's own `extend-ignore`    | pylint's own `disable`            |
-| exclude          | `--exclude GLOB` (repeatable)                                                                                                                                                | `exclude`                                       | flake8's own `exclude`          | pylint's own `ignore-paths`       |
-| format           | `--format`: `text`, `full` (with source), `json`, `github`, `sarif`, `gitlab`, `junit`, `rdjson`                                                                             | -                                               | -                               | -                                 |
-| statistics       | `--statistics` (counts per code, text format)                                                                                                                                | -                                               | -                               | -                                 |
-| jobs             | `--jobs N` (`-j`; 0: one per CPU)                                                                                                                                            | `jobs`                                          | flake8's own `--jobs`           | pylint's own `--jobs`             |
-| baseline         | `--baseline FILE`; `--write-baseline` records it                                                                                                                             | `baseline`                                      | -                               | -                                 |
-| coverage         | `--coverage`, `--fail-under PCT`                                                                                                                                             | -                                               | -                               | -                                 |
-| per-path levels  | -                                                                                                                                                                            | `per-path-levels`                               | -                               | -                                 |
-| per-file ignores | -                                                                                                                                                                            | `per-file-ignores`                              | flake8's own `per-file-ignores` | -                                 |
-| stdin            | `-` as the path, `--stdin-filename PATH`                                                                                                                                     | -                                               | flake8's own `-`                | -                                 |
-| exit status      | `--exit-zero`                                                                                                                                                                | -                                               | flake8's own `--exit-zero`      | pylint's own `--exit-zero`        |
-| output file      | `--output-file FILE`                                                                                                                                                         | -                                               | flake8's own `--output-file`    | pylint's own `--output`           |
+| Option           | CLI                                                                                                                                                                                                                                                                                                                        | `[tool.constricter]`                            | flake8 (CLI or config)          | pylint                            |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------- | --------------------------------- |
+| level            | `--level`                                                                                                                                                                                                                                                                                                                  | `level`                                         | `--constricter-level`           | `constricter-level`               |
+| strictest        | `--max`: `--level=suffocate` for every path, `--all-scopes`, and the opt-in `LVA012`                                                                                                                                                                                                                                       | —                                               | —                               | —                                 |
+| every fix        | `--max-fix`: `--max`, `--fix --unsafe-fixes`, and `--infer-with` each of basedpyright, ty and pyrefly that's installed and runs                                                                                                                                                                                            | —                                               | —                               | —                                 |
+| type comments    | `--type-comments`                                                                                                                                                                                                                                                                                                          | `type-comments`                                 | `--constricter-type-comments`   | `constricter-type-comments = yes` |
+| all scopes       | `--all-scopes`                                                                                                                                                                                                                                                                                                             | `all-scopes`                                    | `--constricter-all-scopes`      | `constricter-all-scopes = yes`    |
+| nesting          | `--nesting N`                                                                                                                                                                                                                                                                                                              | `nesting`                                       | `--constricter-nesting`         | `constricter-nesting`             |
+| max length       | `--max-length N` (LVA011)                                                                                                                                                                                                                                                                                                  | `max-length`                                    | `--constricter-max-length`      | `constricter-max-length`          |
+| vague            | `--vague LEVEL` (LVA005, and the fixes offered): -1 none (the default), 0 one `Any` inside a type that says the rest (`tuple[str, Any]`), N from 1 N + 1, or one alone                                                                                                                                                     | `vague`                                         | `--constricter-vague`           | `constricter-vague`               |
+| min python       | `--min-python VERSION` (the oldest Python the code runs on, whose syntax `--fix` writes; default: `requires-python`'s)                                                                                                                                                                                                     | `min-python`                                    | -                               | -                                 |
+| type hierarchy   | -                                                                                                                                                                                                                                                                                                                          | `narrower` (a table)                            | `--constricter-narrower`        | `constricter-narrower`            |
+| fix              | `--fix` (`--unsafe-fixes` for guesses, `--likely` for those measured to hold), `--diff` to preview                                                                                                                                                                                                                         | -                                               | -                               | -                                 |
+| infer with       | `--infer-with CHECKERS` (`basedpyright`, `ty`, `pyrefly`, several: inferred types, as guesses)                                                                                                                                                                                                                             | `infer-with`                                    | -                               | -                                 |
+| infer from       | `--infer-from FILE` (the types `python -m constricter.trace -m pytest` recorded from a run, as guesses)                                                                                                                                                                                                                    | `infer-from`                                    | -                               | -                                 |
+| show fixes       | `--show-fixes` (each fix and how it was decided; with `--fix`, those made too)                                                                                                                                                                                                                                             | -                                               | -                               | -                                 |
+| fix levels       | `--fix-select`, `--fix-ignore`, `--unsafe-fix-select` (mechanisms: [docs/FIXES.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/FIXES.md#fix-levels))                                                                                                                                               | `fix-select`, `fix-ignore`, `unsafe-fix-select` | -                               | -                                 |
+| fix plain bases  | `--fix-plain-bases BASES` (frameworks' classes whose subclasses' bodies `--fix` annotates; django's are built in)                                                                                                                                                                                                          | `fix-plain-bases`                               | -                               | -                                 |
+| fix widen        | `--fix-widen KINDS` (wider types `--fix` may write, each marked: `untyped-parameters`, `empty-containers`, `mixed-containers`, `unions`, `vague`, `untyped-calls`, `unknown-calls`; `all`: every one; [docs/FIXES.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/FIXES.md#wider-types-fix-widen)) | `fix-widen`                                     | -                               | -                                 |
+| select           | `--select CODES` (codes or prefixes)                                                                                                                                                                                                                                                                                       | `select`                                        | flake8's own `select`           | pylint's own `enable`             |
+| extend select    | `--extend-select CODES` (also report these; an opt-in code by its full code)                                                                                                                                                                                                                                               | `extend-select`                                 | flake8's own `extend-select`    | pylint's own `enable`             |
+| ignore           | `--ignore CODES`                                                                                                                                                                                                                                                                                                           | `ignore`                                        | flake8's own `extend-ignore`    | pylint's own `disable`            |
+| exclude          | `--exclude GLOB` (repeatable)                                                                                                                                                                                                                                                                                              | `exclude`                                       | flake8's own `exclude`          | pylint's own `ignore-paths`       |
+| format           | `--format`: `text`, `full` (with source), `json`, `github`, `sarif`, `gitlab`, `junit`, `rdjson`                                                                                                                                                                                                                           | -                                               | -                               | -                                 |
+| statistics       | `--statistics` (counts per code, text format)                                                                                                                                                                                                                                                                              | -                                               | -                               | -                                 |
+| jobs             | `--jobs N` (`-j`; 0: one per CPU)                                                                                                                                                                                                                                                                                          | `jobs`                                          | flake8's own `--jobs`           | pylint's own `--jobs`             |
+| baseline         | `--baseline FILE`; `--write-baseline` records it                                                                                                                                                                                                                                                                           | `baseline`                                      | -                               | -                                 |
+| coverage         | `--coverage`, `--fail-under PCT`                                                                                                                                                                                                                                                                                           | -                                               | -                               | -                                 |
+| per-path levels  | -                                                                                                                                                                                                                                                                                                                          | `per-path-levels`                               | -                               | -                                 |
+| per-file ignores | -                                                                                                                                                                                                                                                                                                                          | `per-file-ignores`                              | flake8's own `per-file-ignores` | -                                 |
+| stdin            | `-` as the path, `--stdin-filename PATH`                                                                                                                                                                                                                                                                                   | -                                               | flake8's own `-`                | -                                 |
+| exit status      | `--exit-zero`                                                                                                                                                                                                                                                                                                              | -                                               | flake8's own `--exit-zero`      | pylint's own `--exit-zero`        |
+| output file      | `--output-file FILE`                                                                                                                                                                                                                                                                                                       | -                                               | flake8's own `--output-file`    | pylint's own `--output`           |
 `constricter --explain LVA002` prints a code's rationale, its fix, and the levels that report it.
@@ -183,6 +193,8 @@ type-comments = false
 all-scopes = true
 nesting = 3
 max-length = 4
+vague = -1 # the default: no `Any`; 0 lets `dict[str, Any]` through, 1 `Any` itself
+min-python = "3.11" # the default: your `requires-python`'s lower bound
 jobs = 0
 baseline = "constricter-baseline.json" # the default; relative to this pyproject.toml
@@ -204,12 +216,17 @@ ignore = ["LVA003"]
 `--fix` adds the annotation where the value decides it: a literal (`count = 0` becomes
 `count: int = 0`), a container whose elements agree, a constructor or a function that declares its
-return type (in another checked file too), a copy, subscript, attribute or method call of a local
-whose type is known, and values computed from those; a loop's target or an unpacking's names get a
-declaration on the line before. `--unsafe-fixes` adds guesses, and `--show-fixes` lists each fix and
-how its value decided it. `--infer-with basedpyright` (or `ty`, or `basedpyright,ty`, installed
-alongside) asks those type checkers for what `--fix` can't type itself, as guesses. The full list is
-in [docs/FIXES.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/FIXES.md).
+return type or whose `return`s agree (in another checked file too), a copy, subscript, attribute or
+method call of a local whose type is known, and values computed from those; a loop's target or an
+unpacking's names get a declaration on the line before. `--unsafe-fixes` adds guesses, `--likely`
+only those measured to hold as often as a certain fix
+([docs/LIKELY.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/LIKELY.md)),
+and `--show-fixes` lists each fix and how its value decided it, and after `--fix` each one made.
+`--infer-with basedpyright` (or `ty`, or `pyrefly`, or several: `basedpyright,ty`; each installed
+alongside) asks those type checkers for what `--fix` can't type itself, as guesses;
+`--infer-from FILE` takes the types a run bound each name to, recorded by
+`python -m constricter.trace -m pytest`, the same way. The full list is in
+[docs/FIXES.md](https://github.com/ivylikethevine/python-constricter/blob/main/docs/FIXES.md).
 ### Installing and running
@@ -234,7 +251,7 @@ pre-commit, after ruff's hooks (or `constricter-fix`, which runs `--fix` first):
 ```yaml
 - repo: https://github.com/ivylikethevine/python-constricter
-  rev: v0.2.3
+  rev: v0.3.6
   hooks:
     - id: constricter
 ```
@@ -267,8 +284,8 @@ default one is used only if it exists.
 total; the bindings are the ones the rules cover (with `--all-scopes`, module and class bodies too),
 and `# noqa` doesn't make one typed. `--fail-under PCT` (which implies `--coverage`) exits 1 below
 PCT, so CI can hold a codebase to a share. With `--format=json` it prints
-`{"typed", "total", "percent", "files"}`, which a badge can read: publish that JSON somewhere (a
-gist, a release asset) and point
+`{"typed", "total", "widened", "percent", "files"}`, which a badge can read: publish that JSON
+somewhere (a gist, a release asset) and point
 [shields.io's dynamic JSON badge](https://shields.io/badges/dynamic-json-badge) at it with the query
 `$.percent`. This project keeps its own share at 100% in CI, so its badge is static.

{python_constricter-0.2.5 → python_constricter-0.3.6}/constricter/__init__.py RENAMED Viewed

@@ -25,7 +25,7 @@ from constricter.offences import (
 )
 from constricter.rules.checker import Coverage, annotation_coverage, check_source, check_tree
-__version__ = "0.2.5"
+__version__ = "0.3.6"
 __all__ = [
     "COMMENT_TYPED_TARGET",
     "DEFAULT_CHECKS",

python_constricter-0.3.6/constricter/__main__.py ADDED Viewed

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: MIT
+"""`python -m constricter`, and the `constricter` script."""
+import contextlib
+import os
+import sys
+from constricter.cli.command import main
+def run() -> None:
+    """Run the command, and leave with its status at once.
+    Not by the interpreter's own exit, which frees every parsed file and the index an object at a
+    time: a fifth of a check of a thousand files. What the command wrote is flushed first; nothing
+    else waits on the exit (its workers have ended, its output file is closed).
+    """
+    status: int = main()
+    with contextlib.suppress(OSError, ValueError):  # a reader that left, a stream closed already
+        _ = sys.stdout.flush()
+        _ = sys.stderr.flush()
+    os._exit(status)
+if __name__ == "__main__":  # not when `--jobs` workers import it
+    run()

python_constricter-0.3.6/constricter/cli/collecting.py ADDED Viewed

@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: MIT
+"""The garbage collector, as the command runs it: by hand, once per file checked.
+A check keeps every file's tree (see `parsed`), and allocates a great deal for each file, little of it
+cyclic. Left to itself, the collector looked through the kept trees again and again as the check
+allocated: a third of the standard library's check (34s, 21s without). So while the command runs,
+it's off: what indexing built is frozen (never looked through again), and after each file, only
+what's been allocated since (the young generations) is collected, which bounds what a cycle can hold.
+"""
+import contextlib
+import gc
+from collections.abc import Generator
+from typing import Final
+_YOUNG: Final = 1  # the generations collected after each file: 0 and 1, never the frozen or the old
+_FREEZES: Final = hasattr(gc, "freeze")  # PyPy's collector has no freezing
+@contextlib.contextmanager
+def by_hand() -> Generator[None]:
+    """Turn automatic collection off for the command's run, and back as it was after.
+    Yields:
+      Nothing: the run.
+    """
+    was: bool = gc.isenabled()
+    gc.disable()
+    try:
+        yield
+    finally:
+        if _FREEZES:
+            gc.unfreeze()
+        if was:
+            gc.enable()
+def indexed() -> None:
+    """Freeze what indexing built (the kept trees, the index): it lives until the check takes it."""
+    if _FREEZES:
+        gc.freeze()
+def sweep() -> None:
+    """Collect what the file just checked left behind (see the module docstring)."""
+    _ = gc.collect(_YOUNG)

python-constricter 0.2.5__tar.gz → 0.3.6__tar.gz

python-constricter 0.2.5tar.gz → 0.3.6tar.gz