fastapi-contractguard 0.1.0__py3-none-any.whl

contractguard/cli.py

@@ -0,0 +1,159 @@
+import typer
+import json
+from pathlib import Path
+from contractguard.openapi import generate_openapi
+from contractguard.comparator import compare_contracts
+from contractguard.docs import show_contract_docs
+app = typer.Typer(
+    name="contractguard",
+    help="[yellow]Now Pratham Detects [bold bright_magenta]breaking changes[/bold bright_magenta] in API Contracts | Please use command --docs for more information",
+    rich_markup_mode="rich"
+)
+
+@app.command("docs")
+def show_docs():
+    """Show ContractGuard documentation."""
+
+    show_contract_docs()
+
+@app.command("init")
+def init(app_path:str=typer.Option(...,"--app")):
+    """Initialize ContractGuard in the current project."""
+    try:
+        typer.echo("Loading FastAPI application....")
+
+        schema = generate_openapi(app_path)
+        folder = Path('.contractguard')
+        folder.mkdir(exist_ok=True)
+
+        print(f"Scehama : {schema}")
+        # schema["paths"]["path"]["description"]
+        baseline = folder / "baseline.json"
+
+
+        paths = schema.get("paths",{})
+
+        protected_routes = []
+        for path,methods in paths.items():
+            for method,details in methods.items():
+                if "protect" in details.get("description","").lower():
+                    details["is_protected"]=True
+                else:
+                    details["is_protected"]=False
+
+        with open(baseline,"w",encoding="utf-8") as file:
+            json.dump(schema,file,indent=2)
+
+        typer.echo("✓ FastAPI app loaded")
+        typer.echo("✓ OpenAPI schema generated")
+        typer.echo(f"✓ Baseline saved: {baseline}")
+
+    except Exception as error:
+        typer.echo(f"✗ Error: {error}", err=True)
+        raise typer.Exit(code=1)
+
+
+@app.command("say-hi")
+def sayhi():
+    """Say Hi as a test message"""
+    typer.echo("Hello from contractguard")
+
+
+@app.command("check")
+def check(app_path:str = typer.Option(...,"--app",help="FastAPI application path . eg: main:app")):
+    """Comparator logic : heart"""
+
+    try:
+        baseline_path = Path(".contractguard/baseline.json")
+
+        #check if baseline is there: 
+        if not baseline_path.exists():
+            typer.echo("No baseline found. Please run `init` first")
+            raise typer.Exit(code=1)
+
+        protected_routes = []
+
+        # else load the basline 
+        with open(baseline_path,"r",encoding="utf-8") as file:
+            old_contract = json.load(file)
+
+        typer.echo("Loading the FastAPI application...")
+        new_contract = generate_openapi(app_path)
+
+        #Compare the paths
+        changes = compare_contracts(old_contract,new_contract)
+
+        typer.echo("Changes in the contracts :\n")
+
+        if not changes:
+            typer.echo(
+                "No changes beem occurred | "
+            )
+
+        for change in changes:
+            typer.echo(f"\nchange value : {change}")
+
+            if change["severity"] == "breaking":
+                icon = "🔴"
+                label = 'BREAKING CHANGE'
+            else:
+                icon = "🟢"
+                label = "SAFE CHANGE"
+
+            method = change.get("method")
+
+            if method:
+                endpoint = (
+                    f"{method} {change['path']}"
+                )
+            else:
+                endpoint = change['path']
+
+            typer.echo(
+                f"{icon} {label}: "
+                f"{endpoint}"
+            )
+
+    except Exception as error:
+        typer.echo(
+            f"✗ Failed to check API contract: {error}",
+            err=True,
+        )
+
+        raise typer.Exit(code=1)
+
+
+@app.command("update")
+def update(
+    app_path:str=typer.Option(
+        ...,
+        "--app",
+        help="To update the baseline Eg.main:app"
+    )
+):
+
+    """Updating the openapi.json"""
+
+    try:
+        typer.echo("Generating the current Current API contract...")
+
+        openapi_schema = generate_openapi(app_path=app_path)
+        print("Got the protected route info : ",openapi_schema[""])
+        print(f"OPEN API SCHEMA : \n",openapi_schema)
+        contractguard_path=Path('.contractguard')
+        contractguard_path.mkdir(exist_ok=True)
+
+        baseline_path = contractguard_path / "baseline.json"
+
+        with open(baseline_path,"w",encoding="utf-8") as file:
+            json.dump(openapi_schema,file,indent=2)
+
+        typer.echo(f"✓ API baseline updated: {baseline_path}")
+
+    except Exception as e:
+        typer.echo(
+            f"✗ Failed to update baseline: {e}",
+            err=True,
+        )
+if __name__ == "__main__":
+    app()

