python-checks 0.1.0__py3-none-any.whl

py_checks/checks/placement/_required_class.py

@@ -0,0 +1,179 @@
+"""Модуль объявляет тот класс, ради которого его директория существует."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar, Final
+
+from py_checks.checks._kind import Kind, declarations
+from py_checks.checks._location import place
+from py_checks.checks.placement._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.checks._kind import Declaration
+    from py_checks.checks._location import Place
+    from py_checks.core import ParsedFile
+
+CODE: Final = "required-class"
+
+# Вид объявления, которому позволено стоять выше требуемого класса. Алиас и
+# перечисление — словарь, а не второй предмет разговора: тело класса
+# выполняется в момент объявления, поэтому имена, которые требуемый класс
+# называет у себя внутри, ниже него написать нельзя.
+VOCABULARY: Final[frozenset[Kind]] = frozenset({Kind.ALIAS, Kind.ENUM})
+
+
+class RequiredClassSettings(CheckSettings):
+    suffixes: dict[str, str] = {}
+
+
+class RequiredClass:
+    """Падает, если модуль не объявил класс, ради которого лежит в этой директории.
+
+    Файл в `use_cases` существует ради сценария, файл в `repositories` — ради
+    репозитория, файл в `config` — ради группы настроек. Модуль, который
+    объявил что-то другое, либо назван не так, либо лежит не там.
+
+    Класс идёт первым и идёт один. Первым — потому что читатель, открывший
+    `repositories/order.py`, ищет репозиторий, а хелпер перед ним читается как
+    что-то более важное. Один — потому что имя файла и есть то, как читатель
+    находит класс: три сценария в одном модуле отвечают на вопрос «где
+    `ResolveLimitsUseCase`» словами «прочти все три».
+
+    Выше требуемого класса разрешены константы, алиасы и перечисления: имя
+    читают там, где им пользуются, а значение вторым предметом разговора не
+    становится.
+
+    `__init__.py` ничего не объявляет, а переэкспортирует; пустой модуль ещё
+    ничего не обещал; модуль с подчёркиванием (`_base.py`) держит машинерию
+    своей директории, а не один из её классов. Эти трое правилу не подсудны.
+
+    Настройка: `suffixes`.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = RequiredClassSettings
+    scope: ClassVar[Scope] = Scope.FILE
+    marker: ClassVar[str] = MARKER
+
+    @classmethod
+    def run(
+        cls,
+        *,
+        file: ParsedFile,
+        settings: CheckSettings,
+    ) -> Iterator[Violation]:
+        suffixes = settings_as(
+            settings=settings,
+            model=RequiredClassSettings,
+            code=CODE,
+        ).suffixes
+        where = place(file=file)
+        if where is None or file.path.stem.startswith("_"):
+            return
+        suffix = cls._suffix(
+            where=where,
+            suffixes=suffixes,
+        )
+        if suffix is None:
+            return
+        declared = list(declarations(tree=file.tree))
+        if not declared:
+            return
+        yield from cls._violations(
+            file=file,
+            declared=declared,
+            suffix=suffix,
+        )
+
+    @classmethod
+    def _violations(
+        cls,
+        *,
+        file: ParsedFile,
+        declared: list[Declaration],
+        suffix: str,
+    ) -> Iterator[Violation]:
+        required = [one for one in declared if one.name.endswith(suffix)]
+        if not required:
+            yield cls._says(
+                file=file,
+                node=declared[0],
+                message=(
+                    f"модуль объявляет {cls._listed(declared=declared)}, "
+                    f"а в этой директории объявляют класс ...{suffix}"
+                ),
+            )
+            return
+        if len(required) > 1:
+            yield cls._says(
+                file=file,
+                node=required[1],
+                message=(
+                    f"в модуле {cls._listed(declared=required)} — "
+                    f"один ...{suffix} на модуль, и модуль назван его именем"
+                ),
+            )
+            return
+        ahead = cls._ahead(
+            declared=declared,
+            suffix=suffix,
+        )
+        if ahead is not None:
+            yield cls._says(
+                file=file,
+                node=ahead,
+                message=(
+                    f"{ahead.name} объявлен выше ...{suffix}, ради которого "
+                    f"существует модуль; хелперам место ниже"
+                ),
+            )
+
+    @staticmethod
+    def _ahead(
+        *,
+        declared: list[Declaration],
+        suffix: str,
+    ) -> Declaration | None:
+        """Первое объявление, вставшее выше требуемого класса."""
+        for one in declared:
+            if one.name.endswith(suffix):
+                return None
+            if one.kind not in VOCABULARY:
+                return one
+        return None
+
+    @staticmethod
+    def _suffix(
+        *,
+        where: Place,
+        suffixes: dict[str, str],
+    ) -> str | None:
+        """Суффикс самой внутренней из совпавших директорий."""
+        matched = [
+            (depth, len(directory), suffix)
+            for directory, suffix in suffixes.items()
+            if (depth := where.within(directory=directory)) is not None
+        ]
+        return max(matched)[2] if matched else None
+
+    @staticmethod
+    def _says(
+        *,
+        file: ParsedFile,
+        node: Declaration,
+        message: str,
+    ) -> Violation:
+        return Violation.from_node(
+            node=node.node,
+            path=file.path,
+            code=CODE,
+            message=message,
+        )
+
+    @staticmethod
+    def _listed(*, declared: list[Declaration]) -> str:
+        return ", ".join(one.name for one in declared)

