pylint-complex-struct 0.1.0__py3-none-any.whl

pylint_complex_struct/__init__.py

@@ -0,0 +1,21 @@
+"""A pylint checker for over-nested type annotations.
+
+Load it with ``pylint --load-plugins=pylint_complex_struct``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .checker import ComplexStructChecker
+
+if TYPE_CHECKING:
+    from pylint.lint import PyLinter
+
+__version__ = "0.1.0"
+__all__ = ["ComplexStructChecker", "register"]
+
+
+def register(linter: PyLinter) -> None:
+    """Entry point called by pylint when the plugin is loaded."""
+    linter.register_checker(ComplexStructChecker(linter))

pylint_complex_struct/checker.py

@@ -0,0 +1,380 @@
+"""The pylint checker: where annotations are collected and messages emitted."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Iterator, NamedTuple
+
+from astroid import nodes
+from pylint.checkers import BaseChecker
+from pylint.interfaces import HIGH
+
+from .depth import MAX_LEVEL, Policy, Verdict, flatten_union, measure, namedtuple_candidate
+from .names import GENERIC_ORIGINS, ImportMap, is_type_alias_annotation, resolve_head
+
+if TYPE_CHECKING:
+    from pylint.lint import PyLinter
+
+VALID_SCOPES = frozenset({"returns", "params", "attributes", "locals", "aliases"})
+
+
+class MessageKey(NamedTuple):
+    """Identity of an emitted message, for the belt-and-braces dedup set."""
+
+    symbol: str
+    lineno: int
+    col_offset: int
+
+
+class AnnotationSite(NamedTuple):
+    """One annotation found on a function signature."""
+
+    annotation: nodes.NodeNG
+    name: str
+
+
+def _depth_reason(verdict: Verdict, budget: int) -> str:
+    """Phrase the budget breach, without inventing a number for a truncated walk."""
+    if verdict.truncated:
+        return f"nesting depth over {MAX_LEVEL} > {budget}"
+    return f"nesting depth {verdict.depth} > {budget}"
+
+
+class ComplexStructChecker(BaseChecker):
+    """Push nested inline annotations towards aliases, NamedTuples and TypedDicts."""
+
+    name = "complex-struct"
+
+    msgs = {
+        "R9501": (
+            "Type annotation of %s is too complex (%s); extract a type alias, "
+            "a NamedTuple or a TypedDict",
+            "complex-type-annotation",
+            "Emitted when a type annotation nests type constructors more deeply, or "
+            "spells out more type terms, than the configured budget. A reference to a "
+            "type alias counts as a single term, so extracting an alias always fixes "
+            "the message.",
+        ),
+        "R9502": (
+            "Type alias %s is too complex (%s); compose it from smaller aliases",
+            "complex-type-alias",
+            "Emitted when the body of a type alias exceeds the (laxer) alias budget. "
+            "Composing aliases is encouraged; hiding one unreadable structure behind a "
+            "single name is not.",
+        ),
+        "R9503": (
+            "%s is a heterogeneous %d-field tuple; return a NamedTuple (or a "
+            "dataclass) so the fields have names",
+            "tuple-should-be-namedtuple",
+            "Emitted when a function returns a fixed-size tuple of differing types, "
+            "forcing every call site to unpack it positionally.",
+        ),
+    }
+
+    options = (
+        (
+            "max-annotation-complexity",
+            {
+                "default": 2,
+                "type": "int",
+                "metavar": "<int>",
+                "help": "Maximum nesting depth of a type annotation. 'int' is 1, "
+                "'list[int]' is 2, 'dict[str, list[int]]' is 3. A reference to a type "
+                "alias counts as 1, whatever the alias expands to.",
+            },
+        ),
+        (
+            "max-alias-complexity",
+            {
+                "default": 3,
+                "type": "int",
+                "metavar": "<int>",
+                "help": "Maximum nesting depth allowed in the body of a type alias "
+                "('type X = ...', 'X: TypeAlias = ...'). Laxer than "
+                "max-annotation-complexity, because absorbing structure is what an "
+                "alias is for.",
+            },
+        ),
+        (
+            "max-annotation-terms",
+            {
+                "default": 7,
+                "type": "int",
+                "metavar": "<int>",
+                "help": "Maximum number of type terms (leaves) in one annotation; a "
+                "Literal[...] counts as one term. Set to 0 to disable.",
+            },
+        ),
+        (
+            "count-optional-as-nesting",
+            {
+                "default": False,
+                "type": "yn",
+                "metavar": "<y or n>",
+                "help": "Count 'Optional[X]' and 'X | None' as a level of nesting.",
+            },
+        ),
+        (
+            "count-union-as-nesting",
+            {
+                "default": True,
+                "type": "yn",
+                "metavar": "<y or n>",
+                "help": "Count a union of two or more non-None members as a level of "
+                "nesting. Applies equally to 'A | B' and 'Union[A, B]'.",
+            },
+        ),
+        (
+            "count-callable-params-as-nesting",
+            {
+                "default": False,
+                "type": "yn",
+                "metavar": "<y or n>",
+                "help": "Count the parameter-list bracket of 'Callable[[A, B], R]' as a "
+                "level of nesting. The parameter types themselves are always counted.",
+            },
+        ),
+        (
+            "namedtuple-check-scope",
+            {
+                "default": ("returns",),
+                "type": "csv",
+                "metavar": "<scopes>",
+                "help": "Where to suggest a NamedTuple for heterogeneous fixed-size "
+                "tuples: any of returns, params, attributes, locals, aliases. Empty "
+                "disables the check.",
+            },
+        ),
+        (
+            "min-namedtuple-fields",
+            {
+                "default": 2,
+                "type": "int",
+                "metavar": "<int>",
+                "help": "Minimum number of elements a heterogeneous tuple must have "
+                "before a NamedTuple is suggested.",
+            },
+        ),
+        (
+            "check-implicit-type-aliases",
+            {
+                "default": False,
+                "type": "yn",
+                "metavar": "<y or n>",
+                "help": "Also treat unannotated module- or class-level assignments whose "
+                "value is a generic subscription ('Rows = dict[str, list[int]]') as type "
+                "aliases.",
+            },
+        ),
+    )
+
+    def __init__(self, linter: PyLinter | None = None) -> None:
+        super().__init__(linter)
+        self._imports = ImportMap()
+        self._policy: Policy | None = None
+        self._reported: set[MessageKey] = set()
+        self._skip_module = False
+
+    # -- lifecycle ------------------------------------------------------------
+
+    def open(self) -> None:
+        """Validate the options once, so a typo is not silently ignored."""
+        unknown = sorted(set(self.linter.config.namedtuple_check_scope) - VALID_SCOPES - {""})
+        if unknown:
+            raise ValueError(
+                f"{self.name}: unknown namedtuple-check-scope value(s) {unknown}; "
+                f"valid values are {sorted(VALID_SCOPES)}"
+            )
+
+    def visit_module(self, node: nodes.Module) -> None:
+        """Reset per-module state and resolve the options."""
+        self._imports = ImportMap()
+        self._reported = set()
+        self._policy = self._build_policy()
+        # Stubs describe APIs the author often cannot refactor.
+        self._skip_module = bool(node.file and node.file.endswith(".pyi"))
+
+    def leave_module(self, _node: nodes.Module) -> None:
+        """Drop per-module state."""
+        self._imports = ImportMap()
+        self._reported = set()
+        self._policy = None
+        self._skip_module = False
+
+    def visit_import(self, node: nodes.Import) -> None:
+        """Record `import typing as t`."""
+        for name, alias in node.names:
+            self._imports.add_module(alias or name, name)
+
+    def visit_importfrom(self, node: nodes.ImportFrom) -> None:
+        """Record `from typing import Optional as Opt`."""
+        for name, alias in node.names:
+            self._imports.add_from(alias or name, node.modname, name)
+
+    # -- annotation sites -----------------------------------------------------
+
+    def visit_functiondef(self, node: nodes.FunctionDef) -> None:
+        """Check every parameter and the return annotation."""
+        if self._skip_module:
+            return
+        for annotation, arg_name in self._arg_annotations(node.args):
+            self._check(annotation, f"parameter '{arg_name}'", "params")
+        if node.returns is not None:
+            self._check(node.returns, f"the return value of '{node.name}'", "returns")
+
+    visit_asyncfunctiondef = visit_functiondef
+
+    def visit_annassign(self, node: nodes.AnnAssign) -> None:
+        """Check an annotated assignment, or a PEP 613 alias body."""
+        if self._skip_module:
+            return
+        if is_type_alias_annotation(node.annotation, self._imports):
+            # PEP 613. The annotation is just the marker; the alias body is the value.
+            if node.value is not None:
+                self._check_alias(node.value, self._target_name(node.target))
+            return
+        subject, scope = self._annassign_subject(node)
+        self._check(node.annotation, subject, scope)
+
+    def visit_typealias(self, node: nodes.TypeAlias) -> None:
+        """Check a PEP 695 `type X = ...` body."""
+        if self._skip_module:
+            return
+        self._check_alias(node.value, node.name.name)
+
+    def visit_assign(self, node: nodes.Assign) -> None:
+        """Check an unannotated assignment that looks like a type alias."""
+        policy = self._current_policy()
+        if self._skip_module or not policy.check_implicit_type_aliases:
+            return
+        if len(node.targets) != 1:
+            return
+        target = node.targets[0]
+        if not isinstance(target, nodes.AssignName):
+            return
+        # SCREAMING_CASE is a constant (PEP 8), not a type alias: `PEELABLE = TRANSPARENT
+        # | ANNOTATED` is a frozenset union, not a union type. Found by running this
+        # checker over its own source.
+        if target.name.isupper():
+            return
+        if not isinstance(node.scope(), (nodes.Module, nodes.ClassDef)):
+            return
+        if not self._looks_like_alias(node.value):
+            return
+        self._check_alias(node.value, target.name)
+
+    # -- checks ---------------------------------------------------------------
+
+    def _check(self, annotation: nodes.NodeNG, subject: str, scope: str) -> None:
+        policy = self._current_policy()
+        verdict = measure(annotation, policy, self._imports)
+        if verdict.depth > policy.max_annotation_complexity:
+            reason = _depth_reason(verdict, policy.max_annotation_complexity)
+            self._report("complex-type-annotation", annotation, (subject, reason))
+            return
+        if policy.max_annotation_terms and verdict.terms > policy.max_annotation_terms:
+            reason = f"{verdict.terms} type terms > {policy.max_annotation_terms}"
+            self._report("complex-type-annotation", annotation, (subject, reason))
+            return
+        self._check_heuristics(annotation, subject, scope)
+
+    def _check_alias(self, body: nodes.NodeNG, name: str) -> None:
+        policy = self._current_policy()
+        verdict = measure(body, policy, self._imports)
+        if verdict.depth > policy.max_alias_complexity:
+            reason = _depth_reason(verdict, policy.max_alias_complexity)
+            self._report("complex-type-alias", body, (f"'{name}'", reason))
+            return
+        if policy.max_annotation_terms and verdict.terms > policy.max_annotation_terms:
+            reason = f"{verdict.terms} type terms > {policy.max_annotation_terms}"
+            self._report("complex-type-alias", body, (f"'{name}'", reason))
+            return
+        self._check_heuristics(body, f"type alias '{name}'", "aliases")
+
+    def _check_heuristics(self, annotation: nodes.NodeNG, subject: str, scope: str) -> None:
+        policy = self._current_policy()
+        if scope not in policy.namedtuple_scopes:
+            return
+        candidate = namedtuple_candidate(annotation, self._imports, policy.min_namedtuple_fields)
+        if candidate is None:
+            return
+        self._report(
+            "tuple-should-be-namedtuple",
+            candidate.anchor,
+            (subject[:1].upper() + subject[1:], candidate.fields),
+        )
+
+    def _report(self, symbol: str, node: nodes.NodeNG, args: tuple[object, ...]) -> None:
+        key = MessageKey(symbol, node.lineno or 0, node.col_offset or 0)
+        if key in self._reported:
+            return
+        self._reported.add(key)
+        self.add_message(symbol, node=node, args=args, confidence=HIGH)
+
+    # -- helpers --------------------------------------------------------------
+
+    def _current_policy(self) -> Policy:
+        # Normally built in visit_module; rebuilt lazily so that calling a single
+        # visitor in isolation (as the unit tests do) still works.
+        if self._policy is None:
+            self._policy = self._build_policy()
+        return self._policy
+
+    def _build_policy(self) -> Policy:
+        config = self.linter.config
+        scopes = frozenset(s for s in config.namedtuple_check_scope if s)
+        return Policy(
+            max_annotation_complexity=config.max_annotation_complexity,
+            max_alias_complexity=config.max_alias_complexity,
+            max_annotation_terms=config.max_annotation_terms,
+            count_optional=config.count_optional_as_nesting,
+            count_union=config.count_union_as_nesting,
+            count_callable_params=config.count_callable_params_as_nesting,
+            min_namedtuple_fields=config.min_namedtuple_fields,
+            namedtuple_scopes=scopes,
+            check_implicit_type_aliases=config.check_implicit_type_aliases,
+        )
+
+    @staticmethod
+    def _arg_annotations(args: nodes.Arguments) -> Iterator[AnnotationSite]:
+        groups = (
+            (args.posonlyargs, args.posonlyargs_annotations),
+            (args.args, args.annotations),
+            (args.kwonlyargs, args.kwonlyargs_annotations),
+        )
+        for arg_nodes, annotations in groups:
+            for arg, annotation in zip(arg_nodes or [], annotations or []):
+                if annotation is not None:
+                    yield AnnotationSite(annotation, arg.name)
+        if args.varargannotation is not None:
+            yield AnnotationSite(args.varargannotation, args.vararg)
+        if args.kwargannotation is not None:
+            yield AnnotationSite(args.kwargannotation, args.kwarg)
+
+    @staticmethod
+    def _target_name(target: nodes.NodeNG) -> str:
+        return getattr(target, "name", None) or target.as_string()
+
+    def _annassign_subject(self, node: nodes.AnnAssign) -> tuple[str, str]:
+        target = node.target
+        if isinstance(target, nodes.AssignAttr):
+            return f"attribute '{target.as_string()}'", "attributes"
+        name = self._target_name(target)
+        scope = node.scope()
+        if isinstance(scope, nodes.ClassDef):
+            return f"attribute '{name}'", "attributes"
+        if isinstance(scope, nodes.Module):
+            return f"variable '{name}'", "locals"
+        return f"local variable '{name}'", "locals"
+
+    def _looks_like_alias(self, value: nodes.NodeNG | None) -> bool:
+        """Tell `Rows = dict[str, int]` from `rows = cache["key"]`, syntactically."""
+        if isinstance(value, nodes.Subscript):
+            return resolve_head(value.value, self._imports) in GENERIC_ORIGINS
+        if isinstance(value, nodes.BinOp) and value.op == "|":
+            members = flatten_union(value)
+            return all(
+                isinstance(m, (nodes.Name, nodes.Attribute, nodes.Subscript))
+                or (isinstance(m, nodes.Const) and m.value is None)
+                for m in members
+            )
+        return False

