python-constricter 0.4.1__cp313-cp313-win32.whl

constricter/fix/index/stubs/stubbed.py

@@ -0,0 +1,208 @@
+# SPDX-License-Identifier: MIT
+"""Installed packages' functions whose arguments decide their type: their signatures, read for a call.
+
+The functions and methods a file calls, and the classes it passes, found through its imports;
+their stubs' overloads read by `constricter.fix.index.stubs.signatures` into the signatures the
+standard library's tables hold (see `constricter.fix.libraries.overloads`), so a call is matched
+the same way, and kept from one file to the next (`constricter.fix.index.stubs.read`).
+"""
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import TYPE_CHECKING, Final, NamedTuple, TypeAlias, cast
+
+from constricter.fix.core.known import Guarded, Origin
+from constricter.fix.core.signatures import Expansion, ReadSignature
+from constricter.fix.index import own_overloads, project
+from constricter.fix.index.modules import SUFFIX, Index, Module, module_name
+from constricter.fix.index.stubs import chained, classnames
+from constricter.fix.index.stubs.names import call_origin
+from constricter.fix.index.stubs.read import MEMO, Expanded, Memo
+from constricter.fix.index.stubs.signatures import Reader, read_all
+
+if TYPE_CHECKING:
+    from constricter.fix.index.stubs.declared import Class, Declarations, Signature
+
+_KIND: Final = "signatures"
+
+
+_Read: TypeAlias = dict[str, tuple[ReadSignature, ...]]  # functions' signatures, by a call's name
+
+
+def overloaded(catalog: Index, path: Path, guarded: dict[str, Guarded] | None = None) -> _Read:
+    """Find the functions the file at `path` calls whose arguments decide their type.
+
+    An installed package's, and a checked file's defined with `@overload` (see `own_overloads`):
+    `guarded` records the names their returns need imported for type checking.
+
+    Returns:
+      Each one's signatures (one variant, see `overloads.chosen`), by the call's name as written
+      (`np.empty`); none for a file `catalog` doesn't have.
+
+    """
+    modules: dict[str, Module] = catalog.modules
+    target: Module | None
+    if path.suffix != SUFFIX or (target := modules.get(module_name(path))) is None:
+        return {}
+    found: dict[str, tuple[ReadSignature, ...]] = {}
+    memo: dict[tuple[str, str], tuple[ReadSignature, ...]] = MEMO.of(modules).read
+    key: str
+    for key in sorted(target.called):
+        origin: Origin | None = call_origin(modules, target, key)
+        defined: tuple[Module, str] | None
+        if origin is None or (defined := project.definition(modules, origin, _KIND)) is None:
+            continue
+        if not defined[0].installed:
+            # Read each time: what a checked file's parameters take rests on the checked files' classes.
+            read: tuple[ReadSignature, ...] = read_signatures(modules, *defined)
+            found[key] = own_overloads.spelled(catalog, target, defined, read, guarded)
+            continue
+        where: tuple[str, str]
+        if (where := (defined[0].name, defined[1])) not in memo:
+            memo[where] = read_signatures(modules, *defined)
+        found[key] = memo[where]
+    return {key: read for key, read in found.items() if read}
+
+
+def classes(catalog: Index, path: Path) -> frozenset[str]:
+    """Find the installed classes the file at `path` passes as arguments (`dtype=np.float64`).
+
+    A class, or an alias of one (`np.int32 = signedinteger[_32Bit]`), through any re-exports.
+
+    Returns:
+      Each as the file writes it; none for a file `catalog` doesn't have.
+
+    """
+    modules: dict[str, Module] = catalog.modules
+    target: Module | None
+    if path.suffix != SUFFIX or (target := modules.get(module_name(path))) is None:
+        return frozenset()
+    reader: Reader = Reader(modules)
+    return frozenset(name for name in target.passed if reader.is_class(target, name))
+
+
+class Methods(NamedTuple):
+    """Installed classes' methods a file may call whose arguments or instance decide their type.
+
+    `signatures`: each one's, by the class as the file writes it and the method (`np.ndarray.astype`);
+    `parameters`: each such class's type parameters, in order, which a receiver's type binds;
+    `lineage`: each installed class the file names, as it writes it, with where it's defined and its
+    ancestors' (`numpy.float64`, `numpy.floating`, ...), `?` last where a base can't be followed: a
+    receiver's type is matched against a method's `self` by them. `aliases`: each public alias of an
+    installed generic class the file names (`npt.NDArray`), whose methods are its class's; the
+    classes its expansion names are in `lineage` by their paths (`numpy.dtype`).
+    """
+
+    signatures: dict[str, tuple[ReadSignature, ...]]
+    parameters: dict[str, tuple[str, ...]]
+    lineage: dict[str, tuple[str, ...]]
+    aliases: dict[str, Expansion]
+
+
+def methods(catalog: Index, path: Path, guarded: Mapping[str, Guarded] | None = None) -> Methods:
+    """Find the methods the file at `path` calls that an installed class it names declares (see `Methods`).
+
+    Named through its imports, those under `if TYPE_CHECKING:` included, and those its fixes will add
+    there (`guarded`, see `project.Imported`): a return type spelled through one is a receiver's.
+
+    Returns:
+      Them; none for a file `catalog` doesn't have.
+
+    """
+    modules: dict[str, Module] = catalog.modules
+    found: Methods = Methods({}, {}, {}, {})
+    target: Module | None
+    if path.suffix != SUFFIX or (target := modules.get(module_name(path))) is None or not target.method_calls:
+        return found
+    reader: Reader = Reader(modules)
+    memo: Memo = MEMO.of(modules)
+    spelled: str
+    origin: Origin
+    names: dict[str, Origin] = {
+        **{name: found.origin for name, found in (guarded or {}).items()},
+        **target.guarded,
+        **target.names,
+    }
+    names.update(_packages(modules, names))
+    for spelled, origin in classnames.classes(modules, names, memo.packages):
+        _class_methods(found, reader, target, spelled, origin)
+    alias: Origin
+    for spelled, alias in classnames.classes(modules, names, memo.packages, aliases=True):
+        if alias not in memo.expansions:
+            memo.expansions[alias] = reader.expansion(alias)
+        expanded: Expanded | None
+        if (expanded := memo.expansions[alias]) is None:
+            continue
+        paths: tuple[tuple[str, Origin], ...]
+        origin, found.aliases[spelled], paths = expanded
+        _class_methods(found, reader, target, spelled, origin)
+        path_named: str
+        for path_named, origin in paths:
+            found.lineage[path_named] = _lineage(reader, origin)
+    return found
+
+
+def _packages(modules: Mapping[str, Module], names: Mapping[str, Origin]) -> dict[str, Origin]:
+    """Find the installed packages a file takes names of without importing them (`from grids import make`).
+
+    Returns:
+      Each, by its name, where the file binds it to nothing: a fix may import one's alias, which
+      is then a receiver's type, named by its dotted path.
+
+    """
+    tops: set[str] = {origin[0].partition(".")[0] for origin in names.values()} - set(names)
+    return {top: (top, None) for top in tops if top in modules and modules[top].installed}
+
+
+def _lineage(reader: Reader, origin: Origin) -> tuple[str, ...]:
+    """Find an installed class's lineage (see `Methods.lineage`), and the methods it has, once.
+
+    Returns:
+      It.
+
+    """
+    memo: Memo = MEMO.of(reader.modules)
+    if origin not in memo.lines:
+        memo.lines[origin] = tuple(dict.fromkeys(reader.lineage(origin, 0)))
+        memo.names[origin] = classnames.method_names(reader.modules, memo.lines[origin])
+    return memo.lines[origin]
+
+
+def _class_methods(found: Methods, reader: Reader, target: Module, spelled: str, origin: Origin) -> None:
+    """Add an installed class's methods `target` calls, as it writes the class (`spelled`), to `found`."""
+    found.lineage[spelled] = _lineage(reader, origin)
+    memo: Memo = MEMO.of(reader.modules)
+    module: Module = reader.modules[origin[0]]
+    klass: Class = cast("Declarations", module.declared).classes[origin[1] or ""]
+    name: str
+    for name in sorted(memo.names[origin] & target.method_calls):
+        if (origin, name) not in memo.methods:
+            # Its lineage has the method: the class or a base declares it.
+            memo.methods[origin, name] = cast(
+                "tuple[ReadSignature, ...]",
+                reader.method(module, klass, name, 0),
+            )
+        found.signatures[f"{spelled}.{name}"] = memo.methods[origin, name]
+        found.parameters[spelled] = tuple(param for param, _ in klass.params)
+        attr: str
+        each: tuple[Signature, ...]
+        # What it reads of the method's return, off the call (see `chained`).
+        for attr, each in chained.attributes(module, klass, name, target.attributes).items():
+            found.signatures[f"{spelled}.{chained.key(name, attr)}"] = read_all(
+                reader,
+                module,
+                each,
+                frozenset(param for param, _ in klass.params),
+                dict(klass.params),
+            )
+
+
+def read_signatures(modules: Mapping[str, Module], module: Module, name: str) -> tuple[ReadSignature, ...]:
+    """Read an installed function's signatures as the tables hold theirs.
+
+    Returns:
+      Them.
+
+    """
+    # Found by its signatures (`project.definition`): an installed module's, or a checked file's overloads.
+    return read_all(Reader(modules), module, own_overloads.written(module, name), frozenset(), {})

