grind-t-lint-rules 0.1.0__tar.gz

grind_t_lint_rules-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: grind-t-lint-rules
+Version: 0.1.0
+Summary: Custom lint rules for Python projects
+Author: grind-t
+Author-email: grind-t <grindt.gd@gmail.com>
+License-Expression: ISC
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/grind-t/lint-rules-py
+Project-URL: Issues, https://github.com/grind-t/lint-rules-py/issues

grind_t_lint_rules-0.1.0/pyproject.toml

@@ -0,0 +1,130 @@
+[project]
+name = "grind-t-lint-rules"
+version = "0.1.0"
+description = "Custom lint rules for Python projects"
+license = "ISC"
+requires-python = ">=3.14"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = []
+
+[[project.authors]]
+name = "grind-t"
+email = "grindt.gd@gmail.com"
+
+[project.urls]
+Homepage = "https://github.com/grind-t/lint-rules-py"
+Issues = "https://github.com/grind-t/lint-rules-py/issues"
+
+[project.scripts]
+lint-rules = "lint_rules._wiring.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.12.9,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "lint_rules"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "RUF",
+    "PT",
+    "N",
+    "C4",
+    "PIE",
+    "PERF",
+    "FURB",
+    "PTH",
+    "T20",
+    "ANN",
+    "ASYNC",
+    "DTZ",
+]
+ignore = ["RUF001"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["ANN"]
+"benchmarks/**" = ["ANN"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = [
+    "--import-mode=importlib",
+    "--strict-markers",
+    "--strict-config",
+    "-ra",
+]
+xfail_strict = true
+filterwarnings = ["error"]
+
+[tool.poe.tasks]
+fmt = "ruff format"
+typecheck = "ty check"
+test-unit = "pytest tests/core tests/usecases"
+test-integration = "pytest tests --ignore=tests/core --ignore=tests/usecases"
+test = "pytest"
+bench = "pytest benchmarks --codspeed"
+build = "uv build"
+check = [
+    "lint",
+    "typecheck",
+    "test-unit",
+]
+
+[[tool.poe.tasks.lint]]
+cmd = "ruff check"
+
+[[tool.poe.tasks.lint]]
+cmd = "lint-imports"
+
+[[tool.poe.tasks.lint]]
+cmd = "lint-rules src"
+
+[tool.importlinter]
+root_package = "lint_rules"
+include_external_packages = true
+
+[[tool.importlinter.contracts]]
+name = "Layers: dependencies point inward only"
+type = "layers"
+layers = [
+    "lint_rules._wiring",
+    "lint_rules._adapters | lint_rules._usecases",
+    "lint_rules._ports",
+    "lint_rules._core",
+]
+
+[[tool.importlinter.contracts]]
+name = "Core, ports and use cases do no I/O"
+type = "forbidden"
+source_modules = [
+    "lint_rules._core",
+    "lint_rules._ports",
+    "lint_rules._usecases",
+]
+forbidden_modules = [
+    "os",
+    "io",
+    "pathlib",
+    "socket",
+    "subprocess",
+]
+
+[dependency-groups]
+dev = [
+    "import-linter",
+    "poethepoet",
+    "pytest",
+    "pytest-codspeed",
+    "ruff",
+    "ty",
+]

grind_t_lint_rules-0.1.0/pyproject.toml.orig

@@ -0,0 +1,92 @@
+[project]
+name = "grind-t-lint-rules"
+version = "0.1.0"
+description = "Custom lint rules for Python projects"
+license = "ISC"
+authors = [
+    { name = "grind-t", email = "grindt.gd@gmail.com" }
+]
+requires-python = ">=3.14"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/grind-t/lint-rules-py"
+Issues = "https://github.com/grind-t/lint-rules-py/issues"
+
+[project.scripts]
+lint-rules = "lint_rules._wiring.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.12.9,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "lint_rules"
+
+[tool.ruff.lint]
+select = [
+    "E", "F", "I", "UP", "B", "SIM", "RUF", "PT", "N",
+    "C4", "PIE", "PERF", "FURB", "PTH", "T20", "ANN", "ASYNC", "DTZ",
+]
+ignore = ["RUF001"]  # allow Cyrillic in strings
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["ANN"]
+"benchmarks/**" = ["ANN"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["--import-mode=importlib", "--strict-markers", "--strict-config", "-ra"]
+xfail_strict = true
+filterwarnings = ["error"]
+
+[tool.poe.tasks]
+fmt = "ruff format"
+lint = [
+    { cmd = "ruff check" },
+    { cmd = "lint-imports" },
+    { cmd = "lint-rules src" },
+]
+typecheck = "ty check"
+test-unit = "pytest tests/core tests/usecases"
+test-integration = "pytest tests --ignore=tests/core --ignore=tests/usecases"
+test = "pytest"
+bench = "pytest benchmarks --codspeed"
+build = "uv build"
+check = ["lint", "typecheck", "test-unit"]
+
+[dependency-groups]
+dev = [
+    "import-linter",
+    "poethepoet",
+    "pytest",
+    "pytest-codspeed",
+    "ruff",
+    "ty",
+]
+
+# ---------- Architecture rules enforced by lint-imports ----------
+[tool.importlinter]
+root_package = "lint_rules"
+include_external_packages = true
+
+[[tool.importlinter.contracts]]
+name = "Layers: dependencies point inward only"
+type = "layers"
+layers = [
+    "lint_rules._wiring",
+    "lint_rules._adapters | lint_rules._usecases",
+    "lint_rules._ports",
+    "lint_rules._core",
+]
+
+[[tool.importlinter.contracts]]
+name = "Core, ports and use cases do no I/O"
+type = "forbidden"
+source_modules = ["lint_rules._core", "lint_rules._ports", "lint_rules._usecases"]
+# also add adapters' third-party dependencies here (httpx, etc.)
+forbidden_modules = ["os", "io", "pathlib", "socket", "subprocess"]

grind_t_lint_rules-0.1.0/src/lint_rules/__init__.py

@@ -0,0 +1,4 @@
+from lint_rules._core.violation import Violation
+from lint_rules._wiring.cli import main
+
+__all__ = ["Violation", "main"]

grind_t_lint_rules-0.1.0/src/lint_rules/_adapters/fs_source_files.py

@@ -0,0 +1,9 @@
+from collections.abc import Iterable, Iterator
+from pathlib import Path
+
+
+def read_fs_source_files(roots: Iterable[str]) -> Iterator[tuple[str, str]]:
+    """Python files from the local filesystem."""
+    for root in roots:
+        for path in sorted(Path(root).rglob("*.py")):
+            yield str(path), path.read_text(encoding="utf-8")

grind_t_lint_rules-0.1.0/src/lint_rules/_core/bases.py

@@ -0,0 +1,12 @@
+import ast
+
+
+def base_name(base: ast.expr) -> str:
+    """Last name component of a base class expression, e.g. ``Protocol[T]``."""
+    if isinstance(base, ast.Subscript):
+        base = base.value
+    if isinstance(base, ast.Name):
+        return base.id
+    if isinstance(base, ast.Attribute):
+        return base.attr
+    return ""

grind_t_lint_rules-0.1.0/src/lint_rules/_core/public_classes.py

@@ -0,0 +1,27 @@
+import ast
+
+from lint_rules._core.bases import base_name
+
+ENUM_BASES = {"Enum", "IntEnum", "StrEnum", "Flag", "IntFlag"}
+EXCEPTION_SUFFIXES = ("Error", "Exception", "Warning")
+
+
+def _is_exempt(cls: ast.ClassDef, exempt: set[str]) -> bool:
+    names = [base_name(base) for base in cls.bases]
+    return any(
+        n in ENUM_BASES or n in exempt or n.endswith(EXCEPTION_SUFFIXES) for n in names
+    )
+
+
+def public_classes(tree: ast.Module) -> list[str]:
+    """Public top-level classes of a module, excluding exceptions and enums."""
+    exempt: set[str] = set()
+    found: list[str] = []
+    for node in tree.body:
+        if not isinstance(node, ast.ClassDef):
+            continue
+        if _is_exempt(node, exempt):
+            exempt.add(node.name)
+        elif not node.name.startswith("_"):
+            found.append(node.name)
+    return found

grind_t_lint_rules-0.1.0/src/lint_rules/_core/single_method_classes.py

@@ -0,0 +1,67 @@
+import ast
+from collections.abc import Iterator
+
+from lint_rules._core.bases import base_name
+
+FUNCTION_TYPES = (ast.FunctionDef, ast.AsyncFunctionDef)
+BLOCK_FIELDS = ("body", "orelse", "finalbody", "handlers", "cases")
+BLOCK_TYPES = (ast.stmt, ast.excepthandler, ast.match_case)
+
+
+def _statements(tree: ast.Module) -> Iterator[ast.AST]:
+    """Every statement block of a module, without descending into expressions.
+
+    Classes can only appear among statements, so this finds the same classes
+    as ``ast.walk`` while skipping the bulk of the tree.
+    """
+    stack: list[ast.AST] = [tree]
+    while stack:
+        node = stack.pop()
+        yield node
+        for field in BLOCK_FIELDS:
+            block = getattr(node, field, None)
+            if isinstance(block, list):
+                stack.extend(child for child in block if isinstance(child, BLOCK_TYPES))
+
+
+def _is_filler(stmt: ast.stmt) -> bool:
+    """Docstrings, ``...`` and ``pass``: statements that add nothing to a class."""
+    if isinstance(stmt, ast.Pass):
+        return True
+    return isinstance(stmt, ast.Expr) and isinstance(stmt.value, ast.Constant)
+
+
+def _single_method(cls: ast.ClassDef) -> str | None:
+    """Name of the only method of a stateless class."""
+    if cls.decorator_list or cls.keywords:
+        return None
+    bases = {base_name(base) for base in cls.bases} - {"object"}
+    if bases - {"Protocol"}:
+        return None
+    methods: list[str] = []
+    for stmt in cls.body:
+        if isinstance(stmt, FUNCTION_TYPES):
+            methods.append(stmt.name)
+        elif not _is_filler(stmt):
+            return None
+    if len(methods) != 1 or methods == ["__init__"]:
+        return None
+    if "Protocol" in bases and methods == ["__call__"]:
+        return None
+    return methods[0]
+
+
+def single_method_classes(tree: ast.Module) -> list[tuple[str, str, int]]:
+    """``(class, method, line)`` for every class that should be a function.
+
+    A class qualifies when its body is one method other than ``__init__`` and
+    nothing else: no decorators, no base classes other than ``Protocol``,
+    no class attributes. A ``Protocol`` whose only method is ``__call__`` is
+    the recommended replacement and is not reported.
+    """
+    found = [
+        (node.name, method, node.lineno)
+        for node in _statements(tree)
+        if isinstance(node, ast.ClassDef) and (method := _single_method(node))
+    ]
+    return sorted(found, key=lambda item: item[2])

grind_t_lint_rules-0.1.0/src/lint_rules/_core/violation.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Violation:
+    path: str
+    message: str
+
+    def __str__(self) -> str:
+        return f"{self.path}: {self.message}"

grind_t_lint_rules-0.1.0/src/lint_rules/_ports/source_files.py

@@ -0,0 +1,8 @@
+from collections.abc import Iterable
+from typing import Protocol
+
+
+class ReadSourceFiles(Protocol):
+    def __call__(self, roots: Iterable[str]) -> Iterable[tuple[str, str]]:
+        """Yield ``(path, source)`` for every Python file under ``roots``."""
+        ...

grind_t_lint_rules-0.1.0/src/lint_rules/_usecases/check_public_classes.py

@@ -0,0 +1,19 @@
+import ast
+
+from lint_rules._core.public_classes import public_classes
+from lint_rules._core.violation import Violation
+
+MARKER = "# allow-multiple-public-classes"
+
+
+def check_public_classes(path: str, source: str, tree: ast.Module) -> list[Violation]:
+    if MARKER in source:
+        return []
+    classes = public_classes(tree)
+    if len(classes) <= 1:
+        return []
+    message = (
+        f"{len(classes)} public classes ({', '.join(classes)}); "
+        "split them into separate modules"
+    )
+    return [Violation(path, message)]

grind_t_lint_rules-0.1.0/src/lint_rules/_usecases/check_single_method_classes.py

@@ -0,0 +1,21 @@
+import ast
+
+from lint_rules._core.single_method_classes import single_method_classes
+from lint_rules._core.violation import Violation
+
+MARKER = "# allow-single-method-classes"
+
+
+def check_single_method_classes(
+    path: str, source: str, tree: ast.Module
+) -> list[Violation]:
+    if MARKER in source:
+        return []
+    return [
+        Violation(
+            path,
+            f"line {line}: class {cls} has a single method {method}; "
+            "use a function, a Callable alias or a Protocol with __call__",
+        )
+        for cls, method, line in single_method_classes(tree)
+    ]

grind_t_lint_rules-0.1.0/src/lint_rules/_usecases/check_source_files.py

@@ -0,0 +1,25 @@
+import ast
+from collections.abc import Callable, Iterable
+
+from lint_rules._core.violation import Violation
+from lint_rules._ports.source_files import ReadSourceFiles
+from lint_rules._usecases.check_public_classes import check_public_classes
+from lint_rules._usecases.check_single_method_classes import (
+    check_single_method_classes,
+)
+
+type Check = Callable[[str, str, ast.Module], list[Violation]]
+
+CHECKS: tuple[Check, ...] = (check_public_classes, check_single_method_classes)
+
+
+def check_source_files(
+    read_files: ReadSourceFiles, roots: Iterable[str]
+) -> list[Violation]:
+    """Run every check on each file, parsing it only once."""
+    violations = []
+    for path, source in read_files(roots):
+        tree = ast.parse(source)
+        for check in CHECKS:
+            violations.extend(check(path, source, tree))
+    return violations

grind_t_lint_rules-0.1.0/src/lint_rules/_wiring/cli.py

@@ -0,0 +1,12 @@
+import sys
+
+from lint_rules._adapters.fs_source_files import read_fs_source_files
+from lint_rules._usecases.check_source_files import check_source_files
+
+
+def main(argv: list[str] | None = None) -> int:
+    roots = (sys.argv[1:] if argv is None else argv) or ["src"]
+    violations = check_source_files(read_fs_source_files, roots)
+    for violation in violations:
+        sys.stderr.write(f"{violation}\n")
+    return int(bool(violations))