fastapi-breakgate 1.0.1__tar.gz

fastapi_breakgate-1.0.1/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.venv/
+venv/
+.env
+*.snapshot.json.bak
+contract-report.md
+contract-comment.md
+openapi.json
+.DS_Store

fastapi_breakgate-1.0.1/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 1.0.1 — 2026-11-15
+
+### Changed
+
+- PyPI distribution name is **`fastapi-breakgate`** (`fastapi-contract` was already taken on PyPI)
+- CLI entry points: `fastapi-breakgate` (primary) and `fastapi-contract` (alias)
+- GitHub repo: `prakash888kp/fastapi-breakgate`
+
+### Fixed
+
+- Resolve nested OpenAPI `$ref` enums (FastAPI component schemas) during property comparison
+- Diff component-level enum add/remove so policy (`additive-friendly` vs `strict`) applies correctly
+- Expanded integration E2E coverage for additive/breaking/intentional/CLI/pytest-plugin flows
+
+## 1.0.0 — 2026-11-15
+
+### Added
+
+- Production-ready `fastapi-contract` package with CLI, pytest plugin, and GitHub Action
+- Reliable OpenAPI export ladder (live / factory / snapshot) with `doctor`
+- Pure-Python OpenAPI breaking-change classifier with `additive-friendly` and `strict` policies
+- Optional oasdiff integration when the binary is available
+- Intentional breaking-change protocol (label/title marker + changelog section)
+- PR markdown reports, SemVer bump hints, and GitHub Actions annotations

fastapi_breakgate-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 prakash888kp / fastapi-breakgate contributors
+
+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.

