python-constricter 0.4.1__cp313-cp313-win32.whl

constricter/fix/libraries/library.py

@@ -0,0 +1,420 @@
+# SPDX-License-Identifier: MIT
+"""Calls to the standard library `--fix` types from the tables (see `constricter.fix.libraries.stdlib`).
+
+A class, or a function returning one (`library_class`); a function with a fixed builtin result, one
+whose arguments decide its type (`constricter.fix.libraries.overloads`), an installed package's too (see
+`constricter.fix.index.stubs.stubbed`), or `os.environ.get` (`library_call`).
+"""
+
+import ast
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Final, TypeAlias
+
+from constricter.fix.core.imports import added_dotted
+from constricter.fix.core.known import ImportPlan, Inference, Known
+from constricter.fix.core.signatures import AWAIT
+from constricter.fix.libraries import overloads, stdlib
+from constricter.rules.annotations import dotted, vague_fits
+
+if TYPE_CHECKING:
+    from constricter.fix.core.signatures import Expansion
+
+_STDLIB: Final = "stdlib"  # the fix kind
+_STR: Final = "str"
+_DOT: Final = "."
+_SELF: Final = "Self"  # a method's own class, in a template
+_WITH_DEFAULT: Final = 2  # `os.environ.get(key, default)`'s arguments
+_TYPING_ANY: Final = "typing.Any"
+_ARITHMETIC: Final = "arithmetic"  # the fix kind
+_NUMBERS: Final = frozenset({"bool", "int", "float", "complex"})  # whose operators take these alone
+_Operator: TypeAlias = type[ast.operator]
+_Operands: TypeAlias = tuple[Inference | None, Inference | None]
+# The method each binary operator calls on its left operand (see `library_operator`).
+_OPERATORS: Final[dict[_Operator, str]] = {
+    ast.Add: "__add__",
+    ast.Sub: "__sub__",
+    ast.Mult: "__mul__",
+    ast.Div: "__truediv__",
+    ast.FloorDiv: "__floordiv__",
+    ast.Mod: "__mod__",
+    ast.BitAnd: "__and__",
+    ast.BitOr: "__or__",
+    ast.BitXor: "__xor__",
+}
+
+
+def library_class(value: ast.Call, known: Known) -> Inference | None:
+    """Infer a call to a standard-library class, or a function returning one (`stdlib.CLASSES`).
+
+    Returns:
+      The class, spelled (and imported, if it must be) as the module can; or `None`.
+
+    """
+    name: str | None = stdlib.resolved(value.func, known.names.stdlib)
+    plan: ImportPlan | None = known.names.plan
+    spelled: str | None = (
+        None if name not in stdlib.CLASSES or plan is None else plan.spell(stdlib.CLASSES[name])
+    )
+    return None if spelled is None else Inference(spelled, f"`{name}`'s return type", frozenset({_STDLIB}))
+
+
+def library_operator(op: ast.operator, sides: _Operands, known: Known) -> Inference | None:
+    """Type an operator by its left operand's standard-library class's method (`__add__`, `__sub__`).
+
+    `when - start`, two `datetime`s, is a `timedelta` (see `overloads.operated`). Where the right
+    operand is a builtin's or a standard-library class's instance too: another class's reflected
+    method may be the one that answers. A builtin number's, left of a standard-library class's
+    instance (not a class under the number's own), is the right one's reflected method's
+    (`2 * span`, a `timedelta`). A class the module defines under a library one is that one's (see
+    `_as_library`), its `Self` the module's own; a generic class's instance is matched by its type
+    arguments (`Counter[str] + Counter[str]`, see `overloads.operated`).
+
+    Returns:
+      The inference, or `None`.
+
+    """
+    name: str | None = _OPERATORS.get(type(op))
+    if name is None or sides[0] is None or sides[1] is None:
+        return None
+    kinds: frozenset[str] = sides[0].kinds | sides[1].kinds | {_ARITHMETIC}
+    receiver: str = sides[0].annotation
+    other: str = sides[1].annotation
+    named: tuple[str, str] = (name, f"__r{name[2:]}")
+    taken: str = _as_library(receiver, named, known)
+    given: str = _as_library(other, named, known)
+    left: str | None
+    right: str | None
+    arguments: tuple[str, ...] | None
+    left, _ = _operand(taken, known)
+    right, arguments = _operand(given, known)
+    if left in _NUMBERS and right is not None and _DOT in right and not stdlib.inherits(right, left):
+        # A builtin number's own methods take builtin numbers alone: a standard-library class's
+        # Reflected method answers (`2 * span`, `timedelta.__rmul__`).
+        name, receiver, taken, left, right = named[1], other, given, right, left
+    method: stdlib.Method | None = stdlib.overloaded_method(taken, name, known)
+    if left is None or right is None or method is None:
+        return None
+    found: Inference | None = overloads.operated(
+        stdlib.for_receiver(method, receiver),
+        (left, right),
+        known,
+        arguments,
+        same=other == receiver,
+    )
+    return None if found is None else found._replace(kinds=found.kinds | kinds)
+
+
+def _as_library(annotation: str, names: tuple[str, str], known: Known) -> str:
+    """Read an operand of a class the module defines as the library class it takes an operator from.
+
+    `class Money(Decimal)`: a `Decimal`, where neither it nor a class between binds the operator's
+    method or its reflected twin (`names`).
+
+    Returns:
+      That class as its subclass writes it (`deque[int]`), or `annotation` itself.
+
+    """
+    found: set[str | None] = {known.class_side.lineage.definer(annotation, name) for name in names}
+    base: str | None = found.pop() if len(found) == 1 else None
+    return annotation if base is None or base == annotation or _operand(base, known)[0] is None else base
+
+
+def _operand(annotation: str, known: Known) -> tuple[str | None, tuple[str, ...] | None]:
+    """Name an operand's type as an operator's `takes` does, a generic class's instance by its class.
+
+    Returns:
+      Its name (see `stdlib.operand`), and a generic class's instance's type arguments, as written.
+
+    """
+    tree: ast.expr = ast.parse(annotation, mode="eval").body
+    if not isinstance(tree, ast.Subscript):
+        return stdlib.operand(annotation, known), None
+    head: str | None = stdlib.operand(ast.unparse(tree.value), known)
+    parts: list[ast.expr] = tree.slice.elts if isinstance(tree.slice, ast.Tuple) else [tree.slice]
+    return head, tuple(ast.unparse(part) for part in parts)
+
+
+def library_variable(value: ast.expr, known: Known) -> Inference | None:
+    """Infer a standard-library module's variable (`sys.path`, `os.sep`, `from sys import argv`).
+
+    Returns:
+      Its type, a class spelled (and imported, if it must be) as the module can, its type arguments
+      too (`sys.modules`: a `dict[str, ModuleType]`); or `None`.
+
+    """
+    name: str | None = (
+        stdlib.resolved(value, known.names.stdlib) if isinstance(value, ast.Name | ast.Attribute) else None
+    )
+    found: str | None = None if name is None else stdlib.VARIABLES.get(name)
+    plan: ImportPlan | None = known.names.plan
+    if found is not None and stdlib.is_class(found):
+        found = None if plan is None else plan.spell(found)
+    elif found is not None and _DOT in found:  # a template: classes' paths, in a type that says more
+        found = overloads.write((found, {}), known)
+    return (
+        None
+        if found is None
+        else Inference(found, f"`{name}`'s annotation in typeshed", frozenset({_STDLIB}))
+    )
+
+
+def installed_call(
+    value: ast.expr,
+    known: Known,
+    infer: Callable[[ast.expr], Inference | None],
+) -> Inference | None:
+    """Infer a call to an installed package's function whose arguments decide its type (`np.empty`).
+
+    By the signature its arguments certainly match (see `constricter.fix.index.stubs.stubbed`); `infer`
+    types an argument.
+
+    Returns:
+      The inference, or `None` for any other call, or arguments that don't decide it.
+
+    """
+    callee: str | None
+    func: ast.Name | ast.Attribute
+    match value:
+        case ast.Call(func=ast.Name() | ast.Attribute() as func) if (
+            known.names.installed and (callee := dotted(func)) in known.names.installed
+        ):
+            return overloads.chosen(callee or "", value, known, infer)
+        case _:
+            return None
+
+
+def installed_method(receiver: str, name: str, known: Known) -> stdlib.Method | None:
+    """Find an installed class's method whose arguments or instance decide its type, on a receiver's type.
+
+    Its class's type parameters bound to the receiver's type arguments (`np.ndarray[tuple[int], ...]`),
+    and `Self` to the receiver's type; through a public alias of the class (`npt.NDArray[np.float64]`),
+    the alias's parameters bound instead, and the class's by what the alias writes for them.
+
+    Returns:
+      It (its `entry`: the method's key in `LibraryNames.installed`), or `None`.
+
+    """
+    tree: ast.expr = ast.parse(receiver, mode="eval").body
+    base: str = _imported(ast.unparse(tree.value if isinstance(tree, ast.Subscript) else tree), known)
+    entry: str
+    if (entry := f"{base}.{name}") not in known.names.installed:
+        return None
+    args: list[ast.expr] = []
+    if isinstance(tree, ast.Subscript):
+        args = list(tree.slice.elts) if isinstance(tree.slice, ast.Tuple) else [tree.slice]
+    texts: list[str] = [ast.unparse(arg) for arg in args]
+    expansion: Expansion | None
+    if (expansion := known.names.aliases.get(base)) is not None:
+        own: dict[str, str] = dict(zip(expansion.params, texts, strict=False))
+        return stdlib.Method(
+            entry,
+            None,
+            {**own, _SELF: receiver},
+            dict(expansion.templates),
+            overloads.substituted(expansion.receiver, own),
+        )
+    params: tuple[str, ...] = known.names.parameters.get(base, ())
+    return stdlib.Method(entry, None, {**dict(zip(params, texts, strict=False)), _SELF: receiver})
+
+
+def _imported(base: str, known: Known) -> str:
+    """Name a class `--fix` is importing (`NDArray`) as the module's imports do (`np.typing.NDArray`).
+
+    Returns:
+      It, as `LibraryNames.installed` has its methods (by its dotted path, where no import of the
+      module's leads to it); `base` itself for any other.
+
+    """
+    plan: ImportPlan | None = known.names.plan
+    if plan is None or base not in plan.added:
+        return base
+    qualified: str = added_dotted(plan.added[base])
+    bound: str
+    origin: str
+    for bound, origin in plan.bound.items():
+        if qualified.startswith(f"{origin}{_DOT}"):
+            return f"{bound}{qualified.removeprefix(origin)}"
+    return qualified
+
+
+def installed_chain(
+    value: ast.expr,
+    known: Known,
+    infer: Callable[[ast.expr], Inference | None],
+) -> Inference | None:
+    """Infer an attribute of what an installed class's method returns, off the call (`cap.readouterr().out`).
+
+    By the entry the index wrote for it beside the method's (see `constricter.fix.index.stubs.chained`),
+    the receiver's type arguments binding it as they do the method's own return.
+
+    Returns:
+      The inference, or `None` for any other value, a receiver of no known type, or no such entry.
+
+    """
+    receiver: ast.expr
+    call: ast.Call
+    name: str
+    attr: str
+    match value:
+        case ast.Attribute(
+            value=ast.Call(func=ast.Attribute(value=receiver, attr=name)) as call,
+            attr=attr,
+        ):
+            owner: Inference | None = infer(receiver)
+            method: stdlib.Method | None = (
+                None if owner is None else installed_method(owner.annotation, f"{name}().{attr}", known)
+            )
+            if owner is None or method is None:
+                return None
+            found: Inference | None = overloads.chosen(
+                method.entry,
+                call,
+                known,
+                infer,
+                stdlib.for_receiver(method, owner.annotation),
+            )
+            return None if found is None else found._replace(kinds=found.kinds | owner.kinds - {"copy"})
+        case _:
+            return None
+
+
+def chains(value: ast.expr, known: Known) -> bool:
+    """Check whether `value` calls a method the index wrote its return's attribute of (see `installed_chain`).
+
+    Returns:
+      Whether it may: a method of that name has one, whatever its receiver is.
+
+    """
+    name: str
+    match value:
+        case ast.Call(func=ast.Attribute(attr=name)):
+            return any(f".{name}()." in entry for entry in known.names.installed)
+        case _:
+            return False
+
+
+def _any(text: str, known: Known, found: Inference) -> Inference | None:
+    """Spell a table's bare `Any` (`json.loads`'s) as the module can, where `vague` lets it be written.
+
+    Returns:
+      `found`, as the module names `Any`; `None` where it's vaguer than `vague` allows, or `Any`
+      can't be named. Any other type as it is.
+
+    """
+    if text != stdlib.ANY:
+        return found
+    plan: ImportPlan | None = known.names.plan
+    spelled: str | None = (
+        None
+        if plan is None or not vague_fits(ast.Name(text), known.limits.vague)
+        else plan.spell(_TYPING_ANY)
+    )
+    return None if spelled is None else found._replace(annotation=spelled)
+
+
+def library_awaited(
+    value: ast.expr,
+    known: Known,
+    infer: Callable[[ast.expr], Inference | None],
+) -> Inference | None:
+    """Infer `await` of a call of a standard-library coroutine (see `stdlib.awaited_call`).
+
+    A function's, by its arguments where they decide it (`await asyncio.wait_for(fetch(), 1)`), or a
+    method's on a receiver whose type `infer` knows; or of any value typed as an awaitable of
+    something (`await asyncio.gather(a(), b())`, an `asyncio.Future[tuple[A, B]]`; `await task`).
+
+    Returns:
+      The inference, or `None` for any other value.
+
+    """
+    call: ast.Call
+    held: ast.expr
+    match value:
+        case ast.Await(value=ast.Call() as call):
+            return _awaited_call(call, known, infer) or _awaited_value(call, known, infer)
+        case ast.Await(value=held):
+            return _awaited_value(held, known, infer)
+        case _:
+            return None
+
+
+def _awaited_call(
+    call: ast.Call,
+    known: Known,
+    infer: Callable[[ast.expr], Inference | None],
+) -> Inference | None:
+    receiver: ast.expr
+    name: str
+    owner: Inference | None = None
+    found: Inference | None = None
+    match call.func:
+        case ast.Attribute(value=receiver, attr=name) if (owner := infer(receiver)) is not None:
+            found = stdlib.awaited_member(owner.annotation, name, known)
+            method: stdlib.Method | None
+            # A generic class's own coroutine, by the receiver's arguments (`await queue.get()`).
+            if found is None and (
+                (method := stdlib.overloaded_method(owner.annotation, f"{AWAIT}{name}", known)) is not None
+            ):
+                found = overloads.chosen(
+                    method.entry,
+                    call,
+                    known,
+                    infer,
+                    stdlib.for_receiver(method, owner.annotation),
+                )
+        case _:
+            pass
+    if found is not None and owner is not None:
+        return found._replace(kinds=found.kinds | owner.kinds - {"copy"})
+    path: str | None = stdlib.resolved(call.func, known.names.stdlib)
+    return stdlib.awaited_call(call.func, known) or (
+        overloads.chosen(f"{AWAIT}{path}", call, known, infer) if path in stdlib.AWAITED_OVERLOADS else None
+    )
+
+
+def _awaited_value(
+    value: ast.expr,
+    known: Known,
+    infer: Callable[[ast.expr], Inference | None],
+) -> Inference | None:
+    made: Inference | None = infer(value)
+    given: str | None = None if made is None else stdlib.awaited_value(made.annotation, known)
+    return (
+        None
+        if made is None or given is None
+        else made._replace(annotation=given, reason=f"{made.reason}, awaited")
+    )
+
+
+def library_call(
+    call: ast.Call,
+    known: Known,
+    infer: Callable[[ast.expr], Inference | None],
+) -> Inference | None:
+    """Infer a call to a standard-library function the tables type (see `constricter.fix.libraries.stdlib`).
+
+    A fixed builtin result, whatever the arguments; the signature its arguments certainly match, for
+    one whose overloads or type variables they decide (see `constricter.fix.libraries.overloads`); and
+    `os.environ.get`'s `str | None` (`str` with a `str` default), passed positionally. `infer`
+    types an argument.
+
+    Returns:
+      The inference, or `None` for any other call, or arguments that don't decide it.
+
+    """
+    args: list[ast.expr] = call.args
+    name: str | None = stdlib.resolved(call.func, known.names.stdlib)
+    reason: str = f"`{name}`'s return type"
+    kinds: frozenset[str] = frozenset({_STDLIB})
+    if name in stdlib.RETURNS:
+        return _any(stdlib.RETURNS[name], known, Inference(stdlib.RETURNS[name], reason, kinds))
+    if name is not None and name in stdlib.OVERLOADS:
+        return overloads.chosen(name, call, known, infer)
+    # `os.environ.get`, decided by its positional arguments' types, worked out only for it.
+    if call.keywords or name != stdlib.ENVIRONMENT:
+        return None
+    parts: list[Inference | None] = [infer(arg) for arg in args]
+    if len(args) == 1:
+        return Inference("str | None", reason, kinds)
+    default: Inference | None = parts[1] if len(args) == _WITH_DEFAULT else None
+    return Inference(_STR, reason, kinds | default.kinds) if default and default.annotation == _STR else None

