python-constricter 0.2.9__tar.gz → 0.3.1__tar.gz

python_constricter-0.3.1/.gitignore

@@ -0,0 +1,21 @@
+# 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/
+
+# Backups merge tools leave next to a conflicted file.
+*.orig

{python_constricter-0.2.9 → python_constricter-0.3.1}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: python-constricter
-Version: 0.2.9
+Version: 0.3.1
+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
 
@@ -264,7 +264,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.9
+  rev: v0.3.1
   hooks:
     - id: constricter
 ```
@@ -378,4 +378,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.9 → python_constricter-0.3.1}/README.md

@@ -237,7 +237,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.9
+  rev: v0.3.1
   hooks:
     - id: constricter
 ```

{python_constricter-0.2.9 → python_constricter-0.3.1}/constricter/__init__.py

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

{python_constricter-0.2.9 → python_constricter-0.3.1}/constricter/fix/overloads.py

@@ -2,7 +2,7 @@
 """Standard-library calls whose arguments decide their type: the signatures a call may match.
 
 `tables/overloads.json` holds each such function's signatures, in order, as each platform and Python
-version reads them (see `tests/typeshed/overloads.py`): every parameter's kind, whether it has a
+version reads them (see `stdlib_tables/overloads.py`): every parameter's kind, whether it has a
 default, and which argument types (`SCALARS`) it certainly takes or refuses; and the return, as a
 template naming classes by their dotted paths and type variables by their names.
 
@@ -31,6 +31,7 @@ from constricter.fix.signatures import (
     Constant,
     Parameter,
     ReadSignature,
+    Variant,
 )
 from constricter.rules.walked import walk
 
@@ -308,7 +309,7 @@ def _signatures(name: str) -> tuple[tuple[ReadSignature, ...], ...]:
       Each variant's signatures.
 
     """
