python-naming-linter 0.1.0__py3-none-any.whl

python_naming_linter/checkers/__init__.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Violation:
+    rule_name: str
+    file_path: str
+    lineno: int
+    name: str
+    message: str

python_naming_linter/checkers/class_.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import ast
+import re
+
+from python_naming_linter.checkers import Violation
+from python_naming_linter.config import Rule
+
+# Common built-in exception base classes used for the "Exception" heuristic
+_EXCEPTION_BASE_CLASSES = {
+    "Exception",
+    "BaseException",
+    "ValueError",
+    "TypeError",
+    "RuntimeError",
+    "KeyError",
+    "IndexError",
+    "AttributeError",
+    "NotImplementedError",
+    "OSError",
+    "IOError",
+    "FileNotFoundError",
+    "PermissionError",
+    "TimeoutError",
+    "StopIteration",
+    "GeneratorExit",
+    "SystemExit",
+    "ArithmeticError",
+    "LookupError",
+    "EnvironmentError",
+    "ConnectionError",
+    "ImportError",
+    "NameError",
+    "OverflowError",
+    "RecursionError",
+    "MemoryError",
+    "UnicodeError",
+    "Warning",
+}
+
+
+def _is_exception_like(name: str) -> bool:
+    """Return True if the name looks like an exception class."""
+    return (
+        name in _EXCEPTION_BASE_CLASSES
+        or name.endswith("Error")
+        or name.endswith("Exception")
+    )
+
+
+def _base_names(node: ast.ClassDef) -> list[str]:
+    """Return the plain names of all direct base classes."""
+    names = []
+    for base in node.bases:
+        if isinstance(base, ast.Name):
+            names.append(base.id)
+        elif isinstance(base, ast.Attribute):
+            names.append(base.attr)
+    return names
+
+
+def _matches_base_class_filter(node: ast.ClassDef, base_class_filter: str) -> bool:
+    """Return True if the class satisfies the base_class filter."""
+    bases = _base_names(node)
+    if base_class_filter == "Exception":
+        return any(_is_exception_like(b) for b in bases)
+    return base_class_filter in bases
+
+
+def _check_name(class_name: str, naming: dict) -> str | None:
+    """Return an error message if class_name violates naming constraints, else None."""
+
+    if "prefix" in naming:
+        prefix = naming["prefix"]
+        if isinstance(prefix, list):
+            if not any(class_name.startswith(p) for p in prefix):
+                msg = (
+                    f"Expected name to start with one of {prefix!r}, got '{class_name}'"
+                )
+                return msg
+        else:
+            if not class_name.startswith(prefix):
+                return f"Expected name to start with '{prefix}', got '{class_name}'"
+
+    if "suffix" in naming:
+        suffix = naming["suffix"]
+        if isinstance(suffix, list):
+            if not any(class_name.endswith(s) for s in suffix):
+                msg = f"Expected name to end with one of {suffix!r}, got '{class_name}'"
+                return msg
+        else:
+            if not class_name.endswith(suffix):
+                return f"Expected name to end with '{suffix}', got '{class_name}'"
+
+    if "regex" in naming:
+        pattern = naming["regex"]
+        if not re.search(pattern, class_name):
+            return f"Expected name to match '{pattern}', got '{class_name}'"
+
+    if "case" in naming:
+        case = naming["case"]
+        if case == "PascalCase":
+            if not re.fullmatch(r"[A-Z][a-zA-Z0-9]*", class_name):
+                return f"Expected PascalCase name, got '{class_name}'"
+        elif case == "snake_case":
+            if not re.fullmatch(r"[a-z_][a-z0-9_]*", class_name):
+                return f"Expected snake_case name, got '{class_name}'"
+        elif case == "UPPER_CASE":
+            if not re.fullmatch(r"[A-Z][A-Z0-9_]*", class_name):
+                return f"Expected UPPER_CASE name, got '{class_name}'"
+
+    return None
+
+
+def check_class(tree: ast.Module, rule: Rule, file_path: str) -> list[Violation]:
+    """Check class names in tree against the given rule."""
+    naming = rule.naming
+    filters = rule.filter
+
+    base_class_filter = filters.get("base_class")
+    decorator_filter = filters.get("decorator")
+
+    violations: list[Violation] = []
+
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.ClassDef):
+            continue
+
+        class_name = node.name
+
+        # Apply base_class filter
+        if base_class_filter is not None:
+            if not _matches_base_class_filter(node, base_class_filter):
+                continue
+
+        # Apply decorator filter
+        if decorator_filter is not None:
+            decorator_names = []
+            for dec in node.decorator_list:
+                if isinstance(dec, ast.Name):
+                    decorator_names.append(dec.id)
+                elif isinstance(dec, ast.Attribute):
+                    decorator_names.append(dec.attr)
+            if decorator_filter not in decorator_names:
+                continue
+
+        # Check naming
+        msg = _check_name(class_name, naming)
+        if msg is not None:
+            violations.append(
+                Violation(
+                    rule_name=rule.name,
+                    file_path=file_path,
+                    lineno=node.lineno,
+                    name=class_name,
+                    message=msg,
+                )
+            )
+
+    return violations