constricter/fix/index/taken.py

@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: MIT
+"""Cross-module `--fix` for an empty container passed to another checked file's function.
+
+Found through the calling file's imports and the re-exports between them (`add(names, "a")`,
+`util.add(names, "a")`); a parameter the function declares a builtin container (`names: list[str]`)
+types what's passed to it, where the file can write that type (see `project.portable`, and
+`constricter.fix.values.fills`).
+"""
+
+from pathlib import Path
+
+from constricter.fix.core.known import Guarded, Takers
+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, Takers]:
+    """Find the parameters the functions the file at `path` calls declare a builtin container.
+
+    `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 (`add`, `util.add`), mapped to those parameters (see `Takers`),
+      each type as the file can write it; none for a file `catalog` doesn't have.
+
+    """
+    target: Module | None = catalog.modules.get(module_name(path)) if path.suffix == SUFFIX else None
+    found: dict[str, Takers] = {}
+    if target is None:
+        return found
+    spelled: str
+    defined: tuple[Module, str]
+    for spelled, defined in sides.called(catalog.modules, target, lambda module, name: name in module.takers):
+        declared: Takers = defined[0].takers[defined[1]]
+        kept: dict[str, str] = project.portable(
+            catalog.modules,
+            (target, defined),
+            spelled,
+            {name: taken[2] for name, taken in declared.items()},
+            guarded,
+        )
+        if kept:
+            found[spelled] = {name: (*declared[name][:2], text) for name, text in kept.items()}
+    return found

