Oneport ApiDiff

Breaking-change gate for PRs — straight from the Python code diff. No OpenAPI spec required.

oasdiff needs an OpenAPI spec. buf breaking needs protobuf. Most Python codebases have neither — their public API is the code. Oneport ApiDiff diffs the actual public surface of your changed .py files (via the ast module, deterministically) and gates the merge when a change would break consumers.

$ oneport-apidiff check --staged

oneport-apidiff — --staged
==========================
Verdict: BREAKING   (2 breaking, 0 risky, 1 compatible; 1 file(s) checked)

[BREAKING]   charge  (pkg/payments.py:6)
    param `timeout` was removed
    - def charge(amount, currency='usd', timeout=30)
    + def charge(amount, currency='usd')
    impact:    callers passing timeout positionally or by keyword now break
    migration: drop the timeout argument; configure timeouts on the client instead
    internal callers (2):
      app/billing.py:1   from pkg.payments import charge
      app/billing.py:14  charge(total, timeout=5)

Exit code 1 on BREAKING — wire it into CI and the merge is blocked until someone consciously overrides.

How it works

Deterministic detection, LLM classification. The model never decides what changed — only what it means.

1. Deterministic core (ast) — base and head versions of every changed .py file are compared as public API surfaces: removed symbols, added/removed/renamed/reordered required params, changed defaults, changed type annotations, sync↔async flips, module constants, enum members, dataclass / pydantic-model fields, @property accessors, and __init__.py re-exports. A public symbol that simply moves between modules is reported as a relocation, not a false remove + add. If an openapi.yaml/openapi.json changed, its paths/methods/responses are diffed structurally too. Internal callers of every changed symbol are found by a deterministic, usage-aware repo scan (calls, attribute access, and imports — not every line that happens to contain the name) and listed with file:line.
2. LLM layer (Claude or Gemini) — each detected change is classified BREAKING / RISKY / COMPATIBLE with a one-line consumer-impact narrative and a migration note. Every change carries a deterministic default verdict, so if the model is down, wrong, or skipped (--no-llm), the gate still works.

Install

pip install oneport-apidiff
export GEMINI_API_KEY=...   # free at https://aistudio.google.com/apikey
# or: export ANTHROPIC_API_KEY=sk-ant-...

Usage

oneport-apidiff check --staged          # gate what you're about to commit (default)
oneport-apidiff check --head            # gate the last commit
oneport-apidiff check --base main       # gate your branch against main
oneport-apidiff check https://github.com/org/repo/pull/42          # gate a PR
oneport-apidiff check https://github.com/org/repo/pull/42 --post   # ...and post the verdict

Flags:

Exit codes: 0 clean/compatible · 1 breaking changes · 2 usage/config/auth error.

Waivers

Approve a specific break without opening the gate for everything. Drop a .oneport/apidiff-waivers.yml in the repo:

waivers:
  - symbol: core.Client.fetch     # exact qualname (or OpenAPI endpoint)
    reason: consumers migrated in v3
    expires: "2026-12-31"         # optional; after it, the gate closes again
    kind: symbol_removed          # optional; narrow to one change kind

A waived change still appears in the report (marked [WAIVED], and suppressed in SARIF) but no longer fails CI. An expired waiver is ignored automatically, so a temporary exception can't silently hide a break forever.

Team guidelines

ApiDiff reads the same .oneport/guidelines.md file as oneport-review. Verdicts respect your policy:

- internal package, private API — only changes to __all__ symbols are breaking
- CLI flag names are public API too

Detection stays deterministic either way; guidelines only shape what a change means.

CI

See examples/workflows/apidiff.yml. Minimal version:

- run: pip install oneport-apidiff
- run: oneport-apidiff check "${{ github.event.pull_request.html_url }}" --post
  env:
    GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Privacy

Serverless by design: your code goes from your machine (or your CI runner) directly to the model API with your own key. No Oneport servers, no telemetry, no storage. See PRIVACY.md.

vs. the alternatives

Part of the Oneport pre-ship gate suite, alongside oneport-review.