python-constricter 0.4.1__cp313-cp313-win32.whl

constricter/rules/settings.py

@@ -0,0 +1,189 @@
+# SPDX-License-Identifier: MIT
+"""What a module is checked with (`Settings`): its options, and what `--fix` knows of it.
+
+Its own tables (`Tables`) joined with what other checked files say of it (`Outside`): functions'
+returns, classes' members and lines of bases, the standard library's classes it takes from, what a
+type checker sees otherwise (`facts`), and its parameters' types given from outside. A type the
+module's own code writes with a type variable it imports is left out: `--fix` sees only its own.
+"""
+
+import ast
+from collections.abc import Mapping, Sequence
+from dataclasses import replace
+from typing import Final, cast
+
+from constricter.fix.core import imports, inherited
+from constricter.fix.core.known import (
+    Classes,
+    ClassSide,
+    Indirect,
+    Known,
+    LibraryNames,
+    Limits,
+    Outside,
+    Partial,
+)
+from constricter.fix.libraries import stdlib
+from constricter.fix.values import callables, classvars, entered, fills, stored
+from constricter.fix.values.doubts import facts, says_self
+from constricter.offences import (
+    STARRED_SUBSCRIPTS,
+    Checks,
+)
+from constricter.rules import late, widened
+from constricter.rules.annotations import free_of, free_of_all
+from constricter.rules.calls import keyed, marked
+from constricter.rules.declarations import (
+    awaited_returns,
+    casts,
+    class_attributes,
+    defined_type_vars,
+    factories,
+    self_returns,
+)
+from constricter.rules.decorators import passing
+from constricter.rules.flow import Hierarchy
+from constricter.rules.scoped import Seeded, Settings
+from constricter.rules.syntax import (
+    owners,
+    python2_compatible,
+)
+from constricter.rules.tables import Tables
+from constricter.rules.walked import of_type
+
+TYPING_ALIAS: Final = (3, 10)  # the first Python whose `typing` has `TypeAlias`
+
+
+def module_settings(
+    tree: ast.Module,
+    checks: Checks,
+    lines: Sequence[str],
+    own: Tables,
+    outside: Outside | None = None,
+) -> Settings:
+    """Work out what the module `tree` is checked with (see the module docstring).
+
+    `checks`: its options; `lines`: its source lines; `own`: its own tables; `outside`: what the CLI
+    knows of it from the other checked files, if it's one of them.
+
+    Returns:
+      Its settings.
+
+    """
+    stored.hand(tree, {} if outside is None else outside.emptied)
+    # The functions' declared returns: other checked files' (see `Outside`), then the module's own.
+    calls: dict[str, str] = {**({} if outside is None else outside.calls), **own.returns, **own.side_calls}
+    imported: Classes | None = None if outside is None else outside.classes
+    # The bases whose members are known whole: the standard library's, and other checked files' below.
+    bases: dict[str, str] = stdlib.bases(tree, stdlib.origins(tree))
+    beyond: Mapping[str, inherited.Beyond] = {} if outside is None else outside.beyond
+    library: dict[str, inherited.Library] = {
+        text: (stdlib.members(path), stdlib.lines(path))
+        for text, path in (*bases.items(), *((end, end) for end in inherited.several(beyond)))
+        if path
+    }
+    # The file's own types that mention a type variable it imports (`--fix` sees only its own).
+    free: frozenset[str] = frozenset() if outside is None else outside.type_vars
+    selfish: dict[str, frozenset[str]] = self_returns(tree)
+    return Settings(
+        checks._replace(type_comments=checks.type_comments or python2_compatible(tree)),
+        lines,
+        Known(
+            free_of(calls, free),
+            factories(tree) | (frozenset[str]() if outside is None else outside.values),
+            {**(imported.attributes if imported else {}), **free_of_all(own.classes, free)},
+            {**(imported.methods if imported else {}), **free_of_all(own.methods, free)},
+            Indirect(
+                {**({} if outside is None else outside.awaits), **free_of(awaited_returns(tree), free)},
+                _partial(own, free, outside),
+                {**({} if outside is None else outside.tuples), **free_of(own.tuples, free)},
+                {**({} if outside is None else outside.unions), **own.unions},
+                {**({} if outside is None else outside.takers), **fills.takers(tree)},
+            ),
+            ClassSide(
+                free_of_all(own.order.flattened(class_attributes(tree)), free),
+                free_of_all(own.sides, free),
+                inherited.lineage(
+                    tree,
+                    selfish,
+                    # A base whose line the index followed is in sight too, another package's included.
+                    frozenset(bases).union(imported.methods if imported else (), beyond),
+                    beyond,
+                    library,
+                ),
+                classvars.variables(tree, classvars.imported(tree), outside, checks.plain_bases),
+                classvars.own_plain(tree, classvars.imported(tree), outside, checks.plain_bases),
+            ),
+            LibraryNames(
+                casts(tree),
+                stdlib.origins(tree),
+                # What annotations alone can name: its own imports for type checking, and other files' types'.
+                replace(
+                    imports.plan(tree),
+                    guarded={} if outside is None else {**outside.checking, **outside.guarded},
+                ),
+                {} if outside is None else outside.overloaded,
+                frozenset() if outside is None else outside.installed_classes,
+                {} if outside is None else outside.installed_parameters,
+                {} if outside is None else outside.installed_lineage,
+                {} if outside is None else outside.installed_aliases,
+                checks.min_python is not None and checks.min_python >= STARRED_SUBSCRIPTS,
+                checks.min_python is None or checks.min_python >= TYPING_ALIAS,
+            ),
+            Limits(checks.max_length, checks.vague, widened.marks(lines)),
+            vouched=passing(tree, defined_type_vars(tree)).union(
+                frozenset() if outside is None else outside.vouched,
+            ),
+        ),
+        Hierarchy.for_module(
+            tree,
+            {name: frozenset(wider) for name, wider in checks.narrower},
+            () if outside is None else outside.same,
+        ),
+        owners(tree, says_self),
+        tuple(
+            sorted(
+                (node.lineno, node.col_offset)
+                for node in cast("list[ast.NamedExpr]", of_type(tree, ast.NamedExpr))
+            ),
+        ),
+        () if outside is None else outside.hints,
+        facts(
+            tree,
+            selfish,
+            stdlib.generics(stdlib.origins(tree)) | (outside.generics if outside else frozenset[str]()),
+            {
+                **({} if outside is None else outside.managers),
+                **{name: (yielded, frozenset[str]()) for name, yielded in entered.managers(tree).items()},
+            },
+            defined_type_vars(tree) | free,
+        )._replace(
+            untyped=frozenset() if outside is None else outside.untyped,
+            attributed=frozenset(
+                node.value.id
+                for node in cast("list[ast.Attribute]", of_type(tree, ast.Attribute))
+                if isinstance(node.value, ast.Name)
+            ),
+            positional=callables.signatures(tree),
+            excused=late.excusing(lines),
+        ),
+        Seeded(
+            keyed(tree, {} if outside is None else outside.parameters),
+            {} if outside is None else outside.fixtures,
+            marked=marked(tree),
+        ),
+    )
+
+
+def _partial(own: Tables, free: frozenset[str], outside: Outside | None) -> Partial:
+    """Gather the returns only an unpacking can use: other checked files', then the module's own.
+
+    Returns:
+      Them, less the module's that mention a type variable it imports (`free`).
+
+    """
+    given: Partial = Partial() if outside is None else outside.partial
+    return Partial(
+        {**given.calls, **free_of(own.partial, free)},
+        {**given.methods, **free_of_all(own.partial_methods, free)},
+    )

