privata 0.1.0

A Python module privacy checker for keeping public interfaces intentional.

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

uv tool install privata

For local development:

uv sync --extra dev

Usage

Run Privata from a project root:

privata .

Example output:

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:

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

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