py_checks/checks/signatures/__init__.py

@@ -0,0 +1,33 @@
+"""Сигнатуры и тела.
+
+Длина функции и модуля, глубина вложенности, требование писать сигнатуру
+полностью и раскладывать её по столбцу. Число аргументов судит
+`operation-shape` — там, где известно, какой класс операция и какая у неё
+дверь; вложенный `with` отдан ruff, правилу `SIM117` с автофиксом.
+"""
+
+from py_checks.checks.signatures._function_length import (
+    FunctionLength,
+    FunctionLengthSettings,
+)
+from py_checks.checks.signatures._keyword_only import KeywordOnlyArguments
+from py_checks.checks.signatures._marker import MARKER
+from py_checks.checks.signatures._module_length import ModuleLength, ModuleLengthSettings
+from py_checks.checks.signatures._nesting import Nesting, NestingSettings
+from py_checks.checks.signatures._signature_layout import (
+    SignatureLayout,
+    SignatureLayoutSettings,
+)
+
+__all__ = [
+    "MARKER",
+    "FunctionLength",
+    "FunctionLengthSettings",
+    "KeywordOnlyArguments",
+    "ModuleLength",
+    "ModuleLengthSettings",
+    "Nesting",
+    "NestingSettings",
+    "SignatureLayout",
+    "SignatureLayoutSettings",
+]

py_checks/checks/signatures/_function_length.py

@@ -0,0 +1,90 @@
+"""Длина функции."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar, Final
+
+from pydantic import Field
+
+from py_checks.checks.signatures._functions import definitions, signature_end
+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.checks.signatures._functions import Definition
+    from py_checks.core import ParsedFile
+
+CODE: Final = "function-length"
+
+
+class FunctionLengthSettings(CheckSettings):
+    max_lines: int = Field(
+        default=50,
+        gt=0,
+    )
+
+
+class FunctionLength:
+    """Падает, если функция длиннее лимита.
+
+    Функция за пределом прячет внутри себя вторую. Считается тело как
+    написано — пустые строки и комментарии тоже держат в голове, — а подпись и
+    декораторы нет: они описывают функцию, а не работу, которую она делает.
+
+    Похожее правило есть у ruff, `PLR0915`, но оно считает инструкции, а не
+    строки: замер на четырёх сервисах дал ноль срабатываний при пределе в
+    полсотни, а самая длинная функция там — 91 строка и две инструкции.
+
+    Настройка: `max-lines`.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = FunctionLengthSettings
+    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=FunctionLengthSettings,
+            code=CODE,
+        )
+        for definition in definitions(node=file.tree):
+            length = cls._length(definition=definition)
+            if length <= limits.max_lines:
+                continue
+            yield Violation.from_node(
+                node=definition.node,
+                path=file.path,
+                code=CODE,
+                # Пометке место в конце подписи: на строке `def` она не всегда
+                # помещается, а подпись, разложенная по столбцу, кончается
+                # совсем не там, куда указывает нарушение.
+                end_line=signature_end(node=definition.node),
+                message=(
+                    f"{definition.name}: строк {length}, предел {limits.max_lines}; "
+                    "вынеси часть в отдельную функцию"
+                ),
+            )
+
+    @staticmethod
+    def _length(*, definition: Definition) -> int:
+        """Строки тела: от первой инструкции до последней строки функции.
+
+        Подпись не считается: разложенная по столбцу, она добавила бы функции
+        десяток строк, которых в ней никто не читает как работу.
+        """
+        node = definition.node
+        end = node.end_lineno
+        if end is None:
+            return 0
+        return end - node.body[0].lineno + 1

py_checks/checks/signatures/_functions.py

