python-checks 0.1.0__py3-none-any.whl

py_checks/checks/signatures/_nesting.py

@@ -0,0 +1,156 @@
+"""Глубина вложенности управляющих конструкций."""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, ClassVar, Final, Self
+
+from pydantic import model_validator
+
+from py_checks.checks.signatures._marker import MARKER
+from py_checks.config import CheckSettings
+from py_checks.core import Scope, Violation, settings_as
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from py_checks.core import ParsedFile
+
+CODE: Final = "nesting"
+
+# Виды, о которых правило умеет говорить. `with` в списке есть, но держать его
+# в таблице проекту незачем: вложенный `with` ловит ruff `SIM117`, с автофиксом
+# и с готовым ответом — «сделай один `with a, b:`».
+KINDS: Final[dict[str, tuple[type[ast.stmt], ...]]] = {
+    "try": (ast.Try, ast.TryStar),
+    "with": (ast.With, ast.AsyncWith),
+    "if": (ast.If,),
+    "for": (ast.For, ast.AsyncFor),
+    "while": (ast.While,),
+    "match": (ast.Match,),
+}
+
+# Списки инструкций, которые узел держит в себе.
+BRANCHES: Final[tuple[str, ...]] = ("body", "orelse", "finalbody")
+
+
+class NestingSettings(CheckSettings):
+    limits: dict[str, int] = {}
+
+    @model_validator(mode="after")
+    def _known(self) -> Self:
+        unknown = sorted(set(self.limits) - set(KINDS))
+        if unknown:
+            message = f"неизвестные конструкции: {', '.join(unknown)}"
+            raise ValueError(message)
+        if any(limit < 1 for limit in self.limits.values()):
+            message = "предел вложенности — целое от единицы"
+            raise ValueError(message)
+        return self
+
+
+class Nesting:
+    """Падает, если управляющие конструкции вложены глубже предела.
+
+    Глубина — это место, где логику перестают читать и начинают расшифровывать.
+    Предел у каждого вида свой, потому что стоят они разного: второй `try`
+    внутри первого прячет, какая строка бросила, а второй уровень `if` — это
+    обычная развилка, и лишним становится третий.
+
+    `elif` — ветка, а не уровень, и уровнем не считается. Написанный
+    развёрнуто `else:` с `if` внутри — считается: это и есть лишний отступ.
+
+    Вложенный `with` в таблицу лучше не класть: его ловит ruff `SIM117`, с
+    автофиксом и с ответом на месте.
+
+    Настройка: `limits`.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = NestingSettings
+    scope: ClassVar[Scope] = Scope.FILE
+    marker: ClassVar[str] = MARKER
+
+    @classmethod
+    def run(
+        cls,
+        *,
+        file: ParsedFile,
+        settings: CheckSettings,
+    ) -> Iterator[Violation]:
+        limits = settings_as(
+            settings=settings,
+            model=NestingSettings,
+            code=CODE,
+        ).limits
+        if not limits:
+            return
+        depths = dict.fromkeys(limits, 0)
+        for node in file.tree.body:
+            yield from cls._visit(
+                file=file,
+                node=node,
+                depths=depths,
+                limits=limits,
+            )
+
+    @classmethod
+    def _visit(
+        cls,
+        *,
+        file: ParsedFile,
+        node: ast.stmt,
+        depths: dict[str, int],
+        limits: dict[str, int],
+    ) -> Iterator[Violation]:
+        kind = cls._kind(
+            node=node,
+            limits=limits,
+        )
+        if kind is not None:
+            depth = depths[kind] + 1
+            if depth > limits[kind]:
+                yield Violation.from_node(
+                    node=node,
+                    path=file.path,
+                    code=CODE,
+                    message=f"{kind} вложен на {depth}, предел {limits[kind]}",
+                )
+            depths = {**depths, kind: depth}
+        for child in cls._children(node=node):
+            inner = depths
+            if isinstance(node, ast.If) and cls._elif(
+                node=node,
+                child=child,
+            ):
+                inner = {**depths, "if": depths["if"] - 1}
+            yield from cls._visit(
+                file=file,
+                node=child,
+                depths=inner,
+                limits=limits,
+            )
+
+    @staticmethod
+    def _kind(
+        *,
+        node: ast.stmt,
+        limits: dict[str, int],
+    ) -> str | None:
+        return next((kind for kind in limits if isinstance(node, KINDS[kind])), None)
+
+    @staticmethod
+    def _children(*, node: ast.stmt) -> Iterator[ast.stmt]:
+        for field in BRANCHES:
+            yield from getattr(node, field, [])
+        for handler in getattr(node, "handlers", []):
+            yield from handler.body
+
+    @staticmethod
+    def _elif(
+        *,
+        node: ast.If,
+        child: ast.stmt,
+    ) -> bool:
+        """`elif` стоит в той же колонке, что его `if`; написанный `else: if` — нет."""
+        return isinstance(child, ast.If) and child.col_offset == node.col_offset

py_checks/checks/signatures/_signature_layout.py

@@ -0,0 +1,231 @@
+"""Список из двух и более элементов пишется в столбик."""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, ClassVar, Final
+
+from py_checks.checks.signatures._functions import definitions, receiver
+from py_checks.checks.signatures._marker import MARKER
+from py_checks.config import CheckSettings
+from py_checks.core import Edit, Scope, Violation, column, settings_as
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Sequence
+
+    from py_checks.checks.signatures._functions import Definition, Function
+    from py_checks.core import ParsedFile
+
+CODE: Final = "signature-layout"
+
+# Двух элементов достаточно: один в строке читается как одно слово, а два уже
+# приходится разбирать.
+ENOUGH: Final = 2
+
+
+class SignatureLayoutSettings(CheckSettings):
+    calls: bool = True
+
+
+class SignatureLayout:
+    """Падает, если список из двух и более элементов записан в одну строку.
+
+    Обе половины вызова: подпись, которая объявляет параметры, и место, которое
+    их передаёт. В столбике правка одного аргумента трогает одну строку и
+    говорит ровно это; тот же список в строку сдвигает всё, что стоит после
+    правки, и ревью читает его целиком, чтобы найти изменение. В вызове это
+    важнее, чем в подписи: там стоят выражения, а не имена.
+
+    `self` и `cls` не в счёт — их передаёт интерпретатор.
+
+    В вызове правило срабатывает от двух и более ИМЕНОВАННЫХ аргументов, и это
+    вся граница между своим кодом и чужим: у нас каждая функция keyword-only,
+    поэтому вызов нашей функции — сплошь имена и под правило попадает, а
+    `isinstance(node, ast.Call)` и `range(1, 10)` — чужая позиционная подпись, и
+    её не трогают. Как только сработало, в столбик идут все аргументы,
+    позиционные тоже: наполовину развёрнутый вызов правилу ни к чему.
+
+    Декоратор — единственное исключение: `@dataclass(frozen=True, slots=True)`
+    это метка, а не список, который читают ради смысла. Те же слова на каждом
+    dataclass сервиса, переставлять там нечего.
+
+    `--fix` дописывает висячую запятую и зовёт `ruff format`: форматтер держит
+    список в столбик, когда запятая стоит, но сам её никогда не ставит.
+
+    Настройка: `calls` — судить ли места вызова. Половина правила про вызовы
+    дороже половины про подписи: в сервисе, который писали без неё, она трогает
+    почти каждый файл, и выключить её на время переезда честнее, чем выключить
+    правило целиком.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = SignatureLayoutSettings
+    scope: ClassVar[Scope] = Scope.FILE
+    marker: ClassVar[str] = MARKER
+
+    @classmethod
+    def run(
+        cls,
+        *,
+        file: ParsedFile,
+        settings: CheckSettings,
+    ) -> Iterator[Violation]:
+        calls = settings_as(
+            settings=settings,
+            model=SignatureLayoutSettings,
+            code=CODE,
+        ).calls
+        for definition in definitions(node=file.tree):
+            yield from cls._signature(
+                file=file,
+                definition=definition,
+            )
+        if not calls:
+            return
+        marks = cls._decorators(tree=file.tree)
+        for node in ast.walk(file.tree):
+            if isinstance(node, ast.Call) and id(node) not in marks:
+                yield from cls._call(
+                    file=file,
+                    node=node,
+                )
+
+    @classmethod
+    def _signature(
+        cls,
+        *,
+        file: ParsedFile,
+        definition: Definition,
+    ) -> Iterator[Violation]:
+        node = definition.node
+        listed = cls._parameters(definition=definition)
+        defaults = cls._defaults(node=node)
+        if len(listed) < ENOUGH or cls._columned(
+            listed=listed,
+            after=node.lineno,
+        ):
+            return
+        yield Violation.from_node(
+            node=node,
+            path=file.path,
+            code=CODE,
+            message=(
+                f"{definition.name}: параметров {len(listed)} в одну строку; по одному на строку"
+            ),
+            edit=cls._comma(
+                file=file,
+                ends=[*cls._ends(nodes=listed), *cls._ends(nodes=defaults)],
+            ),
+        )
+
+    @classmethod
+    def _call(
+        cls,
+        *,
+        file: ParsedFile,
+        node: ast.Call,
+    ) -> Iterator[Violation]:
+        listed: list[ast.expr | ast.keyword] = [*node.args, *node.keywords]
+        if len(node.keywords) < ENOUGH:
+            return
+        after = node.func.end_lineno or node.func.lineno
+        if cls._columned(
+            listed=listed,
+            after=after,
+        ):
+            return
+        yield Violation.from_node(
+            node=node,
+            path=file.path,
+            code=CODE,
+            message=(
+                f"{cls._called(node=node)}: аргументов {len(listed)} в одну строку; "
+                f"по одному на строку"
+            ),
+            edit=cls._comma(
+                file=file,
+                ends=cls._ends(nodes=listed),
+            ),
+        )
+
+    @staticmethod
+    def _columned(
+        *,
+        listed: Sequence[ast.expr | ast.keyword | ast.arg],
+        after: int,
+    ) -> bool:
+        """По одному на строку, и ни одного на той строке, где список открылся."""
+        lines = {element.lineno for element in listed}
+        return len(lines) == len(listed) and min(lines) > after
+
+    @staticmethod
+    def _parameters(*, definition: Definition) -> list[ast.arg]:
+        """Параметры, которые заполняет вызывающий, в порядке записи."""
+        arguments = definition.node.args
+        listed = [
+            *arguments.posonlyargs,
+            *arguments.args,
+            *([arguments.vararg] if arguments.vararg else []),
+            *arguments.kwonlyargs,
+            *([arguments.kwarg] if arguments.kwarg else []),
+        ]
+        return listed[receiver(definition=definition) :]
+
+    @staticmethod
+    def _defaults(*, node: Function) -> list[ast.expr]:
+        """Значения по умолчанию: запятая ставится после них, а не после имени."""
+        return [one for one in (*node.args.defaults, *node.args.kw_defaults) if one is not None]
+
+    @staticmethod
+    def _ends(*, nodes: Sequence[ast.expr | ast.keyword | ast.arg]) -> list[tuple[int, int]]:
+        """Где кончается каждый элемент списка."""
+        return [
+            (node.end_lineno, node.end_col_offset)
+            for node in nodes
+            if node.end_lineno is not None and node.end_col_offset is not None
+        ]
+
+    @staticmethod
+    def _comma(
+        *,
+        file: ParsedFile,
+        ends: list[tuple[int, int]],
+    ) -> Edit | None:
+        """Правка: висячая запятая после последнего элемента списка.
+
+        Последний — по концу, а не по порядку записи: у параметра со значением
+        по умолчанию запятая ставится после значения, а не после имени.
+
+        Дальше раскладка — забота форматтера: `ruff format` разворачивает
+        список в столбик, как только запятая стоит.
+        """
+        if not ends:
+            return None
+        line, offset = max(ends)
+        at = column(
+            line=file.lines[line - 1],
+            offset=offset,
+        )
+        return Edit(
+            line=line,
+            column=at,
+            end_line=line,
+            end_column=at,
+            text=",",
+        )
+
+    @staticmethod
+    def _called(*, node: ast.Call) -> str:
+        """Как вызов записан: `self._policy`, `price`, `Model.build`."""
+        return ast.unparse(node.func)
+
+    @staticmethod
+    def _decorators(*, tree: ast.Module) -> frozenset[int]:
+        """Вызовы, которые на самом деле декораторы, — по тождеству узла."""
+        return frozenset(
+            id(decorator)
+            for node in ast.walk(tree)
+            if isinstance(node, ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef)
+            for decorator in node.decorator_list
+            if isinstance(decorator, ast.Call)
+        )