python_naming_linter/checkers/function.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import ast
+import re
+
+from python_naming_linter.checkers import Violation
+from python_naming_linter.config import Rule
+
+
+def _get_return_type_name(node: ast.FunctionDef | ast.AsyncFunctionDef) -> str | None:
+    """Return the plain name of the function's return annotation, or None."""
+    annotation = node.returns
+    if annotation is None:
+        return None
+    if isinstance(annotation, ast.Name):
+        return annotation.id
+    if isinstance(annotation, ast.Attribute):
+        return annotation.attr
+    if isinstance(annotation, ast.Constant):
+        return str(annotation.value)
+    return None
+
+
+def _check_name(func_name: str, naming: dict) -> str | None:
+    """Return error message if func_name violates naming constraints, else None."""
+
+    if "prefix" in naming:
+        prefix = naming["prefix"]
+        if isinstance(prefix, list):
+            if not any(func_name.startswith(p) for p in prefix):
+                msg = (
+                    f"Expected name to start with one of {prefix!r}, got '{func_name}'"
+                )
+                return msg
+        else:
+            if not func_name.startswith(prefix):
+                return f"Expected name to start with '{prefix}', got '{func_name}'"
+
+    if "suffix" in naming:
+        suffix = naming["suffix"]
+        if isinstance(suffix, list):
+            if not any(func_name.endswith(s) for s in suffix):
+                return f"Expected name to end with one of {suffix!r}, got '{func_name}'"
+        else:
+            if not func_name.endswith(suffix):
+                return f"Expected name to end with '{suffix}', got '{func_name}'"
+
+    if "regex" in naming:
+        pattern = naming["regex"]
+        if not re.search(pattern, func_name):
+            return f"Expected name to match '{pattern}', got '{func_name}'"
+
+    if "case" in naming:
+        case = naming["case"]
+        if case == "snake_case":
+            if not re.fullmatch(r"[a-z_][a-z0-9_]*", func_name):
+                return f"Expected snake_case name, got '{func_name}'"
+        elif case == "UPPER_CASE":
+            if not re.fullmatch(r"[A-Z][A-Z0-9_]*", func_name):
+                return f"Expected UPPER_CASE name, got '{func_name}'"
+
+    return None
+
+
+def _build_parent_map(tree: ast.Module) -> dict[int, ast.AST]:
+    """Return a mapping from node id to its parent node."""
+    parent_map: dict[int, ast.AST] = {}
+    for node in ast.walk(tree):
+        for child in ast.iter_child_nodes(node):
+            parent_map[id(child)] = node
+    return parent_map
+
+
+def check_function(tree: ast.Module, rule: Rule, file_path: str) -> list[Violation]:
+    """Check function/method names in tree against the given rule."""
+    naming = rule.naming
+    filters = rule.filter
+
+    target_filter = filters.get("target")  # "method", "function", or None (both)
+    return_type_filter = filters.get("return_type")  # e.g. "bool"
+    decorator_filter = filters.get("decorator")  # e.g. "property"
+
+    parent_map = _build_parent_map(tree)
+
+    violations: list[Violation] = []
+
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+
+        func_name = node.name
+
+        # Skip dunder methods
+        if func_name.startswith("__") and func_name.endswith("__"):
+            continue
+
+        # Determine if this is a method (direct parent is ClassDef)
+        parent = parent_map.get(id(node))
+        is_method = isinstance(parent, ast.ClassDef)
+
+        # Apply target filter
+        if target_filter == "method" and not is_method:
+            continue
+        if target_filter == "function" and is_method:
+            continue
+
+        # Apply return_type filter
+        if return_type_filter is not None:
+            actual_return = _get_return_type_name(node)
+            if actual_return != return_type_filter:
+                continue
+
+        # Apply decorator filter
+        if decorator_filter is not None:
+            decorator_names = []
+            for dec in node.decorator_list:
+                if isinstance(dec, ast.Name):
+                    decorator_names.append(dec.id)
+                elif isinstance(dec, ast.Attribute):
+                    decorator_names.append(dec.attr)
+            if decorator_filter not in decorator_names:
+                continue
+
+        # Check naming
+        msg = _check_name(func_name, naming)
+        if msg is not None:
+            violations.append(
+                Violation(
+                    rule_name=rule.name,
+                    file_path=file_path,
+                    lineno=node.lineno,
+                    name=func_name,
+                    message=msg,
+                )
+            )
+
+    return violations

