test-privata 0.1.0__py3-none-any.whl

privata/__init__.py

@@ -0,0 +1,37 @@
+"""Python module privacy checks."""
+
+from privata._checker import (
+    find_export_issues,
+    find_private_candidates,
+    find_private_module_imports,
+    find_private_symbol_imports,
+)
+from privata._imports import (
+    collect_private_module_imports,
+    collect_private_symbol_imports,
+    find_cross_imports,
+)
+from privata._models import ExportIssue, Module, PrivateModuleImport, PrivateSymbolImport, Symbol
+from privata._modules import collect_modules
+
+try:
+    from privata._version import __version__
+except ImportError:  # pragma: no cover - only used from editable trees before hatch-vcs writes it
+    __version__ = "0.0.0"
+
+__all__ = [
+    "ExportIssue",
+    "Module",
+    "PrivateModuleImport",
+    "PrivateSymbolImport",
+    "Symbol",
+    "__version__",
+    "collect_modules",
+    "collect_private_module_imports",
+    "collect_private_symbol_imports",
+    "find_cross_imports",
+    "find_export_issues",
+    "find_private_candidates",
+    "find_private_module_imports",
+    "find_private_symbol_imports",
+]

privata/__main__.py

@@ -0,0 +1,5 @@
+"""Run Privata with ``python -m privata``."""
+
+from privata.cli import main
+
+raise SystemExit(main())

privata/_checker.py

