python-constricter 0.4.1__cp313-cp313-win32.whl

constricter/fix/values/narrowed.py

@@ -0,0 +1,220 @@
+# SPDX-License-Identifier: MIT
+"""Where a type checker narrows a value: the lines a test governs, and what it tests there.
+
+An `if` or `while` narrows what its condition tests in its body (and, negated, in its `else`); a
+`match` its subject in each case; an `assert`, and an `if` whose body always leaves (`return`,
+`raise`, `continue`, `break`), what they test for the rest of their block. A copy of a narrowed
+value there has the narrowed type, not its declared one: `--fix` offers it none (see `scope`). A
+check (`isinstance`, a `TypeGuard`, a `match`) narrows any type; a truth test or a comparison only
+a union (`int | None`).
+"""
+
+import ast
+from collections.abc import Iterator, Mapping, Sequence
+from functools import lru_cache
+from typing import Final, TypeAlias, cast
+
+from constricter.rules.walked import walk
+
+# The lines a test governs (first and last, from 1), and whether it's a check, which narrows any
+# type (not a truth test or comparison, which narrows only a union); by each value it narrows.
+Region: TypeAlias = tuple[int, int, bool]
+Regions: TypeAlias = Mapping[str, tuple[Region, ...]]
+_LEAVING: Final = (ast.Return, ast.Raise, ast.Continue, ast.Break)
+_GUARDS: Final = frozenset({"isinstance", "issubclass", "callable", "hasattr"})
+_READS: Final = (ast.Name, ast.Attribute, ast.Subscript)
+
+
+def regions(tree: ast.Module) -> Regions:
+    """Find every region a test narrows a value in, in a module.
+
+    Returns:
+      Each value's regions.
+
+    """
+    found: dict[str, list[Region]] = {}
+    text: str
+    region: Region
+    for text, region in _block(tree.body):
+        found.setdefault(text, []).append(region)
+    return {text: tuple(spans) for text, spans in found.items()}
+
+
+def narrowed_at(found: Regions, value: ast.expr, line: int, *, union: bool) -> bool:
+    """Check whether a read (`x`, `self.x`, `d[k]`) is narrowed at `line` by a test around it.
+
+    `union`: whether its type is one, which a truth test or a comparison narrows too.
+
+    Returns:
+      Whether it is.
+
+    """
+    return isinstance(value, _READS) and read_narrowed(found, ast.unparse(value), line, union=union)
+
+
+def read_narrowed(found: Regions, read: str, line: int, *, union: bool) -> bool:
+    """Check whether a read, as text, is narrowed at `line` (see `narrowed_at`).
+
+    Returns:
+      Whether it is.
+
+    """
+    return any(start <= line <= end and (check or union) for start, end, check in found.get(read, ()))
+
+
+@lru_cache(maxsize=64)  # asked of each of a function's guessed unions
+def tested_lines(function: ast.AST) -> Mapping[str, frozenset[int]]:
+    """Find the lines on which a test of a function's own narrows a value it goes on to read.
+
+    A condition's own lines (`if opt and opt.cb:`), a conditional expression's
+    (`opt.cb if opt else None`), a filtered comprehension's, and those of an `and` or `or` anywhere
+    (`return opt and opt.cb`).
+
+    Returns:
+      Each value such a test narrows, as source text, and those lines.
+
+    """
+    found: dict[str, set[int]] = {}
+    node: ast.AST
+    for node in walk(function):
+        test: ast.expr
+        whole: ast.expr
+        for test, whole in _spanned(node):
+            lines: range = range(min(test.lineno, whole.lineno), (whole.end_lineno or whole.lineno) + 1)
+            text: str
+            for text, _ in _narrows(test):
+                found.setdefault(text, set()).update(lines)
+    return {text: frozenset(lines) for text, lines in found.items()}
+
+
+def _spanned(node: ast.AST) -> Iterator[tuple[ast.expr, ast.expr]]:
+    """Find the tests a node holds, each with the expression whose lines it narrows on.
+
+    Yields:
+      Each test, and that expression: the test itself, or what it's part of.
+
+    """
+    test: ast.expr
+    match node:
+        case ast.If(test=test) | ast.While(test=test) | ast.Assert(test=test):
+            yield test, test
+        case ast.IfExp(test=test):
+            yield test, node
+        case ast.BoolOp():
+            yield node, node
+        case ast.ListComp() | ast.SetComp() | ast.DictComp() | ast.GeneratorExp():
+            yield from ((test, node) for each in node.generators for test in each.ifs)
+        case _:
+            pass
+
+
+def _block(body: Sequence[ast.stmt]) -> Iterator[tuple[str, Region]]:
+    """Walk a block's statements for the regions their tests narrow, inner blocks included.
+
+    Yields:
+      Each narrowed value, and a region.
+
+    """
+    end: int = (body[-1].end_lineno or body[-1].lineno) if body else 0
+    stmt: ast.stmt
+    for stmt in body:
+        rest: tuple[int, int] = ((stmt.end_lineno or stmt.lineno) + 1, end)
+        text: str
+        check: bool
+        for text, check in _tested(stmt):
+            yield from ((text, (*span, check)) for span in _governed(stmt, rest))
+        inner: list[ast.stmt]
+        for inner in _bodies(stmt):
+            yield from _block(inner)
+
+
+def _tested(stmt: ast.stmt) -> frozenset[tuple[str, bool]]:
+    """Name what a statement's test narrows.
+
+    Returns:
+      Each value, as source text, and whether it's checked (see `Region`).
+
+    """
+    test: ast.expr
+    subject: ast.expr
+    match stmt:
+        case ast.If(test=test) | ast.While(test=test) | ast.Assert(test=test):
+            return frozenset(_narrows(test))
+        case ast.Match(subject=subject) if isinstance(subject, _READS):
+            return frozenset({(ast.unparse(subject), True)})
+        case _:
+            return frozenset()
+
+
+def _narrows(test: ast.expr) -> Iterator[tuple[str, bool]]:
+    """Walk a condition for the values it narrows: a value tested for truth, compared, or checked.
+
+    Yields:
+      Each, as source text (`x`, `self.x`), not what it's compared with or checked against; and
+      whether it's checked (a call's argument: `isinstance`, a `TypeGuard` function).
+
+    """
+    operand: ast.expr
+    values: list[ast.expr]
+    left: ast.expr
+    args: list[ast.expr]
+    name: str
+    match test:
+        case ast.Name() | ast.Attribute() | ast.Subscript():
+            yield ast.unparse(test), False
+        case ast.UnaryOp(operand=operand):
+            yield from _narrows(operand)
+        case ast.BoolOp(values=values):
+            yield from (found for value in values for found in _narrows(value))
+        case ast.Compare(left=left) if isinstance(left, _READS):
+            yield ast.unparse(left), False
+        case ast.Call(func=ast.Name(id=name), args=args) if name in _GUARDS:
+            yield from ((ast.unparse(arg), True) for arg in args[:1] if isinstance(arg, _READS))
+        case ast.Call(args=args):  # a `TypeGuard` or `TypeIs` function may narrow any it's passed
+            yield from ((ast.unparse(arg), True) for arg in args if isinstance(arg, _READS))
+        case _:
+            pass
+
+
+def _governed(stmt: ast.stmt, rest: tuple[int, int]) -> Iterator[tuple[int, int]]:
+    """Find the lines a statement's test governs.
+
+    Yields:
+      Each region: its branches, and the rest of its block (`rest`) after an `assert`, or after an
+      `if` whose body always leaves.
+
+    """
+    match stmt:
+        case ast.Assert():
+            yield rest
+        case ast.If() | ast.While():
+            yield from (_span(branch) for branch in (stmt.body, stmt.orelse) if branch)
+            if isinstance(stmt, ast.If) and isinstance(stmt.body[-1], _LEAVING):
+                yield rest
+        case _:  # a `match`, the one other statement `_tested` finds a test in
+            yield from (_span(case.body) for case in cast("ast.Match", stmt).cases)
+
+
+def _span(body: Sequence[ast.stmt]) -> tuple[int, int]:
+    return body[0].lineno, body[-1].end_lineno or body[-1].lineno
+
+
+def _bodies(stmt: ast.stmt) -> Iterator[list[ast.stmt]]:
+    """Find the blocks inside a statement: a function's or class's body, a branch, a handler, a case.
+
+    Yields:
+      Each.
+
+    """
+    match stmt:
+        case ast.FunctionDef() | ast.AsyncFunctionDef() | ast.ClassDef() | ast.With() | ast.AsyncWith():
+            yield stmt.body
+        case ast.If() | ast.For() | ast.AsyncFor() | ast.While():
+            yield from (block for block in (stmt.body, stmt.orelse) if block)
+        case ast.Try() | ast.TryStar():
+            yield from (block for block in (stmt.body, stmt.orelse, stmt.finalbody) if block)
+            yield from (handler.body for handler in stmt.handlers)
+        case ast.Match():
+            yield from (case.body for case in stmt.cases)
+        case _:
+            pass