-    variants: list[stdlib.Variant] = stdlib.OVERLOADS.get(name) or stdlib.method_signatures()[name]
+    variants: list[Variant] = stdlib.OVERLOADS.get(name) or stdlib.method_signatures()[name]
     return tuple(
         tuple(
             ReadSignature(

{python_constricter-0.2.9 → python_constricter-0.3.1}/constricter/fix/signatures.py

@@ -1,12 +1,13 @@
 # SPDX-License-Identifier: MIT
 """The signatures `--fix` matches a call against: the standard library's tables', and installed packages'.
 
-What each parameter takes (`Accepts`) and the signature it's in (`ReadSignature`); see
-`constricter.fix.overloads`, which matches them, `constricter.fix.stdlib`, whose tables hold them,
-and `constricter.fix.stubbed`, which reads an installed package's.
+What each parameter takes (`Accepts`), and a signature as the tables hold it (`Signature`) and as
+it's matched (`ReadSignature`); see `constricter.fix.overloads`, which matches them,
+`constricter.fix.stdlib`, whose tables hold them, and `constricter.fix.stubbed`, which reads an
+installed package's.
 """
 
-from typing import Final, NamedTuple, Required, TypeAlias, TypedDict
+from typing import Final, NamedTuple, NotRequired, Required, TypeAlias, TypedDict
 
 # `Accepts`' keys for an installed package's parameter (see `constricter.fix.stubbed`): a class passed
 # as the argument, and a builtin container.
@@ -58,6 +59,22 @@ class Accepts(TypedDict, total=False):
 Parameter: TypeAlias = tuple[str, str, bool, Accepts | None]
 
 
+class Signature(TypedDict):
+    """One signature of a function whose arguments decide its type: its parameters, and its return.
+
+    The return is a template (see `constricter.fix.overloads`), or `None` if `--fix` can't write it.
+    `self`: for a generic class's method declaring its instance's type (`self: Pattern[str]`), the
+    type arguments that instance must have.
+    """
+
+    params: list[Parameter | str]
+    returns: str | None
+    self: NotRequired[list[str]]
+
+
+Variant: TypeAlias = list[Signature]  # one configuration's signatures, in order
+
+
 class ReadSignature(NamedTuple):
     """One signature, read: its parameters in full, its return template, and its `self`'s type arguments."""
 

{python_constricter-0.2.9 → python_constricter-0.3.1}/constricter/fix/stdlib.py

@@ -1,8 +1,8 @@
 # SPDX-License-Identifier: MIT
 """Standard-library functions and classes whose types `--fix` knows, and how a module names them.
 
-The tables are generated from typeshed's stubs into `tables/`, one JSON file each (see
-`tests/typeshed/stdlib_tables.py`): `RETURNS` holds functions returning the same builtin type
+The tables are generated from typeshed's stubs into `tables/` when the package is built, one JSON
+file each (see `stdlib_tables/generate.py`): `RETURNS` holds functions returning the same builtin type
 whatever their arguments; `OVERLOADS` those whose arguments decide it (`str` in, `str` out;
 `bytes` in, `bytes` out), so they're typed only when those are known; `CLASSES` holds
 non-generic classes, and functions returning one; `library_member` types those classes' methods
@@ -18,29 +18,13 @@ from collections.abc import Iterable, Mapping
 from functools import cache, lru_cache
 from pathlib import Path
 from types import MappingProxyType
-from typing import Final, NamedTuple, NotRequired, TypeAlias, TypedDict, cast
+from typing import Final, NamedTuple, TypeAlias, cast
 
 from constricter.fix.known import ImportPlan, Inference, Known
-from constricter.fix.signatures import Parameter
+from constricter.fix.signatures import Variant
 from constricter.rules.syntax import import_bindings
 
 
-class Signature(TypedDict):
-    """One signature of a function whose arguments decide its type: its parameters, and its return.
-
-    The return is a template (see `constricter.fix.overloads`), or `None` if `--fix` can't write it.
-    `self`: for a generic class's method declaring its instance's type (`self: Pattern[str]`), the
-    type arguments that instance must have.
-    """
-
-    params: list[Parameter | str]
-    returns: str | None
-    self: NotRequired[list[str]]
-
-
-Variant: TypeAlias = list[Signature]  # one configuration's signatures, in order
-
-
 def _table(name: str) -> object:
     """Read one of the tables (`tables/<name>.json`), plain JSON as generated.
 

python_constricter-0.3.1/constricter/fix/tables/source.json

@@ -0,0 +1,22 @@
+{
+"basedpyright": "1.40.1",
+"digest": "4ccf811c7737d0379e2ccbd9a361889ae27ea04c1cc4ee0450f31ea3e2ef44ae",
+"tables": [
+"aliases",
+"attributes",
+"bases",
+"classes",
+"generic_attributes",
+"method_overloads",
+"method_signatures",
+"methods",
+"overloads",
+"returns",
+"scalar_members",
+"scalars",
+"subscriptable",
+"type_parameters",
+"variables"
+],
+"typeshed": "289e5d3568961c8bcd33d01eef5b7ec5e1ad33ad"
+}

python_constricter-0.3.1/hatch_build.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: MIT
+"""Hatchling's build hook: generate the standard-library tables where they're missing or stale.
+
+They aren't tracked (see `stdlib_tables.generate`). A build from a checkout generates them, and asks
+for the basedpyright version `uv.lock` pins to read typeshed's stubs from; one from an sdist, which
+carries them, asks for nothing.
+"""
+
+import importlib
+import sys
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Protocol, cast
+
+from hatchling.builders.config import BuilderConfig
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+if TYPE_CHECKING:
+    from typing_extensions import override  # `typing.override` is 3.12+
+else:
+
+    def override(func: object) -> object:
+        """Mark an override (for type checkers only).
+
+        Returns:
+          `func`.
+
+        """
+        return func
+
+
+class _Generator(Protocol):  # pylint: disable=too-few-public-methods  # a module's functions
+    """What the hook uses of `stdlib_tables.generate`."""
+
+    STUBS: str
+    current: Callable[[], bool]  # whether the tables are all there, and current
+    pinned: Callable[[], str]  # the basedpyright version the tables are read from
+    ensure: Callable[[], bool]  # generate the tables if they're missing or stale
+
+
+def _typed(generator: object) -> _Generator:
+    """Type the generator's module by what the hook uses of it.
+
+    Returns:
+      It.
+
+    """
+    return cast("_Generator", generator)
+
+
+class TablesHook(BuildHookInterface[BuilderConfig]):
+    """Generate the tables before a build, and ask for basedpyright only when it must."""
+
+    def _generator(self) -> _Generator:
+        """Import `stdlib_tables.generate` from the project being built.
+
+        Returns:
+          It.
+
+        """
+        if self.root not in sys.path:
+            sys.path.insert(0, self.root)
+        return _typed(importlib.import_module("stdlib_tables.generate"))
+
+    @override
+    def dependencies(self) -> list[str]:
+        """Ask for the pinned basedpyright, if the tables must be generated.
+
+        Returns:
+          It, or nothing.
+
+        """
+        generator: _Generator = self._generator()
+        return [] if generator.current() else [f"{generator.STUBS}=={generator.pinned()}"]
+
+    @override
+    def initialize(self, version: str, build_data: dict[str, object]) -> None:
+        """Generate the tables, if they're missing or stale."""
+        _ = self._generator().ensure()

{python_constricter-0.2.9 → python_constricter-0.3.1}/pyproject.toml

@@ -7,6 +7,7 @@ license = "MIT"
 license-files = ["LICENSE.md"]
 authors = [{ name = "Ivy Duggan" }]
 requires-python = ">=3.11"
+import-names = ["constricter"]
 dependencies = []
 classifiers = [
     "Framework :: Flake8",
@@ -29,11 +30,19 @@ pylint = ["pylint>=3"]
 
 [dependency-groups]
 # Locked with hashes in uv.lock (see README, Development).
+# What an editable install needs, with no build isolation: the build backend (and what it asks for
+# an editable one), and the basedpyright whose typeshed stubs the standard-library tables are
+# generated from (see hatch_build.py).
+build = [
+    "basedpyright",
+    "editables",
+    "hatchling>=1.27,<2",
+]
 # What the tests need: pure Python, so it installs on PyPy and free-threaded builds too.
 test = [
+    { include-group = "build" },
     "fastjsonschema", # validates the SARIF output against its schema
     "flake8>=7",
-    "flit_core>=4.1,<5",
     "hypothesis",
     "pylint>=3",
     "pytest",
@@ -44,8 +53,8 @@ test = [
 # runtime-validation library and a data library, each a different style of real-world Python.
 # Pure Python 2 code (Twisted 12.3.0) can't be installed on 3.11+: tests/corpus/corpus_sources.py fetches it.
 corpus = [
+    { include-group = "build" }, # for the setup action's editable `-e .` install
     "django==5.2.17", # 6.x needs Python 3.12+; 5.2 is the current LTS and still supports 3.11
-    "flit_core>=4.1,<5", # build backend, needed for the setup action's editable `-e .` install
     "pandas==3.0.6", # a large, partly annotated data library: overloads, generics, TYPE_CHECKING imports
     "pydantic==2.13.5",
     "sqlalchemy==2.0.54",
@@ -73,11 +82,25 @@ constricter = "constricter.cli.command:main"
 LVA = "constricter.plugins.flake8:ConstricterChecker"
 
 [build-system]
-requires = ["flit_core>=4.1,<5"]
-build-backend = "flit_core.buildapi"
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "constricter/__init__.py"
+
+[tool.hatch.build]
+# Generated where they're missing or stale (hatch_build.py), not tracked. `partial.json` is the tests',
+# in the sdist only: a wheel built from it counts the tables current only with it there.
+artifacts = ["constricter/fix/tables/*.json", "stdlib_tables/partial.json"]
+
+[tool.hatch.build.hooks.custom]
+
+[tool.hatch.build.targets.wheel]
+packages = ["constricter"]
 
-[tool.flit.module]
-name = "constricter"
+[tool.hatch.build.targets.sdist]
+# The generator too: a wheel built from the sdist checks the tables it carries are current.
+only-include = ["constricter", "stdlib_tables", "hatch_build.py", "README.md", "LICENSE.md"]
 
 [tool.constricter]
 # Drafts for other projects (Trunk, conda-forge); Trunk's `basic.in.py` is untyped on purpose. The
@@ -116,6 +139,10 @@ notice-rgx = "SPDX-License-Identifier: MIT"
 # `--infer-with`'s tests start its guard and a fake server, and a constricter to kill.
 "tests/cli/test_hints.py" = ["assert", "suspicious-subprocess-import", "subprocess-without-shell-equals-true"]
 "tests/corpus/corpus_suite.py" = ["suspicious-subprocess-import", "subprocess-without-shell-equals-true", "start-process-with-partial-path"]
+# Hatchling's build hook interface: generating the tables needs neither the version nor the build data.
+"hatch_build.py" = ["unused-method-argument"]
+# The generator imports `constricter`'s modules without its `__init__`: its tests import it apart.
+"tests/fix/test_stdlib_tables.py" = ["assert", "suspicious-subprocess-import", "subprocess-without-shell-equals-true"]
 # The census of what `--fix` can't type runs this checkout's constricter on each corpus.
 "tests/corpus/corpus_untyped.py" = ["suspicious-subprocess-import", "subprocess-without-shell-equals-true"]
 # The local CI runner runs the workflow's own steps (and git) as subprocesses.
@@ -126,11 +153,13 @@ notice-rgx = "SPDX-License-Identifier: MIT"
 # `--infer-with` starts the type checker's language server, from a fixed table of commands (and
 # asks it its version, to see it runs).
 "constricter/cli/{hints,guard,protocol}.py" = ["suspicious-subprocess-import", "subprocess-without-shell-equals-true"]
+# The generator's modules import `constricter`'s without its `__init__`, which loads the tables.
+"stdlib_tables/__init__.py" = ["non-empty-init-module"]
 "tests/corpus/corpus_sources.py" = ["suspicious-url-open-usage"] # downloads only its pinned https URLs
 "tests/cli/test_cli.py" = ["suspicious-url-open-usage"] # fetches the SARIF schema from its pinned URL
 
 [tool.mypy]
-files = ["constricter", "tests"]
+files = ["constricter", "stdlib_tables", "tests", "hatch_build.py"]
 python_version = "3.11"
 cache_dir = "local/.mypy_cache"
 strict = true
@@ -219,12 +248,8 @@ module = ["numpy", "numpy.*"]
 follow_imports = "skip"
 follow_imports_for_stubs = true  # numpy ships `.pyi` stubs, which `follow_imports` alone doesn't cover
 
+# What only basedpyright has: pyrightconfig.json, which both it and Pyright read, extends this.
 [tool.basedpyright]
-include = ["constricter", "tests"]
-# The dev venv (see README, Development).
-venvPath = "local"
-venv = ".venv"
-pythonVersion = "3.11"
 typeCheckingMode = "all"
 # astroid (pylint's AST) and fastjsonschema (the SARIF test's validator) ship no annotations.
 allowedUntypedLibraries = ["astroid", "fastjsonschema"]

python_constricter-0.3.1/stdlib_tables/__init__.py

@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: MIT
+"""The generator of `constricter/fix/tables/`, from typeshed's standard-library stubs (see `generate`).
+
+`constricter`'s own `__init__` loads those tables, so unless it's imported already, the modules of it
+the generator uses are imported without it: a checkout has no tables until they're generated.
+"""
+
+import sys
+from pathlib import Path
+from types import ModuleType
+from typing import Final
+
+_NAME: Final = "constricter"
+_PACKAGE: Final = ModuleType(_NAME)
+_PACKAGE.__path__ = [str(Path(__file__).parents[1] / _NAME)]
+_ = sys.modules.setdefault(_NAME, _PACKAGE)

python_constricter-0.3.1/stdlib_tables/__main__.py

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: MIT
+"""Generate the standard-library tables: `python -m stdlib_tables` (see `stdlib_tables.generate`)."""
+
+import sys
+
+from stdlib_tables.generate import main
+
+sys.exit(main(sys.argv[1:]))