privata 0.1.0__tar.gz

privata-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Build package
+        run: uv build
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run pre-commit (via prek)
+        uses: j178/prek-action@v1

privata-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install dependencies
+        run: uv sync --group docs
+
+      - name: Build documentation
+        run: uv run zensical build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: ./site
+
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

privata-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,24 @@
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/privata
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Build
+        run: uv build
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

privata-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.DS_Store
+.venv/
+.ruff_cache/
+.pytest_cache/
+__pycache__/
+*.py[cod]
+dist/
+build/
+site/
+*.egg-info/
+.privata/
+src/privata/_version.py

privata-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.9
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy (type checker)
+        entry: uv run mypy src tests
+        language: system
+        types: [python]
+        pass_filenames: false
+
+      - id: ty
+        name: ty (type checker)
+        entry: uv run ty check
+        language: system
+        types: [python]
+        pass_filenames: false

privata-0.1.0/AGENTS.md

@@ -0,0 +1,23 @@
+# Repository Guidelines
+
+Privata is a small Python package for AST-based module privacy checks.
+
+## Development
+
+- Use `uv sync --extra dev --group docs` for a full development environment.
+- Run `uv run pytest` for tests.
+- Run `uv run ruff check .`, `uv run ruff format --check .`, `uv run mypy src tests`, and `uv run ty check` before submitting changes.
+- Use `uv build` to verify packaging.
+
+## Structure
+
+- `src/privata/_checker.py` contains the checker implementation.
+- `src/privata/cli.py` exposes the console script.
+- `tests/test_checker.py` contains focused behavior tests.
+- `docs/` contains the Zensical documentation site.
+
+## Style
+
+- Keep runtime dependencies minimal.
+- Prefer standard-library parsing and typed data structures.
+- Preserve the rule that test imports do not count when deciding whether a symbol should remain public.

privata-0.1.0/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.

privata-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,76 @@
+# 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/docs/assets/logo.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" role="img" aria-labelledby="title desc">
+  <title id="title">Privata logo</title>
+  <desc id="desc">A shield containing a private module underscore.</desc>
+  <rect width="128" height="128" rx="28" fill="#312e81"/>
+  <path d="M64 18l36 14v28c0 24.5-14.2 42.8-36 52-21.8-9.2-36-27.5-36-52V32l36-14z" fill="#eef2ff"/>
+  <path d="M64 28l25 9.7v21.1c0 18-9.5 31.8-25 39.7-15.5-7.9-25-21.7-25-39.7V37.7L64 28z" fill="#4f46e5"/>
+  <path d="M39 82h50v10H39z" fill="#c7d2fe"/>
+  <path d="M51 69h26v8H51z" fill="#ffffff"/>
+</svg>

privata-0.1.0/docs/contributing.md