python_naming_linter/checkers/module.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import ast
+import re
+from pathlib import Path
+
+from python_naming_linter.checkers import Violation
+from python_naming_linter.config import Rule
+
+
+def _to_snake_case(name: str) -> str:
+    """Convert a CamelCase / PascalCase name to snake_case."""
+    s1 = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", name)
+    result = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", s1)
+    return result.lower()
+
+
+def check_module(tree: ast.Module, rule: Rule, file_path: str) -> list[Violation]:
+    """Check module filename against the given rule."""
+    module_name = Path(file_path).stem
+
+    # Skip __init__ files
+    if module_name == "__init__":
+        return []
+
+    naming = rule.naming
+    violations: list[Violation] = []
+
+    if "source" in naming and naming.get("source") == "class_name":
+        transform = naming.get("transform", "snake_case")
+        if transform == "snake_case":
+            # Find the first ClassDef at module level (or anywhere via walk)
+            first_class: ast.ClassDef | None = None
+            for node in ast.walk(tree):
+                if isinstance(node, ast.ClassDef):
+                    first_class = node
+                    break
+
+            if first_class is None:
+                return []
+
+            expected = _to_snake_case(first_class.name)
+            if module_name != expected:
+                msg = f"Expected module name '{expected}', got '{module_name}'"
+                violations.append(
+                    Violation(
+                        rule_name=rule.name,
+                        file_path=file_path,
+                        lineno=0,
+                        name=module_name,
+                        message=msg,
+                    )
+                )
+
+    elif "regex" in naming:
+        pattern = naming["regex"]
+        if not re.fullmatch(pattern, module_name):
+            msg = f"Expected module name to match '{pattern}', got '{module_name}'"
+            violations.append(
+                Violation(
+                    rule_name=rule.name,
+                    file_path=file_path,
+                    lineno=0,
+                    name=module_name,
+                    message=msg,
+                )
+            )
+
+    elif "case" in naming:
+        case = naming["case"]
+        msg: str | None = None
+        if case == "snake_case":
+            if not re.fullmatch(r"[a-z_][a-z0-9_]*", module_name):
+                msg = f"Expected snake_case module name, got '{module_name}'"
+        elif case == "UPPER_CASE":
+            if not re.fullmatch(r"[A-Z][A-Z0-9_]*", module_name):
+                msg = f"Expected UPPER_CASE module name, got '{module_name}'"
+        elif case == "PascalCase":
+            if not re.fullmatch(r"[A-Z][a-zA-Z0-9]*", module_name):
+                msg = f"Expected PascalCase module name, got '{module_name}'"
+        if msg is not None:
+            violations.append(
+                Violation(
+                    rule_name=rule.name,
+                    file_path=file_path,
+                    lineno=0,
+                    name=module_name,
+                    message=msg,
+                )
+            )
+
+    return violations

python_naming_linter/checkers/package.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import re
+
+from python_naming_linter.checkers import Violation
+from python_naming_linter.config import Rule
+
+
+def check_package(rule: Rule, package_name: str) -> list[Violation]:
+    naming = rule.naming
+    violations = []
+
+    if "case" in naming:
+        if naming["case"] == "snake_case" and package_name != package_name.lower():
+            violations.append(
+                Violation(
+                    rule_name=rule.name,
+                    file_path=package_name,
+                    lineno=0,
+                    name=package_name,
+                    message="expected: snake_case",
+                )
+            )
+
+    if "regex" in naming:
+        if not re.match(naming["regex"], package_name):
+            violations.append(
+                Violation(
+                    rule_name=rule.name,
+                    file_path=package_name,
+                    lineno=0,
+                    name=package_name,
+                    message=f"expected pattern: {naming['regex']}",
+                )
+            )
+
+    return violations