pylint_complex_struct/depth.py

@@ -0,0 +1,348 @@
+"""The annotation complexity metric.  Pure, and deliberately inference-free.
+
+This module must not import pylint, so that the metric can be unit-tested with
+nothing but ``astroid.extract_node``.
+
+It must also never ask astroid what a name *refers to* -- no inference, no scope
+lookups.  A name is always a leaf, whatever it expands to.  That is not a
+shortcut, it is the whole point: it makes the rule actionable, because pulling a
+subtree out into an alias mechanically brings the score back within budget and
+re-linting the fixed file is clean.  A metric that expanded aliases would score
+the fixed code exactly like the original, and there would be no legal way to
+write the type at all.  ``tests/test_no_inference.py`` enforces this by grepping
+the source of this module.
+"""
+
+from __future__ import annotations
+
+import functools
+from dataclasses import dataclass
+from typing import NamedTuple
+
+import astroid
+from astroid import nodes
+
+from .names import (
+    ANNOTATED,
+    CALLABLE,
+    COROUTINE,
+    LITERAL,
+    NONE_NAMES,
+    OPTIONAL,
+    PEELABLE,
+    TRANSPARENT,
+    TUPLE_HEADS,
+    UNION,
+    UNPACK,
+    ImportMap,
+    resolve_head,
+)
+
+#: Nesting beyond this is over any sane budget, so we stop walking and say so
+#: rather than risking a RecursionError inside pylint.
+MAX_LEVEL = 32
+#: Guard against machine-generated monsters.
+MAX_NODES = 2000
+
+_PARSEABLE = (
+    nodes.Name,
+    nodes.Attribute,
+    nodes.Subscript,
+    nodes.BinOp,
+    nodes.Const,
+    nodes.Tuple,
+    nodes.List,
+    nodes.Starred,
+)
+
+
+@dataclass(frozen=True)
+class Policy:  # pylint: disable=too-many-instance-attributes  # a bundle of options
+    """Resolved option values, built once per module."""
+
+    max_annotation_complexity: int = 2
+    max_alias_complexity: int = 3
+    max_annotation_terms: int = 7
+    count_optional: bool = False
+    count_union: bool = True
+    count_callable_params: bool = False
+    min_namedtuple_fields: int = 2
+    namedtuple_scopes: frozenset[str] = frozenset({"returns"})
+    check_implicit_type_aliases: bool = False
+
+
+@dataclass
+class Verdict:
+    """What one annotation scored."""
+
+    depth: int
+    terms: int
+    #: True when the walk hit MAX_LEVEL or MAX_NODES, so `depth` is a floor.
+    truncated: bool = False
+
+
+@dataclass
+class _Ctx:
+    """Per-annotation walk state."""
+
+    policy: Policy
+    imports: ImportMap
+    terms: int = 0
+    seen: int = 0
+    truncated: bool = False
+
+    def budget_left(self) -> bool:
+        """Count one node and report whether the walk may continue."""
+        self.seen += 1
+        return self.seen <= MAX_NODES
+
+    def leaf(self) -> int:
+        """Record a type term and score it as a leaf."""
+        self.terms += 1
+        return 1
+
+
+@functools.lru_cache(maxsize=512)
+def parse_forward_ref(text: str) -> nodes.NodeNG | None:
+    """Parse a quoted annotation.  Quoting must not be an escape hatch.
+
+    Failure is always silent and scores as a leaf: annotations like
+    ``x: "the widget id"`` are prose, not types, and reporting on them would be
+    worse than missing them.
+    """
+    stripped = text.strip()
+    if not stripped or len(stripped) > 512 or "\n" in stripped:
+        return None
+    try:
+        node = astroid.extract_node(stripped)
+    except (astroid.AstroidSyntaxError, SyntaxError, ValueError, RecursionError, AttributeError):
+        return None
+    return node if isinstance(node, _PARSEABLE) else None
+
+
+def slice_elements(slice_node: nodes.NodeNG | None) -> list[nodes.NodeNG]:
+    """The arguments of a subscript.  ``dict[str, int]`` -> ``[str, int]``."""
+    if slice_node is None:
+        return []
+    if isinstance(slice_node, nodes.Tuple):
+        return list(slice_node.elts)
+    return [slice_node]
+
+
+def flatten_union(node: nodes.BinOp) -> list[nodes.NodeNG]:
+    """Flatten ``a | b | c`` iteratively.
+
+    Not an optimisation: ``|`` parses left-deep, so a generated thousand-member
+    union would otherwise recurse a thousand frames and blow the stack inside
+    pylint.
+    """
+    out: list[nodes.NodeNG] = []
+    stack: list[nodes.NodeNG] = [node]
+    while stack:
+        current = stack.pop()
+        if isinstance(current, nodes.BinOp) and current.op == "|":
+            stack.append(current.left)
+            stack.append(current.right)
+        else:
+            out.append(current)
+    return out
+
+
+def is_ellipsis(node: nodes.NodeNG | None) -> bool:
+    """True for the `...` in `tuple[int, ...]` and `Callable[..., R]`."""
+    return isinstance(node, nodes.Const) and node.value is Ellipsis
+
+
+def is_none(node: nodes.NodeNG | None) -> bool:
+    """True for every spelling of the None type."""
+    if isinstance(node, nodes.Const) and node.value is None:
+        return True
+    if isinstance(node, nodes.Name) and node.name in NONE_NAMES:
+        return True
+    return isinstance(node, nodes.Attribute) and node.attrname == "NoneType"
+
+
+def _max0(values: list[int]) -> int:
+    return max(values) if values else 0
+
+
+def _depth(  # pylint: disable=too-many-return-statements  # one return per node kind
+    node: nodes.NodeNG | None, ctx: _Ctx, level: int
+) -> int:
+    if node is None:
+        return 0
+    if level >= MAX_LEVEL or not ctx.budget_left():
+        ctx.truncated = True
+        return MAX_LEVEL
+
+    if isinstance(node, (nodes.Name, nodes.Attribute)):
+        return ctx.leaf()
+
+    if isinstance(node, nodes.Const):
+        if node.value is Ellipsis:
+            return 0
+        if isinstance(node.value, str):
+            parsed = parse_forward_ref(node.value)
+            if parsed is None:
+                return ctx.leaf()
+            return _depth(parsed, ctx, level + 1)
+        return ctx.leaf()
+
+    if isinstance(node, nodes.Starred):
+        return _depth(node.value, ctx, level + 1)
+
+    if isinstance(node, (nodes.Tuple, nodes.List)):
+        # A bare bracket: a subscript's argument list, or Callable's parameter
+        # list.  Syntax, not nesting, so no +1.
+        return _max0([_depth(elt, ctx, level + 1) for elt in node.elts])
+
+    if isinstance(node, nodes.BinOp):
+        if node.op == "|":
+            return _union_depth(flatten_union(node), ctx, level)
+        return ctx.leaf()
+
+    if isinstance(node, nodes.Subscript):
+        return _subscript_depth(node, ctx, level)
+
+    return ctx.leaf()
+
+
+def _union_depth(members: list[nodes.NodeNG], ctx: _Ctx, level: int) -> int:
+    real = [m for m in members if not is_none(m)]
+    had_none = len(real) != len(members)
+    if not real:
+        return ctx.leaf()
+    inner = max(_depth(m, ctx, level + 1) for m in real)
+    if len(real) == 1:
+        # Optional-equivalent.  Nullability is a bit on a shape, not a shape.
+        return inner + (1 if had_none and ctx.policy.count_optional else 0)
+    return inner + (1 if ctx.policy.count_union else 0)
+
+
+def _subscript_depth(  # pylint: disable=too-many-return-statements  # one per head kind
+    node: nodes.Subscript, ctx: _Ctx, level: int
+) -> int:
+    head = resolve_head(node.value, ctx.imports)
+    args = slice_elements(node.slice)
+
+    if head in LITERAL:
+        # Members are values, not types.  Recursing would also parse
+        # Literal["dict[str, int]"] as a forward reference.
+        return ctx.leaf()
+
+    if head in ANNOTATED:
+        # Metadata is arbitrary runtime objects; it has no type shape.
+        return _depth(args[0], ctx, level + 1) if args else ctx.leaf()
+
+    if head in TRANSPARENT:
+        inner = _depth(args[0], ctx, level + 1) if args else ctx.leaf()
+        if head in OPTIONAL and ctx.policy.count_optional:
+            return inner + 1
+        return inner
+
+    if head in UNION:
+        # Same code path as ``|`` so the two spellings can never disagree.
+        return _union_depth(args, ctx, level)
+
+    if head in CALLABLE:
+        if len(args) >= 2:
+            params, result = args[0], args[-1]
+        else:
+            params, result = None, (args[0] if args else None)
+        param_depth = 0 if is_ellipsis(params) else _depth(params, ctx, level + 1)
+        if ctx.policy.count_callable_params and param_depth:
+            param_depth += 1
+        return 1 + max(param_depth, _depth(result, ctx, level + 1), 1)
+
+    return 1 + _max0([_depth(arg, ctx, level + 1) for arg in args])
+
+
+def measure(node: nodes.NodeNG, policy: Policy, imports: ImportMap) -> Verdict:
+    """Score one annotation."""
+    ctx = _Ctx(policy=policy, imports=imports)
+    value = _depth(node, ctx, 0)
+    # Unwinding adds a level per frame, so a truncated walk can report more than
+    # MAX_LEVEL. Clamp it and let the caller say "over" instead of a made-up number.
+    return Verdict(
+        depth=min(value, MAX_LEVEL) if ctx.truncated else value,
+        terms=ctx.terms,
+        truncated=ctx.truncated,
+    )
+
+
+class Peeled(NamedTuple):
+    """A stripped annotation and the node a message about it should point at."""
+
+    node: nodes.NodeNG | None
+    anchor: nodes.NodeNG
+
+
+class TupleShape(NamedTuple):
+    """A fixed-size heterogeneous tuple found in an annotation."""
+
+    fields: int
+    anchor: nodes.NodeNG
+
+
+def peel(node: nodes.NodeNG, imports: ImportMap) -> Peeled:
+    """Strip wrappers that do not change "what shape is this really?".
+
+    The anchor stays on the original node once we descend into a parsed forward
+    reference, because those nodes carry positions from a synthetic module.
+    """
+    anchor = node
+    synthetic = False
+    for _ in range(MAX_LEVEL):
+        if isinstance(node, nodes.Const) and isinstance(node.value, str):
+            parsed = parse_forward_ref(node.value)
+            if parsed is None:
+                return Peeled(None, anchor)
+            node, synthetic = parsed, True
+            continue
+        if isinstance(node, nodes.BinOp) and node.op == "|":
+            real = [m for m in flatten_union(node) if not is_none(m)]
+            if len(real) != 1:
+                break
+            node = real[0]
+            if not synthetic:
+                anchor = node
+            continue
+        if isinstance(node, nodes.Subscript):
+            head = resolve_head(node.value, imports)
+            args = slice_elements(node.slice)
+            target = None
+            if head in PEELABLE and args:
+                target = args[0]
+            elif head in COROUTINE and len(args) == 3:
+                # Coroutine[Any, Any, X] must behave like `async def ... -> X`.
+                target = args[2]
+            if target is None:
+                break
+            node = target
+            if not synthetic:
+                anchor = node
+            continue
+        break
+    return Peeled(node, anchor)
+
+
+def namedtuple_candidate(  # pylint: disable=too-many-return-statements  # a filter chain
+    node: nodes.NodeNG, imports: ImportMap, min_fields: int
+) -> TupleShape | None:
+    """The tuple shape, if this annotation is a heterogeneous fixed-size tuple."""
+    peeled, anchor = peel(node, imports)
+    if not isinstance(peeled, nodes.Subscript):
+        return None
+    if resolve_head(peeled.value, imports) not in TUPLE_HEADS:
+        return None
+    elements = slice_elements(peeled.slice)
+    if len(elements) < max(min_fields, 1):
+        return None
+    for element in elements:
+        if is_ellipsis(element) or isinstance(element, nodes.Starred):
+            return None  # tuple[int, ...] is a sequence; tuple[*Ts] is polymorphic
+        if isinstance(element, nodes.Subscript) and resolve_head(element.value, imports) in UNPACK:
+            return None
+    if len({element.as_string() for element in elements}) < 2:
+        return None  # tuple[int, int] is a fixed-size vector, not a record
+    return TupleShape(len(elements), anchor)