contractguard/comparator.py

@@ -0,0 +1,61 @@
+def compare_contracts(old: dict, new: dict):
+    changes = []
+
+    old_paths = old.get("paths", {})
+    new_paths = new.get("paths", {})
+
+    # --------------------------------
+    # Check removed endpoints / methods
+    # --------------------------------
+
+    for path, old_methods in old_paths.items():
+        print("Path ",old_paths)
+        # Entire endpoint was removed
+        if path not in new_paths:
+            changes.append({
+                "type": "removed_endpoint",
+                "path": path,
+                "severity": "breaking",
+            })
+
+            continue
+
+        # Check if individual HTTP methods were removed
+        for method in old_methods:
+
+            if method not in new_paths[path]:
+                changes.append({
+                    "type": "removed_endpoint",
+                    "path": path,
+                    "method": method.upper(),
+                    "severity": "breaking",
+                })
+
+    # --------------------------------
+    # Check added endpoints / methods
+    # --------------------------------
+
+    for path, new_methods in new_paths.items():
+
+        # Entire endpoint was added
+        if path not in old_paths:
+            changes.append({
+                "type": "added_endpoint",
+                "path": path,
+                "severity": "safe",
+            })
+
+            continue
+
+        # Check if individual HTTP methods were added
+        for method in new_methods:
+
+            if method not in old_paths[path]:
+                changes.append({
+                    "type": "added_endpoint",
+                    "path": path,
+                    "method": method.upper(),
+                    "severity": "safe",
+                })
+
+    return changes

contractguard/config.py

@@ -0,0 +1,17 @@
+from pathlib import Path
+import tomllib
+
+
+def load_config():
+    config_path = Path("contractguard.toml")
+
+    if not config_path.exists():
+        raise FileNotFoundError(
+            "contractguard.toml not found !"
+            "Run `contractguard init` from your FastAPI project."
+        )
+
+    with open(config_path,"rb") as file:
+        config = tomllib.load(file)
+        
+    return config

contractguard/docs.py

@@ -0,0 +1,50 @@
+import typer
+
+def show_contract_docs():
+    typer.echo("")
+    typer.secho(
+        "CONTRACTGUARD",
+        fg=typer.colors.YELLOW,
+        bold=True,
+    )
+
+    typer.echo(
+        "\nContractGuard detects breaking changes "
+        "in FastAPI API contracts."
+    )
+
+    typer.echo("\nCOMMANDS")
+    typer.echo("  init     Create the initial API baseline")
+    typer.echo("  check    Check the current API against the baseline")
+    typer.echo("  update   Update the approved API baseline")
+    typer.echo("  docs     Show ContractGuard documentation")
+
+    typer.echo("\nWORKFLOW")
+    typer.echo("  1. Initialize the baseline")
+    typer.echo("  2. Modify your FastAPI API")
+    typer.echo("  3. Run check")
+    typer.echo("  4. Review the detected changes")
+    typer.echo("  5. Run update when the changes are approved")
+
+    typer.echo("\nPROTECTED ROUTES")
+    typer.echo(
+        '  If a route must be strictly protected, '
+        'include the word "protected" in the route docstring.'
+    )
+
+    typer.echo("\nEXAMPLE")
+    typer.echo(
+        '  @app.get("/users", description="protected")'
+    )
+    typer.echo("\nEXAMPLES")
+    typer.echo(
+        "  contractguard init --app main:app"
+    )
+    typer.echo(
+        "  contractguard check --app main:app"
+    )
+    typer.echo(
+        "  contractguard update --app main:app"
+    )
+
+    typer.echo("")

