python-checks 0.1.0__py3-none-any.whl

py_checks/checks/api/_marker.py

@@ -0,0 +1,5 @@
+"""Слово группы для пометок: `# api-ok: <код>: <причина>`."""
+
+from typing import Final
+
+MARKER: Final = "# api-ok"

py_checks/checks/calls/__init__.py

@@ -0,0 +1,13 @@
+"""Места вызова.
+
+Есть функции, у которых законных мест вызова ровно столько, сколько их
+перечислено: конверсия денег, например. Правило держит этот список.
+"""
+
+from py_checks.checks.calls._confined_functions import (
+    ConfinedFunctions,
+    ConfinedFunctionsSettings,
+)
+from py_checks.checks.calls._marker import MARKER
+
+__all__ = ["MARKER", "ConfinedFunctions", "ConfinedFunctionsSettings"]

py_checks/checks/calls/_confined_functions.py

@@ -0,0 +1,102 @@
+"""У некоторых функций законных мест вызова ровно столько, сколько перечислено."""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, ClassVar, Final
+
+from py_checks.checks._location import place
+from py_checks.checks._names import matches
+from py_checks.checks.calls._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 = "confined-functions"
+
+
+class ConfinedFunctionsSettings(CheckSettings):
+    calls: dict[str, tuple[str, ...]] = {}  # noqa: RUF012 — pydantic копирует значение сам
+    home: str | None = None
+
+
+class ConfinedFunctions:
+    """Падает, если названная функция позвана не оттуда, откуда ей можно.
+
+    Написано ради конверсии денег. Сервис считает в одной валюте, и гарантия
+    за этой фразой — не имя типа: это то, что у конверсии одна реализация и
+    места её вызова можно перечислить. Где угодно ещё конверсия — это сумма в
+    чьей-то валюте посреди расчёта, и ошибка, которую она даёт, — число,
+    верное ровно до того дня, когда встретятся две валюты.
+
+    Место — кусок пути, а не файл: край — это место в замысле, и файл, который
+    разделили надвое, краем быть не перестал.
+
+    `home` — модуль, где функция объявлена: там она написана, а не позвана, и
+    правило его не трогает.
+
+    Настройки: `calls`, `home`.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = ConfinedFunctionsSettings
+    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=ConfinedFunctionsSettings,
+            code=CODE,
+        )
+        where = place(file=file)
+        if where is None or not limits.calls:
+            return
+        if limits.home is not None and where.holds(path=limits.home):
+            return
+        for node in ast.walk(file.tree):
+            if not isinstance(node, ast.Call):
+                continue
+            called = ast.unparse(node.func)
+            allowed = cls._allowed(
+                called=called,
+                calls=limits.calls,
+            )
+            if allowed is None or where.anywhere(
+                zones=allowed,
+            ):
+                continue
+            yield Violation.from_node(
+                node=node,
+                path=file.path,
+                code=CODE,
+                message=f"{called}() зовут не отсюда; её места — {', '.join(allowed)}",
+            )
+
+    @staticmethod
+    def _allowed(
+        *,
+        called: str,
+        calls: dict[str, tuple[str, ...]],
+    ) -> tuple[str, ...] | None:
+        return next(
+            (
+                zones
+                for pattern, zones in calls.items()
+                if matches(
+                    called=called,
+                    pattern=pattern,
+                )
+            ),
+            None,
+        )

py_checks/checks/calls/_marker.py

@@ -0,0 +1,5 @@
+"""Слово группы для пометок: `# call-ok: <код>: <причина>`."""
+
+from typing import Final
+
+MARKER: Final = "# call-ok"

py_checks/checks/database/__init__.py

@@ -0,0 +1,39 @@
+"""База данных.
+
+Граница транзакции, материал колонки, форма запроса. Готового тут почти нет:
+`pytest-alembic` отвечает на откат миграции, `alembic check` — на расхождение
+моделей и миграций, но звать его приходится самим: ему нужна живая база,
+поэтому `schema-drift` объявлен `ENVIRONMENT`. Остальное — соглашения проекта.
+"""
+
+from py_checks.checks.database._bound_checks import BoundChecks, BoundChecksSettings
+from py_checks.checks.database._confined_calls import (
+    Confined,
+    ConfinedCalls,
+    ConfinedCallsSettings,
+)
+from py_checks.checks.database._marker import MARKER
+from py_checks.checks.database._model_boundary import ModelBoundary, ModelBoundarySettings
+from py_checks.checks.database._model_columns import ModelColumns, ModelColumnsSettings
+from py_checks.checks.database._raw_sql import RawSql, RawSqlSettings
+from py_checks.checks.database._schema_drift import SchemaDrift, SchemaDriftSettings
+from py_checks.checks.database._statement_keys import StatementKeys, StatementKeysSettings
+
+__all__ = [
+    "MARKER",
+    "BoundChecks",
+    "BoundChecksSettings",
+    "Confined",
+    "ConfinedCalls",
+    "ConfinedCallsSettings",
+    "ModelBoundary",
+    "ModelBoundarySettings",
+    "ModelColumns",
+    "ModelColumnsSettings",
+    "RawSql",
+    "RawSqlSettings",
+    "SchemaDrift",
+    "SchemaDriftSettings",
+    "StatementKeys",
+    "StatementKeysSettings",
+]

py_checks/checks/database/_bound_checks.py

@@ -0,0 +1,186 @@
+"""Ограниченная колонка повторяет своё ограничение в базе."""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, ClassVar, Final
+
+from py_checks.checks._location import ZonedSettings, zoned
+from py_checks.checks._names import name
+from py_checks.checks.database._marker import MARKER
+from py_checks.core import Scope, Violation, settings_as
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from py_checks.config import CheckSettings
+    from py_checks.core import ParsedFile
+
+CODE: Final = "bound-checks"
+
+MAPPED: Final = "Mapped"
+
+
+class BoundChecksSettings(ZonedSettings):
+    primitives: tuple[str, ...] = ()
+    call: str = "bound_check"
+    column: str = "column"
+    primitive: str = "primitive"
+
+
+class BoundChecks:
+    """Падает, если ограниченная колонка не повторила своё ограничение как CHECK.
+
+    Колонка, объявленная `Mapped[PositiveDecimal]`, обещает дважды. pyright
+    держит каждую строку, СОБРАННУЮ здесь, значениями, которые тип пропустил;
+    `bound_check(column=..., primitive=PositiveDecimal)` в `__table_args__`
+    держит каждую строку, записанную любым другим способом — бэкфилл, сессия
+    psql, второй сервис в следующем году. Правило связывает две половины:
+    аннотация без CHECK — это база, доверяющая коду, которого она не видела.
+
+    Проверяется наличие, а не эквивалентность, и потому ему можно верить: SQL
+    генерируется из того же `BOUND`, которым отказывает тип, так что второго
+    выражения для сравнения просто нет — есть вызов, который могли забыть.
+    Отдельно отвергается `primitive=`, называющий не тот тип, что в аннотации:
+    это единственный способ протащить расхождение обратно.
+
+    Список ограниченных типов проектный: библиотека не может знать, что у
+    этого сервиса деньги — `PositiveDecimal`, а доля — `MarginFraction`. Без
+    списка правило молчит.
+
+    Настройки: `zones`, `primitives`, `call`, `column`, `primitive`.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = BoundChecksSettings
+    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=BoundChecksSettings,
+            code=CODE,
+        )
+        where = zoned(
+            file=file,
+            zones=limits.zones,
+        )
+        if where is None:
+            return
+        for node in file.tree.body:
+            if isinstance(node, ast.ClassDef):
+                yield from cls._columns(
+                    file=file,
+                    node=node,
+                    limits=limits,
+                )
+
+    @classmethod
+    def _columns(
+        cls,
+        *,
+        file: ParsedFile,
+        node: ast.ClassDef,
+        limits: BoundChecksSettings,
+    ) -> Iterator[Violation]:
+        declared = cls._declared(
+            node=node,
+            limits=limits,
+        )
+        for statement in node.body:
+            if not isinstance(statement, ast.AnnAssign):
+                continue
+            if not isinstance(statement.target, ast.Name):
+                continue
+            bounded = cls._bounded(node=statement.annotation)
+            if bounded is None or bounded not in limits.primitives:
+                continue
+            field = statement.target.id
+            said = declared.get(field)
+            if said == bounded:
+                continue
+            yield Violation.from_node(
+                node=statement,
+                path=file.path,
+                code=CODE,
+                message=cls._message(
+                    field=field,
+                    bounded=bounded,
+                    said=said,
+                    limits=limits,
+                ),
+            )
+
+    @staticmethod
+    def _message(
+        *,
+        field: str,
+        bounded: str,
+        said: str | None,
+        limits: BoundChecksSettings,
+    ) -> str:
+        if said is None:
+            return (
+                f"{field} объявлено как {bounded}, но CHECK не несёт; добавь "
+                f"{limits.call}({limits.column}={field}, {limits.primitive}={bounded}) "
+                f"в __table_args__"
+            )
+        return (
+            f"{field} объявлено как {bounded}, а его {limits.call} называет {said}; "
+            f"аннотация и CHECK читают одну границу"
+        )
+
+    @classmethod
+    def _declared(
+        cls,
+        *,
+        node: ast.ClassDef,
+        limits: BoundChecksSettings,
+    ) -> dict[str, str]:
+        """Колонка — тип, по каждому вызову в теле класса."""
+        found: dict[str, str] = {}
+        for child in ast.walk(node):
+            if not isinstance(child, ast.Call) or name(node=child.func) != limits.call:
+                continue
+            column = cls._argument(
+                node=child,
+                named=limits.column,
+            )
+            primitive = cls._argument(
+                node=child,
+                named=limits.primitive,
+            )
+            if column is not None and primitive is not None:
+                found[column] = primitive
+        return found
+
+    @staticmethod
+    def _argument(
+        *,
+        node: ast.Call,
+        named: str,
+    ) -> str | None:
+        for keyword in node.keywords:
+            if keyword.arg == named and isinstance(keyword.value, ast.Name):
+                return keyword.value.id
+        return None
+
+    @staticmethod
+    def _bounded(*, node: ast.expr) -> str | None:
+        """X из `Mapped[X]` или `Mapped[X | None]`, если это простое имя."""
+        if not isinstance(node, ast.Subscript) or name(node=node.value) != MAPPED:
+            return None
+        match node.slice:
+            case ast.Name(id=inside):
+                return inside
+            case ast.BinOp(left=ast.Name(id=inside), op=ast.BitOr()):
+                return inside
+            case _:
+                return None

