flake8-elegant-objects 1.0.0__py3-none-any.whl

flake8_elegant_objects/__init__.py

@@ -0,0 +1,36 @@
+"""Flake8 plugin for Elegant Objects violations.
+
+This plugin detects violations of the Elegant Objects principles including
+"-er" entities, null usage, mutable objects, static methods, and more.
+
+Based on Yegor Bugayenko's principles from elegantobjects.org
+"""
+
+import ast
+from collections.abc import Iterator
+from typing import Any
+
+from .base import ElegantObjectsCore
+
+
+class ElegantObjectsPlugin:
+    """Flake8 plugin to check for Elegant Objects violations."""
+
+    name = "flake8-elegant-objects"
+    version = "1.0.0"
+
+    def __init__(self, tree: ast.AST) -> None:
+        self.tree = tree
+        self._core = ElegantObjectsCore(tree)
+
+    def run(self) -> Iterator[tuple[int, int, str, type["ElegantObjectsPlugin"]]]:
+        """Run the checker and yield errors."""
+        violations = self._core.check_violations()
+        for violation in violations:
+            yield (violation.line, violation.column, violation.message, type(self))
+
+
+# Entry point for flake8 plugin registration
+def factory(_app: Any) -> type[ElegantObjectsPlugin]:
+    """Factory function for flake8 plugin."""
+    return ElegantObjectsPlugin

flake8_elegant_objects/__main__.py

@@ -0,0 +1,68 @@
+"""Standalone command-line interface for flake8-elegant-objects."""
+
+import argparse
+import ast
+import sys
+
+from .base import ElegantObjectsCore
+
+
+def main() -> None:
+    """Standalone command-line interface."""
+    parser = argparse.ArgumentParser(
+        description="Check Python files for Elegant Objects violations"
+    )
+    parser.add_argument("files", nargs="+", help="Python files to check")
+    parser.add_argument(
+        "--show-source",
+        action="store_true",
+        help="Show source code context for violations",
+    )
+
+    args = parser.parse_args()
+
+    total_errors = 0
+
+    for file_path in args.files:
+        if not file_path.endswith(".py"):
+            continue
+
+        try:
+            with open(file_path, encoding="utf-8") as f:
+                source = f.read()
+
+            tree = ast.parse(source, filename=file_path)
+            core = ElegantObjectsCore(tree)
+
+            file_errors = 0
+            violations = core.check_violations()
+
+            for violation in violations:
+                print(
+                    f"{file_path}:{violation.line}:{violation.column}: {violation.message}"
+                )
+
+                if args.show_source:
+                    lines = source.split("\n")
+                    if 0 <= violation.line - 1 < len(lines):
+                        print(f"    {lines[violation.line - 1].strip()}")
+                    print()
+
+                file_errors += 1
+                total_errors += 1
+
+            if file_errors == 0:
+                print(f"{file_path}: No violations found ✓")
+
+        except Exception as e:
+            print(f"Error processing {file_path}: {e}", file=sys.stderr)
+
+    if total_errors > 0:
+        print(f"\nTotal violations found: {total_errors}")
+        sys.exit(1)
+    else:
+        print("\nAll files comply with Elegant Objects principles! ✓")
+
+
+if __name__ == "__main__":
+    main()

flake8_elegant_objects/base.py