@@ -0,0 +1,162 @@
+"""Detect module privacy issues within Python source roots."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from privata._entrypoints import collect_external_entrypoints, load_tach_interface_exports
+from privata._exports import collect_export_issues
+from privata._imports import (
+    collect_private_module_imports,
+    collect_private_symbol_imports,
+    find_cross_imports,
+)
+from privata._modules import collect_modules
+from privata._source_roots import source_roots
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from privata._models import ExportIssue, PrivateModuleImport, PrivateSymbolImport, Symbol
+
+
+def _collect_privacy_findings(
+    project_root: Path,
+) -> tuple[list[Symbol], list[PrivateModuleImport], list[PrivateSymbolImport], list[ExportIssue]]:
+    """Collect public-symbol and private-module boundary findings."""
+    modules = collect_modules(source_roots(project_root))
+    cross_imports = find_cross_imports(modules)
+    external_entrypoints = collect_external_entrypoints(project_root)
+    public_interface_exports = load_tach_interface_exports(project_root)
+
+    candidates = [
+        sym
+        for mod in modules.values()
+        for sym in mod.symbols
+        if (sym.module, sym.name) not in cross_imports
+        and (sym.module, sym.name) not in external_entrypoints
+        and (sym.module, sym.name) not in public_interface_exports
+    ]
+    candidates.sort(key=lambda s: (str(s.path), s.lineno))
+    private_module_imports = collect_private_module_imports(modules)
+    private_symbol_imports = collect_private_symbol_imports(modules)
+    export_issues = collect_export_issues(modules)
+    return candidates, private_module_imports, private_symbol_imports, export_issues
+
+
+def find_private_candidates(project_root: Path) -> list[Symbol]:
+    """Find symbols that appear module-local and should be private."""
+    candidates, _, _, _ = _collect_privacy_findings(project_root)
+    return candidates
+
+
+def find_private_module_imports(project_root: Path) -> list[PrivateModuleImport]:
+    """Find private modules imported from outside their package subtree."""
+    _, private_module_imports, _, _ = _collect_privacy_findings(project_root)
+    return private_module_imports
+
+
+def find_private_symbol_imports(project_root: Path) -> list[PrivateSymbolImport]:
+    """Find private top-level symbols imported from another production module."""
+    _, _, private_symbol_imports, _ = _collect_privacy_findings(project_root)
+    return private_symbol_imports
+
+
+def find_export_issues(project_root: Path) -> list[ExportIssue]:
+    """Find literal __all__ declarations that are stale or incomplete."""
+    _, _, _, export_issues = _collect_privacy_findings(project_root)
+    return export_issues
+
+
+def check_project(project_root: Path) -> int:
+    """Scan project and report module-local public symbols."""
+    project_root = project_root.resolve()
+    candidates, private_module_imports, private_symbol_imports, export_issues = (
+        _collect_privacy_findings(project_root)
+    )
+
+    if (
+        not candidates
+        and not private_module_imports
+        and not private_symbol_imports
+        and not export_issues
+    ):
+        print("No module privacy issues found.")
+        return 0
+
+    if candidates:
+        _print_private_candidates(candidates, project_root)
+
+    if private_module_imports:
+        if candidates:
+            print()
+        _print_private_module_imports(private_module_imports, project_root)
+
+    if private_symbol_imports:
+        if candidates or private_module_imports:
+            print()
+        _print_private_symbol_imports(private_symbol_imports, project_root)
+
+    if export_issues:
+        if candidates or private_module_imports or private_symbol_imports:
+            print()
+        _print_export_issues(export_issues, project_root)
+
+    return 1
+
+
+def _print_private_candidates(candidates: list[Symbol], project_root: Path) -> None:
+    print(f"Found {len(candidates)} public symbols that could be made private:\n")
+    for symbol in candidates:
+        rel = symbol.path.relative_to(project_root).as_posix()
+        print(f"  {rel}:{symbol.lineno}: {symbol.kind} `{symbol.name}`")
+
+
+def _print_private_module_imports(
+    private_module_imports: list[PrivateModuleImport],
+    project_root: Path,
+) -> None:
+    print(
+        "Found "
+        f"{len(private_module_imports)} "
+        "private module imports outside their package subtree:\n",
+    )
+    for private_import in private_module_imports:
+        rel = private_import.imported_by_path.relative_to(project_root).as_posix()
+        print(f"  {rel}:{private_import.lineno}: imports private module `{private_import.module}`")
+
+
+def _print_private_symbol_imports(
+    private_symbol_imports: list[PrivateSymbolImport],
+    project_root: Path,
+) -> None:
+    print(
+        f"Found {len(private_symbol_imports)} private symbol imports from production modules:\n",
+    )
+    for private_import in private_symbol_imports:
+        rel = private_import.imported_by_path.relative_to(project_root).as_posix()
+        print(
+            f"  {rel}:{private_import.lineno}: imports private symbol "
+            f"`{private_import.module}.{private_import.name}`",
+        )
+
+
+def _print_export_issues(export_issues: list[ExportIssue], project_root: Path) -> None:
+    print(f"Found {len(export_issues)} __all__ export issues:\n")
+    for export_issue in export_issues:
+        rel = export_issue.path.relative_to(project_root).as_posix()
+        if export_issue.kind == "unknown":
+            print(
+                f"  {rel}:{export_issue.lineno}: "
+                f"__all__ exports unknown name `{export_issue.name}`",
+            )
+        elif export_issue.kind == "private":
+            print(
+                f"  {rel}:{export_issue.lineno}: "
+                f"__all__ exports private name `{export_issue.name}`",
+            )
+        else:
+            print(
+                f"  {rel}:{export_issue.lineno}: "
+                f"public name `{export_issue.name}` missing from __all__",
+            )

privata/_entrypoints.py

@@ -0,0 +1,87 @@
+"""External public-interface discovery."""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+_ENTRYPOINT_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_\\.]*:[A-Za-z_][A-Za-z0-9_]*$")
+_UVICORN_RE = re.compile(r"\buvicorn\s+([A-Za-z_][A-Za-z0-9_\.]*):([A-Za-z_][A-Za-z0-9_]*)\b")
+
+
+def collect_external_entrypoints(project_root: Path) -> set[tuple[str, str]]:
+    """Return symbols made public by external entrypoint declarations."""
+    pairs = _load_pyproject_entrypoints(project_root)
+    pairs.update(_load_shell_uvicorn_entrypoints(project_root))
+    return pairs
+
+
+def _load_pyproject_entrypoints(project_root: Path) -> set[tuple[str, str]]:
+    """Return pyproject console and GUI script entrypoint targets."""
+    pyproject_path = project_root / "pyproject.toml"
+    if not pyproject_path.exists():
+        return set()
+
+    data = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+    project_table = data.get("project", {})
+
+    pairs: set[tuple[str, str]] = set()
+    for table_key in ("scripts", "gui-scripts"):
+        table = project_table.get(table_key, {})
+        if not isinstance(table, dict):
+            continue
+        for raw in table.values():
+            if not isinstance(raw, str):
+                continue
+            if not _ENTRYPOINT_RE.fullmatch(raw):
+                continue
+            module_name, symbol_name = raw.split(":", 1)
+            pairs.add((module_name, symbol_name))
+    return pairs
+
+
+def _entrypoint_shell_files(project_root: Path) -> list[Path]:
+    """Return shell-like files that may launch Python entrypoints."""
+    files: list[Path] = []
+    files.extend(project_root.glob("*.sh"))
+    files.extend(project_root.glob("Dockerfile*"))
+    scripts_dir = project_root / "scripts"
+    if scripts_dir.exists():
+        files.extend(scripts_dir.rglob("*.sh"))
+    return sorted(set(files))
+
+
+def _load_shell_uvicorn_entrypoints(project_root: Path) -> set[tuple[str, str]]:
+    """Return Uvicorn app targets referenced by shell files."""
+    pairs: set[tuple[str, str]] = set()
+    for path in _entrypoint_shell_files(project_root):
+        text = path.read_text(encoding="utf-8")
+        for module_name, symbol_name in _UVICORN_RE.findall(text):
+            pairs.add((module_name, symbol_name))
+    return pairs
+
+
+def load_tach_interface_exports(project_root: Path) -> set[tuple[str, str]]:
+    """Return symbols exposed by Tach interfaces."""
+    tach_path = project_root / "tach.toml"
+    if not tach_path.exists():
+        return set()
+
+    data = tomllib.loads(tach_path.read_text(encoding="utf-8"))
+    pairs: set[tuple[str, str]] = set()
+    for interface in data.get("interfaces", []):
+        source_modules = interface.get("from", [])
+        exposed_names = interface.get("expose", [])
+        if not isinstance(source_modules, list) or not isinstance(exposed_names, list):
+            continue
+        for module_name in source_modules:
+            if not isinstance(module_name, str):
+                continue
+            for symbol_name in exposed_names:
+                if isinstance(symbol_name, str):
+                    pairs.add((module_name, symbol_name))
+    return pairs

privata/_exports.py

@@ -0,0 +1,170 @@
+"""Validation for literal __all__ declarations."""
+
+from __future__ import annotations
+
+import ast
+
+from privata._models import ExportIssue, Module
+from privata._modules import names_from_target
+
+_IGNORED_PUBLIC_BINDINGS = {"logger"}
+
+
+def collect_export_issues(modules: dict[str, Module]) -> list[ExportIssue]:
+    """Return mismatches between literal __all__ and public bindings."""
+    issues: list[ExportIssue] = []
+
+    for module in modules.values():
+        if module.tree is None:
+            continue
+
+        all_names, lineno = _literal_all(module.tree)
+        if all_names is None:
+            continue
+
+        all_bindings = _all_bindings(module.tree)
+        public_bindings = _public_bindings(module.tree)
+
+        issues.extend(
+            ExportIssue(
+                module=module.name,
+                path=module.path,
+                name=name,
+                kind="unknown",
+                lineno=lineno,
+            )
+            for name in sorted(all_names - all_bindings)
+        )
+
+        issues.extend(
+            ExportIssue(
+                module=module.name,
+                path=module.path,
+                name=name,
+                kind="private",
+                lineno=lineno,
+            )
+            for name in sorted(name for name in all_names & all_bindings if _is_private(name))
+        )
+
+        issues.extend(
+            ExportIssue(
+                module=module.name,
+                path=module.path,
+                name=name,
+                kind="missing",
+                lineno=lineno,
+            )
+            for name in sorted(public_bindings - all_names)
+        )
+
+    return sorted(issues, key=lambda item: (str(item.path), item.lineno, item.kind, item.name))
+
+
+def _literal_all(tree: ast.Module) -> tuple[set[str] | None, int]:
+    for node in tree.body:
+        if isinstance(node, ast.Assign):
+            for target in node.targets:
+                if isinstance(target, ast.Name) and target.id == "__all__":
+                    return _strings_from_node(node.value), node.lineno
+    return None, 0
+
+
+def _strings_from_node(node: ast.expr) -> set[str] | None:
+    if isinstance(node, (ast.List, ast.Tuple, ast.Set)):
+        names: set[str] = set()
+        for elt in node.elts:
+            if isinstance(elt, ast.Constant) and isinstance(elt.value, str):
+                names.add(elt.value)
+            else:
+                return None
+        return names
+    return None
+
+
+def _all_bindings(tree: ast.Module) -> set[str]:
+    bindings: set[str] = set()
+    _collect_bound_names(tree.body, bindings, public_only=False, include_imports=True)
+    return bindings
+
+
+def _public_bindings(tree: ast.Module) -> set[str]:
+    bindings: set[str] = set()
+    _collect_bound_names(
+        tree.body,
+        bindings,
+        public_only=True,
+        include_imports=False,
+    )
+    return bindings
+
+
+def _collect_bound_names(
+    statements: list[ast.stmt],
+    bindings: set[str],
+    *,
+    public_only: bool,
+    include_imports: bool,
+) -> None:
+    for node in statements:
+        if include_imports or not isinstance(node, (ast.Import, ast.ImportFrom)):
+            for name in _bound_names(node):
+                _add_binding(bindings, name, public_only=public_only)
+        for nested_statements in _nested_public_binding_statements(node):
+            _collect_bound_names(
+                nested_statements,
+                bindings,
+                public_only=public_only,
+                include_imports=include_imports,
+            )
+
+
+def _bound_names(node: ast.stmt) -> list[str]:
+    names: list[str] = []
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+        names = [node.name]
+    elif isinstance(node, ast.Assign):
+        names = [
+            name
+            for target in node.targets
+            for name in names_from_target(target)
+            if name != "__all__"
+        ]
+    elif isinstance(node, ast.AnnAssign):
+        names = names_from_target(node.target)
+    elif hasattr(ast, "TypeAlias") and isinstance(node, ast.TypeAlias):
+        names = names_from_target(node.name)
+    elif isinstance(node, ast.Import):
+        names = [alias.asname or alias.name.split(".")[0] for alias in node.names]
+    elif isinstance(node, ast.ImportFrom):
+        names = _import_from_bound_names(node)
+    return names
+
+
+def _import_from_bound_names(node: ast.ImportFrom) -> list[str]:
+    if node.module == "__future__":
+        return []
+    return [alias.asname or alias.name for alias in node.names if alias.name != "*"]
+
+
+def _nested_public_binding_statements(node: ast.stmt) -> list[list[ast.stmt]]:
+    if not isinstance(node, ast.Try):
+        return []
+    return [
+        node.body,
+        node.orelse,
+        node.finalbody,
+        *(handler.body for handler in node.handlers),
+    ]
+
+
+def _add_binding(bindings: set[str], name: str, *, public_only: bool) -> None:
+    if public_only and name in _IGNORED_PUBLIC_BINDINGS:
+        return
+    if public_only and _is_private(name):
+        return
+    bindings.add(name)
+
+
+def _is_private(name: str) -> bool:
+    return name.startswith("_") and not (name.startswith("__") and name.endswith("__"))