community-of-python-flake8-plugin 0.1.0__py3-none-any.whl

community_of_python_flake8_plugin/__init__.py

@@ -0,0 +1,4 @@
+from community_of_python_flake8_plugin.plugin import CommunityOfPythonFlake8Plugin
+
+
+__all__ = ["CommunityOfPythonFlake8Plugin"]

community_of_python_flake8_plugin/checks/README.md

@@ -0,0 +1,35 @@
+# Community of Python Flake8 Plugin - Check Files
+
+This directory contains individual check files, each implementing a specific rule (COP error code).
+
+## Current Checks
+
+| File | Error Code | Description |
+|------|------------|-------------|
+| `cop001.py` | COP001 | Use module import when importing more than two names |
+| `cop002.py` | COP002 | Import standard library modules as whole modules |
+| `cop003.py` | COP003 | Avoid explicit scalar type annotations |
+| `cop004.py` | COP004 | Name must be at least 8 characters |
+| `cop005.py` | COP005 | Function name must be a verb |
+| `cop006.py` | COP006 | Avoid get_ prefix in async function names |
+| `cop007.py` | COP007 | Avoid temporary variables used only once |
+| `cop008.py` | COP008 | Classes should be marked typing.final |
+| `cop009.py` | COP009 | Wrap module dictionaries with types.MappingProxyType |
+| `cop010.py` | COP010 | Use dataclasses with kw_only=True, slots=True, frozen=True |
+
+## File Structure
+
+Each check file follows this pattern:
+- Contains a single class that inherits from `ast.NodeVisitor`
+- Implements visit methods for the AST nodes it needs to check
+- Stores violations in a `self.violations` list
+- Each file is responsible for exactly one error code
+
+## Adding New Checks
+
+To add a new check:
+1. Create a new file `copXXX.py` where XXX is the next available error code
+2. Implement a check class following the pattern of existing checks
+3. Add the import and instantiation in `__init__.py`
+4. Add tests in the test file
+5. Update this README

community_of_python_flake8_plugin/checks/__init__.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+import ast
+import typing
+
+from community_of_python_flake8_plugin.checks.cop001 import COP001Check
+from community_of_python_flake8_plugin.checks.cop002 import COP002Check
+from community_of_python_flake8_plugin.checks.cop003 import COP003Check
+from community_of_python_flake8_plugin.checks.cop004 import COP004Check
+from community_of_python_flake8_plugin.checks.cop005 import COP005Check
+from community_of_python_flake8_plugin.checks.cop006 import COP006Check
+from community_of_python_flake8_plugin.checks.cop007 import COP007Check
+from community_of_python_flake8_plugin.checks.cop008 import COP008Check
+from community_of_python_flake8_plugin.checks.cop009 import COP009Check
+from community_of_python_flake8_plugin.checks.cop010 import COP010Check
+from community_of_python_flake8_plugin.utils import check_module_has_all_declaration
+
+
+if typing.TYPE_CHECKING:
+    from community_of_python_flake8_plugin.violations import Violation
+
+
+def execute_all_validations(syntax_tree: ast.AST) -> list[Violation]:
+    contains_all_declaration: typing.Final = (
+        check_module_has_all_declaration(syntax_tree) if isinstance(syntax_tree, ast.Module) else False
+    )
+    collected_violations: typing.Final[list[Violation]] = []
+
+    # COP001: Use module import when importing more than two names
+    cop001_validator: typing.Final = COP001Check(contains_all_declaration)
+    cop001_validator.visit(syntax_tree)
+    collected_violations.extend(cop001_validator.violations)
+
+    # COP002: Import standard library modules as whole modules
+    cop002_validator: typing.Final = COP002Check()
+    cop002_validator.visit(syntax_tree)
+    collected_violations.extend(cop002_validator.violations)
+
+    # COP003: Avoid explicit scalar type annotations
+    cop003_validator: typing.Final = COP003Check(syntax_tree)
+    cop003_validator.visit(syntax_tree)
+    collected_violations.extend(cop003_validator.violations)
+
+    # COP004: Name must be at least 8 characters
+    cop004_validator: typing.Final = COP004Check(syntax_tree)
+    cop004_validator.visit(syntax_tree)
+    collected_violations.extend(cop004_validator.violations)
+
+    # COP005: Function identifier must be a verb
+    cop005_validator: typing.Final = COP005Check(syntax_tree)
+    cop005_validator.visit(syntax_tree)
+    collected_violations.extend(cop005_validator.violations)
+
+    # COP006: Avoid get_ prefix in async function names
+    cop006_validator: typing.Final = COP006Check()
+    cop006_validator.visit(syntax_tree)
+    collected_violations.extend(cop006_validator.violations)
+
+    # COP007: Avoid temporary variables used only once
+    cop007_validator: typing.Final = COP007Check()
+    cop007_validator.visit(syntax_tree)
+    collected_violations.extend(cop007_validator.violations)
+
+    # COP008: Classes should be marked typing.final
+    cop008_validator: typing.Final = COP008Check()
+    cop008_validator.visit(syntax_tree)
+    collected_violations.extend(cop008_validator.violations)
+
+    # COP009: Wrap module dictionaries with types.MappingProxyType
+    cop009_validator: typing.Final = COP009Check()
+    cop009_validator.visit(syntax_tree)
+    collected_violations.extend(cop009_validator.violations)
+
+    # COP010: Use dataclasses with kw_only=True, slots=True, frozen=True
+    cop010_validator: typing.Final = COP010Check()
+    cop010_validator.visit(syntax_tree)
+    collected_violations.extend(cop010_validator.violations)
+
+    return collected_violations

