python-constricter 0.4.1__cp312-cp312-win32.whl

constricter/fix/core/signatures.py

@@ -0,0 +1,132 @@
+# 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 a signature as the tables hold it (`Signature`) and as
+it's matched (`ReadSignature`); see `constricter.fix.libraries.overloads`, which matches them,
+`constricter.fix.libraries.stdlib`, whose tables hold them, and `constricter.fix.index.stubs.stubbed`,
+which reads an installed package's.
+"""
+
+from typing import Final, NamedTuple, NotRequired, Required, TypeAlias, TypedDict
+
+# `Accepts`' keys for an installed package's parameter (see `constricter.fix.index.stubs.signatures`): a
+# class passed as the argument, and a builtin container.
+# Before a path, an `async def`'s entry for `overloads.chosen`; before a method's name in
+# `method_overloads`, an `async def` method's: its signatures' returns are what awaiting a call gives.
+AWAIT: Final = "await "
+CLASS_VERDICT: Final = "k"
+CLASS_BINDS: Final = "kv"
+CLASS_BOUNDED: Final = "kb"
+CLASS_TUPLE: Final = "kt"
+CONTAINER_VERDICTS: Final = "b"
+ELEMENT_VERDICTS: Final = "be"
+CONTAINER_BINDS: Final = "bc"
+OWN: Final = "own"
+OWN_ELEMENTS: Final = "own_e"
+FUTURE_BINDS: Final = "f"
+
+Constant: TypeAlias = bool | int | float | complex | str | bytes | None  # a literal's value
+
+
+class Accepts(TypedDict, total=False):
+    """Which argument types a parameter takes (see `constricter.fix.libraries.overloads`).
+
+    `v`: a verdict (`y`, `n`, `?`) per `overloads.SCALARS` type, for an argument that isn't a
+    literal; `c`: for a literal not among `lit` (its `Literal[...]` values), where that differs;
+    `var`: the type variable the parameter is, and its type, for an argument of each type; or just
+    its name, where each binds it to its own type (a `str` literal's `str`). `t`: the type variable
+    the parameter is, unbounded, so any argument binds it to its own type (`copy.copy(x)`). `e`, for
+    a parameter that is a generic class of one type variable (`Iterable[_T]`): that variable, which
+    an argument of a builtin container in `of` (`list[str]`) binds to its type argument at that index;
+    `ei`, for one of a generic class of another (`Iterable[Iterable[_S]]`): the container that type
+    argument must be in turn, and the index of its own that binds the variable (`list[list[int]]`).
+    `r`: the type variable a callable parameter returns (`Callable[..., _T]`), which a function
+    argument binds to its declared return (`functools.partial(helper, 1)`). `w`: the type variable
+    an awaitable parameter gives awaited (`Coroutine[Any, Any, _T]`), which a coroutine's call binds
+    to what awaiting it gives (`asyncio.run(main())`). `k`: for an installed
+    package's parameter, a verdict for a class passed as the argument (`dtype=np.float64`), `kv`
+    the type variable it binds to that class (`type[_T]`'s `_T`), `kb` whether that variable
+    is bounded: a builtin class may be outside its bound, and another signature's to take; and `kt`
+    whether a tuple of classes is taken too (`type[_E] | tuple[type[_E], ...]`), which binds the
+    variable to their union. `b`: a
+    verdict per builtin container argument (`tuple`), and `be`, where the parameter says what its
+    elements must be, a verdict per `SCALARS` type for them; `bc`: the bounded type variable a
+    container argument it takes binds. `f`: the type variable the parameter is, bounded by a future
+    (`asyncio.ensure_future`'s `_FT`), which a future or a task binds to its type, and no
+    coroutine's call does.
+    `own`: for a checked file's parameter that takes nothing but checked files' classes, their paths,
+    which an argument's class is matched against by its lineage; `own_e`: those a builtin sequence's
+    or set's elements must be, for one that takes iterables of them (see `index.own_types`).
+    """
+
+    v: Required[str]
+    c: str
+    lit: list[Constant]
+    var: str | dict[str, list[str]]
+    t: str
+    e: str
+    of: dict[str, int]
+    ei: dict[str, int]
+    r: str
+    w: str
+    k: str
+    kv: str
+    kb: bool
+    kt: bool
+    b: dict[str, str]
+    be: dict[str, str]
+    bc: str
+    f: str
+    own: list[str]
+    own_e: list[str]
+
+
+# A parameter: its name, kind (`p` positional, `e` either, `k` keyword, `a` `*args`, `w` `**kwargs`),
+# whether it has a default, and what it takes (`None`: whatever every signature takes there). The
+# tables write one every signature has alike as `"name kind"`, `=` after it if it has a default.
+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.libraries.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. `takes`: for an operator's method (`__add__`), its one
+    operand's type as a template, or `None` if `--fix` can't write it.
+    """
+
+    params: list[Parameter | str]
+    returns: str | None
+    self: NotRequired[list[str]]
+    takes: NotRequired[str | None]
+
+
+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."""
+
+    params: tuple[Parameter, ...]
+    returns: str | None
+    instance: list[str] | None
+    # An installed class's method declaring its `self`: the type its receiver must have, as a pattern
+    # (classes by where they're defined, `typing.Any` for anything, type variables bare), and those
+    # variables' bounds, likewise (see `constricter.fix.index.stubs.signatures`).
+    receiver: str | None = None
+    bounds: tuple[tuple[str, str], ...] = ()
+
+
+class Expansion(NamedTuple):
+    """A public alias of an installed generic class (`npt.NDArray`), as a receiver's type is written.
+
+    `params`: its own type parameters, renamed apart from any a method names (`_alias0`), which the
+    receiver's type arguments bind; `receiver`: what it stands for, as a pattern naming them (see
+    `ReadSignature.receiver`); `templates`: the class's type parameters, each with a template naming
+    them (`np.dtype[_alias0]`), where one can be written.
+    """
+
+    params: tuple[str, ...]
+    receiver: str
+    templates: tuple[tuple[str, str], ...]

constricter/fix/index/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: MIT
+"""What the checked files and installed packages define, for each other: the cross-file index."""

constricter/fix/index/awaits.py

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: MIT
+"""Cross-module `--fix` for `await` of a call to another checked file's `async def`.
+
+Found through the calling file's imports and the re-exports between them (`await load(url)`,
+`await client.load(url)` after `import pkg.client as client`); its declared return types the
+awaited call where the file can write it (see `project.portable`), or else its `return`s do, once
+its file is checked (see `constricter.fix.values.returned`). A method's is its class's (see
+`rules.tables`).
+"""
+
+from pathlib import Path
+
+from constricter.fix.core.known import Guarded, Returns
+from constricter.fix.core.signatures import AWAIT
+from constricter.fix.index import project, sides
+from constricter.fix.index.modules import SUFFIX, Index, Module, module_name
+
+
+def calls(catalog: Index, path: Path, guarded: dict[str, Guarded]) -> dict[str, str]:
+    """Type what awaiting the calls the file at `path` makes to other checked files' `async def`s gives.
+
+    `guarded`: the names its imported types need imported for type checking (see `Guarded`), which
+    these types' are added to.
+
+    Returns:
+      Each call's name as written (`load`, `client.load`), mapped to its type; none for a file
+      `catalog` doesn't have.
+
+    """
+    found: dict[str, str] = {}
+    target: Module | None
+    if path.suffix != SUFFIX or (target := catalog.modules.get(module_name(path))) is None:
+        return found
+    spelled: str
+    defined: tuple[Module, str]
+    for spelled, defined in sides.called(catalog.modules, target, _awaitable):
+        if defined[1] in defined[0].awaits:
+            declared: dict[str, str] = {spelled: defined[0].awaits[defined[1]]}
+            found.update(project.portable(catalog.modules, (target, defined), spelled, declared, guarded))
+    return found
+
+
+def returned(catalog: Index, path: Path, guarded: dict[str, Guarded], found: Returns) -> Returns:
+    """Add what awaiting the file's calls to other checked files' undeclared `async def`s gives to `found`.
+
+    By their `return`s, for modules already checked, each under `AWAIT` before the call's name as
+    written, with what it rests on if it's a guess.
+
+    Returns:
+      `found`, with them; `found` itself for a file `catalog` doesn't have, or one that calls none.
+
+    """
+    awaited: dict[str, str] = {}
+    guesses: dict[str, frozenset[str]] = {}
+    target: Module | None
+    if path.suffix != SUFFIX or (target := catalog.modules.get(module_name(path))) is None:
+        return found
+    spelled: str
+    defined: tuple[Module, str]
+    for spelled, defined in sides.called(catalog.modules, target, _awaitable):
+        key: str
+        if (key := f"{AWAIT}{defined[1]}") not in defined[0].returned.calls:
+            continue
+        typed: dict[str, str] = {spelled: defined[0].returned.calls[key]}
+        kept: dict[str, str]
+        if kept := project.portable(catalog.modules, (target, defined), spelled, typed, guarded):
+            awaited[f"{AWAIT}{spelled}"] = kept[spelled]
+            if key in defined[0].returned.guesses:
+                guesses[f"{AWAIT}{spelled}"] = defined[0].returned.guesses[key]
+    if not awaited:
+        return found
+    return found._replace(calls={**found.calls, **awaited}, guesses={**found.guesses, **guesses})
+
+
+def needs(catalog: Index, module: Module) -> set[str]:
+    """Find the other modules whose `async def`s `module` calls that only their `return`s could type.
+
+    Returns:
+      Their names: checked before it, what awaiting each gives is known.
+
+    """
+    return {
+        defined[0].name
+        for _, defined in sides.called(catalog.modules, module, _awaitable)
+        if defined[1] in defined[0].unawaited
+    } - {module.name}
+
+
+def _awaitable(module: Module, name: str) -> bool:  # whether it defines an `async def` of the name
+    return name in module.awaits or name in module.unawaited

constricter/fix/index/beyond.py

@@ -0,0 +1,149 @@
+# SPDX-License-Identifier: MIT
+"""The standard-library class another checked file's class inherits from, out of a file's sight.
+
+A file's class under another file's (`django.test.TestCase`) can't see what that one inherits from:
+the index can. `library_bases` follows each of a file's classes' bases through the checked files
+and the installed packages, to the standard-library class its lines of bases end at
+(`unittest.TestCase`), with the names the classes on the way bind: any other member is the
+library class's, as `constricter.fix.core.inherited.Lineage.definer` then says. A package that
+declares no types is read for its classes' bases alone (`installed.unseen`). Two lines each ending
+at a library class give both, in order, where they share no ancestor.
+"""
+
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import TYPE_CHECKING, Final
+
+from constricter.fix.core.inherited import SEVERAL, Beyond
+from constricter.fix.index import plain
+from constricter.fix.index.modules import SUFFIX, Index, Module, module_name, takes
+from constricter.fix.index.stubs import installed
+from constricter.fix.libraries import stdlib
+from constricter.fix.values import classvars
+
+if TYPE_CHECKING:
+    from constricter.fix.index.stubs.declared import Class
+
+_DOT: Final = "."
+_OBJECT: Final = "object"
+_DEPTH: Final = 8  # how many classes a line of bases is followed through
+
+
+def library_bases(catalog: Index, path: Path) -> dict[str, Beyond]:
+    """Find where the line of each base of the file at `path`'s classes ends, for one another module defines.
+
+    Returns:
+      Each such base, as the file writes it, with the standard-library class its line of single
+      bases ends at (one the tables hold whole; `""` for a line that ends at none, a mixin's) and
+      the names bound on the way; none for a base whose line has a class of several bases or one
+      out of sight, nor for a file `catalog` doesn't have.
+
+    """
+    target: Module | None
+    if path.suffix != SUFFIX or (target := catalog.modules.get(module_name(path))) is None:
+        return {}
+    written: set[str] = {base for bases in target.bases.values() for base in bases} - {classvars.SPECIAL}
+    ends: dict[str, Beyond | None] = {
+        base: _end(catalog.modules, plain.resolved(catalog.modules, target, base))
+        for base in sorted(written)
+        if base not in target.bases
+    }
+    return {base: end for base, end in ends.items() if end is not None}
+
+
+def _end(modules: Mapping[str, Module], defined: str) -> Beyond | None:
+    """Follow a class another module defines (`defined`: its dotted path) up its bases.
+
+    Returns:
+      The standard-library class it ends at (`""`: none, a class with no base), and the names the
+      classes on the way bind; `None` if `defined` is no indexed module's class, or its line
+      doesn't end.
+
+    """
+    found: Beyond | None = _line(modules, defined, _DEPTH)
+    return None if found is None or (found[0] and not found[1]) else found
+
+
+def _line(modules: Mapping[str, Module], defined: str, depth: int) -> Beyond | None:
+    """Follow a class's bases to where they end: at a library class, any mixins beside it.
+
+    A class of several bases ends where those that reach a library class do, the others (each
+    ending at none) binding what they bind before them. An installed package that declares no
+    types is read for its classes' bases (see `installed.unseen`).
+
+    Returns:
+      The standard-library class (the tables hold whole; `""`: none; several, `SEVERAL` between
+      them) and the names bound on the way; `None` for a base out of sight, two lines reaching
+      library classes that share an ancestor, or one too deep.
+
+    """
+    name: str = defined.rpartition(_DOT)[2]
+    module: Module | None = modules.get(defined.rpartition(_DOT)[0])
+    library: str | None = stdlib.held_whole(defined)
+    if module is None and library is None:
+        module = installed.unseen(defined.rpartition(_DOT)[0])
+    bases: list[str] | None = None if module is None else _bases(module, name)
+    if module is not None and bases is None and depth and takes(module, name):  # a re-export: followed
+        onward: tuple[str, str | None] = module.names[name]
+        return _line(modules, _DOT.join(part for part in onward if part), depth - 1)
+    if module is None or bases is None:
+        return None if library is None else (library, frozenset())
+    hidden: frozenset[str] = module.bound[name] | {name}
+    ends: list[Beyond | None] = [
+        _line(
+            modules,
+            f"{module.name}{_DOT}{base}" if base in module.bound else plain.resolved(modules, module, base),
+            depth - 1,
+        )
+        if depth
+        else None
+        for base in bases
+    ]
+    reached: list[str] = [end[0] for end in ends if end is not None and end[0]]
+    lines: list[frozenset[str]] = [stdlib.lines(path) for each in reached for path in each.split(SEVERAL)]
+    if None in ends or len(frozenset[str]().union(*lines)) != sum(len(line) for line in lines):
+        return None
+    return (SEVERAL.join(reached), hidden.union(*(end[1] for end in ends if end is not None)))
+
+
+def _bases(module: Module, name: str) -> list[str] | None:
+    """List the bases of a class `module` (a checked file's, or an installed package's) defines once.
+
+    Returns:
+      Them as written, `object` left out; `None` if it defines no such class.
+
+    """
+    if name not in module.bound:
+        return None
+    declared: Class | None = None if module.declared is None else module.declared.classes.get(name)
+    written: Sequence[str] = module.bases.get(name, ()) if declared is None else declared.bases
+    return [base for base in written if base not in {classvars.SPECIAL, _OBJECT}]
+
+
+def emptied(catalog: Index, path: Path) -> dict[str, Mapping[str, str]]:
+    """Find the attributes the file at `path`'s classes take bound to an empty container from another file's.
+
+    A base another checked file defines, which binds one so and does no more with it (see
+    `Module.emptied`): what the file's own classes' methods add to it types it for them.
+
+    Returns:
+      Each such class's attributes' kinds, by its name; none for a file `catalog` doesn't have.
+
+    """
+    target: Module | None
+    if path.suffix != SUFFIX or (target := catalog.modules.get(module_name(path))) is None:
+        return {}
+    found: dict[str, Mapping[str, str]] = {}
+    name: str
+    bases: tuple[str, ...]
+    for name, bases in target.bases.items():
+        kinds: dict[str, str] = {}
+        base: str
+        for base in bases:
+            defined: str = "" if base in target.bases else plain.resolved(catalog.modules, target, base)
+            module: Module | None = catalog.modules.get(defined.rpartition(_DOT)[0])
+            if module is not None and not module.installed:
+                kinds.update(module.emptied.get(defined.rpartition(_DOT)[2], {}))
+        if kinds:
+            found[name] = kinds
+    return found

constricter/fix/index/callers.py

@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: MIT
+"""Unannotated parameters typed by their callers: what every call in the checked files passes each one.
+
+Once every file is checked, each module's `Observed` calls to the checked files' open functions (see
+`params.open_functions`) are matched to their parameters, as Python binds them. A parameter left
+unannotated is typed when every call passes it, each an argument of the same known type
+(`rules.calls` says which count); not if a call leaves it to its default, can't be matched, or
+unpacks its arguments, nor if the function escapes (a callback), and never for a function no file
+calls. The files defining them are then checked again knowing those types, as guesses (`callers`):
+a caller outside the checked files may pass anything.
+"""
+
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import replace
+from pathlib import Path
+from typing import Final, TypeAlias
+
+from constricter.fix.core.known import Call, Callee, Observed, Origin, Passed, Seeds
+from constricter.fix.index import project
+from constricter.fix.index.modules import SUFFIX, Index
+from constricter.fix.index.params import Param
+
+KIND: Final = "callers"  # the guessing mechanism (`FIX_KINDS`)
+# A module's functions' typed parameters: each one's type and what it rests on, by name, by function.
+Parameters: TypeAlias = dict[str, dict[str, Passed]]
+_POSITIONAL: Final = frozenset({"p", "e"})
+_KEYWORD: Final = frozenset({"e", "k"})
+_UNPASSED: Final = ""  # a parameter a call leaves to its default
+
+
+def parameters(observations: Iterable[Observed], catalog: Index) -> dict[str, Parameters]:
+    """Type the checked files' functions' unannotated parameters by every call to them (see the docstring).
+
+    Returns:
+      Each typed parameter's type, by its function and module.
+
+    """
+    calls: dict[Callee, list[Call]] = {}
+    escaped: set[Callee] = set()
+    observed: Observed
+    for observed in observations:
+        escaped.update(observed.escaped)
+        callee: Callee
+        found: tuple[Call, ...]
+        for callee, found in observed.calls.items():
+            calls.setdefault(callee, []).extend(found)
+    typed: dict[str, Parameters] = {}
+    each: list[Call]
+    for callee, each in calls.items():
+        module: str
+        function: str
+        module, function = callee
+        params: tuple[Param, ...] | None = (
+            None
+            if callee in escaped or module not in catalog.modules
+            else catalog.modules[module].open.get(function)
+        )
+        types: dict[str, Passed]
+        if types := {} if params is None else _typed(params, each):
+            typed.setdefault(module, {})[function] = types
+    return typed
+
+
+def _typed(params: Sequence[Param], calls: Sequence[Call]) -> dict[str, Passed]:
+    """Type a function's unannotated parameters by `calls`: each one's, if every call passes it the same.
+
+    Returns:
+      Each typed parameter's type, and what its arguments' types rest on together.
+
+    """
+    bound: list[dict[str, Passed | None] | None] = [_bound(params, call) for call in calls]
+    found: dict[str, Passed] = {}
+    param: Param
+    for param in params:
+        name: str = param[0]
+        passed: list[Passed | None] = [
+            None if one is None else one.get(name, (_UNPASSED, frozenset())) for one in bound
+        ]
+        types: set[str | None] = {None if one is None else one[0] for one in passed}
+        only: str | None = types.pop() if len(types) == 1 else None
+        if not param[3] and only:
+            found[name] = (only, frozenset().union(*(one[1] for one in passed if one is not None)))
+    return found
+
+
+def _bound(params: Sequence[Param], call: Call) -> dict[str, Passed | None] | None:
+    """Bind a call's arguments' types to a function's parameters, as Python binds the arguments.
+
+    Returns:
+      Each parameter's argument's type (`None`: unknown), by name, a parameter it leaves to its
+      default missing; or `None` if they can't be bound (unpacked, too many, an unknown keyword, one
+      bound twice): a call that fails, or can't be read.
+
+    """
+    positional: list[str] = [param[0] for param in params if param[1] in _POSITIONAL]
+    if call.unpacked or len(call.positional) > len(positional):
+        return None
+    bound: dict[str, Passed | None] = dict(zip(positional, call.positional, strict=False))
+    keyword: str
+    typed: Passed | None
+    for keyword, typed in call.keywords:
+        if keyword in bound or not any(param[0] == keyword and param[1] in _KEYWORD for param in params):
+            return None
+        bound[keyword] = typed
+    return bound
+
+
+def callees(catalog: project.Index, path: Path) -> dict[str, Callee]:
+    """Find the checked files' functions the file at `path` may call whose parameters aren't all annotated.
+
+    Its own (`f`), and those it imports (`f`, `u.f`, through re-exports); not an installed package's.
+
+    Returns:
+      Each, as the file spells it, mapped to its module and name; nothing for a file `catalog` doesn't
+      have.
+
+    """
+    target: project.Module | None
+    if path.suffix != SUFFIX or (target := catalog.modules.get(project.module_name(path))) is None:
+        return {}
+    found: dict[str, Callee] = {name: (target.name, name) for name in target.open}
+    key: str
+    origin: Origin
+    for key, origin in project.spellings(catalog, target, project.OPEN):
+        defined: tuple[project.Module, str] | None = project.definition(catalog.modules, origin, project.OPEN)
+        if defined is not None and not defined[0].installed:
+            found[key] = (defined[0].name, defined[1])
+    return found
+
+
+def own_parameters(catalog: project.Index, path: Path) -> Seeds:
+    """Find what every call passes the unannotated parameters of the file at `path`'s functions.
+
+    Returns:
+      Each function's parameters' types, by name (see `with_parameters`).
+
+    """
+    target: project.Module | None = (
+        catalog.modules.get(project.module_name(path)) if path.suffix == SUFFIX else None
+    )
+    return {} if target is None else target.parameters
+
+
+def with_parameters(catalog: project.Index, found: Mapping[str, Seeds]) -> project.Index:
+    """Record what every call passes checked modules' functions' unannotated parameters (by module name).
+
+    Returns:
+      The index, with them.
+
+    """
+    modules: dict[str, project.Module] = dict(catalog.modules)
+    name: str
+    for name in found.keys() & modules.keys():
+        modules[name] = replace(modules[name], parameters=found[name])
+    return catalog._replace(modules=modules)