python_naming_linter/checkers/variable.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import ast
+import re
+
+from python_naming_linter.checkers import Violation
+from python_naming_linter.config import Rule
+
+
+def _to_snake_case(name: str) -> str:
+    """Convert a CamelCase / PascalCase name to snake_case."""
+    # Insert underscore before sequences of uppercase letters followed by lowercase
+    s1 = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", name)
+    result = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", s1)
+    return result.lower()
+
+
+def _is_upper_case(name: str) -> bool:
+    return bool(re.fullmatch(r"[A-Z][A-Z0-9_]*", name))
+
+
+def _get_annotation_name(annotation: ast.expr | None) -> str | None:
+    """Extract the plain name from a type annotation node."""
+    if annotation is None:
+        return None
+    if isinstance(annotation, ast.Name):
+        return annotation.id
+    if isinstance(annotation, ast.Attribute):
+        return annotation.attr
+    # For subscripted types like List[X], use the outer name
+    if isinstance(annotation, ast.Subscript):
+        return _get_annotation_name(annotation.value)
+    return None
+
+
+def _check_name_against_naming(
+    var_name: str,
+    annotation: ast.expr | None,
+    naming: dict,
+) -> str | None:
+    """Return error message string if name violates naming rule, else None."""
+
+    if "source" in naming and naming.get("source") == "type_annotation":
+        transform = naming.get("transform", "snake_case")
+        if transform == "snake_case":
+            type_name = _get_annotation_name(annotation)
+            if type_name is None:
+                # No annotation to derive from; skip
+                return None
+            expected = _to_snake_case(type_name)
+            # Allow exact match or {prefix}_{expected} form
+            if var_name == expected:
+                return None
+            if var_name.endswith("_" + expected):
+                return None
+            return f"Expected '{expected}' (or '<prefix>_{expected}'), got '{var_name}'"
+
+    if "case" in naming:
+        case = naming["case"]
+        if case == "UPPER_CASE":
+            if _is_upper_case(var_name):
+                return None
+            return f"Expected UPPER_CASE name, got '{var_name}'"
+
+    if "prefix" in naming:
+        prefix = naming["prefix"]
+        if not var_name.startswith(prefix):
+            return f"Expected name to start with '{prefix}', got '{var_name}'"
+
+    if "suffix" in naming:
+        suffix = naming["suffix"]
+        if not var_name.endswith(suffix):
+            return f"Expected name to end with '{suffix}', got '{var_name}'"
+
+    if "regex" in naming:
+        pattern = naming["regex"]
+        if not re.fullmatch(pattern, var_name):
+            return f"Expected name to match '{pattern}', got '{var_name}'"
+
+    return None
+
+
+def _collect_attributes(
+    tree: ast.Module,
+) -> list[tuple[str, ast.expr | None, int]]:
+    """Collect annotated assignments inside class bodies."""
+    results = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            for item in node.body:
+                if isinstance(item, ast.AnnAssign):
+                    if isinstance(item.target, ast.Name):
+                        results.append((item.target.id, item.annotation, item.lineno))
+    return results
+
+
+def _collect_parameters(
+    tree: ast.Module,
+) -> list[tuple[str, ast.expr | None, int]]:
+    """Collect function/method parameters, skipping self and cls."""
+    results = []
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            args = node.args
+            all_args = args.posonlyargs + args.args + args.kwonlyargs
+            if args.vararg:
+                all_args.append(args.vararg)
+            if args.kwarg:
+                all_args.append(args.kwarg)
+            for arg in all_args:
+                if arg.arg in ("self", "cls"):
+                    continue
+                results.append((arg.arg, arg.annotation, arg.lineno))
+    return results
+
+
+def _collect_local_variables(
+    tree: ast.Module,
+) -> list[tuple[str, ast.expr | None, int]]:
+    """Collect annotated assignments inside function bodies."""
+    results = []
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            for item in ast.walk(node):
+                if isinstance(item, ast.AnnAssign) and isinstance(
+                    item.target, ast.Name
+                ):
+                    results.append((item.target.id, item.annotation, item.lineno))
+    return results
+
+
+def _collect_constants(
+    tree: ast.Module,
+) -> list[tuple[str, ast.expr | None, int]]:
+    """Collect module-level assignments with UPPER_CASE names (constants)."""
+    results = []
+    for node in tree.body:
+        if isinstance(node, ast.Assign):
+            for target in node.targets:
+                if isinstance(target, ast.Name):
+                    results.append((target.id, None, node.lineno))
+        elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+            results.append((node.target.id, node.annotation, node.lineno))
+    return results
+
+
+def check_variable(tree: ast.Module, rule: Rule, file_path: str) -> list[Violation]:
+    target = rule.filter.get("target", "")
+    naming = rule.naming
+
+    if target == "attribute":
+        candidates = _collect_attributes(tree)
+    elif target == "parameter":
+        candidates = _collect_parameters(tree)
+    elif target == "local_variable":
+        candidates = _collect_local_variables(tree)
+    elif target == "constant":
+        candidates = _collect_constants(tree)
+    else:
+        return []
+
+    violations = []
+    for var_name, annotation, lineno in candidates:
+        msg = _check_name_against_naming(var_name, annotation, naming)
+        if msg is not None:
+            violations.append(
+                Violation(
+                    rule_name=rule.name,
+                    file_path=file_path,
+                    lineno=lineno,
+                    name=var_name,
+                    message=msg,
+                )
+            )
+    return violations