community_of_python_flake8_plugin/checks/cop001.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+import ast
+import typing
+from importlib import util as importlib_util
+
+from community_of_python_flake8_plugin.violation_codes import ViolationCodes as ViolationCode
+from community_of_python_flake8_plugin.violations import Violation
+
+
+def check_module_path_exists(module_name: str) -> bool:
+    try:
+        return importlib_util.find_spec(module_name) is not None
+    except (ModuleNotFoundError, ValueError):
+        return False
+
+
+MAX_IMPORT_NAMES: typing.Final = 2
+
+
+@typing.final
+class COP001Check(ast.NodeVisitor):
+    def __init__(self, contains_all_declaration: bool) -> None:
+        self.contains_all_declaration = contains_all_declaration
+        self.violations: list[Violation] = []
+
+    def visit_ImportFrom(self, ast_node: ast.ImportFrom) -> None:
+        if ast_node.module and ast_node.level == 0:
+            self.validate_import_size(ast_node)
+        self.generic_visit(ast_node)
+
+    def validate_import_size(self, ast_node: ast.ImportFrom) -> None:
+        if len(ast_node.names) <= MAX_IMPORT_NAMES:
+            return
+        if self.contains_all_declaration:
+            return
+        module_name: typing.Final = ast_node.module
+        if module_name is not None and module_name.endswith(".settings"):
+            return
+
+        contains_module_import: typing.Final = any(
+            isinstance(identifier, ast.alias)
+            and module_name is not None
+            and check_module_path_exists(f"{module_name}.{identifier.name}")
+            for identifier in ast_node.names
+        )
+        if not contains_module_import:
+            self.violations.append(
+                Violation(
+                    line_number=ast_node.lineno,
+                    column_number=ast_node.col_offset,
+                    violation_code=ViolationCode.MODULE_IMPORT,
+                )
+            )

community_of_python_flake8_plugin/checks/cop002.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+import ast
+import sys
+import typing
+from importlib import util as importlib_util
+
+from community_of_python_flake8_plugin.constants import ALLOWED_STDLIB_FROM_IMPORTS
+from community_of_python_flake8_plugin.violation_codes import ViolationCodes as ViolationCode
+from community_of_python_flake8_plugin.violations import Violation
+
+
+def check_is_stdlib_module(module_name: str) -> bool:
+    return module_name in sys.stdlib_module_names
+
+
+def check_is_stdlib_package(module_name: str) -> bool:
+    if not check_is_stdlib_module(module_name):
+        return False
+    module_spec: typing.Final = importlib_util.find_spec(module_name)
+    return module_spec is not None and module_spec.submodule_search_locations is not None
+
+
+@typing.final
+class COP002Check(ast.NodeVisitor):
+    def __init__(self) -> None:
+        self.violations: list[Violation] = []
+
+    def visit_ImportFrom(self, ast_node: ast.ImportFrom) -> None:
+        if ast_node.module and ast_node.level == 0 and ast_node.module not in ALLOWED_STDLIB_FROM_IMPORTS:
+            self.validate_stdlib_import(ast_node)
+        self.generic_visit(ast_node)
+
+    def validate_stdlib_import(self, ast_node: ast.ImportFrom) -> None:
+        module_name: typing.Final = ast_node.module
+        if module_name is None:
+            return
+        if module_name == "__future__":
+            return
+        if (check_is_stdlib_module(module_name) and not check_is_stdlib_package(module_name)) or (
+            "." in module_name and check_is_stdlib_package(module_name.split(".")[0])
+        ):
+            self.violations.append(
+                Violation(
+                    line_number=ast_node.lineno,
+                    column_number=ast_node.col_offset,
+                    violation_code=ViolationCode.STDLIB_IMPORT,
+                )
+            )