py_checks/checks/types/__init__.py

@@ -0,0 +1,36 @@
+"""Типы и аннотации.
+
+Чем объявлено значение и что об этом видно из подписи. Готовых правил тут
+почти нет: `typing.Literal` закрывается строкой `banned-api` в ruff, голый
+дженерик — строгим режимом pyright, остальное — соглашения проекта.
+"""
+
+from py_checks.checks.types._annotation_shapes import (
+    AnnotationShapes,
+    AnnotationShapesSettings,
+)
+from py_checks.checks.types._config_fields import ConfigFields, ConfigFieldsSettings
+from py_checks.checks.types._confined_types import ConfinedTypes, ConfinedTypesSettings
+from py_checks.checks.types._constant_annotations import (
+    ConstantAnnotations,
+    ConstantAnnotationsSettings,
+)
+from py_checks.checks.types._frozen_dataclasses import (
+    FrozenDataclasses,
+    FrozenDataclassesSettings,
+)
+from py_checks.checks.types._marker import MARKER
+
+__all__ = [
+    "MARKER",
+    "AnnotationShapes",
+    "AnnotationShapesSettings",
+    "ConfigFields",
+    "ConfigFieldsSettings",
+    "ConfinedTypes",
+    "ConfinedTypesSettings",
+    "ConstantAnnotations",
+    "ConstantAnnotationsSettings",
+    "FrozenDataclasses",
+    "FrozenDataclassesSettings",
+]

