fastapi-breakgate 1.0.1__py3-none-any.whl

fastapi_breakgate-1.0.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,22 @@
+fastapi_contract/__init__.py,sha256=j8qt2RigbXF_9F-doZm7axdLWJUqzz28w0PPvzV9PEs,772
+fastapi_contract/__main__.py,sha256=Du_1KCfuMIJD4QsCmXjK7s7cJv9-6D5rIiAFZw4rgJg,75
+fastapi_contract/__version__.py,sha256=d4QHYmS_30j0hPN8NmNPnQ_Z0TphDRbu4MtQj9cT9e8,22
+fastapi_contract/check.py,sha256=FfuKW7NLDq4qQq32COiAiX9XmyWjTkz03JQGEpy-QjE,5131
+fastapi_contract/cli.py,sha256=6z_l1VloRjVRi9B7AsmpXZ1STJ6pUlE6wcrc2voUwUA,10415
+fastapi_contract/comment.py,sha256=_a0eq2r9CBGPJlsHBohyERasCZm1WDTbH1oUVhhiqek,3550
+fastapi_contract/config.py,sha256=urfETO8TqXhVACbOfwhXDNmEYXntdQ5vcA_jBvuvA1U,6749
+fastapi_contract/doctor.py,sha256=2Cqrh1Lj_HLwzrINuOD7Ky1RY_wor8-MQoim4Kj0e2I,8057
+fastapi_contract/export.py,sha256=y9DaHlTpcK5W6YgOCtUmI9KVUGiCZhGj-J8bRseksbU,9930
+fastapi_contract/intentional.py,sha256=O2xuDyISVVasfh8zQc7ML8STsxfeQwJrZQtglAyi7wg,3214
+fastapi_contract/models.py,sha256=93y2kKw2ofBOz0AgA2w9eow9-dIp-tI9Z7CRSXpLp0U,615
+fastapi_contract/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastapi_contract/pytest_plugin.py,sha256=W_EHilInPPKsb9f9IbqWAxu4z7I-eWgA6aXxyY_P4l8,3170
+fastapi_contract/diff/__init__.py,sha256=k6NbibV_zvlMZ7sjCIBWDxwy10rckH8sB1UmNrEoDJc,211
+fastapi_contract/diff/classifier.py,sha256=-EvQYZ-W8rmE6bUSy4Z1-k3owqG8_w9C3q-fYIoI4qw,24296
+fastapi_contract/diff/oasdiff.py,sha256=h5cEMrQrHUW2e1lKj0KOkIIeDQswo0f3IfANLQ-ushw,5914
+fastapi_contract/diff/policy.py,sha256=xBP8M4-0qyYlf-PtmLwOWcoW3aBgaxsh28Qq3I3AyZo,3544
+fastapi_breakgate-1.0.1.dist-info/METADATA,sha256=fo-b_lnpgAtMesvpOBdzKaiXXx92HHOn6tK2yNjEZc4,6126
+fastapi_breakgate-1.0.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+fastapi_breakgate-1.0.1.dist-info/entry_points.txt,sha256=7i7o8b8whc2AXCJWQEFOTt2naL5HgNpIv9Xns1xTREM,169
+fastapi_breakgate-1.0.1.dist-info/licenses/LICENSE,sha256=-XknleU--HhRvKSoQX-LZcNUtDP-PpMphuIOh0lnAv0,1102
+fastapi_breakgate-1.0.1.dist-info/RECORD,,

fastapi_breakgate-1.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fastapi_breakgate-1.0.1.dist-info/entry_points.txt

@@ -0,0 +1,6 @@
+[console_scripts]
+fastapi-breakgate = fastapi_contract.cli:app
+fastapi-contract = fastapi_contract.cli:app
+
+[pytest11]
+fastapi_contract = fastapi_contract.pytest_plugin

fastapi_breakgate-1.0.1.dist-info/licenses/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_contract/__init__.py

@@ -0,0 +1,26 @@
+"""fastapi-contract — production merge gate for FastAPI OpenAPI breaking changes."""
+
+from __future__ import annotations
+
+from fastapi_contract.__version__ import __version__
+from fastapi_contract.check import CheckResult, run_check
+from fastapi_contract.config import ContractConfig, load_config
+from fastapi_contract.diff.classifier import Change, ChangeSeverity, DiffResult, diff_openapi
+from fastapi_contract.export import ExportResult, export_openapi
+from fastapi_contract.models import FailOn, PolicyName
+
+__all__ = [
+    "__version__",
+    "Change",
+    "ChangeSeverity",
+    "CheckResult",
+    "ContractConfig",
+    "DiffResult",
+    "ExportResult",
+    "FailOn",
+    "PolicyName",
+    "diff_openapi",
+    "export_openapi",
+    "load_config",
+    "run_check",
+]

fastapi_contract/__main__.py

@@ -0,0 +1,4 @@
+from fastapi_contract.cli import app
+
+if __name__ == "__main__":
+    app()

fastapi_contract/__version__.py

@@ -0,0 +1 @@
+__version__ = "1.0.1"

fastapi_contract/check.py

