privata 0.1.0__py3-none-any.whl

privata/__init__.py

@@ -0,0 +1,29 @@
+"""Python module privacy checks."""
+
+from privata._checker import (
+    Module,
+    PrivateModuleImport,
+    Symbol,
+    collect_modules,
+    collect_private_module_imports,
+    find_cross_imports,
+    find_private_candidates,
+    find_private_module_imports,
+)
+
+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__ = [
+    "Module",
+    "PrivateModuleImport",
+    "Symbol",
+    "__version__",
+    "collect_modules",
+    "collect_private_module_imports",
+    "find_cross_imports",
+    "find_private_candidates",
+    "find_private_module_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,702 @@
+"""Detect module privacy issues within ``src/``.
+
+- Public top-level symbols that are never imported by other src modules.
+- Private modules imported from outside their containing package subtree.
+
+Usage:
+    privata <project-root>
+
+Only imports within ``src/`` count, so test imports are ignored.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+import sys
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class Symbol:
+    """A public top-level symbol found in a module."""
+
+    name: str
+    kind: str  # "function", "class", or "variable"
+    lineno: int
+    module: str
+    path: Path
+
+
+@dataclass
+class Module:
+    """A parsed Python module with its top-level symbols."""
+
+    name: str
+    path: Path
+    package_parts: tuple[str, ...]
+    symbols: list[Symbol] = field(default_factory=list)
+    tree: ast.Module | None = None
+
+
+@dataclass
+class PrivateModuleImport:
+    """A private module imported from outside its containing package subtree."""
+
+    module: str
+    path: Path
+    imported_by: str
+    imported_by_path: Path
+    lineno: int
+
+
+@dataclass(frozen=True)
+class _SymbolCandidate:
+    name: str
+    kind: str
+    lineno: int
+
+
+_ROUTE_DECORATORS = {
+    "api_route",
+    "delete",
+    "get",
+    "head",
+    "options",
+    "patch",
+    "post",
+    "put",
+    "trace",
+    "websocket",
+    "websocket_route",
+}
+_CLI_DECORATORS = {"callback", "command"}
+_FRAMEWORK_CONSTRUCTORS = {"APIRouter", "FastAPI", "Typer"}
+_FRAMEWORK_REGISTRATION_CALLS = {"add_api_route", "add_api_websocket_route", "include_router"}
+_ALLOWED_PUBLIC_NAMES = {"logger"}
+_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")
+_MIN_ARG_COUNT = 2
+_SPLIT_MODULE_PART_COUNT = 2
+
+
+def _find_src_dir(project_root: Path) -> Path | None:
+    src = project_root / "src"
+    return src if src.is_dir() else None
+
+
+def _module_name_from_path(py_file: Path, src_dir: Path) -> str | None:
+    """Derive dotted module name from file path relative to src/."""
+    rel = py_file.relative_to(src_dir)
+    parts = list(rel.with_suffix("").parts)
+    if not parts:
+        return None
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+    if not parts:
+        return None
+    return ".".join(parts)
+
+
+def _package_parts(module_name: str, *, is_package_init: bool = False) -> tuple[str, ...]:
+    if is_package_init:
+        return tuple(module_name.split("."))
+    parts = module_name.rsplit(".", 1)
+    if len(parts) == 1:
+        return ()
+    return tuple(parts[0].split("."))
+
+
+def _is_private_module_name(module_name: str) -> bool:
+    return any(part.startswith("_") for part in module_name.split("."))
+
+
+def _private_module_owner_package(module_name: str) -> str:
+    parts = module_name.rsplit(".", 1)
+    return parts[0] if len(parts) == _SPLIT_MODULE_PART_COUNT else module_name
+
+
+def _module_is_within_package(module_name: str, package_name: str) -> bool:
+    return module_name == package_name or module_name.startswith(f"{package_name}.")
+
+
+def collect_modules(src_dir: Path) -> dict[str, Module]:  # noqa: C901, PLR0912
+    """Parse every .py under src/ and collect top-level public definitions."""
+    modules: dict[str, Module] = {}
+
+    for py_file in sorted(src_dir.rglob("*.py")):
+        if "__pycache__" in py_file.parts:
+            continue
+        mod_name = _module_name_from_path(py_file, src_dir)
+        if mod_name is None:
+            continue
+
+        source = py_file.read_text(encoding="utf-8")
+        try:
+            tree = ast.parse(source, filename=str(py_file))
+        except SyntaxError:
+            continue
+
+        # Detect __all__ to skip explicitly exported names
+        explicit_exports = _extract_all(tree)
+        framework_related_names = _collect_framework_related_names(tree)
+        pydantic_model_names: set[str] = set()
+
+        mod = Module(
+            name=mod_name,
+            path=py_file,
+            package_parts=_package_parts(mod_name, is_package_init=py_file.name == "__init__.py"),
+            tree=tree,
+        )
+
+        for node in tree.body:
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                if _is_framework_callback(node):
+                    continue
+                _maybe_add(
+                    mod,
+                    _SymbolCandidate(node.name, "function", node.lineno),
+                    explicit_exports,
+                    ignored_names=framework_related_names,
+                )
+            elif isinstance(node, ast.ClassDef):
+                if _is_pydantic_model(node, pydantic_model_names):
+                    pydantic_model_names.add(node.name)
+                    continue
+                _maybe_add(
+                    mod,
+                    _SymbolCandidate(node.name, "class", node.lineno),
+                    explicit_exports,
+                    ignored_names=framework_related_names,
+                )
+            elif isinstance(node, ast.Assign):
+                if _is_framework_constructor_call(node.value):
+                    continue
+                for target in node.targets:
+                    for name in _names_from_target(target):
+                        _maybe_add(
+                            mod,
+                            _SymbolCandidate(name, "variable", node.lineno),
+                            explicit_exports,
+                            ignored_names=framework_related_names,
+                        )
+            elif isinstance(node, ast.AnnAssign) and node.target:
+                if node.value is not None and _is_framework_constructor_call(node.value):
+                    continue
+                for name in _names_from_target(node.target):
+                    _maybe_add(
+                        mod,
+                        _SymbolCandidate(name, "variable", node.lineno),
+                        explicit_exports,
+                        ignored_names=framework_related_names,
+                    )
+            elif hasattr(ast, "TypeAlias") and isinstance(node, ast.TypeAlias):
+                for name in _names_from_target(node.name):
+                    _maybe_add(
+                        mod,
+                        _SymbolCandidate(name, "variable", node.lineno),
+                        explicit_exports,
+                        ignored_names=framework_related_names,
+                    )
+
+        modules[mod_name] = mod
+
+    return modules
+
+
+def _extract_all(tree: ast.Module) -> set[str] | None:
+    """Return the set of names in __all__, or None if not defined."""
+    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)
+    return None
+
+
+def _dotted_name(node: ast.expr) -> str | None:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        parent = _dotted_name(node.value)
+        if parent is None:
+            return None
+        return f"{parent}.{node.attr}"
+    return None
+
+
+def _decorator_attr_name(decorator: ast.expr) -> str | None:
+    target = decorator.func if isinstance(decorator, ast.Call) else decorator
+    if isinstance(target, ast.Attribute):
+        return target.attr
+    return None
+
+
+def _is_framework_callback(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    for decorator in node.decorator_list:
+        attr_name = _decorator_attr_name(decorator)
+        if attr_name in _ROUTE_DECORATORS or attr_name in _CLI_DECORATORS:
+            return True
+    return False
+
+
+def _framework_callback_names(node: ast.FunctionDef | ast.AsyncFunctionDef) -> set[str]:
+    names: set[str] = set()
+    expressions: list[ast.expr] = [*node.decorator_list]
+
+    if node.returns is not None:
+        expressions.append(node.returns)
+
+    arg_annotations = [
+        arg.annotation
+        for arg in [*node.args.posonlyargs, *node.args.args, *node.args.kwonlyargs]
+        if arg.annotation is not None
+    ]
+    expressions.extend(arg_annotations)
+    if node.args.vararg and node.args.vararg.annotation is not None:
+        expressions.append(node.args.vararg.annotation)
+    if node.args.kwarg and node.args.kwarg.annotation is not None:
+        expressions.append(node.args.kwarg.annotation)
+
+    defaults = [*node.args.defaults, *(d for d in node.args.kw_defaults if d is not None)]
+    expressions.extend(defaults)
+
+    for expr in expressions:
+        names.update(_names_in_expr(expr))
+
+    return names
+
+
+def _names_in_expr(node: ast.AST | None) -> set[str]:
+    if node is None:
+        return set()
+    return {child.id for child in ast.walk(node) if isinstance(child, ast.Name)}
+
+
+def _is_framework_registration_call(node: ast.expr) -> bool:
+    if not isinstance(node, ast.Call):
+        return False
+    if not isinstance(node.func, ast.Attribute):
+        return False
+    return node.func.attr in _FRAMEWORK_REGISTRATION_CALLS
+
+
+def _collect_framework_related_names(tree: ast.Module) -> set[str]:
+    names: set[str] = set()
+    for node in tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            if _is_framework_callback(node):
+                names.update(_framework_callback_names(node))
+            continue
+
+        expr: ast.expr | None = None
+        if isinstance(node, (ast.Expr, ast.Assign, ast.AnnAssign)):
+            expr = node.value
+
+        if expr is not None and _is_framework_registration_call(expr):
+            names.update(_names_in_expr(expr))
+
+    return names
+
+
+def _is_pydantic_model(node: ast.ClassDef, known_models: set[str]) -> bool:
+    for base in node.bases:
+        base_name = _dotted_name(base)
+        if base_name is None:
+            continue
+        if base_name == "BaseModel" or base_name.endswith(".BaseModel"):
+            return True
+        short = base_name.rsplit(".", 1)[-1]
+        if short in known_models:
+            return True
+    return False
+
+
+def _is_framework_constructor_call(node: ast.expr) -> bool:
+    if not isinstance(node, ast.Call):
+        return False
+    callee = _dotted_name(node.func)
+    if callee is None:
+        return False
+    short = callee.rsplit(".", 1)[-1]
+    return short in _FRAMEWORK_CONSTRUCTORS
+
+
+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  # non-literal element, bail
+        return names
+    return None
+
+
+def _names_from_target(node: ast.expr) -> list[str]:
+    if isinstance(node, ast.Name):
+        return [node.id]
+    if isinstance(node, (ast.Tuple, ast.List)):
+        result: list[str] = []
+        for elt in node.elts:
+            result.extend(_names_from_target(elt))
+        return result
+    return []
+
+
+def _maybe_add(
+    mod: Module,
+    candidate: _SymbolCandidate,
+    explicit_exports: set[str] | None,
+    *,
+    ignored_names: set[str] | None = None,
+) -> None:
+    name = candidate.name
+    if name.startswith("_"):
+        return
+    if name in _ALLOWED_PUBLIC_NAMES:
+        return
+    if explicit_exports is not None and name in explicit_exports:
+        return
+    if ignored_names is not None and name in ignored_names:
+        return
+    mod.symbols.append(
+        Symbol(
+            name=name,
+            kind=candidate.kind,
+            lineno=candidate.lineno,
+            module=mod.name,
+            path=mod.path,
+        ),
+    )
+
+
+def _resolve_relative_import(
+    importer_package: tuple[str, ...],
+    level: int,
+    module_attr: str | None,
+) -> str | None:
+    """Resolve a relative import to an absolute dotted module name."""
+    if level == 0:
+        return module_attr
+
+    # level=1 means current package, level=2 means parent, etc.
+    up = level - 1
+    if up > len(importer_package):
+        return None
+    base = list(importer_package[: len(importer_package) - up])
+    if module_attr:
+        base.extend(module_attr.split("."))
+    return ".".join(base) if base else None
+
+
+def find_cross_imports(modules: dict[str, Module]) -> set[tuple[str, str]]:  # noqa: C901, PLR0912
+    """Return (module_name, symbol_name) pairs that are imported by another src module."""
+    known = set(modules)
+    used: set[tuple[str, str]] = set()
+
+    # Build a quick lookup: module -> set of defined public symbol names
+    defined: dict[str, set[str]] = {}
+    for mod_name, mod in modules.items():
+        defined[mod_name] = {s.name for s in mod.symbols}
+
+    for consumer_name, consumer in modules.items():
+        if consumer.tree is None:
+            continue
+
+        # Track `import X` / `import X as Y` so we can resolve `X.foo`
+        import_aliases: dict[str, str] = {}  # local_name -> module_name
+
+        for node in ast.walk(consumer.tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    local = alias.asname or alias.name.split(".")[0]
+                    import_aliases[local] = alias.name
+
+            elif isinstance(node, ast.ImportFrom):
+                source = _resolve_relative_import(
+                    consumer.package_parts,
+                    node.level or 0,
+                    node.module,
+                )
+                if source is None:
+                    continue
+
+                for alias in node.names:
+                    sym = alias.name
+                    if sym == "*":
+                        # `from mod import *` marks everything as used
+                        if source in defined and source != consumer_name:
+                            for s in defined[source]:
+                                used.add((source, s))
+                        continue
+
+                    # Could be importing a submodule (e.g. `from pkg import submod`)
+                    sub = f"{source}.{sym}"
+                    if sub in known:
+                        local = alias.asname or sym
+                        import_aliases[local] = sub
+                        continue
+
+                    if source != consumer_name and source in defined and sym in defined[source]:
+                        used.add((source, sym))
+
+        # Second pass: resolve attribute access like `module.symbol`
+        for node in ast.walk(consumer.tree):
+            if not isinstance(node, ast.Attribute):
+                continue
+            if not isinstance(node.value, ast.Name):
+                continue
+            obj_name = node.value.id
+            attr = node.attr
+            aliased_module = import_aliases.get(obj_name)
+            if (
+                aliased_module
+                and aliased_module != consumer_name
+                and aliased_module in defined
+                and attr in defined[aliased_module]
+            ):
+                used.add((aliased_module, attr))
+
+    return used
+
+
+def collect_private_module_imports(modules: dict[str, Module]) -> list[PrivateModuleImport]:
+    """Return private src modules imported from outside their package subtree."""
+    private_modules = {
+        module_name for module_name in modules if _is_private_module_name(module_name)
+    }
+    findings: dict[tuple[str, str, int], PrivateModuleImport] = {}
+
+    def record(private_module_name: str, consumer: Module, lineno: int) -> None:
+        if private_module_name == consumer.name:
+            return
+        owner_package = _private_module_owner_package(private_module_name)
+        if _module_is_within_package(consumer.name, owner_package):
+            return
+        findings.setdefault(
+            (private_module_name, consumer.name, lineno),
+            PrivateModuleImport(
+                module=private_module_name,
+                path=modules[private_module_name].path,
+                imported_by=consumer.name,
+                imported_by_path=consumer.path,
+                lineno=lineno,
+            ),
+        )
+
+    for consumer in modules.values():
+        if consumer.tree is None:
+            continue
+
+        for private_module_name, lineno in _find_private_imports_in_module(
+            consumer,
+            private_modules,
+        ):
+            record(private_module_name, consumer, lineno)
+
+    return sorted(
+        findings.values(),
+        key=lambda item: (str(item.imported_by_path), item.lineno, item.module),
+    )
+
+
+def _find_private_imports_in_module(
+    consumer: Module,
+    private_modules: set[str],
+) -> set[tuple[str, int]]:
+    findings: set[tuple[str, int]] = set()
+    if consumer.tree is None:
+        return findings
+
+    for node in ast.walk(consumer.tree):
+        if isinstance(node, ast.Import):
+            findings.update(_private_imports_from_import(node, private_modules))
+            continue
+        if isinstance(node, ast.ImportFrom):
+            findings.update(_private_imports_from_import_from(consumer, node, private_modules))
+
+    return findings
+
+
+def _private_imports_from_import(
+    node: ast.Import,
+    private_modules: set[str],
+) -> set[tuple[str, int]]:
+    return {(alias.name, node.lineno) for alias in node.names if alias.name in private_modules}
+
+
+def _private_imports_from_import_from(
+    consumer: Module,
+    node: ast.ImportFrom,
+    private_modules: set[str],
+) -> set[tuple[str, int]]:
+    source = _resolve_relative_import(
+        consumer.package_parts,
+        node.level or 0,
+        node.module,
+    )
+    if source is None:
+        return set()
+
+    findings: set[tuple[str, int]] = set()
+    if source in private_modules:
+        findings.add((source, node.lineno))
+
+    findings.update(
+        (f"{source}.{alias.name}", node.lineno)
+        for alias in node.names
+        if alias.name != "*" and f"{source}.{alias.name}" in private_modules
+    )
+    return findings
+
+
+def _load_pyproject_entrypoints(project_root: Path) -> set[tuple[str, str]]:
+    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]:
+    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]]:
+    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 _collect_external_entrypoints(project_root: Path) -> set[tuple[str, str]]:
+    pairs = _load_pyproject_entrypoints(project_root)
+    pairs.update(_load_shell_uvicorn_entrypoints(project_root))
+    return pairs
+
+
+def _load_tach_interface_exports(project_root: Path) -> set[tuple[str, str]]:
+    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
+
+
+def _collect_privacy_findings(project_root: Path) -> tuple[list[Symbol], list[PrivateModuleImport]]:
+    """Collect public-symbol and private-module boundary findings."""
+    src_dir = _find_src_dir(project_root)
+    if src_dir is None:
+        msg = f"No src/ directory found in {project_root}"
+        raise FileNotFoundError(msg)
+
+    modules = collect_modules(src_dir)
+    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)
+    return candidates, private_module_imports
+
+
+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 src modules imported from outside their package subtree."""
+    _, private_module_imports = _collect_privacy_findings(project_root)
+    return private_module_imports
+
+
+def main() -> int:
+    """Entry point: scan project and report module-local public symbols."""
+    if len(sys.argv) < _MIN_ARG_COUNT:
+        print(f"Usage: {sys.argv[0]} <project-root>", file=sys.stderr)
+        return 2
+
+    project_root = Path(sys.argv[1]).resolve()
+    try:
+        candidates, private_module_imports = _collect_privacy_findings(project_root)
+    except FileNotFoundError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    if not candidates and not private_module_imports:
+        print("No module privacy issues found.")
+        return 0
+
+    if candidates:
+        print(f"Found {len(candidates)} public symbols that could be made private:\n")
+        for sym in candidates:
+            rel = sym.path.relative_to(project_root)
+            print(f"  {rel}:{sym.lineno}: {sym.kind} `{sym.name}`")
+
+    if private_module_imports:
+        if candidates:
+            print()
+        print(
+            "Found "
+            f"{len(private_module_imports)} "
+            "private module imports outside their package subtree:\n",
+        )
+        for issue in private_module_imports:
+            rel = issue.imported_by_path.relative_to(project_root)
+            print(f"  {rel}:{issue.lineno}: imports private module `{issue.module}`")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

privata/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

privata/cli.py

@@ -0,0 +1,14 @@
+"""Command-line interface for Privata."""
+
+from __future__ import annotations
+
+from privata._checker import main as _checker_main
+
+
+def main() -> int:
+    """Run the Privata module privacy checker."""
+    return _checker_main()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

privata-0.1.0.dist-info/METADATA

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: privata
+Version: 0.1.0
+Summary: A Python module privacy checker for keeping public interfaces intentional.
+Author: Bas Nijholt
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14; extra == 'dev'
+Requires-Dist: pre-commit>=4; extra == 'dev'
+Requires-Dist: pytest>=8.4; extra == 'dev'
+Requires-Dist: ruff>=0.13; extra == 'dev'
+Requires-Dist: ty; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Privata
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![CI](https://github.com/basnijholt/privata/actions/workflows/ci.yml/badge.svg)](https://github.com/basnijholt/privata/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/privata.svg)](https://pypi.org/project/privata/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/privata.svg)](https://pypi.org/project/privata/)
+[![Docs](https://img.shields.io/badge/docs-basnijholt.github.io%2Fprivata-blue)](https://basnijholt.github.io/privata/)
+
+Keep Python module interfaces intentional.
+
+Privata scans a `src/` layout Python project and reports public top-level symbols that are only used inside their own module.
+It also reports imports of private modules from outside their owning package subtree.
+Test imports do not count, so tests can still reach internals without forcing those internals to stay public.
+
+## Install
+
+```bash
+uv tool install privata
+```
+
+For local development:
+
+```bash
+uv sync --extra dev
+```
+
+## Usage
+
+Run Privata from a project root:
+
+```bash
+privata .
+```
+
+Example output:
+
+```text
+Found 2 public symbols that could be made private:
+
+  src/example/service.py:12: function `helper`
+  src/example/service.py:21: class `InternalState`
+
+Found 1 private module imports outside their package subtree:
+
+  src/example/api.py:3: imports private module `example.worker._runtime`
+```
+
+If the project is clean:
+
+```text
+No module privacy issues found.
+```
+
+## What Privata Checks
+
+- Public top-level functions, classes, variables, and type aliases in `src/`.
+- Whether those symbols are imported by another production module under `src/`.
+- Whether private modules such as `pkg._internal` are imported outside their containing package subtree.
+- Console entry points in `pyproject.toml`.
+- Uvicorn entry points in shell scripts and Dockerfiles.
+- Symbols exported through package `__init__.py` and `__all__`.
+- Tach `[[interfaces]]` entries, when `tach.toml` is present.
+
+Privata intentionally ignores imports from `tests/`.
+If only tests import a symbol, Privata treats that symbol as private.
+
+## Development
+
+```bash
+uv run --extra dev pytest
+uv run --extra dev ruff check .
+uv run --extra dev ruff format --check .
+uv run --extra dev mypy src tests
+uv run --extra dev ty check
+uv build
+```

privata-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+privata/__init__.py,sha256=9yrIh2dEwtSxLsbILbfhcPbFzBleRbChuqQKsDusxkI,680
+privata/__main__.py,sha256=mllsJCMYDihaRh7NvQM3R74vw7sWkyvUA-UdDtBVCqY,102
+privata/_checker.py,sha256=-0wAiHIsIH5LMYZSZia1YSeGT7lQ9yp2pyrssXbiGUA,23382
+privata/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
+privata/cli.py,sha256=DoKsqsxwBqq-JOcXsrwpeeqgjKDNcJSvhC5lf2zEGs8,286
+privata-0.1.0.dist-info/METADATA,sha256=3xLKvdDowbgm-gveOM6NvgQab-pGbMgIGEUqj03rkzE,2804
+privata-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+privata-0.1.0.dist-info/entry_points.txt,sha256=hSARcLfghyCOUcXdpV0Y49sJSsquSXCz9XQO7JKbJFQ,45
+privata-0.1.0.dist-info/licenses/LICENSE,sha256=Z-jViiDEIKskSQzvdihxxQ5Z25DDxXFdiPwx4ZK2Jho,1068
+privata-0.1.0.dist-info/RECORD,,

privata-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

privata-0.1.0.dist-info/entry_points.txt

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

privata-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bas Nijholt
+
+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.