contractguard/openapi.py

@@ -0,0 +1,21 @@
+import importlib
+
+def load_fastapi_app(app_path:str):
+
+    if ":" not in app_path:
+        raise ValueError(
+            "Invalid app path. Use the format `module:app`, "
+            "for eg. `main:app` "
+        )
+    module_name,app_name = app_path.split(":",1)
+
+    module = importlib.import_module(module_name)
+    print("MAIN MODULE LOADED FROM:", module.__file__)
+    app = getattr(module,app_name)
+    print("Returning app value : (load_fast_api) function : ",app)
+    return app
+
+def generate_openapi(app_path:str):
+    app = load_fastapi_app(app_path=app_path)
+
+    return app.openapi()

fastapi_contractguard-0.1.0.dist-info/METADATA

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: fastapi-contractguard
+Version: 0.1.0
+Summary: Detect breaking changes in FastAPI API contracts
+Author: Prathamesh Pai
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/PrathamPai2004/contractguard
+Project-URL: Repository, https://github.com/PrathamPai2004/contractguard
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: typer>=0.12.0
+Dynamic: license-file
+
+
+# ContractGuard
+
+ContractGuard is a developer tool for **FastAPI applications** that helps you detect and manage API contract changes.
+
+It generates your application's OpenAPI schema, stores a baseline contract, and compares future changes against that baseline so you can identify breaking API changes before they reach production.
+
+## Why ContractGuard?
+
+APIs evolve constantly.
+
+You add a new endpoint, rename a response field, change a parameter, modify a request body, or remove an endpoint.
+
+The problem is that some of these changes can silently break existing clients.
+
+ContractGuard helps you answer:
+
+> "Did my API contract change?"
+
+and more importantly:
+
+> "Did I accidentally introduce a breaking change?"
+
+---
+
+## Features
+
+- Generate OpenAPI schema from a FastAPI application
+- Initialize an API contract baseline
+- Compare the current API schema with the stored contract
+- Detect API contract changes
+- Check contracts from the command line
+- Update the stored contract after intentional changes
+- Generate API documentation
+- Designed specifically for FastAPI projects
+- Simple CLI workflow
+
+---
+
+-- TO BE LAUNCHED SOON

fastapi_contractguard-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+contractguard/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+contractguard/cli.py,sha256=pLamvR-wEKCDI7P0ltBm_uGpPfg_FvCVv9Oct0wC57k,4713
+contractguard/comparator.py,sha256=DtnMDWfPNDyl2J8K368u2vpvvELZpq8AJbjljvcyYTs,1798
+contractguard/config.py,sha256=eszYeDbrans6W906JeeajXawnjhpGsrQ8dDqchLdNWg,414
+contractguard/docs.py,sha256=kI67_oIhAzW0CFoAk7ofbdOeER1Q_6-R8NxVGGy_Vwg,1414
+contractguard/openapi.py,sha256=578kMSGalPMUAt4BBfB4vL2jsNuI-no0ReIgQ7anjFc,615
+contractguard/reporter.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastapi_contractguard-0.1.0.dist-info/licenses/LICENSE,sha256=LyYAVGiSH06xTPDqs10vRxAu1fHd0R9Jr0QXwvsbVpA,1090
+fastapi_contractguard-0.1.0.dist-info/METADATA,sha256=tzhCl13mSRpDcp_8D6sICIF3NjPZQ9lLTLETWok5Ygk,1677
+fastapi_contractguard-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+fastapi_contractguard-0.1.0.dist-info/entry_points.txt,sha256=t68aIpNGxtxPgBs7t05Uo6T_ntqt1iMtx27hz95mHmw,56
+fastapi_contractguard-0.1.0.dist-info/top_level.txt,sha256=BqCNKdN75bKV6kkU52_jIfpgTxOGcmNYgSnY9ZqKX18,14
+fastapi_contractguard-0.1.0.dist-info/RECORD,,

fastapi_contractguard-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fastapi_contractguard-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+contractguard = contractguard.cli:app

fastapi_contractguard-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prathamesh Pai
+
+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_contractguard-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+contractguard