@@ -0,0 +1,167 @@
+"""Orchestrate export → diff → intentional protocol → exit decision."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from fastapi_contract.comment import render_markdown_report
+from fastapi_contract.config import ContractConfig
+from fastapi_contract.diff.classifier import DiffResult, diff_openapi
+from fastapi_contract.diff.oasdiff import OasdiffNotFoundError, diff_with_oasdiff, find_oasdiff
+from fastapi_contract.export import ExportResult, export_openapi
+from fastapi_contract.intentional import IntentionalStatus, evaluate_intentional
+from fastapi_contract.models import ExportStrategy, FailOn, PolicyName
+
+
+@dataclass
+class CheckResult:
+    passed: bool
+    exit_code: int
+    diff: DiffResult
+    candidate: ExportResult
+    base: dict[str, Any]
+    intentional: IntentionalStatus | None = None
+    report_markdown: str = ""
+    messages: list[str] = field(default_factory=list)
+
+    @property
+    def accidental_breaking(self) -> bool:
+        return bool(self.diff.breaking) and not (
+            self.intentional is not None and self.intentional.allowed
+        )
+
+
+def _load_schema_file(path: Path) -> dict[str, Any]:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError(f"Schema at {path} must be a JSON object")
+    return data
+
+
+def compare_schemas(
+    base: dict[str, Any],
+    candidate: dict[str, Any],
+    *,
+    policy: PolicyName,
+    prefer_oasdiff: bool = False,
+    oasdiff_bin: str | None = None,
+) -> DiffResult:
+    use_oasdiff = prefer_oasdiff or bool(oasdiff_bin and find_oasdiff(oasdiff_bin))
+    if use_oasdiff:
+        try:
+            return diff_with_oasdiff(
+                base,
+                candidate,
+                policy=policy,
+                oasdiff_bin=oasdiff_bin,
+            )
+        except OasdiffNotFoundError:
+            pass
+        except Exception:  # noqa: BLE001 - always fall back to Python engine
+            pass
+    return diff_openapi(base, candidate, policy=policy)
+
+
+def _should_fail(diff: DiffResult, fail_on: FailOn) -> bool:
+    if fail_on == FailOn.ANY:
+        return bool(diff.changes)
+    if fail_on == FailOn.RISKY:
+        return bool(diff.breaking or diff.risky)
+    return bool(diff.breaking)
+
+
+def run_check(
+    config: ContractConfig | None = None,
+    *,
+    cwd: Path | None = None,
+    base_schema: dict[str, Any] | None = None,
+    base_schema_path: Path | None = None,
+    candidate_schema: dict[str, Any] | None = None,
+    pr_title: str | None = None,
+    pr_labels: list[str] | None = None,
+    changelog_text: str | None = None,
+) -> CheckResult:
+    """Run a full contract check.
+
+    Base schema resolution order:
+    1. Explicit ``base_schema``
+    2. Explicit ``base_schema_path``
+    3. Committed snapshot at ``config.snapshot_path`` (common local/CI mode)
+    """
+    cfg = config or ContractConfig()
+    root = (cwd or Path.cwd()).resolve()
+    messages: list[str] = []
+
+    if candidate_schema is not None:
+        candidate = ExportResult(
+            schema=candidate_schema,
+            strategy=ExportStrategy.LIVE,
+            app_path=cfg.app,
+        )
+    else:
+        candidate = export_openapi(cfg, cwd=root)
+        messages.extend(candidate.warnings)
+
+    if base_schema is not None:
+        base = base_schema
+    elif base_schema_path is not None:
+        base = _load_schema_file(base_schema_path)
+    else:
+        snap = root / cfg.snapshot_path
+        if not snap.is_file():
+            raise FileNotFoundError(
+                f"Base schema not provided and snapshot missing at {snap}. "
+                "Run `fastapi-contract snapshot` on main, or pass --base-file."
+            )
+        base = _load_schema_file(snap)
+        messages.append(f"Using base schema from snapshot {snap}")
+
+    diff = compare_schemas(
+        base,
+        candidate.schema,
+        policy=cfg.policy,
+        prefer_oasdiff=cfg.prefer_oasdiff,
+        oasdiff_bin=cfg.oasdiff_bin,
+    )
+
+    intentional: IntentionalStatus | None = None
+    would_fail = _should_fail(diff, cfg.fail_on)
+    if would_fail and diff.breaking:
+        intentional = evaluate_intentional(
+            cfg,
+            pr_title=pr_title,
+            pr_labels=pr_labels,
+            cwd=root,
+            changelog_text=changelog_text,
+        )
+        if intentional.allowed:
+            messages.append("Intentional breaking-change protocol satisfied.")
+            failed = False
+            exit_code = 0
+        else:
+            messages.extend(intentional.reasons)
+            failed = True
+            exit_code = 1
+    elif would_fail:
+        failed = True
+        exit_code = 1
+    else:
+        failed = False
+        exit_code = 0
+
+    report = render_markdown_report(
+        diff, intentional=intentional, failed=failed
+    )
+    return CheckResult(
+        passed=not failed,
+        exit_code=exit_code,
+        diff=diff,
+        candidate=candidate,
+        base=base,
+        intentional=intentional,
+        report_markdown=report,
+        messages=messages,
+    )