fastapi_breakgate-1.0.1/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.5
+Name: fastapi-breakgate
+Version: 1.0.1
+Summary: Production merge gate for FastAPI: export live OpenAPI, detect breaking changes, enforce intentional-break protocol.
+Project-URL: Homepage, https://github.com/prakash888kp/fastapi-breakgate
+Project-URL: Documentation, https://github.com/prakash888kp/fastapi-breakgate#readme
+Project-URL: Repository, https://github.com/prakash888kp/fastapi-breakgate
+Project-URL: Issues, https://github.com/prakash888kp/fastapi-breakgate/issues
+Project-URL: Changelog, https://github.com/prakash888kp/fastapi-breakgate/blob/main/CHANGELOG.md
+Author-email: prakash888kp <prakash888kp@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-compatibility,breaking-changes,ci,contract-testing,fastapi,openapi
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.110
+Requires-Dist: rich>=13.7
+Requires-Dist: tomli>=2.0.1; python_version < '3.11'
+Requires-Dist: typer>=0.12
+Requires-Dist: typing-extensions>=4.8; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: oasdiff
+Description-Content-Type: text/markdown
+
+# fastapi-breakgate
+
+**Production merge gate for FastAPI.** Export live OpenAPI in CI, fail on accidental breaking changes, and make intentional breaks an explicit, changelog-backed review event.
+
+> Status: **Beta (v1.0.1)** — core gate is solid; dogfood on real apps welcome.  
+> Not a fuzzer (that’s Schemathesis). Not a visual OpenAPI browser. A **hard merge gate** with FastAPI-aware DX.
+
+> **Note:** The PyPI name is `fastapi-breakgate` because `fastapi-contract` is already taken by an unrelated project. The import package remains `fastapi_contract`.
+
+## Install
+
+```bash
+pip install fastapi-breakgate
+```
+
+CLI commands (either entry point works):
+
+```bash
+fastapi-breakgate --help
+fastapi-contract --help
+```
+
+## 5-minute setup
+
+### 1. Configure
+
+```toml
+# pyproject.toml
+[tool.fastapi_contract]
+app = "myapp.main:app"
+policy = "additive-friendly"   # or "strict"
+fail_on = "breaking"
+snapshot_path = "openapi.snapshot.json"
+intentional_label = "breaking-change"
+intentional_title_marker = "[breaking-change]"
+changelog_required_heading = "### Breaking"
+```
+
+### 2. Commit a base snapshot
+
+```bash
+fastapi-breakgate doctor --app myapp.main:app
+fastapi-breakgate snapshot --app myapp.main:app
+git add openapi.snapshot.json && git commit -m "chore: add OpenAPI contract snapshot"
+```
+
+### 3. Gate PRs (GitHub Action)
+
+```yaml
+# .github/workflows/contract.yml
+name: API contract
+on:
+  pull_request:
+jobs:
+  contract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install project
+        run: pip install -e ".[dev]"
+      - uses: prakash888kp/fastapi-breakgate/action@v1
+        with:
+          app: myapp.main:app
+          fail-on: breaking
+          policy: additive-friendly
+          install-command: ""
+```
+
+Or call the CLI directly:
+
+```bash
+pip install fastapi-breakgate
+fastapi-breakgate check --app myapp.main:app --annotations
+```
+
+## CLI
+
+| Command | Purpose |
+|---------|---------|
+| `fastapi-breakgate doctor` | Diagnose import/export readiness |
+| `fastapi-breakgate export -o openapi.json` | Export live OpenAPI |
+| `fastapi-breakgate snapshot` | Write committed snapshot |
+| `fastapi-breakgate diff --base-file openapi.snapshot.json` | Classify changes |
+| `fastapi-breakgate check` | CI entrypoint (exit 1 on accidental breaks) |
+| `fastapi-breakgate comment -o pr.md` | Render PR markdown |
+
+## Intentional breaking changes
+
+Accidental breaks fail CI. Planned breaks must complete the protocol:
+
+1. PR label `breaking-change` **or** title contains `[breaking-change]`
+2. `CHANGELOG.md` includes `### Breaking` with at least one bullet
+
+Then the check passes with a visible warning and SemVer **major** suggestion.
+
+## Pytest plugin
+
+```python
+def test_openapi_contract(fastapi_contract):
+    fastapi_contract.assert_compatible()
+```
+
+```bash
+pytest --fastapi-contract-app=myapp.main:app --fastapi-contract-base=openapi.snapshot.json
+```
+
+## Policy
+
+| Change | `additive-friendly` (default) | `strict` |
+|--------|-------------------------------|----------|
+| Add optional response field | safe | safe |
+| Add response enum value | **safe** | breaking |
+| Remove path / field | breaking | breaking |
+| Add required request field | breaking | breaking |
+
+## Export reliability
+
+Real apps often need DB/env at import time. Strategy ladder:
+
+1. **Live** import with stub/default env + optional `.env.contract`
+2. **Factory** (`create_app()`) when configured/detected
+3. **Snapshot** fallback in `export_mode = "auto"` with an explicit warning
+
+Run `fastapi-breakgate doctor` when CI import fails.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+export PYTHONPATH=src:examples
+python -m coverage run -m pytest
+python -m coverage report --fail-under=75
+ruff check src tests
+```
+
+## Release / PyPI
+
+Tagging `vX.Y.Z` (must match `pyproject.toml`) runs CI tests, publishes to PyPI via Trusted Publishing, and creates a GitHub Release.
+
+## License
+
+MIT

fastapi_breakgate-1.0.1/README.md

@@ -0,0 +1,145 @@
+# fastapi-breakgate
+
+**Production merge gate for FastAPI.** Export live OpenAPI in CI, fail on accidental breaking changes, and make intentional breaks an explicit, changelog-backed review event.
+
+> Status: **Beta (v1.0.1)** — core gate is solid; dogfood on real apps welcome.  
+> Not a fuzzer (that’s Schemathesis). Not a visual OpenAPI browser. A **hard merge gate** with FastAPI-aware DX.
+
+> **Note:** The PyPI name is `fastapi-breakgate` because `fastapi-contract` is already taken by an unrelated project. The import package remains `fastapi_contract`.
+
+## Install
+
+```bash
+pip install fastapi-breakgate
+```
+
+CLI commands (either entry point works):
+
+```bash
+fastapi-breakgate --help
+fastapi-contract --help
+```
+
+## 5-minute setup
+
+### 1. Configure
+
+```toml
+# pyproject.toml
+[tool.fastapi_contract]
+app = "myapp.main:app"
+policy = "additive-friendly"   # or "strict"
+fail_on = "breaking"
+snapshot_path = "openapi.snapshot.json"
+intentional_label = "breaking-change"
+intentional_title_marker = "[breaking-change]"
+changelog_required_heading = "### Breaking"
+```
+
+### 2. Commit a base snapshot
+
+```bash
+fastapi-breakgate doctor --app myapp.main:app
+fastapi-breakgate snapshot --app myapp.main:app
+git add openapi.snapshot.json && git commit -m "chore: add OpenAPI contract snapshot"
+```
+
+### 3. Gate PRs (GitHub Action)
+
+```yaml
+# .github/workflows/contract.yml
+name: API contract
+on:
+  pull_request:
+jobs:
+  contract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install project
+        run: pip install -e ".[dev]"
+      - uses: prakash888kp/fastapi-breakgate/action@v1
+        with:
+          app: myapp.main:app
+          fail-on: breaking
+          policy: additive-friendly
+          install-command: ""
+```
+
+Or call the CLI directly:
+
+```bash
+pip install fastapi-breakgate
+fastapi-breakgate check --app myapp.main:app --annotations
+```
+
+## CLI
+
+| Command | Purpose |
+|---------|---------|
+| `fastapi-breakgate doctor` | Diagnose import/export readiness |
+| `fastapi-breakgate export -o openapi.json` | Export live OpenAPI |
+| `fastapi-breakgate snapshot` | Write committed snapshot |
+| `fastapi-breakgate diff --base-file openapi.snapshot.json` | Classify changes |
+| `fastapi-breakgate check` | CI entrypoint (exit 1 on accidental breaks) |
+| `fastapi-breakgate comment -o pr.md` | Render PR markdown |
+
+## Intentional breaking changes
+
+Accidental breaks fail CI. Planned breaks must complete the protocol:
+
+1. PR label `breaking-change` **or** title contains `[breaking-change]`
+2. `CHANGELOG.md` includes `### Breaking` with at least one bullet
+
+Then the check passes with a visible warning and SemVer **major** suggestion.
+
+## Pytest plugin
+
+```python
+def test_openapi_contract(fastapi_contract):
+    fastapi_contract.assert_compatible()
+```
+
+```bash
+pytest --fastapi-contract-app=myapp.main:app --fastapi-contract-base=openapi.snapshot.json
+```
+
+## Policy
+
+| Change | `additive-friendly` (default) | `strict` |
+|--------|-------------------------------|----------|
+| Add optional response field | safe | safe |
+| Add response enum value | **safe** | breaking |
+| Remove path / field | breaking | breaking |
+| Add required request field | breaking | breaking |
+
+## Export reliability
+
+Real apps often need DB/env at import time. Strategy ladder:
+
+1. **Live** import with stub/default env + optional `.env.contract`
+2. **Factory** (`create_app()`) when configured/detected
+3. **Snapshot** fallback in `export_mode = "auto"` with an explicit warning
+
+Run `fastapi-breakgate doctor` when CI import fails.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+export PYTHONPATH=src:examples
+python -m coverage run -m pytest
+python -m coverage report --fail-under=75
+ruff check src tests
+```
+
+## Release / PyPI
+
+Tagging `vX.Y.Z` (must match `pyproject.toml`) runs CI tests, publishes to PyPI via Trusted Publishing, and creates a GitHub Release.
+
+## License
+
+MIT

fastapi_breakgate-1.0.1/action/action.yml

@@ -0,0 +1,118 @@
+name: fastapi-breakgate
+description: Fail PRs on accidental FastAPI OpenAPI breaking changes.
+author: prakash888kp
+branding:
+  icon: shield
+  color: green
+
+inputs:
+  app:
+    description: FastAPI target as module:attr (e.g. myapp.main:app)
+    required: true
+  fail-on:
+    description: breaking | risky | any
+    required: false
+    default: breaking
+  policy:
+    description: additive-friendly | strict
+    required: false
+    default: additive-friendly
+  base-file:
+    description: Path to base OpenAPI JSON (defaults to openapi.snapshot.json)
+    required: false
+    default: ""
+  working-directory:
+    description: Directory containing the FastAPI project
+    required: false
+    default: "."
+  python-version:
+    description: Python version for the runner setup (informational; use setup-python before)
+    required: false
+    default: "3.12"
+  install-command:
+    description: Command to install project dependencies before the check
+    required: false
+    default: "pip install -e ."
+  pr-title:
+    description: Override PR title for intentional protocol (defaults to github.event.pull_request.title)
+    required: false
+    default: ""
+  pr-labels:
+    description: Comma-separated labels (defaults to PR labels)
+    required: false
+    default: ""
+  report-path:
+    description: Where to write the markdown report
+    required: false
+    default: contract-report.md
+
+outputs:
+  report-path:
+    description: Path to the generated markdown report
+    value: ${{ inputs.report-path }}
+  conclusion:
+    description: success or failure
+    value: ${{ steps.check.outputs.conclusion }}
+
+runs:
+  using: composite
+  steps:
+    - name: Install fastapi-breakgate
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install "fastapi-breakgate>=1.0.1"
+        if [ -n "${{ inputs.install-command }}" ]; then
+          ${{ inputs.install-command }}
+        fi
+
+    - name: Resolve PR metadata
+      id: meta
+      shell: bash
+      run: |
+        TITLE="${{ inputs.pr-title }}"
+        if [ -z "$TITLE" ]; then
+          TITLE="${{ github.event.pull_request.title }}"
+        fi
+        LABELS="${{ inputs.pr-labels }}"
+        if [ -z "$LABELS" ]; then
+          LABELS=$(python - <<'PY'
+        import json, os
+        event_path = os.environ.get("GITHUB_EVENT_PATH")
+        labels = []
+        if event_path and os.path.isfile(event_path):
+            with open(event_path, encoding="utf-8") as f:
+                event = json.load(f)
+            for label in event.get("pull_request", {}).get("labels", []) or []:
+                name = label.get("name")
+                if name:
+                    labels.append(name)
+        print(",".join(labels))
+        PY
+          )
+        fi
+        echo "title=$TITLE" >> "$GITHUB_OUTPUT"
+        echo "labels=$LABELS" >> "$GITHUB_OUTPUT"
+
+    - name: Run contract check
+      id: check
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      env:
+        FAC_PR_TITLE: ${{ steps.meta.outputs.title }}
+        FAC_PR_LABELS: ${{ steps.meta.outputs.labels }}
+      run: |
+        set +e
+        ARGS=(check --app "${{ inputs.app }}" --fail-on "${{ inputs.fail-on }}" --policy "${{ inputs.policy }}" --report "${{ inputs.report-path }}" --annotations)
+        if [ -n "${{ inputs.base-file }}" ]; then
+          ARGS+=(--base-file "${{ inputs.base-file }}")
+        fi
+        fastapi-breakgate "${ARGS[@]}"
+        CODE=$?
+        if [ "$CODE" -eq 0 ]; then
+          echo "conclusion=success" >> "$GITHUB_OUTPUT"
+        else
+          echo "conclusion=failure" >> "$GITHUB_OUTPUT"
+        fi
+        exit "$CODE"

fastapi_breakgate-1.0.1/examples/demo_app/__init__.py

@@ -0,0 +1 @@
+"""Demo FastAPI application used in docs and local smoke tests."""

fastapi_breakgate-1.0.1/examples/demo_app/main.py

@@ -0,0 +1,47 @@
+"""Minimal FastAPI app demonstrating fastapi-contract."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+from fastapi import FastAPI
+from pydantic import BaseModel, Field
+
+
+class Status(str, Enum):
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+
+
+class ItemCreate(BaseModel):
+    name: str = Field(..., min_length=1)
+    status: Status = Status.ACTIVE
+    note: Optional[str] = None
+
+
+class Item(BaseModel):
+    id: int
+    name: str
+    status: Status
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(title="Demo API", version="1.0.0")
+
+    @app.get("/health")
+    def health() -> dict[str, str]:
+        return {"status": "ok"}
+
+    @app.get("/items/{item_id}", response_model=Item)
+    def get_item(item_id: int) -> Item:
+        return Item(id=item_id, name="demo", status=Status.ACTIVE)
+
+    @app.post("/items", response_model=Item, status_code=201)
+    def create_item(payload: ItemCreate) -> Item:
+        return Item(id=1, name=payload.name, status=payload.status)
+
+    return app
+
+
+app = create_app()