@@ -0,0 +1,180 @@
+"""Base classes and protocols for Elegant Objects checkers."""
+
+import ast
+from typing import Protocol
+
+
+class ErrorCodes:
+    """Centralized error message definitions."""
+
+    # Naming violations (EO001-EO004)
+    EO001 = "EO001 Class name '{name}' violates -er principle (describes what it does, not what it is)"
+    EO002 = (
+        "EO002 Method name '{name}' violates -er principle (should be noun, not verb)"
+    )
+    EO003 = (
+        "EO003 Variable name '{name}' violates -er principle (should be noun, not verb)"
+    )
+    EO004 = (
+        "EO004 Function name '{name}' violates -er principle (should be noun, not verb)"
+    )
+    EO005 = "EO005 Null (None) usage violates EO principle (avoid None)"
+    EO006 = "EO006 Code in constructor violates EO principle (constructors should only assign parameters)"
+    EO007 = "EO007 Getter/setter method '{name}' violates EO principle (avoid getters/setters)"
+    EO008 = "EO008 Mutable object violation: '{name}' should be immutable"
+    EO009 = (
+        "EO009 Static method '{name}' violates EO principle (no static methods allowed)"
+    )
+    EO010 = "EO010 isinstance/type casting violates EO principle (avoid type discrimination)"
+    EO011 = "EO011 Public method '{name}' without contract (Protocol/ABC) violates EO principle"
+    EO012 = "EO012 Test method '{name}' contains non-assertThat statements (only assertThat allowed)"
+    EO013 = "EO013 ORM/ActiveRecord pattern '{name}' violates EO principle"
+    EO014 = "EO014 Implementation inheritance violates EO principle (class '{name}' inherits from non-abstract class)"
+
+
+class Violation:
+    """Represents a detected violation."""
+
+    def __init__(self, line: int, column: int, message: str) -> None:
+        self._line = line
+        self._column = column
+        self._message = message
+
+    @property
+    def line(self) -> int:
+        return self._line
+
+    @property
+    def column(self) -> int:
+        return self._column
+
+    @property
+    def message(self) -> str:
+        return self._message
+
+
+Violations = list[Violation]
+
+
+class Source:
+    """Aggregation of AST node and current class context."""
+
+    def __init__(
+        self,
+        node: ast.AST,
+        current_class: ast.ClassDef | None = None,
+        tree: ast.AST | None = None,
+    ) -> None:
+        self._node = node
+        self._current_class = current_class
+        self._tree = tree
+
+    @property
+    def node(self) -> ast.AST:
+        return self._node
+
+    @property
+    def current_class(self) -> ast.ClassDef | None:
+        return self._current_class
+
+    @property
+    def tree(self) -> ast.AST | None:
+        return self._tree
+
+
+class Principle(Protocol):
+    """Protocol for Elegant Objects principles analysis."""
+
+    def check(self, source: Source) -> Violations:
+        """Check source for violations and return list of detected violations."""
+        ...
+
+
+def violation(node: ast.AST, message: str) -> Violations:
+    """Create a violation if node has location information."""
+    if hasattr(node, "lineno") and hasattr(node, "col_offset"):
+        return [Violation(node.lineno, node.col_offset, message)]
+    return []
+
+
+def is_method(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    """Check if function is a method (has self parameter)."""
+    if not node.args.args:
+        return False
+    return node.args.args[0].arg in ("self", "cls")
+
+
+def get_all_principles() -> list[Principle]:
+    """Get all available Elegant Objects principle checkers."""
+    # Import here to avoid circular imports
+    from .no_constructor_code import NoConstructorCode
+    from .no_er_name import NoErName
+    from .no_getters_setters import NoGettersSetters
+    from .no_implementation_inheritance import NoImplementationInheritance
+    from .no_impure_tests import NoImpureTests
+    from .no_mutable_objects import NoMutableObjects
+    from .no_null import NoNull
+    from .no_orm import NoOrm
+    from .no_public_methods_without_contracts import NoPublicMethodsWithoutContracts
+    from .no_static import NoStatic
+    from .no_type_discrimination import NoTypeDiscrimination
+
+    return [
+        NoErName(),
+        NoNull(),
+        NoConstructorCode(),
+        NoGettersSetters(),
+        NoMutableObjects(),
+        NoStatic(),
+        NoTypeDiscrimination(),
+        NoPublicMethodsWithoutContracts(),
+        NoImpureTests(),
+        NoOrm(),
+        NoImplementationInheritance(),
+    ]
+
+
+class ElegantObjectsCore:
+    """Core analyzer for Elegant Objects violations."""
+
+    def __init__(self, tree: ast.AST) -> None:
+        self.tree = tree
+
+    def check_violations(self) -> list[Violation]:
+        """Check for all violations in the AST tree."""
+        violations = []
+        for violation in self._visit(self.tree, None):
+            violations.append(violation)
+        return violations
+
+    def _visit(
+        self, node: ast.AST, current_class: ast.ClassDef | None = None
+    ) -> list[Violation]:
+        """Visit AST nodes and check for violations."""
+        violations = []
+
+        if isinstance(node, ast.ClassDef):
+            current_class = node
+
+        # Check principles on current node
+        violations.extend(self._check_principles(node, current_class))
+
+        # Visit child nodes
+        for child in ast.iter_child_nodes(node):
+            violations.extend(self._visit(child, current_class))
+
+        return violations
+
+    def _check_principles(
+        self, node: ast.AST, current_class: ast.ClassDef | None
+    ) -> list[Violation]:
+        """Check all principles against the given node."""
+        violations = []
+        source = Source(node, current_class, self.tree)
+        principles = get_all_principles()
+
+        for principle in principles:
+            principle_violations = principle.check(source)
+            violations.extend(principle_violations)
+
+        return violations

flake8_elegant_objects/no_constructor_code.py

@@ -0,0 +1,45 @@
+"""No constructor code principle checker for Elegant Objects violations."""
+
+import ast
+
+from .base import ErrorCodes, Source, Violations, is_method, violation
+
+
+class NoConstructorCode:
+    """Checks for code in constructors beyond parameter assignments (EO006)."""
+
+    def check(self, source: Source) -> Violations:
+        """Check source for constructor code violations."""
+        node = source.node
+        if not isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+            return []
+        return self._check_constructor_code(node)
+
+    def _check_constructor_code(
+        self, node: ast.FunctionDef | ast.AsyncFunctionDef
+    ) -> Violations:
+        """Check for code in constructors beyond parameter assignments."""
+        if node.name != "__init__" or not is_method(node):
+            return []
+
+        violations = []
+        # Constructors should only contain assignments to self.attribute = parameter
+        for stmt in node.body:
+            if isinstance(stmt, ast.Assign):
+                # Check if it's a simple self.attr = param assignment
+                if len(stmt.targets) == 1 and isinstance(
+                    stmt.targets[0], ast.Attribute
+                ):
+                    target = stmt.targets[0]
+                    if isinstance(target.value, ast.Name) and target.value.id == "self":
+                        # This is a self.attr assignment, check if value is a simple name
+                        if not isinstance(stmt.value, ast.Name):
+                            violations.extend(violation(stmt, ErrorCodes.EO006))
+                    else:
+                        violations.extend(violation(stmt, ErrorCodes.EO006))
+                else:
+                    violations.extend(violation(stmt, ErrorCodes.EO006))
+            elif not isinstance(stmt, ast.Pass):  # Allow pass statements
+                violations.extend(violation(stmt, ErrorCodes.EO006))
+
+        return violations

flake8_elegant_objects/no_er_name.py

@@ -0,0 +1,306 @@
+"""Naming violations checker for Elegant Objects principles."""
+
+import ast
+import re
+from typing import ClassVar
+
+from .base import ErrorCodes, Source, Violations, is_method, violation
+
+
+class NoErName:
+    """Checks for naming violations in classes, methods, variables, and functions."""
+
+    # Hall of shame: common -er suffixes (from elegantobjects.org)
+    ER_SUFFIXES: ClassVar[set[str]] = {
+        "accumulator",
+        "adapter",
+        "aggregator",
+        "analyzer",
+        "broker",
+        "builder",
+        "calculator",
+        "checker",
+        "collector",
+        "compiler",
+        "compressor",
+        "consumer",
+        "controller",
+        "converter",
+        "coordinator",
+        "creator",
+        "decoder",
+        "decompressor",
+        "deserializer",
+        "dispatcher",
+        "displayer",
+        "encoder",
+        "evaluator",
+        "executor",
+        "exporter",
+        "factory",
+        "fetcher",
+        "filter",
+        "finder",
+        "formatter",
+        "generator",
+        "handler",
+        "helper",
+        "importer",
+        "interpreter",
+        "joiner",
+        "listener",
+        "loader",
+        "manager",
+        "mediator",
+        "merger",
+        "monitor",
+        "observer",
+        "orchestrator",
+        "organizer",
+        "parser",
+        "printer",
+        "processor",
+        "producer",
+        "provider",
+        "reader",
+        "renderer",
+        "reporter",
+        "router",
+        "runner",
+        "saver",
+        "scanner",
+        "scheduler",
+        "serializer",
+        "sorter",
+        "splitter",
+        "supplier",
+        "synchronizer",
+        "tracker",
+        "transformer",
+        "validator",
+        "worker",
+        "wrapper",
+        "writer",
+    }
+
+    # Common procedural verbs that should be nouns
+    PROCEDURAL_VERBS: ClassVar[set[str]] = {
+        "accumulate",
+        "add",
+        "aggregate",
+        "analyze",
+        "append",
+        "build",
+        "calculate",
+        "change",
+        "check",
+        "clean",
+        "clear",
+        "close",
+        "collect",
+        "compile",
+        "compress",
+        "control",
+        "convert",
+        "create",
+        "decode",
+        "decompress",
+        "delete",
+        "deserialize",
+        "dispatch",
+        "display",
+        "do",
+        "encode",
+        "evaluate",
+        "execute",
+        "export",
+        "fetch",
+        "filter",
+        "find",
+        "format",
+        "generate",
+        "get",
+        "handle",
+        "hide",
+        "import",
+        "insert",
+        "interpret",
+        "join",
+        "load",
+        "manage",
+        "merge",
+        "modify",
+        "open",
+        "organize",
+        "parse",
+        "pause",
+        "prepend",
+        "print",
+        "process",
+        "put",
+        "read",
+        "receive",
+        "refresh",
+        "remove",
+        "render",
+        "reset",
+        "resume",
+        "retrieve",
+        "route",
+        "run",
+        "save",
+        "schedule",
+        "search",
+        "send",
+        "serialize",
+        "set",
+        "show",
+        "sort",
+        "split",
+        "start",
+        "stop",
+        "store",
+        "transform",
+        "transmit",
+        "update",
+        "validate",
+        "write",
+    }
+
+    # Allowed exceptions (common patterns that are OK)
+    ALLOWED_EXCEPTIONS: ClassVar[set[str]] = {
+        "buffer",
+        "character",
+        "cluster",
+        "container",
+        "counter",
+        "error",
+        "footer",
+        "header",
+        "identifier",
+        "number",
+        "order",
+        "owner",
+        "parameter",
+        "pointer",
+        "register",
+        "server",
+        "timer",
+        "user",
+    }
+
+    def check(self, source: Source) -> Violations:
+        """Check source for naming violations."""
+        violations = []
+        node = source.node
+
+        if isinstance(node, ast.ClassDef):
+            violations.extend(self._check_class_name(node))
+        elif isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+            violations.extend(self._check_function_name(node))
+        elif isinstance(node, ast.Assign):
+            violations.extend(self._check_variable_assignment(node))
+        elif isinstance(node, ast.AnnAssign):
+            violations.extend(self._check_annotated_assignment(node))
+
+        return violations
+
+    def _check_class_name(self, node: ast.ClassDef) -> Violations:
+        """Check if class name violates -er principle."""
+        name = node.name.lower()
+
+        # Skip if it's an allowed exception
+        if name in self.ALLOWED_EXCEPTIONS:
+            return []
+
+        # Check for -er suffixes (the hall of shame)
+        for suffix in self.ER_SUFFIXES:
+            if name.endswith(suffix):
+                return violation(node, ErrorCodes.EO001.format(name=node.name))
+
+        # Check for procedural patterns in compound names
+        if self._contains_procedural_pattern(name):
+            return violation(node, ErrorCodes.EO001.format(name=node.name))
+
+        return []
+
+    def _check_function_name(
+        self, node: ast.FunctionDef | ast.AsyncFunctionDef
+    ) -> Violations:
+        """Check if function/method name violates -er principle."""
+        # Skip special methods (__init__, __str__, etc.)
+        if node.name.startswith("_"):
+            return []
+
+        # Skip common property patterns
+        if node.name in ("property", "getter", "setter"):
+            return []
+
+        # Check for procedural verbs
+        if self._starts_with_procedural_verb(node.name):
+            # Determine if it's a method or standalone function
+            error_code = ErrorCodes.EO002 if is_method(node) else ErrorCodes.EO004
+            return violation(node, error_code.format(name=node.name))
+
+        return []
+
+    def _check_variable_assignment(self, node: ast.Assign) -> Violations:
+        """Check variable names in assignments."""
+        violations = []
+        for target in node.targets:
+            if isinstance(target, ast.Name):
+                violations.extend(self._check_variable_name(target))
+        return violations
+
+    def _check_annotated_assignment(self, node: ast.AnnAssign) -> Violations:
+        """Check variable names in annotated assignments."""
+        if isinstance(node.target, ast.Name):
+            return self._check_variable_name(node.target)
+        return []
+
+    def _check_variable_name(self, node: ast.Name) -> Violations:
+        """Check if variable name violates -er principle."""
+        # Skip private variables and common patterns
+        if node.id.startswith("_") or node.id.isupper():
+            return []
+
+        name = node.id.lower()
+
+        # Skip if it's an allowed exception
+        if name in self.ALLOWED_EXCEPTIONS:
+            return []
+
+        # Check for -er suffixes
+        for suffix in self.ER_SUFFIXES:
+            if name.endswith(suffix):
+                return violation(node, ErrorCodes.EO003.format(name=node.id))
+
+        # Check for procedural verbs as variable names
+        if self._starts_with_procedural_verb(name):
+            return violation(node, ErrorCodes.EO003.format(name=node.id))
+
+        return []
+
+    def _contains_procedural_pattern(self, name: str) -> bool:
+        """Check if name contains procedural patterns."""
+        # Split camelCase/snake_case into words
+        words = re.findall(r"[a-z]+", name)
+
+        # Check if any word is a procedural verb
+        return any(word in self.PROCEDURAL_VERBS for word in words)
+
+    def _starts_with_procedural_verb(self, name: str) -> bool:
+        """Check if name starts with a procedural verb."""
+        # Split camelCase/snake_case and check first word
+        # First split on underscores, then on camelCase boundaries
+        words: list[str] = []
+        for part in name.split("_"):
+            # Split camelCase: insert space before uppercase letters
+            camel_split = re.sub(r"([a-z])([A-Z])", r"\1 \2", part)
+            words.extend(word.lower() for word in camel_split.split() if word)
+
+        if not words:
+            return False
+
+        first_word = words[0]
+        return first_word in self.PROCEDURAL_VERBS

flake8_elegant_objects/no_getters_setters.py

@@ -0,0 +1,57 @@
+"""No getters/setters principle checker for Elegant Objects violations."""
+
+import ast
+
+from .base import ErrorCodes, Source, Violations, is_method, violation
+
+
+class NoGettersSetters:
+    """Checks for getter/setter methods (EO007)."""
+
+    def check(self, source: Source) -> Violations:
+        """Check source for getter/setter violations."""
+        node = source.node
+        if not isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+            return []
+        return self._check_getters_setters(node)
+
+    def _check_getters_setters(
+        self, node: ast.FunctionDef | ast.AsyncFunctionDef
+    ) -> Violations:
+        """Check for getter/setter methods."""
+        if not is_method(node) or node.name.startswith("_"):
+            return []
+
+        # Skip methods with @property decorator
+        for decorator in node.decorator_list:
+            if isinstance(decorator, ast.Name) and decorator.id == "property":
+                return []
+
+        name = node.name.lower()
+        original_name = node.name
+
+        # Check for getter patterns
+        if (
+            name.startswith("get_")
+            or (
+                name.startswith("get")
+                and len(original_name) > 3
+                and original_name[3].isupper()
+            )
+            or name == "get"
+        ):
+            return violation(node, ErrorCodes.EO007.format(name=node.name))
+
+        # Check for setter patterns
+        if (
+            name.startswith("set_")
+            or (
+                name.startswith("set")
+                and len(original_name) > 3
+                and original_name[3].isupper()
+            )
+            or name == "set"
+        ):
+            return violation(node, ErrorCodes.EO007.format(name=node.name))
+
+        return []