py_checks/checks/database/_confined_calls.py

@@ -0,0 +1,115 @@
+"""Вызов, который принадлежит одному модулю, и больше никому."""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, ClassVar, Final
+
+from py_checks.checks._location import ZonedSettings, place
+from py_checks.checks.database._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._location import Place
+    from py_checks.core import ParsedFile
+
+CODE: Final = "confined-calls"
+
+
+class Confined(ZonedSettings):
+    """Имена методов, зона, где они запрещены, и модуль, который ими владеет.
+
+    `owner` — имя модуля без расширения. Правило его не касается: там вызов и
+    должен стоять, потому и владелец.
+
+    `outside` — куски зоны, где правило молчит. Имя метода — всё, что видно по
+    одному файлу, и край брокера тому пример: `commit()` у консьюмера
+    подтверждает смещение, а не транзакцию базы.
+    """
+
+    methods: tuple[str, ...]
+    outside: tuple[str, ...] = ()
+    owner: str | None = None
+    said: str = "этим владеет другой модуль"
+
+
+class ConfinedCallsSettings(CheckSettings):
+    rules: tuple[Confined, ...] = ()
+
+
+class ConfinedCalls:
+    """Падает, если названный метод позвали не там, где ему место.
+
+    Написано ради границы транзакции. Ставка — это одна транзакция: списать
+    деньги, записать ставку, записать событие, которое расскажет об этом
+    остальной платформе. Репозиторий, коммитящий в середине, превращает её в
+    три, и сальдо перестаёт сходиться со ставками. `begin` запрещён рядом с
+    `commit` и `rollback` по той же причине с другого конца: вызывающий уже
+    открыл транзакцию, а вторая внутри либо падает, либо тихо делает вложенную.
+
+    Имя метода — всё, что видно по одному файлу: чей это объект, сказал бы
+    только вывод типов. Поэтому правило и сужено зоной — там, где `commit()`
+    может быть только у сессии.
+
+    Настройка: `rules`.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = ConfinedCallsSettings
+    scope: ClassVar[Scope] = Scope.FILE
+    marker: ClassVar[str] = MARKER
+
+    @classmethod
+    def run(
+        cls,
+        *,
+        file: ParsedFile,
+        settings: CheckSettings,
+    ) -> Iterator[Violation]:
+        rules = settings_as(
+            settings=settings,
+            model=ConfinedCallsSettings,
+            code=CODE,
+        ).rules
+        where = place(file=file)
+        if where is None:
+            return
+        listed = [
+            rule
+            for rule in rules
+            if cls._covers(
+                rule=rule,
+                where=where,
+                file=file,
+            )
+        ]
+        if not listed:
+            return
+        for node in ast.walk(file.tree):
+            if not isinstance(node, ast.Call) or not isinstance(node.func, ast.Attribute):
+                continue
+            rule = next((one for one in listed if node.func.attr in one.methods), None)
+            if rule is None:
+                continue
+            yield Violation.from_node(
+                node=node,
+                path=file.path,
+                code=CODE,
+                message=f"{ast.unparse(node.func)}: {rule.said}",
+            )
+
+    @staticmethod
+    def _covers(
+        *,
+        rule: Confined,
+        where: Place,
+        file: ParsedFile,
+    ) -> bool:
+        if rule.owner is not None and file.path.stem == rule.owner:
+            return False
+        if where.anywhere(zones=rule.outside):
+            return False
+        return where.anywhere(zones=rule.zones)

py_checks/checks/database/_marker.py

@@ -0,0 +1,5 @@
+"""Слово группы для пометок: `# db-ok: <код>: <причина>`."""
+
+from typing import Final
+
+MARKER: Final = "# db-ok"