python-constricter 0.4.1__cp313-cp313-win32.whl

constricter/fix/index/stubs/chained.py

@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: MIT
+"""An attribute of what an installed class's method returns, read off the call: `capsys.readouterr().out`.
+
+The returned class may be one no file can name (pytest's `CaptureResult`, private to `_pytest`), so
+the call alone has no type to write; its attribute's is the method's own return, as far as the
+receiver's type arguments bind it: a signature of the method's, returning the attribute's type.
+"""
+
+import ast
+import re
+from typing import TYPE_CHECKING, Final
+
+from constricter.fix.index.stubs.atoms import parse_text
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from constricter.fix.index.modules import Module
+    from constricter.fix.index.stubs.declared import Class, Signature
+
+_WORD: Final = re.compile(r"\b\w+\b")
+
+
+def key(method: str, attribute: str) -> str:
+    """Name the entry of an attribute of a method's return, beside the method's own.
+
+    Returns:
+      It.
+
+    """
+    return f"{method}().{attribute}"
+
+
+def attributes(
+    module: "Module",
+    klass: "Class",
+    method: str,
+    wanted: frozenset[str],
+) -> dict[str, tuple["Signature", ...]]:
+    """Read the attributes (of `wanted`) of what `klass`'s own `method` returns, as signatures of its.
+
+    For a method of one signature returning an instance of a class its own module declares, that
+    class's type parameters bound as the return writes them (`CaptureResult[AnyStr]`'s `out`: an
+    `AnyStr`, the receiver's).
+
+    Returns:
+      Each attribute's, by name: the method's signature, returning the attribute's type.
+
+    """
+    written: tuple[Signature, ...] | None = klass.methods.get(method)
+    if written is None or len(written) != 1 or written[0].returns is None or module.declared is None:
+        return {}
+    returned: ast.expr = parse_text(written[0].returns)
+    base: ast.expr = returned.value if isinstance(returned, ast.Subscript) else returned
+    # By its name there: one defined under an `if` isn't among the module's names.
+    result: Class | None = module.declared.classes.get(base.id) if isinstance(base, ast.Name) else None
+    given: list[ast.expr] = []
+    if isinstance(returned, ast.Subscript):
+        given = list(returned.slice.elts) if isinstance(returned.slice, ast.Tuple) else [returned.slice]
+    if result is None or len(given) != len(result.params):
+        return {}
+    bound: Mapping[str, str] = {
+        name: ast.unparse(arg) for (name, _), arg in zip(result.params, given, strict=True)
+    }
+    return {
+        name: (written[0]._replace(returns=_WORD.sub(lambda word: bound.get(word[0], word[0]), text)),)
+        for name, text in result.attributes.items()
+        if name in wanted
+    }

constricter/fix/index/stubs/classnames.py

@@ -0,0 +1,124 @@
+# SPDX-License-Identifier: MIT
+"""The installed classes and aliases a module names, and the methods a class's lineage declares.
+
+For `constricter.fix.index.stubs.stubbed`, which reads their methods' signatures.
+"""
+
+from collections.abc import Iterator, Mapping, Sequence
+from typing import TYPE_CHECKING, TypeAlias
+
+from constricter.fix.core.known import Origin
+from constricter.fix.index import project
+from constricter.fix.index.modules import Module
+
+if TYPE_CHECKING:
+    from constricter.fix.index.stubs.declared import Class, Declarations
+
+# A package's classes (or aliases): each as written after the package's name, and where it's defined.
+Packaged: TypeAlias = tuple[tuple[str, Origin], ...]
+
+
+def method_names(modules: Mapping[str, Module], lineage: Sequence[str]) -> frozenset[str]:
+    """Name the methods a class or any of its installed ancestors (its lineage) declares.
+
+    Returns:
+      Them.
+
+    """
+    found: set[str] = set()
+    path: str
+    for path in lineage:
+        module: str
+        name: str
+        module, _, name = path.rpartition(".")
+        declared: Declarations | None = None if module not in modules else modules[module].declared
+        klass: Class | None = None if declared is None else declared.classes.get(name)
+        found.update(() if klass is None else klass.methods)
+    return frozenset(found)
+
+
+def classes(
+    modules: Mapping[str, Module],
+    names: Mapping[str, Origin],
+    packaged: dict[tuple[str, bool], "Packaged"],
+    *,
+    aliases: bool = False,
+) -> Iterator[tuple[str, Origin]]:
+    """Find the installed classes `names` (a module's) name: imported (`ndarray`), or through a package.
+
+    Through a package, what any of its modules defines or re-exports (`numpy.ndarray`), the package
+    imported from another module too (`from pandas._typing import npt`). With
+    `aliases`, the installed aliases it names instead (`npt.NDArray`). `packaged`: each package's, as
+    read so far.
+
+    Yields:
+      Each as the module writes it, and where it's defined.
+
+    """
+    local: str
+    origin: Origin
+    for local, origin in names.items():
+        where: Origin = project.canonical_origin(modules, origin)
+        if where[1] is not None:
+            if declares(modules, where, aliases=aliases):
+                yield local, where
+            continue
+        if (where[0], aliases) not in packaged:
+            packaged[where[0], aliases] = tuple(_package_classes(modules, where[0], aliases=aliases))
+        suffix: str
+        found: Origin
+        for suffix, found in packaged[where[0], aliases]:
+            yield f"{local}{suffix}", found
+
+
+def _package_classes(
+    modules: Mapping[str, Module],
+    package: str,
+    *,
+    aliases: bool,
+) -> Iterator[tuple[str, Origin]]:
+    """Find the installed classes (or aliases) a package's modules define or re-export.
+
+    Yields:
+      Each as written after the package's name (`.ndarray`, `.linalg.LinAlgError`), and where it's defined.
+
+    """
+    name: str
+    other: Module
+    for name, other in modules.items():
+        if other.installed and (name == package or name.startswith(f"{package}.")):
+            bound: str
+            found: Origin
+            for bound, found in other.names.items():
+                where: Origin = project.canonical_origin(modules, found)
+                if declares(modules, where, aliases=aliases):
+                    yield f"{name.removeprefix(package)}.{bound}", where
+
+
+def declares(modules: Mapping[str, Module], origin: Origin, *, aliases: bool = False) -> bool:
+    """Check whether an installed module declares a class (or an alias) under `origin`'s name.
+
+    Returns:
+      Whether it does.
+
+    """
+    module: Module | None = modules.get(origin[0])
+    declared: Declarations | None = None if module is None or not module.installed else module.declared
+    return declared is not None and origin[1] in (declared.aliases if aliases else declared.classes)
+
+
+def as_module(modules: Mapping[str, Module], origin: Origin | None) -> Origin | None:
+    """Take a name imported from a package that is its submodule (`from pkg import util`) as that module.
+
+    Unless the package itself binds the name another way.
+
+    Returns:
+      The module (`(name, None)`), or `origin` as it is.
+
+    """
+    if origin is None or origin[1] is None:
+        return origin
+    submodule: str = f"{origin[0]}.{origin[1]}"
+    package: Module | None = modules.get(origin[0])
+    bound: bool = package is not None and package.names.get(origin[1], (submodule, None)) != (submodule, None)
+    return (submodule, None) if submodule in modules and not bound else origin