@@ -0,0 +1,92 @@
+"""Функции модуля и то, что о них знает только дерево."""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Final
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+# Единственный способ для метода не получить первый аргумент от интерпретатора.
+STATIC: Final = "staticmethod"
+
+type Function = ast.FunctionDef | ast.AsyncFunctionDef
+
+
+@dataclass(frozen=True, slots=True)
+class Definition:
+    """Функция, её имя вида `Класс.метод` и то, метод ли она.
+
+    Первый аргумент метода передаёт интерпретатор, и автор подписи тут ни при
+    чём — но узнаётся это по месту, а не по имени. `self` в обычной функции или
+    в `@staticmethod` — обычный аргумент.
+    """
+
+    name: str
+    node: Function
+    method: bool
+
+
+def definitions(
+    *,
+    node: ast.AST,
+    prefix: str = "",
+    method: bool = False,
+) -> Iterator[Definition]:
+    """Все функции дерева под именами вида `Класс.метод` или `внешняя.вложенная`.
+
+    Заодно запоминается, тело какого узла мы разбираем: функция в теле класса —
+    метод, а функция внутри метода — уже нет, и первый аргумент ей никто не
+    передаёт.
+    """
+    for child in ast.iter_child_nodes(node):
+        match child:
+            case ast.ClassDef(name=name):
+                yield from definitions(
+                    node=child,
+                    prefix=f"{prefix}{name}.",
+                    method=True,
+                )
+            case ast.FunctionDef(name=name) | ast.AsyncFunctionDef(name=name):
+                yield Definition(
+                    name=f"{prefix}{name}",
+                    node=child,
+                    method=method,
+                )
+                yield from definitions(
+                    node=child,
+                    prefix=f"{prefix}{name}.",
+                    method=False,
+                )
+            case _:
+                yield from definitions(
+                    node=child,
+                    prefix=prefix,
+                    method=method,
+                )
+
+
+def receiver(*, definition: Definition) -> int:
+    """Сколько первых аргументов передаёт интерпретатор: один у метода, иначе ноль."""
+    if not definition.method or static(node=definition.node):
+        return 0
+    return 1
+
+
+def static(*, node: Function) -> bool:
+    return STATIC in {name(node=item) for item in node.decorator_list}
+
+
+def name(*, node: ast.expr) -> str:
+    match node:
+        case ast.Name(id=found) | ast.Attribute(attr=found):
+            return found
+        case _:
+            return ""
+
+
+def signature_end(*, node: Function) -> int:
+    """Последняя строка подписи: на ней стоит пометка, если подпись в столбик."""
+    return max(node.body[0].lineno - 1, node.lineno)

py_checks/checks/signatures/_keyword_only.py