constricter/fix/index/tuples.py

@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: MIT
+"""The tuples a file's names stand for, other checked files': a named tuple's fields, an alias's tuple.
+
+What an unpacking splits a value of one of them by (see `targets.named_tuples`), spelled as the file
+can write it; and the unions its names for their aliases stand for (see `targets.aliased_unions`).
+"""
+
+from collections.abc import Callable, Iterator, Mapping
+from pathlib import Path
+
+from constricter.fix.core.known import Guarded, Origin
+from constricter.fix.index.modules import SUFFIX, Index, Module, module_name
+from constricter.fix.index.project import ALIAS, CLASS, definition, portable
+
+
+def fields(catalog: Index, path: Path, guarded: dict[str, Guarded]) -> dict[str, str]:
+    """Find the tuples the file at `path` can name, by how it names them.
+
+    Those the types written for it name, which it needn't import itself (a property's type, a
+    function's return; see `Guarded`), those it imports, and those a module it imports has.
+
+    Returns:
+      Each name, and the tuple unpacking a value of it gives; nothing 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, str] = {}
+    key: str
+    defined: tuple[Module, str]
+    for key, defined in _named(catalog.modules, target, guarded, _tuples):
+        found.update(_fields(catalog.modules, target, key, defined, guarded))
+    return found
+
+
+def unions(catalog: Index, path: Path, guarded: dict[str, Guarded]) -> dict[str, str]:
+    """Find the unions the file at `path` names by other files' type aliases, by how it names them.
+
+    The aliases `fields` would find, were they tuples'.
+
+    Returns:
+      Each name, and the union as its own module writes it: read for its members, never written.
+
+    """
+    target: Module | None
+    if path.suffix != SUFFIX or (target := catalog.modules.get(module_name(path))) is None:
+        return {}
+    return {
+        key: defined[0].unions[defined[1]]
+        for key, defined in _named(catalog.modules, target, guarded, _unions)
+        if defined[1] in defined[0].unions
+    }
+
+
+def _tuples(module: Module) -> Mapping[str, str]:
+    return module.tuples
+
+
+def _unions(module: Module) -> Mapping[str, str]:
+    return module.unions
+
+
+def _named(
+    modules: Mapping[str, Module],
+    target: Module,
+    guarded: Mapping[str, Guarded],
+    held: Callable[[Module], Mapping[str, str]],
+) -> Iterator[tuple[str, tuple[Module, str]]]:
+    """Find the classes and aliases a file (`target`) names, and those of a module it imports that `held` has.
+
+    Yields:
+      Each one's name as the file spells it (`Pair`, or `shapes.Pair` after
+      `import pkg.shapes as shapes`), and where it's defined.
+
+    """
+    named: list[tuple[str, Origin]] = [
+        *((key, each.origin) for key, each in guarded.items()),
+        *target.guarded.items(),  # under `if TYPE_CHECKING:`
+        *((key, origin) for key, origin in target.names.items() if origin[0] != target.name),
+    ]
+    key: str
+    origin: Origin
+    for key, origin in named:
+        defined: tuple[Module, str] | None = definition(modules, origin, CLASS) or definition(
+            modules,
+            origin,
+            ALIAS,
+        )
+        if defined is not None:
+            yield key, defined
+        module: Module | None
+        if origin[1] is None and (module := modules.get(origin[0])) is not None:
+            yield from ((f"{key}.{name}", (module, name)) for name in held(module))
+
+
+def _fields(
+    modules: Mapping[str, Module],
+    target: Module,
+    key: str,
+    defined: tuple[Module, str],
+    guarded: dict[str, Guarded],
+) -> dict[str, str]:
+    """Spell one tuple type's tuple (see `targets.named_tuples`) for the file (`target`) naming it `key`.
+
+    Returns:
+      `key`, and the tuple; nothing for any other class or alias, or types the file can't write.
+
+    """
+    tuple_type: str | None = defined[0].tuples.get(defined[1])
+    return {} if tuple_type is None else portable(modules, (target, defined), key, {key: tuple_type}, guarded)

constricter/fix/libraries/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: MIT
+"""The standard library's and installed packages' types: the tables, and the signature a call matches."""