constricter/fix/libraries/opened.py

@@ -0,0 +1,147 @@
+# SPDX-License-Identifier: MIT
+"""`--fix` for `open(path, mode)` and `path.open(mode)`: the file object it gives, by its literal mode."""
+
+import ast
+from typing import Final
+
+from constricter.fix.core.known import ImportPlan, Inference, Known
+from constricter.fix.libraries import stdlib
+
+_OPEN: Final = "open"  # the builtin, and the fix kind of what it gives
+# The standard library's functions that open a file as the builtin does, by the mode after their
+# first argument.
+_OPENERS: Final = frozenset({"io.open", "_io.open", "os.fdopen"})
+_READERS: Final = frozenset({"tokenize.open"})  # those that open one as text, whatever they're given
+# Those that give an `io.TextIOWrapper` for a text mode alone (the tables have their other modes).
+_COMPRESSED: Final = frozenset({"gzip.open", "bz2.open", "lzma.open"})
+_SHELF: Final = "shelve.open"  # typeshed's `Shelf[Any]`: written where `vague` lets it be
+_ACTIONS: Final = "rwxa"  # exactly one of them in a mode
+_MODE_CHARACTERS: Final = "rwxabt+"
+_READ: Final = "r"
+_BINARY: Final = "b"
+_TEXT: Final = "t"
+_UPDATE: Final = "+"
+_WRAPPER: Final = "io.TextIOWrapper"
+_TEXT_FILE: Final = "typing.TextIO"  # what typeshed declares `tokenize.open` gives
+
+
+def opened(value: ast.expr, known: Known) -> Inference | None:
+    """Infer the file object `open(path, mode)` gives, by its mode (a literal, or the default `r`).
+
+    Text modes give an `io.TextIOWrapper`; binary ones an `io.BufferedReader` to read,
+    `io.BufferedWriter` to write, and `io.BufferedRandom` for both (`+`). `buffering` or `opener`
+    (in a position or by name) decides nothing: unbuffered, it's an `io.FileIO`. The builtin `open`,
+    never one the module binds itself, and the standard library's own that open as it does
+    (`io.open`, `os.fdopen`); `tokenize.open`, always a `typing.TextIO`; `gzip.open`, `bz2.open` and
+    `lzma.open` given a text mode; and `shelve.open`, a `shelve.Shelf[Any]`.
+
+    Returns:
+      The inference (spelled, and imported if it must be, as the module can), or `None`.
+
+    """
+    plan: ImportPlan | None = known.names.plan
+    func: ast.expr
+    args: list[ast.expr]
+    keywords: list[ast.keyword]
+    match value:
+        case ast.Call(func=func, args=[_, *args], keywords=keywords) if plan is not None:
+            pass
+        case _:
+            return None
+    if isinstance(func, ast.Name) and func.id == _OPEN and _OPEN not in plan.taken:
+        return _by_mode(args, keywords, plan)
+    origin: str | None
+    if (origin := stdlib.resolved(func, known.names.stdlib)) in _OPENERS:
+        return _by_mode(args, keywords, plan)
+    return None if origin is None else _by_opener(origin, _mode(args, keywords), plan)
+
+
+def _by_opener(origin: str, mode: str | None, plan: ImportPlan) -> Inference | None:
+    """Infer what a standard-library function that opens a file its own way gives (see `opened`).
+
+    `mode`: its literal mode, as `_mode` reads it.
+
+    Returns:
+      The inference, or `None` for any other function, or a mode that isn't a text one.
+
+    """
+    spelled: str | None = None
+    if origin == _SHELF:
+        parts: tuple[str | None, str | None] = (plan.spell("shelve.Shelf"), plan.spell("typing.Any"))
+        spelled = None if None in parts else f"{parts[0]}[{parts[1]}]"
+    elif origin in _READERS:
+        spelled = plan.spell(_TEXT_FILE)
+    elif origin in _COMPRESSED and mode is not None and _TEXT in mode and _file_class(mode) is not None:
+        spelled = plan.spell(_WRAPPER)
+    reason: str = f"`{origin}`'s return type in typeshed"
+    return None if spelled is None else Inference(spelled, reason, frozenset({"stdlib"}))
+
+
+def opened_path(receiver: str, value: ast.Call, known: Known) -> Inference | None:
+    """Infer the file object `path.open(mode)` gives on a `pathlib` path, as `open(path, mode)`'s is.
+
+    `receiver`: the path's type, as the module spells it.
+
+    Returns:
+      The inference, or `None` for any other call or receiver.
+
+    """
+    plan: ImportPlan | None = known.names.plan
+    attr: str
+    args: list[ast.expr]
+    keywords: list[ast.keyword]
+    match value:
+        case ast.Call(func=ast.Attribute(attr=attr), args=args, keywords=keywords) if (
+            attr == _OPEN and plan is not None and stdlib.is_path(receiver, known)
+        ):
+            return _by_mode(args, keywords, plan)
+        case _:
+            return None
+
+
+def _mode(args: list[ast.expr], keywords: list[ast.keyword]) -> str | None:
+    """Read a call's literal mode from the arguments after its path: the first, or the one named `mode`.
+
+    Returns:
+      It (`r`, with none given), or `None` if it isn't a string literal.
+
+    """
+    named: dict[str | None, ast.expr] = {keyword.arg: keyword.value for keyword in keywords}
+    mode: ast.expr | None
+    if (mode := args[0] if args else named.get("mode")) is None:
+        return _READ
+    return mode.value if isinstance(mode, ast.Constant) and isinstance(mode.value, str) else None
+
+
+def _by_mode(args: list[ast.expr], keywords: list[ast.keyword], plan: ImportPlan) -> Inference | None:
+    """Infer a file object by the arguments after its path: its mode, first or by name.
+
+    Returns:
+      The inference, or `None` (see `opened`).
+
+    """
+    text: str | None = _mode(args, keywords)
+    if text is None or len(args) > 1 or {None, "buffering", "opener"} & {k.arg for k in keywords}:
+        return None
+    kind: str | None = _file_class(text)
+    spelled: str | None = None if kind is None else plan.spell(f"io.{kind}")
+    return None if spelled is None else Inference(spelled, f"`open`'s mode `{text}`", frozenset({_OPEN}))
+
+
+def _file_class(mode: str) -> str | None:
+    """Name the `io` class `open` gives for `mode`.
+
+    Returns:
+      It, or `None` for a mode that isn't one `open` takes.
+
+    """
+    actions: set[str] = set(mode) & set(_ACTIONS)
+    if not set(mode) <= set(_MODE_CHARACTERS) or len(actions) != 1 or len(set(mode)) != len(mode):
+        return None
+    if _BINARY not in mode:
+        return "TextIOWrapper"
+    if _TEXT in mode:
+        return None
+    if _UPDATE in mode:
+        return "BufferedRandom"
+    return "BufferedReader" if _READ in actions else "BufferedWriter"