@@ -0,0 +1,60 @@
+---
+icon: lucide/git-pull-request
+---
+
+# Contributing
+
+Contributions are welcome.
+
+## Development Setup
+
+```bash
+git clone https://github.com/basnijholt/privata.git
+cd privata
+uv sync --extra dev --group docs
+```
+
+## Run Tests
+
+```bash
+uv run pytest
+```
+
+## Code Quality
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src tests
+uv run ty check
+uv build
+```
+
+The repository also uses pre-commit:
+
+```bash
+uv run pre-commit run --all-files
+```
+
+## Build Docs
+
+```bash
+uv run zensical build
+```
+
+The generated site is written to `site/`.
+
+## Project Structure
+
+```text
+src/privata/
+├── __init__.py   Public package API
+├── __main__.py   python -m privata entry point
+├── _checker.py   AST-based privacy analysis
+└── cli.py        Console script wrapper
+```
+
+## Release
+
+Releases are published from GitHub Releases through trusted publishing.
+Create a release tag such as `v0.1.0`; the `release.yml` workflow builds and uploads to PyPI.

privata-0.1.0/docs/getting-started.md

@@ -0,0 +1,67 @@
+---
+icon: lucide/rocket
+---
+
+# Getting Started
+
+## Prerequisites
+
+You need:
+
+- Python 3.12+
+- a Python project with source code under `src/`
+
+## Installation
+
+=== "uv tool"
+
+    ```bash
+    uv tool install privata
+    ```
+
+=== "pipx"
+
+    ```bash
+    pipx install privata
+    ```
+
+=== "pip"
+
+    ```bash
+    pip install privata
+    ```
+
+=== "From source"
+
+    ```bash
+    git clone https://github.com/basnijholt/privata.git
+    cd privata
+    uv sync --extra dev
+    ```
+
+## Run
+
+From a project root:
+
+```bash
+privata .
+```
+
+Privata exits with status `0` when no privacy issues are found.
+It exits with status `1` when it finds public symbols that can be made private or private module imports that cross package boundaries.
+
+## Expected Layout
+
+Privata expects a `src/` directory:
+
+```text
+project/
+├── pyproject.toml
+└── src/
+    └── package/
+        ├── __init__.py
+        └── module.py
+```
+
+Tests can live anywhere.
+Imports from tests do not count when deciding whether a symbol should stay public.

privata-0.1.0/docs/index.md

@@ -0,0 +1,43 @@
+---
+icon: lucide/shield-check
+---
+
+# Privata
+
+**Keep Python module interfaces intentional**
+
+<div style="text-align: center; margin: 1.5rem 0;">
+  <img src="assets/logo.svg" alt="Privata logo" width="140" />
+</div>
+
+Privata scans Python projects that use a `src/` layout and reports public symbols that are only used inside their own module.
+It also reports private module imports that cross package boundaries.
+
+[PyPI package](https://pypi.org/project/privata/) · [GitHub repository](https://github.com/basnijholt/privata)
+
+## Quick Start
+
+```bash
+uv tool install privata
+privata .
+```
+
+Continue with [Getting Started](getting-started.md), or see the [usage guide](usage.md) for the full checker behavior.
+
+## Features
+
+- Finds public module-level functions, classes, variables, and type aliases that can be made private.
+- Ignores test imports when deciding whether a symbol is public.
+- Detects private modules imported from outside their owning package subtree.
+- Honors package `__init__.py` re-exports and literal `__all__` declarations.
+- Honors `pyproject.toml` console entry points, Uvicorn shell entry points, and Tach interfaces.
+- Uses only the Python standard library at runtime.
+
+## Example
+
+```text
+Found 2 public symbols that could be made private:
+
+  src/example/service.py:12: function `helper`
+  src/example/service.py:21: class `InternalState`
+```

privata-0.1.0/docs/usage.md

@@ -0,0 +1,60 @@
+---
+icon: lucide/terminal
+---
+
+# Usage
+
+## Command
+
+```bash
+privata <project-root>
+```
+
+The command scans Python files under `<project-root>/src`.
+
+## Public Symbols
+
+Privata reports top-level public symbols that are not imported from another production module:
+
+```python
+def helper() -> int:
+    return 1
+```
+
+If `helper` is only used inside its own module, Privata reports it as a candidate for `_helper`.
+
+## Private Module Imports
+
+Private modules are modules whose dotted path contains a private segment:
+
+```text
+package._internal
+package.feature._runtime
+```
+
+Those modules can be imported from inside their owning package subtree.
+Imports from outside that subtree are reported.
+
+## What Counts As Public Use
+
+The following keep a symbol public:
+
+- another module under `src/` imports the symbol
+- a package `__init__.py` re-exports the symbol
+- a literal `__all__` includes the symbol
+- `pyproject.toml` lists the symbol as a console or GUI script entry point
+- a shell script or Dockerfile launches the symbol as a Uvicorn app
+- `tach.toml` exposes the symbol through a `[[interfaces]]` entry
+
+Imports from tests do not count.
+
+## Framework Exceptions
+
+Privata skips common framework-owned names:
+
+- FastAPI route handlers and related request/response models
+- Typer command callbacks
+- framework app/router objects created with `FastAPI`, `APIRouter`, or `Typer`
+- module-level `logger`
+
+These names are often public by framework convention even when they are not imported from another production module.