python_naming_linter/cli.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import ast
+import fnmatch
+from pathlib import Path
+
+import click
+
+from python_naming_linter.checkers.class_ import check_class
+from python_naming_linter.checkers.function import check_function
+from python_naming_linter.checkers.module import check_module
+from python_naming_linter.checkers.package import check_package
+from python_naming_linter.checkers.variable import check_variable
+from python_naming_linter.config import Rule, find_config, load_config
+from python_naming_linter.matcher import matches_pattern_or_submodule
+from python_naming_linter.reporter import format_violations
+
+
+def _file_to_module(file_path: Path, root: Path) -> str:
+    relative = file_path.relative_to(root)
+    parts = relative.with_suffix("").parts
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+    return ".".join(parts)
+
+
+def _package_module(file_path: Path, root: Path) -> str:
+    """Return the package (directory) module path for a file.
+
+    For ``contexts/boards/domain/models.py`` this returns
+    ``contexts.boards.domain``.
+    """
+    relative = file_path.relative_to(root)
+    parts = relative.with_suffix("").parts
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+    else:
+        parts = parts[:-1]
+    return ".".join(parts)
+
+
+def _normalize_pattern(pattern: str, project_root: Path) -> str:
+    """Normalize a pattern so that bare directory names match all files within."""
+    clean = pattern.rstrip("/")
+    candidate = project_root / clean
+    if candidate.is_dir() or not any(c in clean for c in ("*", "?")):
+        clean = f"{clean}/**"
+    return clean
+
+
+def _matches_any(path: Path, patterns: list[str]) -> bool:
+    return any(fnmatch.fnmatch(str(path), p) for p in patterns)
+
+
+def _find_python_files(
+    root: Path,
+    include: list[str] | None = None,
+    exclude: list[str] | None = None,
+) -> list[Path]:
+    all_files = sorted(root.rglob("*.py"))
+
+    if include is not None:
+        normalized = [_normalize_pattern(p, root) for p in include]
+        all_files = [
+            f for f in all_files if _matches_any(f.relative_to(root), normalized)
+        ]
+
+    if exclude is not None:
+        normalized = [_normalize_pattern(p, root) for p in exclude]
+        all_files = [
+            f for f in all_files if not _matches_any(f.relative_to(root), normalized)
+        ]
+
+    return all_files
+
+
+def _get_rules_for_module(module: str, config) -> list[Rule]:
+    """Return the list of Rule objects that apply to a given module."""
+    rule_map = {r.name: r for r in config.rules}
+    matching_rules: list[Rule] = []
+    for entry in config.apply:
+        if matches_pattern_or_submodule(entry.modules, module):
+            for rule_name in entry.rules:
+                rule = rule_map.get(rule_name)
+                if rule is not None and rule not in matching_rules:
+                    matching_rules.append(rule)
+    return matching_rules
+
+
+def _run_checker(
+    tree: ast.Module,
+    rule: Rule,
+    file_path: str,
+    package_name: str,
+) -> list:
+    """Dispatch to the appropriate checker based on rule.type."""
+    if rule.type == "variable":
+        return check_variable(tree, rule, file_path)
+    if rule.type == "function":
+        return check_function(tree, rule, file_path)
+    if rule.type == "class":
+        return check_class(tree, rule, file_path)
+    if rule.type == "module":
+        return check_module(tree, rule, file_path)
+    if rule.type == "package":
+        return check_package(rule, package_name)
+    return []
+
+
+@click.group()
+def main() -> None:
+    pass
+
+
+@main.command()
+@click.option(
+    "--config",
+    "config_path",
+    default=None,
+    help="Path to config file.",
+)
+def check(config_path: str | None) -> None:
+    if config_path is not None:
+        config_file = Path(config_path)
+        if not config_file.exists():
+            click.echo(f"Error: Config file not found: {config_file}")
+            raise SystemExit(2)
+        root = config_file.resolve().parent
+    else:
+        config_file = find_config()
+        if config_file is None:
+            click.echo(
+                "Error: Config file not found. "
+                "Create .python-naming-linter.yaml or configure "
+                "[tool.python-naming-linter] in pyproject.toml."
+            )
+            raise SystemExit(2)
+        root = config_file.resolve().parent
+
+    config = load_config(config_file)
+
+    all_violations = []
+    python_files = _find_python_files(root, config.include, config.exclude)
+
+    checked_packages: set[tuple[str, str]] = set()
+
+    for file_path in python_files:
+        module = _file_to_module(file_path, root)
+        package = _package_module(file_path, root)
+        rules = _get_rules_for_module(module, config)
+        if not rules:
+            continue
+
+        source = file_path.read_text(encoding="utf-8")
+        try:
+            tree = ast.parse(source, filename=str(file_path))
+        except SyntaxError:
+            continue
+
+        rel_path = str(file_path.relative_to(root))
+        file_violations = []
+
+        for rule in rules:
+            if rule.type == "package":
+                # Use the last segment of the package path as the package name
+                pkg_segment = package.split(".")[-1] if package else ""
+                key = (rule.name, package)
+                if key in checked_packages:
+                    continue
+                checked_packages.add(key)
+                violations = check_package(rule, pkg_segment)
+                # Use the package path as the file_path for reporting
+                pkg_rel = package.replace(".", "/")
+                for v in violations:
+                    all_violations.append(v)
+                    output = format_violations(pkg_rel, [v])
+                    if output:
+                        click.echo(output)
+            else:
+                violations = _run_checker(tree, rule, rel_path, package)
+                file_violations.extend(violations)
+
+        if file_violations:
+            output = format_violations(rel_path, file_violations)
+            click.echo(output)
+            all_violations.extend(file_violations)
+
+    if all_violations:
+        click.echo(f"Found {len(all_violations)} violation(s).")
+        raise SystemExit(1)
+    else:
+        click.echo("No violations found.")