constricter/fix/values/operated.py

@@ -0,0 +1,202 @@
+# SPDX-License-Identifier: MIT
+"""Binary operators `--fix` types by their operands' builtin types, whose operators nothing can overload.
+
+Numbers: `/` gives a `float`; `+`, `-`, `*`, `//` and `%` a `float` if either side is one, else an
+`int`; `<<` and `>>` of integers an `int`, as their `&`, `|` and `^` are (of two `bool`s, a `bool`);
+`**` an `int` by a literal exponent that isn't negative, and by any other integer a `float`, which
+takes the `int` it may be as well as the `float` a negative one gives; a `float`'s by an integer a
+`float`. `str` and `bytes`: `+` of two, `*` by an integer on either side, and `%`
+formatting give the same type back; so do a `list[T]`'s `+` of another and `*` by an integer.
+Tuples: `+` gives both sides' parts, and `*` by an integer a `tuple[T, ...]` of the one type they
+have. A `set[T]`'s or a `frozenset[T]`'s `|`, `&`, `-` and `^` with another, and a `dict[K, V]`'s
+`|`, give that type.
+"""
+
+import ast
+from typing import Final, cast
+
+_INT: Final = "int"
+_FLOAT: Final = "float"
+_BOOL: Final = "bool"
+_INTEGERS: Final = frozenset({_BOOL, _INT})
+_NUMBERS: Final = _INTEGERS | {_FLOAT}
+_TEXTS: Final = frozenset({"str", "bytes"})
+_LIST: Final = "list"
+_TUPLE: Final = "tuple"
+_OPEN: Final = "["  # where a subscripted annotation's arguments start
+_SETS: Final = frozenset({"set", "frozenset"})
+_DICT: Final = "dict"
+_SAME_TYPE: Final = (ast.Add, ast.Sub, ast.Mult, ast.FloorDiv, ast.Mod)  # an `int`'s, or a `float`'s
+_SHIFTS: Final = (ast.LShift, ast.RShift)
+_BITWISE: Final = (ast.BitAnd, ast.BitOr, ast.BitXor)
+_SET_OPERATORS: Final = (ast.BitOr, ast.BitAnd, ast.Sub, ast.BitXor)
+_ANY_LENGTH: Final = 2  # `tuple[T, ...]`'s two parts: the element type and the ellipsis
+_ELLIPSIS: Final = "..."
+
+
+def operated(value: ast.BinOp, left: str | None, right: str | None, max_length: int) -> str | None:
+    """Type `value`, a binary operator between values typed `left` and `right` (see the module docstring).
+
+    `max_length`: the longest tuple written part by part.
+
+    Returns:
+      The annotation, or `None` for any other operator or operand.
+
+    """
+    if left is None:
+        return None
+    if left in _NUMBERS and right in _NUMBERS:
+        return _number(value, left, right or "")
+    if left in _INTEGERS and isinstance(value.op, ast.Mult):
+        return _repeated(right or "", left)  # `3 * "ab"`: the sequence's own `*`, reflected
+    if _root(left) == _TUPLE:
+        return _tuple(value.op, left, right or "", max_length)
+    if _root(left) in _SETS | {_DICT}:
+        return _same(value.op, left, right)
+    text: str | None = left if left in _TEXTS or _root(left) == _LIST else None
+    return text if text is not None and _keeps_text(value.op, text, right) else None
+
+
+def _root(annotation: str) -> str:
+    """Name a subscripted annotation's outer type (`list` for `list[int]`).
+
+    Returns:
+      Its text before the `[`, or nothing for one that isn't subscripted: a union of them too.
+
+    """
+    if _OPEN not in annotation:  # an unknown operand's has no text at all
+        return ""
+    # `annotation` is always `ast.unparse`'s own output, so it's always valid Python to parse back.
+    whole: ast.expr = ast.parse(annotation, mode="eval").body
+    return ast.unparse(whole.value) if isinstance(whole, ast.Subscript) else ""
+
+
+def _number(value: ast.BinOp, left: str, right: str) -> str | None:
+    """Type an operator between two builtin numbers.
+
+    Returns:
+      The annotation, or `None` for an operator whose result their types don't decide.
+
+    """
+    op: ast.operator = value.op
+    floating: bool = _FLOAT in {left, right}
+    if isinstance(op, ast.Div):
+        return _FLOAT
+    if isinstance(op, _SAME_TYPE):
+        return _FLOAT if floating else _INT
+    if isinstance(op, ast.Pow):
+        return _power(value.right, left, right)
+    if floating:
+        return None
+    if isinstance(op, _SHIFTS):
+        return _INT
+    both: bool = left == right == _BOOL
+    return (_BOOL if both else _INT) if isinstance(op, _BITWISE) else None
+
+
+def _power(exponent: ast.expr, left: str, right: str) -> str | None:
+    """Type `left ** right`: an integer's by a literal that isn't negative, or by another integer.
+
+    Returns:
+      The annotation: `int` by such a literal; by another integer, which may be negative, a `float`,
+      which takes an `int` too; `None` where the exponent is a `float`: a negative number's gives a
+      `complex`.
+
+    """
+    if right not in _INTEGERS:
+        return None
+    natural: bool = isinstance(exponent, ast.Constant) and isinstance(exponent.value, int)
+    return _INT if left in _INTEGERS and natural else _FLOAT
+
+
+def _repeated(sequence: str, count: str) -> str | None:
+    """Type a `str`, `bytes`, `list` or tuple repeated by a value typed `count`.
+
+    Returns:
+      The sequence's type (a tuple's as `tuple[T, ...]`), or `None` if it isn't one, or `count`
+      isn't an integer.
+
+    """
+    if count not in _INTEGERS:
+        return None
+    if sequence in _TEXTS or _root(sequence) == _LIST:
+        return sequence
+    parts: list[str] | None = _parts(sequence)
+    return None if parts is None else _any_length(parts)
+
+
+def _keeps_text(op: ast.operator, text: str, right: str | None) -> bool:
+    """Check whether `text op right` (`text` a `str`, a `bytes` or a `list[T]`) gives `text` back.
+
+    Returns:
+      Whether it does: `+` of two, `*` by an integer, or a `str`'s or `bytes`'s `%` formatting.
+
+    """
+    if isinstance(op, ast.Add):
+        return right == text
+    if isinstance(op, ast.Mult):
+        return right in _INTEGERS
+    return isinstance(op, ast.Mod) and text in _TEXTS
+
+
+def _tuple(op: ast.operator, left: str, right: str, max_length: int) -> str | None:
+    """Type a tuple's `+` of another, or its `*` by an integer.
+
+    Returns:
+      Both tuples' parts, where each has a fixed length and they're no more than `max_length`; a
+      `tuple[T, ...]` where every part of both is a `T`; else `None`.
+
+    """
+    if isinstance(op, ast.Mult):
+        return _repeated(left, right)
+    first: list[str] | None = _parts(left)
+    second: list[str] | None = _parts(right) if isinstance(op, ast.Add) else None
+    if first is None or second is None:
+        return None
+    fixed: bool = not (_is_any_length(first) or _is_any_length(second))
+    if fixed and len(first) + len(second) <= max_length:
+        return f"{_TUPLE}[{', '.join(first + second)}]"
+    return _any_length(first + second)
+
+
+def _parts(annotation: str) -> list[str] | None:
+    """Read a tuple type's parts (`tuple[int, str]`, `tuple[int, ...]`).
+
+    Returns:
+      Them, as text, a `...` included; `None` for any other type, or a tuple that unpacks one.
+
+    """
+    if _root(annotation) != _TUPLE:
+        return None
+    whole: ast.expr = cast("ast.Subscript", ast.parse(annotation, mode="eval").body).slice
+    elements: list[ast.expr] = whole.elts if isinstance(whole, ast.Tuple) else [whole]
+    starred: bool = any(isinstance(element, ast.Starred) for element in elements)
+    return None if starred or not elements else [ast.unparse(element) for element in elements]
+
+
+def _is_any_length(parts: list[str]) -> bool:
+    return len(parts) == _ANY_LENGTH and parts[1] == _ELLIPSIS
+
+
+def _any_length(parts: list[str]) -> str | None:
+    """Write the `tuple[T, ...]` of tuples' `parts`.
+
+    Returns:
+      It, or `None` where they aren't all one type.
+
+    """
+    types: set[str] = set(parts) - {_ELLIPSIS}
+    return f"{_TUPLE}[{types.pop()}, ...]" if len(types) == 1 else None
+
+
+def _same(op: ast.operator, left: str, right: str | None) -> str | None:
+    """Type a set's operator with another of its type, or a `dict`'s `|` with another of its.
+
+    Returns:
+      That type, or `None` for any other operator, or a right side of another type.
+
+    """
+    if left != right:
+        return None
+    merged: bool = isinstance(op, ast.BitOr) if _root(left) == _DICT else isinstance(op, _SET_OPERATORS)
+    return left if merged else None

