test-privata 0.1.0__tar.gz

test_privata-0.1.0/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(Get-ChildItem -Recurse -Force)",
+      "Bash(Select-Object -First 100)",
+      "Bash(Format-Table FullName)",
+      "Bash(uv run *)"
+    ]
+  }
+}

test_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

test_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

test_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/test-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

test_privata-0.1.0/.gitignore

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

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

@@ -0,0 +1,40 @@
+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: privata
+        name: privata (module privacy)
+        entry: uv run privata .
+        language: system
+        pass_filenames: false
+        types_or: [python, pyi]
+
+      - 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

test_privata-0.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,16 @@
+- id: privata
+  name: privata
+  description: Check that Python module privacy boundaries stay intentional.
+  entry: privata .
+  language: python
+  pass_filenames: false
+  types_or: [python, pyi]
+
+- id: privata-manual
+  name: privata
+  description: Check Python module privacy boundaries on demand.
+  entry: privata .
+  language: python
+  pass_filenames: false
+  stages: [manual]
+  types_or: [python, pyi]

test_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.

test_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.

test_privata-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: test-privata
+Version: 0.1.0
+Summary: A Python module privacy checker for keeping public interfaces intentional.
+Project-URL: Repository, https://github.com/ColinKennedy/privata
+Author: Colin Kennedy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: architecture,code-quality,imports,module-boundaries,python,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14; extra == 'dev'
+Requires-Dist: pre-commit>=4; extra == 'dev'
+Requires-Dist: pytest-cov>=7.1; 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-privata.nijho.lt-blue)](http://privata.nijho.lt/)
+
+<img src="docs/assets/logo.svg" alt="Privata logo" align="right" width="120" />
+
+Find Python code that looks public but is only used privately.
+
+Privata is a static checker for keeping module boundaries intentional.
+It scans your production Python modules and reports four kinds of interface drift:
+
+- public top-level functions, classes, variables, and type aliases that are only used inside their own module
+- imports of private modules such as `pkg._internal` from outside their owning package subtree
+- imports of private top-level symbols such as `pkg.service._Helper` from another production module
+- literal `__all__` declarations that are stale, incomplete, or exporting names that do not exist
+
+It is designed for packages and applications where `helper()` should become `_helper()` once it is no longer part of the production interface.
+Test imports do not count, so tests can still reach internals without forcing those internals to stay public.
+
+## Example
+
+Given:
+
+```python
+# src/example/service.py
+def helper() -> int:
+    return 1
+
+
+def run() -> int:
+    return helper()
+```
+
+Privata reports:
+
+```text
+Found 1 public symbols that could be made private:
+
+  src/example/service.py:1: function `helper`
+```
+
+## Install
+
+```bash
+uv tool install privata
+```
+
+For local development:
+
+```bash
+uv sync --extra dev --group docs
+uv run pre-commit install
+```
+
+## Usage
+
+Run Privata from a project root:
+
+```bash
+privata .
+```
+
+Privata uses `tach.toml` `source_roots` when present.
+Otherwise it prefers `src/` when that directory exists, and falls back to scanning the project root while ignoring tests, virtualenvs, build output, docs output, and hidden tooling directories.
+
+Use Privata as a pre-commit hook in another repository:
+
+```yaml
+repos:
+  - repo: https://github.com/basnijholt/privata
+    rev: v0.1.2
+    hooks:
+      - id: privata
+```
+
+For a less strict setup that only runs when requested:
+
+```yaml
+repos:
+  - repo: https://github.com/basnijholt/privata
+    rev: v0.1.2
+    hooks:
+      - id: privata-manual
+```
+
+```bash
+pre-commit run --hook-stage manual privata-manual --all-files
+```
+
+Full output can include multiple issue types:
+
+```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`
+
+Found 1 private symbol imports from production modules:
+
+  src/example/api.py:4: imports private symbol `example.worker.runtime._Helper`
+
+Found 1 __all__ export issues:
+
+  src/example/__init__.py:5: public name `Service` missing from __all__
+```
+
+If the project is clean:
+
+```text
+No module privacy issues found.
+```
+
+## What Privata Checks
+
+- Public top-level functions, classes, variables, and type aliases in production source roots.
+- Whether those symbols are imported by another production module under those roots.
+- Whether private modules such as `pkg._internal` are imported outside their containing package subtree.
+- Whether private top-level symbols are imported from another production module.
+- Whether literal `__all__` declarations exactly match public top-level bindings.
+- 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 pytest  # enforces 100% coverage
+uv run pre-commit run --all-files
+uv build
+```

test_privata-0.1.0/README.md

@@ -0,0 +1,142 @@
+# 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-privata.nijho.lt-blue)](http://privata.nijho.lt/)
+
+<img src="docs/assets/logo.svg" alt="Privata logo" align="right" width="120" />
+
+Find Python code that looks public but is only used privately.
+
+Privata is a static checker for keeping module boundaries intentional.
+It scans your production Python modules and reports four kinds of interface drift:
+
+- public top-level functions, classes, variables, and type aliases that are only used inside their own module
+- imports of private modules such as `pkg._internal` from outside their owning package subtree
+- imports of private top-level symbols such as `pkg.service._Helper` from another production module
+- literal `__all__` declarations that are stale, incomplete, or exporting names that do not exist
+
+It is designed for packages and applications where `helper()` should become `_helper()` once it is no longer part of the production interface.
+Test imports do not count, so tests can still reach internals without forcing those internals to stay public.
+
+## Example
+
+Given:
+
+```python
+# src/example/service.py
+def helper() -> int:
+    return 1
+
+
+def run() -> int:
+    return helper()
+```
+
+Privata reports:
+
+```text
+Found 1 public symbols that could be made private:
+
+  src/example/service.py:1: function `helper`
+```
+
+## Install
+
+```bash
+uv tool install privata
+```
+
+For local development:
+
+```bash
+uv sync --extra dev --group docs
+uv run pre-commit install
+```
+
+## Usage
+
+Run Privata from a project root:
+
+```bash
+privata .
+```
+
+Privata uses `tach.toml` `source_roots` when present.
+Otherwise it prefers `src/` when that directory exists, and falls back to scanning the project root while ignoring tests, virtualenvs, build output, docs output, and hidden tooling directories.
+
+Use Privata as a pre-commit hook in another repository:
+
+```yaml
+repos:
+  - repo: https://github.com/basnijholt/privata
+    rev: v0.1.2
+    hooks:
+      - id: privata
+```
+
+For a less strict setup that only runs when requested:
+
+```yaml
+repos:
+  - repo: https://github.com/basnijholt/privata
+    rev: v0.1.2
+    hooks:
+      - id: privata-manual
+```
+
+```bash
+pre-commit run --hook-stage manual privata-manual --all-files
+```
+
+Full output can include multiple issue types:
+
+```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`
+
+Found 1 private symbol imports from production modules:
+
+  src/example/api.py:4: imports private symbol `example.worker.runtime._Helper`
+
+Found 1 __all__ export issues:
+
+  src/example/__init__.py:5: public name `Service` missing from __all__
+```
+
+If the project is clean:
+
+```text
+No module privacy issues found.
+```
+
+## What Privata Checks
+
+- Public top-level functions, classes, variables, and type aliases in production source roots.
+- Whether those symbols are imported by another production module under those roots.
+- Whether private modules such as `pkg._internal` are imported outside their containing package subtree.
+- Whether private top-level symbols are imported from another production module.
+- Whether literal `__all__` declarations exactly match public top-level bindings.
+- 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 pytest  # enforces 100% coverage
+uv run pre-commit run --all-files
+uv build
+```

test_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">The private-module mark: bracket, dot, underscore, bracket.</desc>
+  <rect width="128" height="128" rx="28" fill="#101828"/>
+  <path d="M48 36H32v56h16" fill="none" stroke="#cbd5e1" stroke-width="8" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M80 36h16v56H80" fill="none" stroke="#cbd5e1" stroke-width="8" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="54" cy="72" r="6" fill="#f8fafc"/>
+  <rect x="66" y="76" width="18" height="8" rx="4" fill="#22d3ee"/>
+</svg>

test_privata-0.1.0/docs/contributing.md

@@ -0,0 +1,58 @@
+---
+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
+uv run pre-commit install
+```
+
+## Run Tests
+
+```bash
+uv run pytest  # enforces 100% coverage
+```
+
+## Code Quality
+
+```bash
+uv run pre-commit run --all-files
+uv build
+```
+
+Install the Git hook once after setup:
+
+```bash
+uv run pre-commit install
+```
+
+## 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.