constricter/rules/syntax.py

@@ -0,0 +1,472 @@
+# SPDX-License-Identifier: MIT
+"""Walking the syntax the rules read: functions and methods, nested statements, binding targets."""
+
+import ast
+import bisect
+import re
+from collections.abc import Callable, Iterable, Iterator, Sequence
+from typing import Final, TypeAlias, cast
+
+from constricter.offences import at
+from constricter.rules.walked import children as child_nodes
+from constricter.rules.walked import classes, of_type
+
+# A `# type:` comment, as a loop header writes one (LVA003).
+_TYPE_COMMENT: Final = re.compile(rb"#\s*type:")
+
+FunctionDef: TypeAlias = ast.FunctionDef | ast.AsyncFunctionDef
+FUNCTION_DEFS: tuple[type[ast.FunctionDef], type[ast.AsyncFunctionDef]] = (
+    ast.FunctionDef,
+    ast.AsyncFunctionDef,
+)
+# Statements whose nested statements may not all run (or not only once).
+BRANCHING: Final = (ast.If, ast.For, ast.AsyncFor, ast.While, ast.Try, ast.TryStar, ast.Match)
+_LEAVING: Final = (ast.Return, ast.Raise, ast.Continue, ast.Break)
+# The nodes with a scope of their own: what's inside one isn't the enclosing function's.
+NESTED_SCOPES: Final = (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda, ast.ClassDef)
+_END: Final = 1 << 62  # past any line: a module's span has no end
+Start: TypeAlias = tuple[int, int]  # where a node starts: its line and column
+_FUTURE: Final = "__future__"
+_SELF: Final = "self"
+# `from __future__` features only code that also runs on Python 2 imports: its type comments count.
+_PYTHON2_FUTURES: frozenset[str] = frozenset(
+    {
+        "nested_scopes",
+        "generators",
+        "division",
+        "absolute_import",
+        "with_statement",
+        "print_function",
+        "unicode_literals",
+    },
+)
+
+
+def python2_compatible(tree: ast.Module) -> bool:
+    """Check for a `from __future__` import only Python 2 needs.
+
+    Returns:
+      Whether it marks the module as written for Python 2.
+
+    """
+    return any(
+        isinstance(stmt, ast.ImportFrom)
+        and stmt.module == _FUTURE
+        and any(alias.name in _PYTHON2_FUTURES for alias in stmt.names)
+        for stmt in tree.body
+    )
+
+
+def collect_functions(body: list[ast.stmt], into: list[FunctionDef]) -> None:
+    """Collect functions in a module or class body, through compound statements and classes."""
+    stmt: ast.stmt
+    for stmt in body:
+        if isinstance(stmt, FUNCTION_DEFS):
+            into.append(stmt)
+        elif isinstance(stmt, ast.ClassDef):
+            collect_functions(stmt.body, into)
+        else:
+            collect_functions(child_statements(stmt), into)
+
+
+def owners(tree: ast.Module, selfish: Callable[[FunctionDef], bool]) -> dict[int, str]:
+    """Map each direct method of a class to that class's name, by the method's `id`.
+
+    For `--fix` to type a method's `self`. A method is a function directly in a class's body,
+    however deep through `if`/`try`/..., but not through a nested class's or function's own body.
+    A function defined in a method reads the method's `self` (see `_self_readers`): it's mapped
+    too, unless the method is one `selfish` says types its `self` otherwise (as `Self`).
+
+    Returns:
+      Each such function, by `id()`, mapped to its class's name.
+
+    """
+    found: dict[int, str] = {}
+    bindings: list[Start] = _self_bindings(tree)
+    node: ast.AST
+    methods: list[FunctionDef]
+    method: FunctionDef
+    for node in classes(tree):
+        methods = []
+        _direct_methods(node.body, methods)
+        for method in methods:
+            found[id(method)] = node.name
+            if (
+                _SELF in _first_parameter(method)
+                and not _binds_self(method, bindings)
+                and not selfish(method)
+            ):
+                found.update((id(inner), node.name) for inner in _self_readers(method, bindings))
+    return found
+
+
+def _self_bindings(tree: ast.Module) -> list[Start]:
+    """Find where the module binds a name `self` other than as a parameter (few do, anywhere).
+
+    Returns:
+      Where each such store, deletion or import starts, in source order.
+
+    """
+    return sorted(
+        (node.lineno, node.col_offset)
+        for node in cast("list[ast.Name | ast.alias]", of_type(tree, ast.Name, ast.alias))
+        if (
+            (node.id == _SELF and not isinstance(node.ctx, ast.Load))
+            if isinstance(node, ast.Name)
+            else (node.asname or node.name) == _SELF
+        )
+    )
+
+
+def _first_parameter(function: FunctionDef) -> list[str]:
+    """Name a function's first positional parameter.
+
+    Returns:
+      It, alone; nothing for a function without one.
+
+    """
+    return [arg.arg for arg in (*function.args.posonlyargs, *function.args.args)][:1]
+
+
+def _self_readers(function: FunctionDef, bindings: Sequence[Start]) -> Iterator[FunctionDef]:
+    """Walk the functions defined in `function`, however deep, that read its `self`.
+
+    One taking no parameter `self` and binding none, in a function that does neither (but
+    `function` itself, whose `self` it is). `bindings`: the module's `_self_bindings`.
+
+    Yields:
+      Each.
+
+    """
+    nested: list[FunctionDef] = []
+    _direct_methods(function.body, nested)
+    inner: FunctionDef
+    for inner in nested:
+        args: ast.arguments = inner.args
+        params: list[ast.arg | None] = [
+            *args.posonlyargs,
+            *args.args,
+            *args.kwonlyargs,
+            args.vararg,
+            args.kwarg,
+        ]
+        if not any(arg is not None and arg.arg == _SELF for arg in params) and not _binds_self(
+            inner,
+            bindings,
+        ):
+            yield inner
+            yield from _self_readers(inner, bindings)
+
+
+def _binds_self(function: FunctionDef, bindings: Sequence[Start]) -> bool:
+    """Check whether a function's own body binds `self` (an assignment, a loop, an import, ...).
+
+    `bindings`: where the module binds one at all (see `_self_bindings`): a function none is in
+    isn't walked.
+
+    Returns:
+      Whether it does.
+
+    """
+    return has_within(bindings, function) and any(
+        (isinstance(node, ast.Name) and node.id == _SELF and not isinstance(node.ctx, ast.Load))
+        or (isinstance(node, ast.alias) and (node.asname or node.name) == _SELF)
+        for node in own_nodes(function.body)
+    )
+
+
+def _direct_methods(body: list[ast.stmt], into: list[FunctionDef]) -> None:
+    """Collect the functions directly in a class's body, through compound statements.
+
+    A nested class's own methods aren't included.
+    """
+    stmt: ast.stmt
+    for stmt in body:
+        if isinstance(stmt, FUNCTION_DEFS):
+            into.append(stmt)
+        elif not isinstance(stmt, ast.ClassDef):
+            _direct_methods(child_statements(stmt), into)
+
+
+def import_bindings(body: Iterable[ast.stmt]) -> Iterator[tuple[str, str, str]]:
+    """Walk the absolute imports among `body`, and what each name they bind is.
+
+    `import os` binds `os` to `os` (and `import os.path` binds `os` too); `import os.path as p`
+    binds `p` to `os.path`; `from os import getpid as pid` binds `pid` to `os.getpid`. A relative
+    import names no module here.
+
+    Yields:
+      Each bound name, its dotted origin, and the module it comes from: an `import`'s top-level
+      package, a `from` import's module.
+
+    """
+    stmt: ast.stmt
+    module: str
+    alias: ast.alias
+    for stmt in body:
+        match stmt:
+            case ast.Import():
+                for alias in stmt.names:
+                    top: str = alias.name.split(".", 1)[0]
+                    yield alias.asname or top, alias.name if alias.asname else top, top
+            case ast.ImportFrom(module=str() as module, level=0):
+                for alias in stmt.names:
+                    yield alias.asname or alias.name, f"{module}.{alias.name}", module
+            case _:
+                pass
+
+
+def within(starts: Sequence[Start], node: ast.AST, begin: Start | None = None) -> slice:
+    """Find which of `starts` (in source order) are within `node`'s span of the source.
+
+    `begin`, if given, is where the span starts instead (a function's first decorator, say). A node
+    with no position (the module) spans everything.
+
+    Returns:
+      Their slice.
+
+    """
+    return slice(*_bounds(starts, node, begin))
+
+
+def has_within(starts: Sequence[Start], node: ast.AST) -> bool:
+    """Check whether any of `starts` (in source order) is within `node`'s span (see `within`).
+
+    Returns:
+      Whether one is.
+
+    """
+    first: int
+    stop: int
+    first, stop = _bounds(starts, node, None)
+    return stop > first
+
+
+def _bounds(starts: Sequence[Start], node: ast.AST, begin: Start | None) -> tuple[int, int]:
+    """Find where `node`'s span (from `begin`, if given) starts and stops among `starts`.
+
+    Returns:
+      The first index within it, and the first past it.
+
+    """
+    first: Start = begin or (getattr(node, "lineno", 0), getattr(node, "col_offset", 0))
+    end: Start = (getattr(node, "end_lineno", _END) or _END, getattr(node, "end_col_offset", 0) or 0)
+    return bisect.bisect_left(starts, first), bisect.bisect_left(starts, end)
+
+
+def own_nodes(found: Sequence[ast.AST], parents: dict[int, ast.AST] | None = None) -> Iterator[ast.AST]:
+    """Walk `found`, depth first in source order, without entering a nested function, lambda or class.
+
+    `parents`, if given, records each node's parent (by `id()`) before the node is yielded.
+
+    Yields:
+      Each node, a nested scope's own too (but not what's inside it).
+
+    """
+    # A stack, not a recursion: a nested generator passes each node up through every level above it.
+    waiting: list[ast.AST | None] = [None, *reversed(found)]  # `None` at its bottom ends it
+    node: ast.AST
+    for node in iter(waiting.pop, None):
+        yield node
+        if not isinstance(node, NESTED_SCOPES):
+            below: list[ast.AST] = child_nodes(node)
+            if parents is not None:
+                parents.update((id(child), node) for child in below)
+            waiting.extend(reversed(below))
+
+
+def top_level(body: Sequence[ast.stmt]) -> Iterator[ast.stmt]:
+    """Walk a module's top-level statements, those under its `if`s and `try`s too.
+
+    Yields:
+      Each.
+
+    """
+    stmt: ast.stmt
+    for stmt in body:
+        yield stmt
+        if isinstance(stmt, ast.If | ast.Try | ast.TryStar):
+            yield from top_level(child_statements(stmt))
+
+
+def child_statements(stmt: ast.stmt) -> list[ast.stmt]:
+    """Collect the statements nested directly in `stmt`.
+
+    Returns:
+      Them, in source order.
+
+    """
+    children: list[ast.stmt] = []
+    handler: ast.ExceptHandler
+    case: ast.match_case
+    match stmt:
+        case ast.If() | ast.For() | ast.AsyncFor() | ast.While():
+            children += stmt.body + stmt.orelse
+        case ast.With() | ast.AsyncWith():
+            children += stmt.body
+        case ast.Try() | ast.TryStar():
+            children += stmt.body
+            for handler in stmt.handlers:
+                children += handler.body
+            children += stmt.orelse + stmt.finalbody
+        case ast.Match():
+            for case in stmt.cases:
+                children += case.body
+        case _:
+            pass
+    return children
+
+
+def arm_ends(stmt: ast.stmt) -> frozenset[int]:
+    """Find where each arm of a branching statement ends: a body, an `else`, a handler, a `match` case.
+
+    Returns:
+      Each arm's last statement, by its `id()`; not one that leaves (`return`, `raise`, ...), past
+      which its arm doesn't go on.
+
+    """
+    blocks: list[list[ast.stmt]]
+    match stmt:
+        case ast.If() | ast.For() | ast.AsyncFor() | ast.While():
+            blocks = [stmt.body, stmt.orelse]
+        case ast.Try() | ast.TryStar():
+            blocks = [stmt.body, *(handler.body for handler in stmt.handlers), stmt.orelse]
+        case _:  # a `match`, the one other branching statement
+            blocks = [case.body for case in cast("ast.Match", stmt).cases]
+    return frozenset(id(block[-1]) for block in blocks if block and not isinstance(block[-1], _LEAVING))
+
+
+def expressions(stmt: ast.stmt) -> Iterator[ast.AST]:
+    """Walk the parts of `stmt` that aren't statements.
+
+    Yields:
+      Each, as where a `:=` can bind.
+
+    """
+    child: ast.AST
+    for child in child_nodes(stmt):
+        if isinstance(child, ast.match_case | ast.ExceptHandler):
+            yield from (part for part in child_nodes(child) if not isinstance(part, ast.stmt))
+        elif not isinstance(child, ast.stmt):
+            yield child
+
+
+def target_names(target: ast.expr) -> Iterator[ast.Name]:
+    """Walk an assignment target.
+
+    Yields:
+      Each plain name it binds.
+
+    """
+    elements: list[ast.expr]
+    element: ast.expr
+    value: ast.expr
+    match target:
+        case ast.Name():
+            yield target
+        case ast.Tuple(elts=elements) | ast.List(elts=elements):
+            for element in elements:
+                yield from target_names(element)
+        case ast.Starred(value=value):
+            yield from target_names(value)
+        case _:
+            return
+
+
+def captures(pattern: ast.pattern, lines: Sequence[str]) -> Iterator[tuple[str, tuple[int, int]]]:
+    """Walk a `case` pattern.
+
+    Yields:
+      Each name it captures, with where it's bound.
+
+    """
+    node: ast.AST
+    name: str
+    for node in ast.walk(pattern):
+        match node:
+            case ast.MatchAs(name=str() as name) | ast.MatchStar(name=str() as name):
+                yield name, at(node)
+            case ast.MatchMapping(rest=str() as name):
+                yield name, _rest_at(node, name, lines)
+            case _:
+                pass
+
+
+_REST: Final = re.compile(rb"\*\*\s*(\w+)\b")
+
+
+def _rest_at(node: ast.MatchMapping, name: str, lines: Sequence[str]) -> tuple[int, int]:
+    """Find `**name` in a mapping pattern's source.
+
+    Returns:
+      Its position (as `ast` gives it, a byte column), or else the pattern's start.
+
+    """
+    target: bytes = name.encode()
+    number: int
+    encoded: bytes
+    start: int
+    found: re.Match[bytes]
+    for number in range(node.lineno, min(node.end_lineno or node.lineno, len(lines)) + 1):
+        encoded = lines[number - 1].encode()
+        start = node.col_offset if number == node.lineno else 0
+        for found in _REST.finditer(encoded, start):
+            if found.group(1) == target:
+                return number, found.start(1)
+    return at(node)
+
+
+def comment_type(comment: str) -> str | None:
+    """Read a loop's `# type:` comment as an annotation (`int, str` is a tuple's parts).
+
+    Returns:
+      It, or `None` if it doesn't parse as one.
+
+    """
+    text: str = comment.split("#", 1)[0].strip()  # a trailing comment (a noqa one, say) isn't part of it
+    try:
+        parsed: ast.expr = ast.parse(text, mode="eval").body
+    except SyntaxError:
+        return None
+    if isinstance(parsed, ast.Tuple):
+        return f"tuple[{', '.join(ast.unparse(part) for part in parsed.elts)}]"
+    return ast.unparse(parsed)
+
+
+def declared_return(func: FunctionDef) -> ast.expr | None:
+    """Read the return type a function declares: its annotation, or its `# type:` signature comment's.
+
+    `def find():  # type: () -> List[str]` declares a `List[str]`, as a type checker reads it.
+
+    Returns:
+      It, or `None` for a function declaring none (or a comment that isn't a signature).
+
+    """
+    if func.returns is not None or not func.type_comment:
+        return func.returns
+    try:
+        return ast.parse(func.type_comment, mode="func_type").returns
+    except SyntaxError:
+        return None
+
+
+def type_comment_span(lines: Sequence[str], stmt: ast.For | ast.AsyncFor) -> tuple[int, int] | None:
+    """Find the columns (UTF-8 bytes) of a one-line loop header's `# type:` comment, to delete it.
+
+    From the end of the header's code (or, with a comment after it, `# type: int  # noqa`, from the
+    `#`), up to that comment or the end of the line, so the other comment stays.
+
+    Returns:
+      Them, or `None` if the header spans lines or the comment isn't found after the iterable.
+
+    """
+    if not lines or stmt.body[0].lineno == stmt.lineno or stmt.iter.end_lineno != stmt.lineno:
+        return None
+    raw: bytes = lines[stmt.lineno - 1].encode()
+    found: re.Match[bytes] | None
+    if (found := _TYPE_COMMENT.search(raw, stmt.iter.end_col_offset or 0)) is None:
+        return None
+    after: int
+    if (after := raw.find(b"#", found.end())) >= 0:
+        return found.start(), after
+    return len(raw[: found.start()].rstrip()), len(raw.rstrip(b"\r\n"))