@@ -0,0 +1,148 @@
+"""Все аргументы передаются по имени."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar, Final
+
+from py_checks.checks.signatures._functions import (
+    Definition,
+    definitions,
+    receiver,
+    signature_end,
+)
+from py_checks.checks.signatures._marker import MARKER
+from py_checks.config import CheckSettings
+from py_checks.core import Edit, Scope, Violation, column
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from py_checks.checks.signatures._functions import Function
+    from py_checks.core import ParsedFile
+
+CODE: Final = "keyword-only-arguments"
+
+# Дандеры, которые зовёт наш собственный код: их вызов — такой же вызов, как
+# любой другой. Остальные дандеры зовёт интерпретатор, и подпись у них не наша.
+OWN_DUNDERS: Final[frozenset[str]] = frozenset({"__init__", "__new__", "__call__"})
+
+
+class KeywordOnlyArguments:
+    """Падает, если подпись записана не полностью.
+
+    Каждый аргумент передаётся по имени, поэтому место вызова читается как
+    документация, а аргументы можно менять местами, не ломая вызовы:
+
+        def price(*, market: Market, stake: Money) -> Money: ...
+
+    `*args` и `**kwargs` запрещены по той же причине: сборщик принимает что
+    угодно, проверять типы там нечего, а место вызова ничего не объясняет. Их
+    `--fix` не трогает: имена аргументов вместо звёздочек придумывает автор.
+
+    Обратный вызов или обёртка, чью подпись диктует библиотека, помечается в
+    подписи: `def f(a): ...  # check-ok: keyword-only-arguments: sqlalchemy`.
+    Слово группы `# signature-ok` библиотека тоже понимает.
+
+    Настроек нет.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = CheckSettings
+    scope: ClassVar[Scope] = Scope.FILE
+    marker: ClassVar[str] = MARKER
+
+    def run(
+        self,
+        *,
+        file: ParsedFile,
+        settings: CheckSettings,
+    ) -> Iterator[Violation]:
+        _ = settings
+        for definition in definitions(node=file.tree):
+            if self._interpreter_dunder(name=definition.name):
+                continue
+            yield from self._violations(
+                definition=definition,
+                file=file,
+            )
+
+    @classmethod
+    def _violations(
+        cls,
+        *,
+        definition: Definition,
+        file: ParsedFile,
+    ) -> Iterator[Violation]:
+        node, name = definition.node, definition.name
+        end_line = signature_end(node=node)
+        if positional := cls._positional(definition=definition):
+            yield Violation.from_node(
+                node=node,
+                path=file.path,
+                code=CODE,
+                message=(
+                    f"{name} принимает {', '.join(positional)} по позиции; поставь `*` перед ними"
+                ),
+                end_line=end_line,
+                edit=cls._star(
+                    definition=definition,
+                    file=file,
+                ),
+            )
+        if collected := cls._collectors(node=node):
+            yield Violation.from_node(
+                node=node,
+                path=file.path,
+                code=CODE,
+                message=f"{name} принимает {', '.join(collected)}; перечисли аргументы по имени",
+                end_line=end_line,
+            )
+
+    @staticmethod
+    def _interpreter_dunder(*, name: str) -> bool:
+        own = name.rsplit(".", maxsplit=1)[-1]
+        if own in OWN_DUNDERS:
+            return False
+        return own.startswith("__") and own.endswith("__")
+
+    @staticmethod
+    def _positional(*, definition: Definition) -> tuple[str, ...]:
+        """Аргументы, которые вызывающий может передать по позиции."""
+        skip = receiver(definition=definition)
+        arguments = [*definition.node.args.posonlyargs, *definition.node.args.args]
+        return tuple(argument.arg for argument in arguments[skip:])
+
+    @staticmethod
+    def _collectors(*, node: Function) -> tuple[str, ...]:
+        """`*args` и `**kwargs` в том виде, в каком их видит вызывающий."""
+        stars = ((node.args.vararg, "*"), (node.args.kwarg, "**"))
+        return tuple(f"{star}{argument.arg}" for argument, star in stars if argument)
+
+    @staticmethod
+    def _star(
+        *,
+        definition: Definition,
+        file: ParsedFile,
+    ) -> Edit | None:
+        """Правка: `*` перед первым аргументом, который сейчас идёт по позиции.
+
+        Не для всех случаев. При `*args` вторая звезда в подписи не встанет, а
+        при `/` аргументы позиционны по требованию автора, и снимать его
+        требование автофиксу не по чину.
+        """
+        node = definition.node
+        if node.args.vararg is not None or node.args.posonlyargs:
+            return None
+        first = node.args.args[receiver(definition=definition)]
+        line = first.lineno
+        at = column(
+            line=file.lines[line - 1],
+            offset=first.col_offset,
+        )
+        return Edit(
+            line=line,
+            column=at,
+            end_line=line,
+            end_column=at,
+            text="*, ",
+        )

py_checks/checks/signatures/_marker.py

@@ -0,0 +1,7 @@
+"""Слово, которым снимается любая проверка этой группы."""
+
+from __future__ import annotations
+
+from typing import Final
+
+MARKER: Final = "# signature-ok"

py_checks/checks/signatures/_module_length.py

@@ -0,0 +1,64 @@
+"""Длина модуля."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar, Final
+
+from pydantic import Field
+
+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 = "module-length"
+
+
+class ModuleLengthSettings(CheckSettings):
+    max_lines: int = Field(
+        default=600,
+        gt=0,
+    )
+
+
+class ModuleLength:
+    """Падает, если модуль длиннее лимита.
+
+    Длинный модуль — это обычно несколько модулей, которые не разъехались
+    вовремя. Считаются все строки файла, включая пустые и комментарии: правило
+    про размер файла, который приходится держать в голове, а не про плотность
+    кода в нём.
+
+    Настройка: `max-lines`.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = ModuleLengthSettings
+    scope: ClassVar[Scope] = Scope.FILE
+    marker: ClassVar[str] = MARKER
+
+    def run(
+        self,
+        *,
+        file: ParsedFile,
+        settings: CheckSettings,
+    ) -> Iterator[Violation]:
+        limits = settings_as(
+            settings=settings,
+            model=ModuleLengthSettings,
+            code=CODE,
+        )
+        length = len(file.lines)
+        if length <= limits.max_lines:
+            return
+        yield Violation(
+            path=file.path,
+            line=limits.max_lines + 1,
+            column=1,
+            code=CODE,
+            message=f"{length} строк, предел {limits.max_lines}",
+        )