pylint_complex_struct/names.py

@@ -0,0 +1,184 @@
+"""Syntactic resolution of typing construct names.
+
+Everything here is deliberately syntactic: the head of a subscript is resolved
+by looking at what was written and at the module's import statements, never by
+asking astroid what a name refers to.  See :mod:`pylint_complex_struct.depth`
+for why that matters.
+
+The one accepted cost is the bare-name fallback: a bare ``Optional`` is treated
+as ``typing.Optional`` even with no visible import, because re-exports and
+``if TYPE_CHECKING`` blocks are common.  A user-defined class literally named
+``Optional`` is therefore mis-classified.  That is documented and tested.
+"""
+
+from __future__ import annotations
+
+from astroid import nodes
+
+# --- canonical category sets -------------------------------------------------
+
+LITERAL = frozenset({"typing.Literal"})
+ANNOTATED = frozenset({"typing.Annotated"})
+UNION = frozenset({"typing.Union"})
+OPTIONAL = frozenset({"typing.Optional"})
+CALLABLE = frozenset({"typing.Callable"})
+UNPACK = frozenset({"typing.Unpack"})
+AWAITABLE = frozenset({"typing.Awaitable"})
+COROUTINE = frozenset({"typing.Coroutine"})
+TUPLE_HEADS = frozenset({"builtins.tuple"})
+TYPE_ALIAS_NAMES = frozenset({"typing.TypeAlias"})
+
+#: Wrappers that describe how a name is *used* rather than what shape it holds.
+#: ``depth(Wrapper[T]) == depth(T)``.
+TRANSPARENT = frozenset(
+    {
+        "typing.Optional",
+        "typing.Final",
+        "typing.ClassVar",
+        "typing.Required",
+        "typing.NotRequired",
+        "typing.ReadOnly",
+        "typing.Unpack",
+        "typing.TypeGuard",
+        "typing.TypeIs",
+        "dataclasses.InitVar",
+    }
+)
+
+#: Wrappers peeled off before asking "is this really a record?".
+#: ``Coroutine`` is handled separately because the payload is the third argument.
+PEELABLE = TRANSPARENT | ANNOTATED | AWAITABLE
+
+#: Heads that make an unannotated assignment look like a type alias.
+GENERIC_ORIGINS = frozenset(
+    {
+        "builtins.dict",
+        "builtins.list",
+        "builtins.tuple",
+        "builtins.set",
+        "builtins.frozenset",
+        "builtins.type",
+        "collections.abc.Mapping",
+        "collections.abc.MutableMapping",
+        "collections.abc.Sequence",
+        "collections.abc.Iterable",
+        "collections.abc.Iterator",
+        "collections.defaultdict",
+        "collections.deque",
+    }
+    | TRANSPARENT
+    | ANNOTATED
+    | UNION
+    | CALLABLE
+    | LITERAL
+    | AWAITABLE
+    | COROUTINE
+)
+
+_CANONICAL = {
+    "typing.Dict": "builtins.dict",
+    "typing.List": "builtins.list",
+    "typing.Tuple": "builtins.tuple",
+    "typing.Set": "builtins.set",
+    "typing.FrozenSet": "builtins.frozenset",
+    "typing.Type": "builtins.type",
+    "typing.DefaultDict": "collections.defaultdict",
+    "typing.Deque": "collections.deque",
+    "typing.Mapping": "collections.abc.Mapping",
+    "typing.MutableMapping": "collections.abc.MutableMapping",
+    "typing.Sequence": "collections.abc.Sequence",
+    "typing.Iterable": "collections.abc.Iterable",
+    "typing.Iterator": "collections.abc.Iterator",
+    "collections.abc.Callable": "typing.Callable",
+    "collections.abc.Awaitable": "typing.Awaitable",
+    "collections.abc.Coroutine": "typing.Coroutine",
+}
+
+_TYPING_BARE = (
+    "Optional Union Literal Annotated Callable Final ClassVar Required NotRequired "
+    "ReadOnly Unpack TypeGuard TypeIs Awaitable Coroutine TypeAlias Dict List Tuple "
+    "Set FrozenSet Type DefaultDict Deque Mapping MutableMapping Sequence Iterable "
+    "Iterator"
+).split()
+
+_BARE_FALLBACK: dict[str, str] = {
+    name: _CANONICAL.get(f"typing.{name}", f"typing.{name}") for name in _TYPING_BARE
+}
+_BARE_FALLBACK.update(
+    {name: f"builtins.{name}" for name in ("dict", "list", "tuple", "set", "frozenset", "type")}
+)
+_BARE_FALLBACK["InitVar"] = "dataclasses.InitVar"
+# collections.abc spellings that are commonly imported bare
+_BARE_FALLBACK.update(
+    {
+        name: f"collections.abc.{name}"
+        for name in ("Mapping", "MutableMapping", "Sequence", "Iterable", "Iterator")
+    }
+)
+
+NONE_NAMES = frozenset({"None", "NoneType"})
+
+
+class ImportMap:
+    """Per-module map from locally visible names to canonical dotted names."""
+
+    __slots__ = ("_modules", "_names")
+
+    def __init__(self) -> None:
+        self._modules: dict[str, str] = {}
+        self._names: dict[str, str] = {}
+
+    def add_module(self, local: str, dotted: str) -> None:
+        """Record ``import typing as t`` as ``t -> typing``."""
+        self._modules[local] = dotted
+
+    def add_from(self, local: str, modname: str, name: str) -> None:
+        """Record ``from typing import Optional as Opt`` as ``Opt -> typing.Optional``."""
+        self._names[local] = f"{modname}.{name}" if modname else name
+
+    def resolve_prefix(self, local: str) -> str | None:
+        """The module a dotted head starts from, e.g. `t` in `t.Dict`."""
+        return self._modules.get(local) or self._names.get(local)
+
+    def resolve_name(self, local: str) -> str | None:
+        """The canonical name a bare identifier was imported as."""
+        return self._names.get(local)
+
+
+def dotted_name(node: nodes.NodeNG | None) -> str | None:
+    """``t.Dict`` -> ``"t.Dict"``; anything that is not a dotted name -> ``None``."""
+    if isinstance(node, nodes.Name):
+        return node.name
+    if isinstance(node, nodes.Attribute):
+        prefix = dotted_name(node.expr)
+        return f"{prefix}.{node.attrname}" if prefix else None
+    return None
+
+
+def canonical(dotted: str) -> str:
+    """Fold spelling variants together: `typing_extensions.X` and `typing.Dict`."""
+    if dotted.startswith("typing_extensions."):
+        dotted = "typing." + dotted.split(".", 1)[1]
+    return _CANONICAL.get(dotted, dotted)
+
+
+def resolve_head(node: nodes.NodeNG | None, imports: ImportMap) -> str | None:
+    """Canonical dotted name for the head of a subscript, or ``None`` if unknown."""
+    dotted = dotted_name(node)
+    if dotted is None:
+        return None
+    parts = dotted.split(".")
+    if len(parts) == 1:
+        qualified = imports.resolve_name(parts[0])
+        if qualified is not None:
+            return canonical(qualified)
+        return _BARE_FALLBACK.get(parts[0])
+    prefix = imports.resolve_prefix(parts[0])
+    if prefix is not None:
+        parts = prefix.split(".") + parts[1:]
+    return canonical(".".join(parts))
+
+
+def is_type_alias_annotation(node: nodes.NodeNG | None, imports: ImportMap) -> bool:
+    """True for the ``TypeAlias`` in ``Rows: TypeAlias = ...`` (PEP 613)."""
+    return resolve_head(node, imports) in TYPE_ALIAS_NAMES