python_naming_linter/config.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+
+@dataclass
+class Rule:
+    name: str
+    type: str
+    naming: dict
+    filter: dict = field(default_factory=dict)
+
+
+@dataclass
+class Apply:
+    name: str
+    rules: list[str]
+    modules: str
+
+
+@dataclass
+class Config:
+    rules: list[Rule]
+    apply: list[Apply]
+    include: list[str] | None = None
+    exclude: list[str] | None = None
+
+
+def _parse_rules(rules_data: list[dict]) -> list[Rule]:
+    rules = []
+    for r in rules_data:
+        rules.append(
+            Rule(
+                name=r["name"],
+                type=r["type"],
+                naming=r.get("naming", {}),
+                filter=r.get("filter", {}),
+            )
+        )
+    return rules
+
+
+def _parse_apply(apply_data: list[dict]) -> list[Apply]:
+    entries = []
+    for a in apply_data:
+        entries.append(
+            Apply(
+                name=a["name"],
+                rules=a["rules"],
+                modules=a["modules"],
+            )
+        )
+    return entries
+
+
+def _load_yaml(path: Path) -> Config:
+    with open(path) as f:
+        data = yaml.safe_load(f)
+    return Config(
+        rules=_parse_rules(data.get("rules", [])),
+        apply=_parse_apply(data.get("apply", [])),
+        include=data.get("include"),
+        exclude=data.get("exclude"),
+    )
+
+
+def _load_toml(path: Path) -> dict:
+    try:
+        import tomllib
+    except ImportError:
+        import tomli as tomllib  # type: ignore[no-redef]
+
+    with open(path, "rb") as f:
+        return tomllib.load(f)
+
+
+def _load_pyproject_toml(path: Path) -> Config:
+    data = _load_toml(path)
+    tool_config = data["tool"]["python-naming-linter"]
+    return Config(
+        rules=_parse_rules(tool_config.get("rules", [])),
+        apply=_parse_apply(tool_config.get("apply", [])),
+        include=tool_config.get("include"),
+        exclude=tool_config.get("exclude"),
+    )
+
+
+def _has_pnl_section(path: Path) -> bool:
+    data = _load_toml(path)
+    return "python-naming-linter" in data.get("tool", {})
+
+
+_CONFIG_FILENAMES = [".python-naming-linter.yaml", "pyproject.toml"]
+
+
+def find_config() -> Path | None:
+    current = Path.cwd().resolve()
+    while True:
+        for name in _CONFIG_FILENAMES:
+            candidate = current / name
+            if candidate.is_file():
+                if name == "pyproject.toml" and not _has_pnl_section(candidate):
+                    continue
+                return candidate
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def load_config(path: Path) -> Config:
+    if not path.exists():
+        raise FileNotFoundError(f"Config file not found: {path}")
+    if path.suffix == ".toml":
+        return _load_pyproject_toml(path)
+    return _load_yaml(path)

python_naming_linter/matcher.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import re
+
+_CAPTURE_RE = re.compile(r"^\{(\w+)\}$")
+
+
+def matches_pattern(pattern: str, module: str) -> bool:
+    return match_pattern_with_captures(pattern, module) is not None
+
+
+def match_pattern_with_captures(pattern: str, module: str) -> dict[str, str] | None:
+    pattern_parts = pattern.split(".")
+    module_parts = module.split(".")
+    captures: dict[str, str] = {}
+    if _match_with_captures(pattern_parts, module_parts, captures):
+        return captures
+    return None
+
+
+def _match_with_captures(
+    pattern_parts: list[str],
+    module_parts: list[str],
+    captures: dict[str, str],
+) -> bool:
+    if not pattern_parts and not module_parts:
+        return True
+    if not pattern_parts:
+        return False
+
+    if pattern_parts[0] == "**":
+        for i in range(1, len(module_parts) + 1):
+            snapshot = dict(captures)
+            if _match_with_captures(pattern_parts[1:], module_parts[i:], captures):
+                return True
+            captures.clear()
+            captures.update(snapshot)
+        return False
+
+    if not module_parts:
+        return False
+
+    m = _CAPTURE_RE.match(pattern_parts[0])
+    if m:
+        name = m.group(1)
+        value = module_parts[0]
+        if name in captures:
+            if captures[name] != value:
+                return False
+        else:
+            captures[name] = value
+        return _match_with_captures(pattern_parts[1:], module_parts[1:], captures)
+
+    if pattern_parts[0] == "*" or pattern_parts[0] == module_parts[0]:
+        return _match_with_captures(pattern_parts[1:], module_parts[1:], captures)
+
+    return False
+
+
+def matches_pattern_or_submodule(pattern: str, module: str) -> bool:
+    if matches_pattern(pattern, module):
+        return True
+    module_parts = module.split(".")
+    pattern_parts = pattern.split(".")
+    if len(module_parts) > len(pattern_parts):
+        prefix = ".".join(module_parts[: len(pattern_parts)])
+        if matches_pattern(pattern, prefix):
+            return True
+    return False

python_naming_linter/reporter.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from python_naming_linter.checkers import Violation
+
+
+def format_violations(file_path: str, violations: list[Violation]) -> str:
+    if not violations:
+        return ""
+
+    lines = []
+    for v in violations:
+        lines.append(f"{file_path}:{v.lineno}")
+        lines.append(f"    [{v.rule_name}] {v.name} ({v.message})")
+        lines.append("")
+
+    return "\n".join(lines)

python_naming_linter-0.1.0.dist-info/METADATA

