Skip to content

Betterleaks Python Integration Docs

This folder captures the project plan and technical decisions for building a self-contained Python package for Betterleaks.

Document Map

  • Project brief: what this project is, why it exists, and what has already been verified.
  • Getting started: install, local build, scan examples, Docker, and docs commands.
  • Configuration: typed config models, Betterleaks TOML mapping, Expr filters, and validation env vars.
  • Benchmarks: current synthetic benchmark results, reproduction commands, and interpretation notes.
  • API reference: generated public Python API reference.
  • Workplan: phased implementation plan from scaffold to PyPI release.
  • Architecture: proposed package layout, native bridge design, public Python API, and CI/release model.
  • ABI contract: JSON request/response shape and exported native functions.
  • Implementation notes: detailed packaging, testing, compatibility, and supply-chain notes.
  • Betterleaks pin: the bundled upstream version, provenance links, and upgrade checklist.
  • Release checklist: maintainer checklist for wheel and PyPI releases.
  • Troubleshooting: common local build and install issues.
  • v1.0 readiness: release-readiness criteria and suggested path to a stable 1.0.0.
  • Roadmap: release scope, blocked musllinux work, and follow-up features.
  • Backlog: unsupported features, future tasks, and open decisions.
  • v0.2 plan: config API, async cancellation, benchmarks, release hardening, and acceptance criteria.
  • v0.3 plan: Git workflows, streaming APIs, config coverage, and release hardening.
  • AI handoff: compact context for future AI agents and human maintainers.
  • Docker E2E: Docker end-to-end tests, fixtures, and runner.

Current Status

Created on 2026-07-08 and updated after the first PyPI release on 2026-07-09. The repository now contains the Python SDK, native ABI bridge, typed config API, async wrappers, tests, Docker E2E harness, CI workflows, generated docs site, benchmarks, and release docs.