pylint_complex_struct-0.1.0.dist-info/METADATA

@@ -0,0 +1,343 @@
+Metadata-Version: 2.4
+Name: pylint-complex-struct
+Version: 0.1.0
+Summary: A pylint checker that flags over-nested type annotations and pushes them towards type aliases, NamedTuples and TypedDicts
+Author: Daniel Gutson
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dgutson/pylint-complex-struct
+Project-URL: Repository, https://github.com/dgutson/pylint-complex-struct
+Project-URL: Issues, https://github.com/dgutson/pylint-complex-struct/issues
+Keywords: pylint,pylint-plugin,linter,typing,type-annotations,static-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pylint>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# pylint-complex-struct
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![pylint](https://img.shields.io/badge/pylint-4.0%2B-green.svg)](https://pylint.readthedocs.io/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
+
+A pylint plugin that flags over-nested type annotations and pushes them towards type
+aliases, `NamedTuple`s and `TypedDict`s.
+
+```python
+# flagged
+def load_records() -> tuple[list[dict[str, Any]], dict[str, Any]]: ...
+
+# fixed
+type Record  = dict[str, Any]
+type Summary = dict[str, Any]
+
+class LoadResult(NamedTuple):
+    records: list[Record]
+    summary: Summary
+
+def load_records() -> LoadResult: ...
+```
+
+Nothing in pylint 4 checks this — `pylint.extensions.typing` only covers redundant and
+deprecated typing constructs — and ruff has no equivalent rule.
+
+## Table of contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Messages](#messages)
+- [Configuration](#configuration)
+- [How the metric works](#how-the-metric-works)
+- [Adopting it on an existing codebase](#adopting-it-on-an-existing-codebase)
+- [Comparison with flake8 and ruff](#comparison-with-flake8-and-ruff)
+- [Known limitations](#known-limitations)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+Requires Python 3.10+ and pylint 4.0+.
+
+```bash
+pip install pylint-complex-struct
+```
+
+Or from a checkout:
+
+```bash
+git clone https://github.com/dgutson/pylint-complex-struct.git
+cd pylint-complex-struct
+pip install -e .
+```
+
+## Quick start
+
+Pylint has no entry-point autoloading, so the plugin must be named explicitly:
+
+```bash
+pylint --load-plugins=pylint_complex_struct yourpackage
+```
+
+To survey an existing codebase with only this plugin's output:
+
+```bash
+pylint --load-plugins=pylint_complex_struct --disable=all \
+       --enable=complex-type-annotation,complex-type-alias,tuple-should-be-namedtuple \
+       yourpackage
+```
+
+Or configure it once in `pyproject.toml`:
+
+```toml
+[tool.pylint.main]
+load-plugins = ["pylint_complex_struct"]
+
+[tool.pylint."complex-struct"]
+max-annotation-complexity = 2
+```
+
+The config section is the checker's name, `complex-struct`, which needs quoting in TOML
+because of the hyphen. The equivalent in `pylintrc` is `[complex-struct]`, and in
+`setup.cfg` or `tox.ini` it is `[pylint.complex-struct]`.
+
+<details>
+<summary>pre-commit hook</summary>
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: pylint-complex-struct
+        name: complex type annotations
+        entry: pylint --load-plugins=pylint_complex_struct
+        language: python
+        additional_dependencies: [pylint, pylint-complex-struct]
+        types: [python]
+```
+
+The plugin has to be importable in the same environment as pylint, so both are named in
+`additional_dependencies` and pre-commit builds one venv holding the pair. Swap
+`language: python` for `language: system` and drop `additional_dependencies` to reuse the
+environment you already have.
+</details>
+
+<details>
+<summary>CI</summary>
+
+```yaml
+- run: pip install pylint-complex-struct
+- run: pylint --load-plugins=pylint_complex_struct --disable=all
+         --enable=complex-type-annotation,complex-type-alias,tuple-should-be-namedtuple
+         yourpackage
+```
+
+All three messages are in the refactor category, so a clean run exits `0` and a run with
+findings sets bit 3 (exit status `8`).
+</details>
+
+## Messages
+
+| ID | Symbol | Fires on |
+|---|---|---|
+| `R9501` | `complex-type-annotation` | an annotation deeper than `max-annotation-complexity`, or with more terms than `max-annotation-terms` |
+| `R9502` | `complex-type-alias` | the *body* of a type alias, over the laxer `max-alias-complexity` |
+| `R9503` | `tuple-should-be-namedtuple` | a return annotation that is a heterogeneous fixed-size tuple |
+
+At most one message is emitted per annotation site: the depth rule wins over the
+`NamedTuple` suggestion, and an alias body only ever produces `R9502`.
+
+Silence an individual case as you would any pylint message:
+
+```python
+def legacy() -> tuple[dict[str, Any], list[dict[str, str]]]:  # pylint: disable=complex-type-annotation
+    ...
+```
+
+### `R9503` in detail
+
+A returned fixed-size tuple whose elements differ forces every call site to unpack
+positionally and re-invent names for the fields:
+
+```python
+def load() -> tuple[Config, int]: ...     # R9503
+def coords() -> tuple[int, int]: ...      # silent: a fixed-size vector
+def rows() -> tuple[str, ...]: ...        # silent: a homogeneous sequence
+def items() -> list[tuple[str, int]]: ... # silent: the dict.items() shape
+```
+
+Returns only, by default. A parameter typed `tuple[str, int]` is usually pass-through, and
+the caller already has the values named.
+
+## Configuration
+
+All options live under `[tool.pylint."complex-struct"]` and work as ordinary pylint options
+on the command line (`--max-annotation-complexity=3`).
+
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `max-annotation-complexity` | int | `2` | Max nesting depth of an annotation. |
+| `max-alias-complexity` | int | `3` | Max nesting depth of an alias body. |
+| `max-annotation-terms` | int | `7` | Max number of type terms in one annotation; `0` disables. |
+| `count-optional-as-nesting` | yn | `n` | Count `Optional[X]` / `X \| None` as a level. |
+| `count-union-as-nesting` | yn | `y` | Count a 2+ member union as a level. |
+| `count-callable-params-as-nesting` | yn | `n` | Count `Callable`'s parameter bracket. |
+| `namedtuple-check-scope` | csv | `returns` | Any of `returns,params,attributes,locals,aliases`; empty disables `R9503`. |
+| `min-namedtuple-fields` | int | `2` | Minimum elements before suggesting a NamedTuple. |
+| `check-implicit-type-aliases` | yn | `n` | Treat `Rows = dict[str, int]` as an alias. |
+
+The default budget of `2` is stricter than the flake8 equivalent's `3`. If the first run on
+an existing codebase is too loud, set `max-annotation-complexity = 3`.
+
+## How the metric works
+
+Depth counts subscript levels, and **a name is always a leaf**:
+
+```
+int                          1
+dict[str, Any]               2      <- legal by default
+list[dict[str, Any]]         3      <- flagged
+type Row = dict[str, Any]
+type Table = list[Row]
+dict[str, Table]             2      <- legal: extracting the alias fixed it
+```
+
+That last line is the whole design. The metric is purely syntactic and never asks astroid
+what a name refers to, so pulling a subtree out into an alias mechanically brings the score
+back within budget. A metric that expanded aliases would score the fixed code exactly like
+the original — the checker could never be satisfied, and there would be no legal way to
+write the type at all. `tests/test_no_inference.py` enforces this by grepping the source.
+
+It also means results do not depend on which third-party packages happen to be installed,
+so CI and your laptop agree.
+
+### What does not count as nesting
+
+| Construct | Treatment | Why |
+|---|---|---|
+| `X \| None`, `Optional[X]` | transparent | Nullability is a bit on a shape, not a shape to decompose. Aliasing it away hides optionality at the call site. Configurable. |
+| `A \| B`, `Union[A, B]` | one level | A real branch the reader must hold. Both spellings share one code path. |
+| `Callable[[A, B], R]` | the param bracket is free; param *types* count | The bracket is mandatory syntax, not chosen nesting. Configurable. |
+| `Literal["a", "b"]` | leaf, contents never walked | Members are values, not types; there is nothing to extract. |
+| `Annotated[T, meta]` | transparent, metadata never walked | Metadata is arbitrary runtime objects. Every Pydantic/FastAPI codebase would otherwise light up. |
+| `Final`, `ClassVar`, `Required`, `NotRequired`, `ReadOnly`, `Unpack`, `TypeGuard`, `TypeIs`, `InitVar` | transparent | They describe how a name is used, not what shape it holds. |
+| `*tuple[int, str]` | transparent | Must score the same as `Unpack[tuple[int, str]]`. |
+| `...` in `tuple[int, ...]` | contributes nothing | A marker, not a type. |
+| class bases | never visited | An alias cannot cleanly replace a base. |
+
+Quoting is **not** an escape hatch: `-> "dict[str, list[tuple[int, int]]]"` scores the same
+as the unquoted form. A forward reference that will not parse (`x: "the widget id"`) scores
+as a leaf and is silently ignored.
+
+### Type aliases
+
+Alias bodies get their own, laxer budget, because absorbing structure is what an alias is
+for — but hiding one unreadable structure behind a name has only moved the problem:
+
+```python
+type Row   = dict[str, Any]                       # fine
+type Table = list[Row]                            # composing is free
+type Blob  = dict[str, list[dict[str, Any]]]      # R9502: depth 4 > 3
+```
+
+`type X = ...` (PEP 695) and `X: TypeAlias = ...` (PEP 613) are both recognised.
+Unannotated `Rows = dict[str, int]` is opt-in via `check-implicit-type-aliases`, because
+`rows = cache["key"]` is also an assignment whose value is a subscript and there is no sound
+syntactic way to tell them apart in general. A SCREAMING_CASE target is skipped: by PEP 8
+that is a constant, so `PEELABLE = TRANSPARENT | ANNOTATED` is a frozenset union rather than
+a union type.
+
+## Adopting it on an existing codebase
+
+1. Survey first with `--disable=all --enable=...` so the output is only this plugin.
+2. If the count is large, start at `max-annotation-complexity = 3` and ratchet down to `2`
+   once the depth-4 cases are gone.
+3. Fix repeated shapes before one-offs — a single alias usually clears several sites.
+   `--output-format=json2` piped through a counter tells you which shapes repeat.
+4. Widen `namedtuple-check-scope` beyond `returns` only after the depth rule is quiet, since
+   the depth rule masks the NamedTuple suggestion on any site that is also too deep.
+
+## Comparison with flake8 and ruff
+
+**flake8** would be marginally simpler to bootstrap and worse to live with. A flake8 plugin
+is a class taking `(tree, filename)` with a `run()` yielding `(line, col, "XXX001 text",
+type(self))` — perhaps 30 lines less scaffolding. But roughly 70% of this project is the
+depth function, which would be identical, and since the design deliberately avoids type
+inference, astroid's main advantage over the stdlib `ast` goes unused. What pylint buys is
+everything around the check: named message symbols (`# pylint:
+disable=complex-type-annotation` rather than `# noqa: TAE001`), a message catalogue visible
+to `--list-msgs`, typed options with config-file support, confidence levels, and
+`pylint.testutils.CheckerTestCase` as a ready-made harness.
+
+If you are already on flake8,
+[flake8-annotations-complexity](https://github.com/best-doctor/flake8-annotations-complexity)
+covers the nesting metric today (`TAE002`/`TAE003`) with zero code. Its gaps:
+
+- no `ast.BinOp` case, so PEP 604 unions are invisible — `tuple[int, int] | None` scores
+  **1** there and **2** here (pinned by `tests/test_depth.py::test_pep604_union_is_not_free`);
+- no concept of type aliases, so no laxer budget for alias bodies;
+- no `NamedTuple` suggestion.
+
+**ruff** cannot do this at all: it does not support third-party plugins. The meta issue
+([astral-sh/ruff#283](https://github.com/astral-sh/ruff/issues/283)) has been open since
+2022, and as of late 2025 the maintainers described the design as discussed but unstarted.
+Ruff has reimplemented 50+ flake8 plugins natively, but the `TAE` rules are not among them.
+
+## Known limitations
+
+- The head of a construct is recognised syntactically, with a bare-name fallback
+  (`Optional` is assumed to mean `typing.Optional` even with no visible import, because
+  re-exports and `if TYPE_CHECKING` blocks are common). A user-defined class literally named
+  `Optional` or `Literal` is therefore mis-classified. Tested and accepted.
+- `.pyi` stubs are skipped entirely.
+- Not checked: `NewType("X", ...)`, `TypeVar(bound=...)`, `cast("...", x)`, and `# type:`
+  comments.
+- Annotations nested deeper than 32 levels, or larger than 2000 nodes, stop being walked and
+  are reported as "over 32" rather than with an exact number.
+
+## Development
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+.venv/bin/pytest -q
+.venv/bin/pylint --load-plugins=pylint_complex_struct pylint_complex_struct tests
+```
+
+The plugin is run against its own source as part of the test discipline, and is expected to
+stay clean at 10.00/10.
+
+**Layout.** `pylint_complex_struct/depth.py` holds the metric and `names.py` the syntactic
+head resolution; neither imports pylint, so both stay unit-testable with bare astroid.
+`checker.py` holds the pylint plumbing. See [CLAUDE.md](CLAUDE.md) for the architectural
+invariants and [ROADMAP.md](ROADMAP.md) for what is planned.
+
+## Contributing
+
+Issues and pull requests are welcome. Two things to know before opening one:
+
+- **The metric must never infer.** `depth.py` and `names.py` may not import pylint and may
+  not call `.infer()`, `.inferred()`, `safe_infer()`, `.lookup()`, `object_type()` or
+  `.getattr()`. `tests/test_no_inference.py` greps for exactly these. Expanding aliases
+  during scoring would make the rule unsatisfiable, so it will not be accepted.
+- New messages use the `95xx` range; pylint reserves 51–99 as the first two digits for
+  third-party checkers.
+
+Please make sure `pytest` and the self-lint above both pass.
+
+## License
+
+[MIT](LICENSE) © Daniel Gutson

pylint_complex_struct-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pylint_complex_struct/__init__.py,sha256=E_vQxCIU9PxI_lIWMXeJrm47-kTfBA95YZP3OrBbr2s,526
+pylint_complex_struct/checker.py,sha256=HViITkJKzB9g3ghYdh2r4Op-930h1YwatDg7m4mB7h4,15573
+pylint_complex_struct/depth.py,sha256=YcQ9ami5E4wetw22B9lWrqWVeMKT4IcZgzJka5ZTPmg,11610
+pylint_complex_struct/names.py,sha256=bKuD-MOXvgRidNMK6DF4VRBpGaDiLMWhCqgn0MXcbSA,6546
+pylint_complex_struct/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pylint_complex_struct-0.1.0.dist-info/licenses/LICENSE,sha256=ohr_7faNlGK2RD_TaT76Trup2MvlrdQ9CaNVxC0J4Zk,1070
+pylint_complex_struct-0.1.0.dist-info/METADATA,sha256=3tWW4KSTy2SutczKbj4Ud61ucqxIQ36-u7y_DJYWhdA,14635
+pylint_complex_struct-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pylint_complex_struct-0.1.0.dist-info/top_level.txt,sha256=UMPMU0F48EK2_BqqI1dHnUfjT3bjR9KY-KHZAcasrNA,22
+pylint_complex_struct-0.1.0.dist-info/RECORD,,

pylint_complex_struct-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pylint_complex_struct-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Gutson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pylint_complex_struct-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pylint_complex_struct