@@ -0,0 +1,317 @@
+Metadata-Version: 2.4
+Name: python-naming-linter
+Version: 0.1.0
+Summary: A naming convention linter for Python projects
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: ty>=0.0.26; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# python-naming-linter
+
+A naming convention linter for Python projects. Define custom naming rules and enforce them with a single CLI command.
+
+## What It Does
+
+- Define naming rules for variables, functions, classes, modules, and packages
+- Apply rules to specific modules using pattern matching
+- Integrate into CI or pre-commit to keep your naming conventions consistent
+
+For Python developers who want to enforce team-specific naming conventions beyond what PEP 8 and ruff cover.
+
+## Installation
+
+```bash
+pip install python-naming-linter
+```
+
+Or with uv:
+
+```bash
+uv add python-naming-linter
+```
+
+## Quick Start
+
+Create `.python-naming-linter.yaml` in your project root:
+
+```yaml
+rules:
+  - name: bool-method-prefix
+    type: function
+    filter: { return_type: bool }
+    naming: { prefix: [is_, has_, should_] }
+
+  - name: exception-naming
+    type: class
+    filter: { base_class: Exception }
+    naming: { regex: "^[A-Z][a-zA-Z]+(NotFound|Invalid|Denied|Conflict|Failed)Error$" }
+
+apply:
+  - name: all
+    rules: [bool-method-prefix, exception-naming]
+    modules: "**"
+```
+
+Run:
+
+```bash
+pnl check
+```
+
+Output:
+
+```
+src/domain/service.py:12
+    [bool-method-prefix] validate (expected prefix: is_ | has_ | should_)
+
+src/domain/exceptions.py:8
+    [exception-naming] FilterError (expected pattern: ^[A-Z][a-zA-Z]+(NotFound|Invalid|...)Error$)
+
+Found 2 violation(s).
+```
+
+## Examples
+
+### Variable Naming — Match Type Annotation
+
+Enforce that variable names match their type annotation in snake_case:
+
+```yaml
+rules:
+  - name: attribute-matches-type
+    type: variable
+    filter: { target: attribute }
+    naming: { source: type_annotation, transform: snake_case }
+
+apply:
+  - name: domain-layer
+    rules: [attribute-matches-type]
+    modules: contexts.*.domain
+```
+
+This catches `repo: SubscriptionRepository` (should be `subscription_repository`).
+
+The `{prefix}_{expected}` form is also allowed — `source_object_context: ObjectContext` passes because it ends with `_object_context`.
+
+### Module Naming — Match Class Name
+
+Enforce that module filenames match the primary class they contain:
+
+```yaml
+rules:
+  - name: domain-module-naming
+    type: module
+    naming: { source: class_name, transform: snake_case }
+
+apply:
+  - name: domain-layer
+    rules: [domain-module-naming]
+    modules: contexts.*.domain
+```
+
+A file `custom.py` containing `class CustomObject` is a violation — it should be `custom_object.py`.
+
+### Combining Rules Per Layer
+
+Apply different rules to different parts of your codebase:
+
+```yaml
+rules:
+  - name: attribute-matches-type
+    type: variable
+    filter: { target: attribute }
+    naming: { source: type_annotation, transform: snake_case }
+
+  - name: bool-method-prefix
+    type: function
+    filter: { return_type: bool }
+    naming: { prefix: [is_, has_, should_] }
+
+  - name: exception-naming
+    type: class
+    filter: { base_class: Exception }
+    naming: { regex: "^[A-Z][a-zA-Z]+(NotFound|Invalid|Denied|Conflict|Failed)Error$" }
+
+  - name: domain-module-naming
+    type: module
+    naming: { source: class_name, transform: snake_case }
+
+  - name: constant-upper-case
+    type: variable
+    filter: { target: constant }
+    naming: { case: UPPER_CASE }
+
+apply:
+  - name: domain-layer
+    rules:
+      - attribute-matches-type
+      - bool-method-prefix
+      - domain-module-naming
+      - constant-upper-case
+    modules: contexts.*.domain
+
+  - name: global-exceptions
+    rules: [exception-naming]
+    modules: "**"
+```
+
+## Configuration
+
+### Rule Types
+
+| Type | Target |
+|------|--------|
+| `variable` | Variable names (attribute, parameter, local_variable, constant) |
+| `function` | Function/method names |
+| `class` | Class names (including exceptions) |
+| `module` | Module (file) names |
+| `package` | Package (directory) names |
+
+### Filter
+
+Each rule can narrow its scope with type-specific filters:
+
+| Type | Filter | Example Values |
+|------|--------|----------------|
+| `variable` | `target` | `attribute`, `parameter`, `local_variable`, `constant` |
+| `function` | `target` | `method`, `function` |
+| `function` | `return_type` | `bool` |
+| `function` | `decorator` | `staticmethod` |
+| `class` | `base_class` | `Exception` |
+| `class` | `decorator` | `dataclass` |
+
+### Naming Constraints
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `prefix` | Name must start with one of the listed prefixes | `[is_, has_]` |
+| `suffix` | Name must end with one of the listed suffixes | `[Repository, Service]` |
+| `regex` | Name must match a regular expression | `"^[A-Z][a-zA-Z]+Error$"` |
+| `source` + `transform` | Name must be derived from another element | `source: type_annotation`, `transform: snake_case` |
+| `case` | Name must follow a casing convention | `snake_case`, `PascalCase`, `UPPER_CASE` |
+
+### Include / Exclude
+
+Control which files are scanned:
+
+```yaml
+include:
+  - src
+exclude:
+  - src/generated/**
+
+rules:
+  - name: ...
+```
+
+- **No `include` or `exclude`** — All `.py` files under the project root are scanned
+- **`include` only** — Only files matching the given paths are scanned
+- **`exclude` only** — All files except those matching the given paths are scanned
+- **Both** — `include` is applied first, then `exclude` filters within that result
+
+### Wildcard
+
+`*` matches a single level in dotted module paths:
+
+```yaml
+modules: contexts.*.domain  # matches contexts.boards.domain, contexts.auth.domain, ...
+```
+
+`**` matches one or more levels:
+
+```yaml
+modules: contexts.**.domain  # matches contexts.boards.domain, contexts.boards.sub.domain, ...
+```
+
+### Named Capture
+
+`{name}` captures a single level (like `*`) and allows back-referencing:
+
+```yaml
+apply:
+  - name: domain-isolation
+    rules: [attribute-matches-type]
+    modules: contexts.{context}.domain
+```
+
+### pyproject.toml
+
+You can also configure in `pyproject.toml`:
+
+```toml
+[[tool.python-naming-linter.rules]]
+name = "bool-method-prefix"
+type = "function"
+
+[tool.python-naming-linter.rules.filter]
+return_type = "bool"
+
+[tool.python-naming-linter.rules.naming]
+prefix = ["is_", "has_", "should_"]
+
+[[tool.python-naming-linter.apply]]
+name = "all"
+rules = ["bool-method-prefix"]
+modules = "**"
+```
+
+## CLI
+
+```bash
+# Check with auto-discovered config (searches upward from cwd)
+pnl check
+
+# Specify config file (project root = config file's parent directory)
+pnl check --config path/to/config.yaml
+```
+
+Exit codes:
+
+- `0` — No violations
+- `1` — Violations found
+- `2` — Config file not found
+
+If no `--config` is given, the tool searches upward from the current directory for `.python-naming-linter.yaml` or `pyproject.toml` (with `[tool.python-naming-linter]`). The config file's parent directory is used as the project root.
+
+## Pre-commit
+
+Add to `.pre-commit-config.yaml`:
+
+```yaml
+- repo: https://github.com/heumsi/python-naming-linter
+  rev: ''  # Use the tag you want to point at (e.g., v0.1.0)
+  hooks:
+    - id: python-naming-linter
+```
+
+To pass custom options:
+
+```yaml
+- repo: https://github.com/heumsi/python-naming-linter
+  rev: ''
+  hooks:
+    - id: python-naming-linter
+      args: [--config, custom-config.yaml]
+```
+
+## License
+
+MIT