constricter/fix/values/ordered.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: MIT
+"""The order a module's functions are checked in: each after those it calls, whose `return`s then type it."""
+
+import ast
+from collections.abc import Iterator, Sequence
+from typing import TypeAlias
+
+from constricter.fix.values import returned
+from constricter.rules.syntax import FunctionDef
+
+# The functions by name: the module's (`[False]`), then the classes' methods (`[True]`).
+_Named: TypeAlias = tuple[dict[str, list[FunctionDef]], dict[str, list[FunctionDef]]]
+# One function to put in call order, and its callees still to put in before it.
+_Visit: TypeAlias = tuple[FunctionDef, Iterator[FunctionDef]]
+
+
+def in_call_order(module: ast.Module, functions: Sequence[FunctionDef]) -> list[FunctionDef]:
+    """Order `functions` so that each comes after the functions it calls (a cycle's, in any order).
+
+    Its callees: the module's functions it calls by name, and every method named as it calls one
+    (`x.m()`: any class's `m`), as `called` counts them.
+
+    Returns:
+      Them, callees first; otherwise in their own order.
+
+    """
+    named: _Named = ({}, {})
+    func: FunctionDef
+    for func in functions:
+        slot: returned.Slot | None
+        if (slot := returned.slots(module).get(id(func))) is not None:
+            named[slot.owner is not None].setdefault(slot.name, []).append(func)
+    ordered: list[FunctionDef] = []
+    seen: set[int] = set()
+    for func in functions:
+        if id(func) not in seen:
+            seen.add(id(func))
+            _after_callees(module, func, named, (ordered, seen))
+    return ordered
+
+
+def _after_callees(
+    module: ast.Module,
+    func: FunctionDef,
+    named: _Named,
+    into: tuple[list[FunctionDef], set[int]],
+) -> None:
+    """Put `func` in the order after its callees, depth first, with a stack: a call chain can be long."""
+    ordered: list[FunctionDef]
+    seen: set[int]
+    ordered, seen = into
+    # Each entry: a function, and its callees still to put in before it; `None` at the bottom ends it.
+    waiting: list[_Visit | None] = [None, (func, _callees(module, func, named))]
+    entry: _Visit
+    for entry in iter(waiting.pop, None):
+        callee: FunctionDef | None
+        if (callee := next((one for one in entry[1] if id(one) not in seen), None)) is None:
+            ordered.append(entry[0])
+        else:
+            seen.add(id(callee))
+            waiting.extend([entry, (callee, _callees(module, callee, named))])
+
+
+def _callees(module: ast.Module, func: FunctionDef, named: _Named) -> Iterator[FunctionDef]:
+    """Find the functions of `named` that `func` calls: the module's by name, methods by attribute.
+
+    Yields:
+      Each, in the order of its calls.
+
+    """
+    name: str | None
+    attr: str | None
+    for name, attr in returned.callees_in(module, func):
+        yield from named[False].get(name, []) if name is not None else named[True].get(attr or "", [])