py_checks/checks/types/_annotation_shapes.py

@@ -0,0 +1,127 @@
+"""Форма, которая описывает значение беднее, чем оно есть."""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, ClassVar, Final
+
+from py_checks.checks._names import name
+from py_checks.checks.types._marker import MARKER
+from py_checks.config import CheckSettings
+from py_checks.core import Scope, Violation, settings_as
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from py_checks.core import ParsedFile
+
+CODE: Final = "annotation-shapes"
+
+MAPPING: Final = "dict"
+TUPLE: Final = "tuple"
+
+
+class AnnotationShapesSettings(CheckSettings):
+    keys: tuple[str, ...] = ("str",)
+    tuples: bool = True
+
+
+class AnnotationShapes:
+    """Падает, если форма названа так, что поля в ней безымянные.
+
+    Словарь со строковым ключом читается как набор именованных полей, а
+    `TypedDict` или dataclass говорят, каких именно. Ключи бывают и настоящими
+    данными — мешок заголовков, носитель контекста трассировки, — и тогда
+    строка помечается: `# type-ok: annotation-shapes: своя форма у propagator`.
+
+    Кортеж фиксированной длины — тот, у которого последний аргумент не `...`, —
+    называет поля позициями: `row[2]` не говорит ничего и молча переживает
+    перестановку. Имена дают dataclass или `NamedTuple`, если это обязано
+    остаться кортежем.
+
+    Судится каждое место, где форма написана, а не только аннотации: словарь,
+    собранный внутри функции, — та же неописанная форма одним вызовом позже, и
+    обычно именно оттуда аннотация и взялась.
+
+    Настройки: `keys` — какие ключи читаются как имена полей, `tuples` —
+    судить ли кортежи фиксированной длины.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = AnnotationShapesSettings
+    scope: ClassVar[Scope] = Scope.FILE
+    marker: ClassVar[str] = MARKER
+
+    @classmethod
+    def run(
+        cls,
+        *,
+        file: ParsedFile,
+        settings: CheckSettings,
+    ) -> Iterator[Violation]:
+        limits = settings_as(
+            settings=settings,
+            model=AnnotationShapesSettings,
+            code=CODE,
+        )
+        for node in ast.walk(file.tree):
+            if not isinstance(node, ast.Subscript):
+                continue
+            written = name(node=node.value)
+            arguments = cls._arguments(node=node)
+            if written == MAPPING and cls._keyed(
+                arguments=arguments,
+                keys=limits.keys,
+            ):
+                yield cls._says(
+                    file=file,
+                    node=node,
+                    message=(
+                        f"{ast.unparse(node)} читается как набор именованных полей; "
+                        f"какие именно — скажет TypedDict или dataclass"
+                    ),
+                )
+            if written == TUPLE and limits.tuples and cls._fixed(arguments=arguments):
+                yield cls._says(
+                    file=file,
+                    node=node,
+                    message=(
+                        f"{ast.unparse(node)} называет поля позициями; имена даст dataclass, "
+                        f"а NamedTuple — если это обязано остаться кортежем"
+                    ),
+                )
+
+    @staticmethod
+    def _keyed(
+        *,
+        arguments: list[ast.expr],
+        keys: tuple[str, ...],
+    ) -> bool:
+        return bool(arguments) and name(node=arguments[0]) in keys
+
+    @staticmethod
+    def _fixed(*, arguments: list[ast.expr]) -> bool:
+        """Кортеж, у которого длина написана: последний аргумент не `...`."""
+        if not arguments:
+            return False
+        last = arguments[-1]
+        return not (isinstance(last, ast.Constant) and last.value is Ellipsis)
+
+    @staticmethod
+    def _arguments(*, node: ast.Subscript) -> list[ast.expr]:
+        inside = node.slice
+        return list(inside.elts) if isinstance(inside, ast.Tuple) else [inside]
+
+    @staticmethod
+    def _says(
+        *,
+        file: ParsedFile,
+        node: ast.Subscript,
+        message: str,
+    ) -> Violation:
+        return Violation.from_node(
+            node=node,
+            path=file.path,
+            code=CODE,
+            message=message,
+        )