python_naming_linter-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+python_naming_linter/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+python_naming_linter/cli.py,sha256=ITltPeDv7TeRWn563X4kk0BdjLEMe6TULflcsM6mRss,6311
+python_naming_linter/config.py,sha256=AOqDWTsY-TW4uJe5FTiI5RuF8bVURUrMx0C-L8osO1o,2846
+python_naming_linter/matcher.py,sha256=K5BWvlrLWecZnNUzViMN8CDcxsTrCU9SEU4VG5xAY-M,2049
+python_naming_linter/reporter.py,sha256=tMqCFjpKPN7pzTMVqPy0GRL4sCG3LotRjYgVYbTkzPI,417
+python_naming_linter/checkers/__init__.py,sha256=XbFREg3x8LpVLq5ns_enoK16iD37XndNv8QuTZSsf2Y,185
+python_naming_linter/checkers/class_.py,sha256=iFsJ5XD77O1Frc-nkcNaAtPw3oh-i7IlPzc6J5aUONw,5005
+python_naming_linter/checkers/function.py,sha256=QjqjG4nmNnn8tyeuNBL7DEVXrgoPW2tOA5S3DUnS3hk,4735
+python_naming_linter/checkers/module.py,sha256=J-r9bHVxjfI9yQ6pnLERAGuZqeSeEqoyGqTaI-I_yOE,3165
+python_naming_linter/checkers/package.py,sha256=tVRQIThr1QJVV5WgRNc5gmvHZfWYlnPjvYwDhhpbyIw,1084
+python_naming_linter/checkers/variable.py,sha256=9tYYZq0cFsfL0UVJ4N0-cEZAjQjyea1xGHlRHelht9E,6093
+python_naming_linter-0.1.0.dist-info/METADATA,sha256=IZMMwS7dj47cwK87PoPDcNo1JK9tF1odJl5VOT33KXA,8126
+python_naming_linter-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+python_naming_linter-0.1.0.dist-info/entry_points.txt,sha256=B8XYwva_7u3ukDd8PvApVDMi4sf5yszMiVcaWuymhTM,54
+python_naming_linter-0.1.0.dist-info/licenses/LICENSE,sha256=6jnaAo6a4d5VHjYOiCeh2k2tlMKfCXI4itz82GNbuMs,1063
+python_naming_linter-0.1.0.dist-info/RECORD,,

python_naming_linter-0.1.0.dist-info/WHEEL

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

python_naming_linter-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pnl = python_naming_linter.cli:main

python_naming_linter-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 heumsi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.