community_of_python_flake8_plugin/checks/cop003.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+import ast
+import typing
+
+from community_of_python_flake8_plugin.constants import SCALAR_ANNOTATIONS
+from community_of_python_flake8_plugin.utils import find_parent_class_definition
+from community_of_python_flake8_plugin.violation_codes import ViolationCodes as ViolationCode
+from community_of_python_flake8_plugin.violations import Violation
+
+
+def check_is_literal_value(value: ast.AST) -> bool:
+    if isinstance(value, ast.Constant):
+        return True
+    return bool(isinstance(value, (ast.List, ast.Tuple, ast.Set, ast.Dict)))
+
+
+def check_is_final_annotation(annotation: ast.AST) -> bool:
+    if isinstance(annotation, ast.Name):
+        return annotation.id == "Final"
+    if isinstance(annotation, ast.Attribute):
+        return annotation.attr == "Final"
+    if isinstance(annotation, ast.Subscript):
+        return check_is_final_annotation(annotation.value)
+    return False
+
+
+def check_is_scalar_annotation(annotation: ast.AST) -> bool:
+    if isinstance(annotation, ast.Name):
+        return annotation.id in SCALAR_ANNOTATIONS
+    if isinstance(annotation, ast.Attribute):
+        return annotation.attr in SCALAR_ANNOTATIONS
+    if isinstance(annotation, ast.Subscript):
+        if check_is_final_annotation(annotation.value):
+            return check_is_scalar_annotation(annotation.slice)
+        return check_is_scalar_annotation(annotation.value)
+    return False
+
+
+def find_parent_function(syntax_tree: ast.AST, ast_node: ast.AST) -> ast.FunctionDef | ast.AsyncFunctionDef | None:
+    for potential_parent in ast.walk(syntax_tree):
+        if isinstance(potential_parent, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            for child in ast.walk(potential_parent):
+                if child is ast_node:
+                    return potential_parent
+    return None
+
+
+@typing.final
+class COP003Check(ast.NodeVisitor):
+    def __init__(self, syntax_tree: ast.AST) -> None:
+        self.syntax_tree = syntax_tree
+        self.violations: list[Violation] = []
+
+    def visit_AnnAssign(self, ast_node: ast.AnnAssign) -> None:
+        if isinstance(ast_node.target, ast.Name):
+            parent_class: typing.Final = find_parent_class_definition(self.syntax_tree, ast_node)
+            parent_function: typing.Final = find_parent_function(self.syntax_tree, ast_node)
+            in_class_body: typing.Final = parent_class is not None and parent_function is None
+
+            if not in_class_body:
+                self.validate_scalar_annotation(ast_node)
+        self.generic_visit(ast_node)
+
+    def validate_scalar_annotation(self, ast_node: ast.AnnAssign) -> None:
+        if ast_node.value is None:
+            return
+        if not check_is_literal_value(ast_node.value):
+            return
+        if check_is_scalar_annotation(ast_node.annotation):
+            self.violations.append(
+                Violation(
+                    line_number=ast_node.lineno,
+                    column_number=ast_node.col_offset,
+                    violation_code=ViolationCode.SCALAR_ANNOTATION,
+                )
+            )

community_of_python_flake8_plugin/checks/cop004.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+import ast
+import typing
+
+from community_of_python_flake8_plugin.constants import FINAL_CLASS_EXCLUDED_BASES, MIN_NAME_LENGTH
+from community_of_python_flake8_plugin.utils import find_parent_class_definition
+from community_of_python_flake8_plugin.violation_codes import ViolationCodes as ViolationCode
+from community_of_python_flake8_plugin.violations import Violation
+
+
+def check_is_ignored_name(identifier: str) -> bool:
+    if identifier == "_":
+        return True
+    if identifier.isupper():
+        return True
+    if identifier in {"value", "values", "pattern"}:
+        return True
+    if identifier.startswith("__") and identifier.endswith("__"):
+        return True
+    return bool(identifier.startswith("_"))
+
+
+def check_is_whitelisted_annotation(annotation: ast.expr | None) -> bool:
+    if annotation is None:
+        return False
+    if isinstance(annotation, ast.Name):
+        return annotation.id in {"fixture", "Faker"}
+    if isinstance(annotation, ast.Attribute) and isinstance(annotation.value, ast.Name):
+        return annotation.value.id in {"pytest", "faker"}
+    return False
+
+
+def check_is_pytest_fixture(ast_node: ast.AST) -> bool:
+    if not isinstance(ast_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        return False
+    return any(check_is_fixture_decorator(decorator) for decorator in ast_node.decorator_list)
+
+
+def check_is_fixture_decorator(decorator: ast.expr) -> bool:
+    if isinstance(decorator, ast.Name):
+        return decorator.id == "fixture"
+    if isinstance(decorator, ast.Attribute):
+        return decorator.attr == "fixture" and isinstance(decorator.value, ast.Name) and decorator.value.id == "pytest"
+    return False
+
+
+def check_inherits_from_whitelisted_class(class_node: ast.ClassDef) -> bool:
+    for base_class in class_node.bases:
+        if isinstance(base_class, ast.Name) and base_class.id in FINAL_CLASS_EXCLUDED_BASES:
+            return True
+        if isinstance(base_class, ast.Attribute) and base_class.attr in FINAL_CLASS_EXCLUDED_BASES:
+            return True
+    return False
+
+
+@typing.final
+class COP004Check(ast.NodeVisitor):
+    def __init__(self, syntax_tree: ast.AST) -> None:
+        self.syntax_tree = syntax_tree
+        self.violations: list[Violation] = []
+
+    def visit_AnnAssign(self, ast_node: ast.AnnAssign) -> None:
+        if isinstance(ast_node.target, ast.Name):
+            parent_class: typing.Final = find_parent_class_definition(self.syntax_tree, ast_node)
+            self.validate_name_length(ast_node.target.id, ast_node, parent_class)
+        self.generic_visit(ast_node)
+
+    def visit_Assign(self, ast_node: ast.Assign) -> None:
+        for target in ast_node.targets:
+            if isinstance(target, ast.Name):
+                parent_class = find_parent_class_definition(self.syntax_tree, ast_node)
+                self.validate_name_length(target.id, ast_node, parent_class)
+        self.generic_visit(ast_node)
+
+    def visit_FunctionDef(self, ast_node: ast.FunctionDef) -> None:
+        parent_class: typing.Final = find_parent_class_definition(self.syntax_tree, ast_node)
+        self.validate_function_name(ast_node, parent_class)
+        self.validate_function_args(ast_node)
+        self.generic_visit(ast_node)
+
+    def visit_AsyncFunctionDef(self, ast_node: ast.AsyncFunctionDef) -> None:
+        parent_class: typing.Final = find_parent_class_definition(self.syntax_tree, ast_node)
+        self.validate_function_name(ast_node, parent_class)
+        self.validate_function_args(ast_node)
+        self.generic_visit(ast_node)
+
+    def visit_ClassDef(self, ast_node: ast.ClassDef) -> None:
+        if not ast_node.name.startswith("Test"):
+            self.validate_class_name_length(ast_node)
+        self.generic_visit(ast_node)
+
+    def validate_name_length(self, identifier: str, ast_node: ast.stmt, parent_class: ast.ClassDef | None) -> None:
+        if check_is_ignored_name(identifier):
+            return
+        # Only apply parent class exemption for assignments within classes
+        if (
+            parent_class
+            and isinstance(ast_node, (ast.AnnAssign, ast.Assign))
+            and check_inherits_from_whitelisted_class(parent_class)
+        ):
+            return
+        if len(identifier) < MIN_NAME_LENGTH:
+            self.violations.append(
+                Violation(
+                    line_number=ast_node.lineno,
+                    column_number=ast_node.col_offset,
+                    violation_code=ViolationCode.NAME_LENGTH,
+                )
+            )
+
+    def validate_function_name(
+        self, ast_node: ast.FunctionDef | ast.AsyncFunctionDef, parent_class: ast.ClassDef | None
+    ) -> None:
+        if ast_node.name == "main":
+            return
+        if check_is_ignored_name(ast_node.name):
+            return
+        if parent_class and check_inherits_from_whitelisted_class(parent_class):
+            return
+        if check_is_pytest_fixture(ast_node):
+            return
+        if len(ast_node.name) < MIN_NAME_LENGTH:
+            self.violations.append(
+                Violation(
+                    line_number=ast_node.lineno,
+                    column_number=ast_node.col_offset,
+                    violation_code=ViolationCode.NAME_LENGTH,
+                )
+            )
+
+    def validate_function_args(self, ast_node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        arguments: typing.Final = ast_node.args
+        for argument in arguments.posonlyargs + arguments.args + arguments.kwonlyargs:
+            self.validate_argument_name_length(argument)
+        if arguments.vararg is not None:
+            self.validate_argument_name_length(arguments.vararg)
+        if arguments.kwarg is not None:
+            self.validate_argument_name_length(arguments.kwarg)
+
+    def validate_argument_name_length(self, argument: ast.arg) -> None:
+        if argument.arg in {"self", "cls"}:
+            return
+        if check_is_ignored_name(argument.arg):
+            return
+        if check_is_whitelisted_annotation(argument.annotation):
+            return
+        if len(argument.arg) < MIN_NAME_LENGTH:
+            self.violations.append(
+                Violation(
+                    line_number=argument.lineno,
+                    column_number=argument.col_offset,
+                    violation_code=ViolationCode.NAME_LENGTH,
+                )
+            )
+
+    def validate_class_name_length(self, ast_node: ast.ClassDef) -> None:
+        if check_is_ignored_name(ast_node.name):
+            return
+        if len(ast_node.name) < MIN_NAME_LENGTH:
+            self.violations.append(
+                Violation(
+                    line_number=ast_node.lineno,
+                    column_number=ast_node.col_offset,
+                    violation_code=ViolationCode.NAME_LENGTH,
+                )
+            )

community_of_python_flake8_plugin/checks/cop005.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+import ast
+import typing
+
+from community_of_python_flake8_plugin.constants import FINAL_CLASS_EXCLUDED_BASES, VERB_PREFIXES
+from community_of_python_flake8_plugin.utils import find_parent_class_definition
+from community_of_python_flake8_plugin.violation_codes import ViolationCodes as ViolationCode
+from community_of_python_flake8_plugin.violations import Violation
+
+
+def check_is_ignored_name(identifier: str) -> bool:
+    if identifier == "_":
+        return True
+    if identifier.isupper():
+        return True
+    if identifier in {"value", "values", "pattern"}:
+        return True
+    if identifier.startswith("__") and identifier.endswith("__"):
+        return True
+    return bool(identifier.startswith("_"))
+
+
+def check_is_verb_name(identifier: str) -> bool:
+    return any(identifier == verb or identifier.startswith(f"{verb}_") for verb in VERB_PREFIXES)
+
+
+def check_is_property(ast_node: ast.AST) -> bool:
+    if not isinstance(ast_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        return False
+    return any(check_is_property_decorator(decorator) for decorator in ast_node.decorator_list)
+
+
+def check_is_property_decorator(decorator: ast.expr) -> bool:
+    if isinstance(decorator, ast.Name):
+        return decorator.id == "property"
+    if isinstance(decorator, ast.Attribute) and decorator.attr in {"property", "setter", "cached_property"}:
+        if isinstance(decorator.value, ast.Name) and decorator.value.id == "functools":
+            return decorator.attr == "cached_property"
+        return decorator.attr in {"property", "setter"}
+    return False
+
+
+def check_is_pytest_fixture(ast_node: ast.AST) -> bool:
+    if not isinstance(ast_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        return False
+    return any(check_is_fixture_decorator(decorator) for decorator in ast_node.decorator_list)
+
+
+def check_is_fixture_decorator(decorator: ast.expr) -> bool:
+    if isinstance(decorator, ast.Name):
+        return decorator.id == "fixture"
+    if isinstance(decorator, ast.Attribute):
+        return decorator.attr == "fixture" and isinstance(decorator.value, ast.Name) and decorator.value.id == "pytest"
+    return False
+
+
+def retrieve_parent_class(syntax_tree: ast.AST, ast_node: ast.AST) -> ast.ClassDef | None:
+    return find_parent_class_definition(syntax_tree, ast_node)
+
+
+@typing.final
+class COP005Check(ast.NodeVisitor):
+    def __init__(self, syntax_tree: ast.AST) -> None:
+        self.syntax_tree = syntax_tree
+        self.violations: list[Violation] = []
+
+    def visit_FunctionDef(self, ast_node: ast.FunctionDef) -> None:
+        parent_class: typing.Final = retrieve_parent_class(self.syntax_tree, ast_node)
+        self.validate_function_name(ast_node, parent_class)
+        self.generic_visit(ast_node)
+
+    def visit_AsyncFunctionDef(self, ast_node: ast.AsyncFunctionDef) -> None:
+        parent_class: typing.Final = retrieve_parent_class(self.syntax_tree, ast_node)
+        self.validate_function_name(ast_node, parent_class)
+        self.generic_visit(ast_node)
+
+    def validate_function_name(
+        self, ast_node: ast.FunctionDef | ast.AsyncFunctionDef, parent_class: ast.ClassDef | None
+    ) -> None:
+        should_skip: typing.Final = (
+            ast_node.name == "main"
+            or (ast_node.name.startswith("__") and ast_node.name.endswith("__"))
+            or check_is_ignored_name(ast_node.name)
+            or (parent_class and self.check_inherits_from_whitelisted_class(parent_class))
+            or check_is_property(ast_node)
+            or check_is_pytest_fixture(ast_node)
+            or check_is_verb_name(ast_node.name)
+        )
+
+        if should_skip:
+            return
+
+        min_acronym_length: typing.Final = 3
+        if len(ast_node.name) < min_acronym_length:  # Short names are likely acronyms or special cases
+            return
+
+        self.violations.append(
+            Violation(
+                line_number=ast_node.lineno,
+                column_number=ast_node.col_offset,
+                violation_code=ViolationCode.FUNCTION_VERB,
+            )
+        )
+
+    def check_inherits_from_whitelisted_class(self, ast_node: ast.ClassDef) -> bool:
+        for base_class in ast_node.bases:
+            if isinstance(base_class, ast.Name) and base_class.id in FINAL_CLASS_EXCLUDED_BASES:
+                return True
+            if isinstance(base_class, ast.Attribute) and base_class.attr in FINAL_CLASS_EXCLUDED_BASES:
+                return True
+        return False

community_of_python_flake8_plugin/checks/cop006.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+import ast
+import typing
+
+from community_of_python_flake8_plugin.violation_codes import ViolationCodes as ViolationCode
+from community_of_python_flake8_plugin.violations import Violation
+
+
+def check_is_ignored_name(identifier: str) -> bool:
+    if identifier == "_":
+        return True
+    if identifier.isupper():
+        return True
+    if identifier in {"value", "values", "pattern"}:
+        return True
+    if identifier.startswith("__") and identifier.endswith("__"):
+        return True
+    return bool(identifier.startswith("_"))
+
+
+def check_is_property(ast_node: ast.AST) -> bool:
+    if not isinstance(ast_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        return False
+    return any(check_is_property_decorator(decorator) for decorator in ast_node.decorator_list)
+
+
+def check_is_property_decorator(decorator: ast.expr) -> bool:
+    if isinstance(decorator, ast.Name):
+        return decorator.id == "property"
+    if isinstance(decorator, ast.Attribute) and decorator.attr in {"property", "setter", "cached_property"}:
+        if isinstance(decorator.value, ast.Name) and decorator.value.id == "functools":
+            return decorator.attr == "cached_property"
+        return decorator.attr in {"property", "setter"}
+    return False
+
+
+def check_is_pytest_fixture(ast_node: ast.AST) -> bool:
+    if not isinstance(ast_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        return False
+    return any(check_is_fixture_decorator(decorator) for decorator in ast_node.decorator_list)
+
+
+def check_is_fixture_decorator(decorator: ast.expr) -> bool:
+    if isinstance(decorator, ast.Name):
+        return decorator.id == "fixture"
+    if isinstance(decorator, ast.Attribute):
+        return decorator.attr == "fixture" and isinstance(decorator.value, ast.Name) and decorator.value.id == "pytest"
+    return False
+
+
+@typing.final
+class COP006Check(ast.NodeVisitor):
+    def __init__(self) -> None:
+        self.violations: list[Violation] = []
+
+    def visit_AsyncFunctionDef(self, ast_node: ast.AsyncFunctionDef) -> None:
+        self._check_get_prefix(ast_node)
+        self.generic_visit(ast_node)
+
+    def _check_get_prefix(self, ast_node: ast.AsyncFunctionDef) -> None:
+        if check_is_property(ast_node) or check_is_pytest_fixture(ast_node):
+            return
+        if check_is_ignored_name(ast_node.name):
+            return
+        if ast_node.name.startswith("get_"):
+            self.violations.append(
+                Violation(
+                    line_number=ast_node.lineno,
+                    column_number=ast_node.col_offset,
+                    violation_code=ViolationCode.ASYNC_GET_PREFIX,
+                )
+            )

community_of_python_flake8_plugin/checks/cop007.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+import ast
+import typing
+
+from community_of_python_flake8_plugin.violation_codes import ViolationCodes as ViolationCode
+from community_of_python_flake8_plugin.violations import Violation
+
+
+def collect_assignments(ast_node: ast.AST) -> dict[str, list[ast.AST]]:
+    assigned: typing.Final[dict[str, list[ast.AST]]] = {}
+    for child in ast.walk(ast_node):
+        if isinstance(child, ast.Assign):
+            for target in child.targets:
+                if isinstance(target, ast.Name):
+                    assigned.setdefault(target.id, []).append(child)
+        if isinstance(child, ast.AnnAssign) and isinstance(child.target, ast.Name):
+            assigned.setdefault(child.target.id, []).append(child)
+    return assigned
+
+
+def collect_load_counts(ast_node: ast.AST) -> dict[str, int]:
+    load_counts_dict: typing.Final[dict[str, int]] = {}
+    for child in ast.walk(ast_node):
+        if isinstance(child, ast.Name) and isinstance(child.ctx, ast.Load):
+            load_counts_dict[child.id] = load_counts_dict.get(child.id, 0) + 1
+    return load_counts_dict
+
+
+@typing.final
+class COP007Check(ast.NodeVisitor):
+    def __init__(self) -> None:
+        self.violations: list[Violation] = []
+
+    def visit_FunctionDef(self, ast_node: ast.FunctionDef) -> None:
+        self._check_temporary_variables(ast_node)
+        self.generic_visit(ast_node)
+
+    def visit_AsyncFunctionDef(self, ast_node: ast.AsyncFunctionDef) -> None:
+        self._check_temporary_variables(ast_node)
+        self.generic_visit(ast_node)
+
+    def _check_temporary_variables(self, ast_node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        assigned: typing.Final = collect_assignments(ast_node)
+        load_counts: typing.Final = collect_load_counts(ast_node)
+        for statement in ast_node.body:
+            if isinstance(statement, ast.Return) and isinstance(statement.value, ast.Name):
+                identifier = statement.value.id
+                if len(assigned.get(identifier, [])) == 1 and load_counts.get(identifier, 0) == 1:
+                    self.violations.append(
+                        Violation(
+                            line_number=statement.lineno,
+                            column_number=statement.col_offset,
+                            violation_code=ViolationCode.TEMPORARY_VARIABLE,
+                        )
+                    )

community_of_python_flake8_plugin/checks/cop008.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+import ast
+import typing
+
+from community_of_python_flake8_plugin.constants import FINAL_CLASS_EXCLUDED_BASES
+from community_of_python_flake8_plugin.violation_codes import ViolationCodes as ViolationCode
+from community_of_python_flake8_plugin.violations import Violation
+
+
+def check_is_true_literal(ast_node: ast.AST | None) -> bool:
+    return isinstance(ast_node, ast.Constant) and ast_node.value is True
+
+
+def contains_final_decorator(ast_node: ast.ClassDef) -> bool:
+    for decorator in ast_node.decorator_list:
+        target_name = decorator.func if isinstance(decorator, ast.Call) else decorator
+        if isinstance(target_name, ast.Name) and target_name.id == "final":
+            return True
+        if isinstance(target_name, ast.Attribute) and target_name.attr == "final":
+            return True
+    return False
+
+
+def check_inherits_from_whitelisted_class(ast_node: ast.ClassDef) -> bool:
+    for base_class in ast_node.bases:
+        if isinstance(base_class, ast.Name) and base_class.id in FINAL_CLASS_EXCLUDED_BASES:
+            return True
+        if isinstance(base_class, ast.Attribute) and base_class.attr in FINAL_CLASS_EXCLUDED_BASES:
+            return True
+    return False
+
+
+def retrieve_dataclass_decorator(ast_node: ast.ClassDef) -> ast.expr | None:
+    for decorator in ast_node.decorator_list:
+        target_name = decorator.func if isinstance(decorator, ast.Call) else decorator
+        if isinstance(target_name, ast.Name) and target_name.id == "dataclass":
+            return decorator
+        if isinstance(target_name, ast.Attribute) and target_name.attr == "dataclass":
+            return decorator
+    return None
+
+
+def check_is_dataclass(ast_node: ast.ClassDef) -> bool:
+    return retrieve_dataclass_decorator(ast_node) is not None
+
+
+@typing.final
+class COP008Check(ast.NodeVisitor):
+    def __init__(self) -> None:
+        self.violations: list[Violation] = []
+
+    def visit_ClassDef(self, ast_node: ast.ClassDef) -> None:
+        self._check_final_decorator(ast_node)
+        self.generic_visit(ast_node)
+
+    def _check_final_decorator(self, ast_node: ast.ClassDef) -> None:
+        if (
+            not check_is_dataclass(ast_node)
+            and not contains_final_decorator(ast_node)
+            and not ast_node.name.startswith("Test")
+            and not check_inherits_from_whitelisted_class(ast_node)
+        ):
+            self.violations.append(
+                Violation(
+                    line_number=ast_node.lineno,
+                    column_number=ast_node.col_offset,
+                    violation_code=ViolationCode.FINAL_CLASS,
+                )
+            )

community_of_python_flake8_plugin/checks/cop009.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+import ast
+import typing
+
+from community_of_python_flake8_plugin.constants import MAPPING_PROXY_TYPES
+from community_of_python_flake8_plugin.violation_codes import ViolationCodes as ViolationCode
+from community_of_python_flake8_plugin.violations import Violation
+
+
+def check_is_mapping_literal(value: ast.AST | None) -> bool:
+    if isinstance(value, ast.Dict):
+        return True
+    if isinstance(value, ast.Call):
+        if check_is_typed_dict_call(value):
+            return False
+        return any(isinstance(argument, ast.Dict) for argument in value.args)
+    return False
+
+
+def check_is_typed_dict_call(value: ast.Call) -> bool:
+    if isinstance(value.func, ast.Name) and value.func.id == "TypedDict":
+        return True
+    if isinstance(value.func, ast.Attribute) and value.func.attr == "TypedDict":
+        return isinstance(value.func.value, ast.Name) and value.func.value.id in {
+            "typing",
+            "typing_extensions",
+        }
+    return False
+
+
+def check_is_mapping_proxy_call(value: ast.AST | None) -> bool:
+    if not isinstance(value, ast.Call):
+        return False
+    if isinstance(value.func, ast.Name):
+        return value.func.id in MAPPING_PROXY_TYPES
+    if isinstance(value.func, ast.Attribute):
+        return value.func.attr in MAPPING_PROXY_TYPES
+    return False
+
+
+@typing.final
+class COP009Check(ast.NodeVisitor):
+    def __init__(self) -> None:
+        self.violations: list[Violation] = []
+
+    def visit_Module(self, ast_node: ast.Module) -> None:
+        for statement in ast_node.body:
+            self._check_module_assignment(statement)
+        self.generic_visit(ast_node)
+
+    def _check_module_assignment(self, statement: ast.stmt) -> None:
+        value = None
+        if isinstance(statement, (ast.Assign, ast.AnnAssign)):
+            value = statement.value
+
+        if value and check_is_mapping_literal(value) and not check_is_mapping_proxy_call(value):
+            self.violations.append(
+                Violation(
+                    line_number=statement.lineno,
+                    column_number=statement.col_offset,
+                    violation_code=ViolationCode.MAPPING_PROXY,
+                )
+            )

community_of_python_flake8_plugin/checks/cop010.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+import ast
+import typing
+
+from community_of_python_flake8_plugin.violation_codes import ViolationCodes as ViolationCode
+from community_of_python_flake8_plugin.violations import Violation
+
+
+def check_is_true_literal(ast_node: ast.AST | None) -> bool:
+    return isinstance(ast_node, ast.Constant) and ast_node.value is True
+
+
+def retrieve_dataclass_decorator(ast_node: ast.ClassDef) -> ast.expr | None:
+    for decorator in ast_node.decorator_list:
+        target_name = decorator.func if isinstance(decorator, ast.Call) else decorator
+        if isinstance(target_name, ast.Name) and target_name.id == "dataclass":
+            return decorator
+        if isinstance(target_name, ast.Attribute) and target_name.attr == "dataclass":
+            return decorator
+    return None
+
+
+def check_is_dataclass(ast_node: ast.ClassDef) -> bool:
+    return retrieve_dataclass_decorator(ast_node) is not None
+
+
+def check_is_exception_class(_node: ast.ClassDef) -> bool:
+    return False
+
+
+def check_is_inheriting(ast_node: ast.ClassDef) -> bool:
+    return len(ast_node.bases) > 0
+
+
+def check_dataclass_has_keyword(decorator: ast.expr, identifier: str, value: bool | None = None) -> bool:
+    if not isinstance(decorator, ast.Call):
+        return False
+    for keyword in decorator.keywords:
+        if keyword.arg != identifier:
+            continue
+        if value is None:
+            return True
+        return isinstance(keyword.value, ast.Constant) and keyword.value.value is value
+    return False
+
+
+def check_dataclass_has_required_args(decorator: ast.expr, *, require_slots: bool, require_frozen: bool) -> bool:
+    if not isinstance(decorator, ast.Call):
+        return False
+    keywords: typing.Final = {keyword.arg: keyword.value for keyword in decorator.keywords if keyword.arg}
+    if not check_is_true_literal(keywords.get("kw_only")):
+        return False
+    if require_slots and not check_is_true_literal(keywords.get("slots")):
+        return False
+    return not (require_frozen and not check_is_true_literal(keywords.get("frozen")))
+
+
+@typing.final
+class COP010Check(ast.NodeVisitor):
+    def __init__(self) -> None:
+        self.violations: list[Violation] = []
+
+    def visit_ClassDef(self, ast_node: ast.ClassDef) -> None:
+        self._check_dataclass_config(ast_node)
+        self.generic_visit(ast_node)
+
+    def _check_dataclass_config(self, ast_node: ast.ClassDef) -> None:
+        if not check_is_dataclass(ast_node):
+            return
+        decorator: typing.Final = retrieve_dataclass_decorator(ast_node)
+        if decorator is None:
+            return
+        if check_is_inheriting(ast_node):
+            return
+        require_slots: typing.Final = not check_dataclass_has_keyword(decorator, "init", value=False)
+        require_frozen: typing.Final = require_slots and not check_is_exception_class(ast_node)
+        if not check_dataclass_has_required_args(decorator, require_slots=require_slots, require_frozen=require_frozen):
+            self.violations.append(
+                Violation(
+                    line_number=ast_node.lineno,
+                    column_number=ast_node.col_offset,
+                    violation_code=ViolationCode.DATACLASS_CONFIG,
+                )
+            )

community_of_python_flake8_plugin/constants.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+import typing
+
+
+MIN_NAME_LENGTH: typing.Final = 8
+
+VERB_PREFIXES: typing.Final = {
+    "validate",
+    "test",
+    "execute",
+    "visit",
+    "get",
+    "cancel",
+    "retrieve",
+    "lock",
+    "assert",
+    "extract",
+    "enrich",
+    "run",
+    "patch",
+    "build",
+    "start",
+    "ping",
+    "prepare",
+    "publish",
+    "request",
+    "ack",
+    "nack",
+    "reject",
+    "stop",
+    "route",
+    "begin",
+    "subscribe",
+    "connect",
+    "close",
+    "enter",
+    "exit",
+    "take",
+    "dump",
+    "iter",
+    "escape",
+    "unescape",
+    "add",
+    "contains",
+    "unsubscribe",
+    "resubscribe",
+    "commit",
+    "raise",
+    "mock",
+    "produce",
+    "consume",
+    "track",
+    "wait",
+    "bootstrap",
+    "calculate",
+    "check",
+    "collect",
+    "compute",
+    "convert",
+    "create",
+    "delete",
+    "fetch",
+    "find",
+    "format",
+    "generate",
+    "handle",
+    "has",
+    "is",
+    "list",
+    "load",
+    "make",
+    "parse",
+    "process",
+    "read",
+    "receive",
+    "remove",
+    "render",
+    "resolve",
+    "save",
+    "send",
+    "set",
+    "should",
+    "update",
+    "write",
+}
+
+SCALAR_ANNOTATIONS: typing.Final = {"int", "str", "float", "bool", "bytes", "complex"}
+
+MAPPING_PROXY_TYPES: typing.Final = {"MappingProxyType"}
+
+ALLOWED_STDLIB_FROM_IMPORTS: typing.Final = {"collections.abc"}
+
+FINAL_CLASS_EXCLUDED_BASES: typing.Final = {"BaseModel", "RootModel", "ModelFactory"}

community_of_python_flake8_plugin/plugin.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+import typing
+
+
+if typing.TYPE_CHECKING:
+    import ast
+    from collections.abc import Iterable
+
+
+from community_of_python_flake8_plugin.checks import execute_all_validations
+
+
+@typing.final
+class CommunityOfPythonFlake8Plugin:
+    name = "community-of-python-flake8-plugin"  # noqa: COP004
+    version = "0.1.27"  # noqa: COP004
+
+    def __init__(self, tree: ast.AST) -> None:  # noqa: COP004
+        self.ast_tree = tree
+
+    def run(self) -> Iterable[tuple[int, int, str, type[object]]]:  # noqa: COP004
+        violations_list: typing.Final = execute_all_validations(self.ast_tree)
+        for violation in violations_list:
+            violation_message = f"{violation.violation_code.code} {violation.violation_code.description}"
+            yield violation.line_number, violation.column_number, violation_message, type(self)

community_of_python_flake8_plugin/utils.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+import ast
+
+
+def check_module_has_all_declaration(ast_node: ast.Module) -> bool:
+    for statement in ast_node.body:
+        if isinstance(statement, ast.Assign) and any(
+            isinstance(target, ast.Name) and target.id == "__all__" for target in statement.targets
+        ):
+            return True
+        if (
+            isinstance(statement, ast.AnnAssign)
+            and isinstance(statement.target, ast.Name)
+            and statement.target.id == "__all__"
+        ):
+            return True
+    return False
+
+
+def find_parent_class_definition(syntax_tree: ast.AST, ast_node: ast.AST) -> ast.ClassDef | None:
+    for potential_parent in ast.walk(syntax_tree):
+        if isinstance(potential_parent, ast.ClassDef):
+            for child in ast.walk(potential_parent):
+                if child is ast_node:
+                    return potential_parent
+    return None
+
+
+def find_parent_function(syntax_tree: ast.AST, ast_node: ast.AST) -> ast.FunctionDef | ast.AsyncFunctionDef | None:
+    for potential_parent in ast.walk(syntax_tree):
+        if isinstance(potential_parent, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            for child in ast.walk(potential_parent):
+                if child is ast_node:
+                    return potential_parent
+    return None

community_of_python_flake8_plugin/violation_codes.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+import dataclasses
+import typing
+
+
+@typing.final
+@dataclasses.dataclass(frozen=True, kw_only=True, slots=True)
+class ViolationCode:
+    code: str  # noqa: COP004
+    description: str
+
+
+@typing.final
+class ViolationCodes:
+    MODULE_IMPORT = ViolationCode(code="COP001", description="Use module import when importing more than two names")
+    STDLIB_IMPORT = ViolationCode(code="COP002", description="Import standard library modules as whole modules")
+    SCALAR_ANNOTATION = ViolationCode(code="COP003", description="Avoid explicit scalar type annotations")
+    NAME_LENGTH = ViolationCode(code="COP004", description="Name must be at least 8 characters")
+    FUNCTION_VERB = ViolationCode(code="COP005", description="Function identifier must be a verb")
+    ASYNC_GET_PREFIX = ViolationCode(code="COP006", description="Avoid get_ prefix in async function names")
+    TEMPORARY_VARIABLE = ViolationCode(code="COP007", description="Avoid temporary variables used only once")
+    FINAL_CLASS = ViolationCode(code="COP008", description="Classes should be marked typing.final")
+    MAPPING_PROXY = ViolationCode(code="COP009", description="Wrap module dictionaries with types.MappingProxyType")
+    DATACLASS_CONFIG = ViolationCode(
+        code="COP010", description="Use dataclasses with kw_only=True, slots=True, frozen=True"
+    )

community_of_python_flake8_plugin/violations.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+import dataclasses
+import typing
+
+
+if typing.TYPE_CHECKING:
+    from .violation_codes import ViolationCode
+
+
+@typing.final
+@dataclasses.dataclass(frozen=True, kw_only=True, slots=True)
+class Violation:
+    line_number: int
+    column_number: int
+    violation_code: ViolationCode

community_of_python_flake8_plugin-0.1.0.dist-info/METADATA

@@ -0,0 +1,27 @@
+Metadata-Version: 2.3
+Name: community-of-python-flake8-plugin
+Version: 0.1.0
+Summary: Community of Python flake8 plugin
+Author: Lev Vereshchagin
+Author-email: Lev Vereshchagin <mail@vrslev.com>
+Requires-Dist: flake8
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# community-of-python-flake8-plugin
+
+Community of Python flake8 plugin with custom code style checks.
+
+## Run with uv
+
+```bash
+uv run --with flake8 --with "community-of-python-flake8-plugin @ git+https://github.com/community-of-python/pylines.git@code-style-tests#subdirectory=community-of-python-flake8-plugin" -- flake8 --select COP --exclude .venv .
+```
+
+## flake8 config (pyproject.toml)
+
+```toml
+[tool.flake8]
+select = ["COP"]
+exclude = [".venv"]
+```

community_of_python_flake8_plugin-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+community_of_python_flake8_plugin/__init__.py,sha256=nbK0ThjxTd-7g9SrYc_YWtuqyfl9OkXcJca5nAxYG3s,129
+community_of_python_flake8_plugin/checks/README.md,sha256=FHhhvoL-73kcgrjnogiGhXSaBixgamJs1pKyZgTFkl0,1528
+community_of_python_flake8_plugin/checks/__init__.py,sha256=A0n1YctyMM36vm-3SODvVULWBO2HeE4C7OwA8lCrmbw,3458
+community_of_python_flake8_plugin/checks/cop001.py,sha256=6fsyF-4F9So0p-uHgVW7_AZZKnUX7ovNtHyFtkkiw7c,1855
+community_of_python_flake8_plugin/checks/cop002.py,sha256=SPM3WDOSGBhcXa5NkYkYcFZXQZntbt7clDGHzuOH2PU,1839
+community_of_python_flake8_plugin/checks/cop003.py,sha256=1qoEOaih3takr9NbdUoCJNjmaHCKoFO00luyQBqRd60,3074
+community_of_python_flake8_plugin/checks/cop004.py,sha256=8yiTYJ980BbuMjWu2KxOS0bn523Ys1tvUEbgkLGKnGI,6840
+community_of_python_flake8_plugin/checks/cop005.py,sha256=XYUPbYbimU23tPHpGbuvHAe4ioGnlZ0j6Jm-ARWnUgo,4503
+community_of_python_flake8_plugin/checks/cop006.py,sha256=yQdIC1iIAn-rO28h5_uYaY7-nj27aNMQy0UrrqxOeZQ,2698
+community_of_python_flake8_plugin/checks/cop007.py,sha256=EpGP9oNETtURswA4M7mAIfJYjGxFLuqmahoyZu96_d8,2390
+community_of_python_flake8_plugin/checks/cop008.py,sha256=JBqWPya04QepAwQ3uYcSpWxgMr58airTYEK7SHZm9Mg,2661
+community_of_python_flake8_plugin/checks/cop009.py,sha256=08TbX_7HzshNWVpbR_276PH-ZkCTgVuEKtJEfwQ4yoQ,2223
+community_of_python_flake8_plugin/checks/cop010.py,sha256=-SnaeNVADDl5_FhsPUriekaWMz7kn--7-tKn4g1JssM,3260
+community_of_python_flake8_plugin/constants.py,sha256=Xp7jJRBZx1hKeSqhG22APKNc3DgwsHwMVrYYl4F1ZHs,1467
+community_of_python_flake8_plugin/plugin.py,sha256=sqGiWRUiROV4Ooxvn-87BE1c47V2oP3xylpTQQvCWkE,866
+community_of_python_flake8_plugin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+community_of_python_flake8_plugin/utils.py,sha256=Mee2tp9ps-zRHEC3muxYf5HqlrKHum6FQgPOXRCEMxY,1318
+community_of_python_flake8_plugin/violation_codes.py,sha256=ZwQPTLGJHHTSeUcNzvj1XuRcgoBNoTKLSkuTXQnu7jo,1365
+community_of_python_flake8_plugin/violations.py,sha256=gIXWHs4QEQ1zh-u5uMBJ4jXo4ERb8MwyZfmI4iNChTE,315
+community_of_python_flake8_plugin-0.1.0.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
+community_of_python_flake8_plugin-0.1.0.dist-info/entry_points.txt,sha256=TVYG2EjuPUWGB7OMdNP3d2shi9sRmDK_K92mDYDpxkQ,97
+community_of_python_flake8_plugin-0.1.0.dist-info/METADATA,sha256=4hiQa_diUQTWfY5Ejag1wpaNHgLwJM_BhlDRKVpO9cI,737
+community_of_python_flake8_plugin-0.1.0.dist-info/RECORD,,

community_of_python_flake8_plugin-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.28
+Root-Is-Purelib: true
+Tag: py3-none-any

community_of_python_flake8_plugin-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[flake8.extension]
+COP = community_of_python_flake8_plugin.plugin:CommunityOfPythonFlake8Plugin
+