pryti-contract 0.1.0__tar.gz

pryti_contract-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ankush Singh Gandhi
+
+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.

pryti_contract-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: pryti-contract
+Version: 0.1.0
+Summary: Your backend keeps a list of what it does, and cannot lie about it.
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == "django"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: django>=4.2; extra == "dev"
+Dynamic: license-file
+
+# pryti-contract
+
+Your backend keeps a list of what it does. And it can't lie about it.
+
+Companion library to [pryti-semantic-reviewer](https://github.com/AnkushSinghGandhi/pryti-semantic-reviewer).
+Pryti reads code from outside and guesses. This runs inside your app and knows.
+
+## What it does
+
+While your app starts, it records:
+
+- every **route** (path, method, auth)
+- every **model** (fields, types, constraints)
+- every **outside call** (HTTP, email, payments)
+- every **background job**
+- how much of that it actually **knows** vs. couldn't figure out
+
+Then you can ask your app one question and get an answer:
+
+> "What does this app actually do?"
+
+## Why it matters
+
+AI opens a PR with 400 changed lines. You don't read them. You read this:
+
+```
+RISKY (4)
+  POST /orders         auth: user -> public
+  POST /orders         new effect: net:analytics.example.com
+  shop.Customer.email  unique: True -> False
+  shop.Customer.name   field removed (data loss)
+```
+
+Four lines instead of four hundred.
+
+## Install
+
+```bash
+pip install pryti-contract
+```
+
+## Use it — three levels
+
+### Level 1: nothing to write
+
+Works on an existing Django project with zero code changes.
+
+```bash
+pryti-contract export --settings myproject.settings -o contract.json
+```
+
+It reads Django's real router and real model registry. Routes built in loops,
+DRF routers, mixins — all found, because the app already resolved them at startup.
+
+Coverage will be partial. That's reported, not hidden:
+
+```
+wrote contract.json: 9 routes, 6 models, 0 jobs, auth known on 5/9
+```
+
+### Level 2: declare what matters
+
+```python
+from pryti_contract import contract
+
+@contract.route("POST /orders", auth="user")
+@contract.effects("net:api.stripe.com")
+def create_order(request):
+    ...
+```
+
+Eight decorators total, max. AI writes these correctly first try, because
+they look like every Django decorator it has ever seen.
+
+### Level 3: enforce it
+
+```python
+# settings.py
+MIDDLEWARE = ["pryti_contract.middleware.ContractMiddleware", ...]
+
+# conftest.py or apps.py
+from pryti_contract import guard
+guard.install(mode="error")   # off | record | warn | error
+```
+
+Now an undeclared call fails loudly:
+
+```
+shop.views.leaky_order performed undeclared effect 'net:api.stripe.com'.
+Declared: none. Add @contract.effects('net:api.stripe.com') or remove the call.
+```
+
+This is the part no linter can do. The bad code doesn't ship.
+
+**Don't know what to declare?** Run your tests in `record` mode and let it tell you:
+
+```python
+guard.install(mode="record")
+# ... run test suite ...
+json.dump(guard.suggestions(), open("observed.json", "w"))
+```
+
+```bash
+pryti-contract suggest observed.json     # prints the decorators to paste in
+```
+
+## In CI
+
+```yaml
+- run: pryti-contract export --settings myproject.settings -o head.json
+- run: git checkout ${{ github.base_ref }}
+- run: pryti-contract export --settings myproject.settings -o base.json
+- run: pryti-contract diff base.json head.json --markdown --fail-on risky
+```
+
+`--fail-on risky` exits 1 on auth weakening, new outside calls, dropped fields,
+relaxed uniqueness, or changed relations.
+
+## How the effect guard works
+
+One hook at the socket layer, not per-library. `requests`, `httpx`, `urllib`,
+`boto3`, `stripe` — all covered by the same code, including libraries that
+don't exist yet.
+
+- `socket.getaddrinfo` is checked **before** it runs, so a blocked call never leaves the process
+- `socket.socket.connect` catches direct-IP connections
+- `smtplib.SMTP.sendmail` catches email
+- localhost and unix sockets are never effects, so your database doesn't trip it
+
+Patterns support wildcards: `net:*.stripe.com`, `net:*`, `email`.
+
+## What it does not catch
+
+Worth being blunt about.
+
+- **Business logic.** If AI changes a discount from 10% to 90%, the contract is
+  identical. Routes same, models same, effects same. Tests catch that; this doesn't.
+- **Anything the router never sees.** Dead code, unmounted views.
+- **Dynamic hostnames** are caught at runtime, not at export time. The contract
+  records what you declared; the guard records what actually happened.
+
+Structural mistakes: this. Logic mistakes: your tests. You need both.
+
+## Try it
+
+```bash
+git clone ... && cd pryti-contract
+pip install -e ".[dev]"
+pytest
+cd examples/demo && pryti-contract export --settings settings --root . -o /tmp/base.json
+```
+
+MIT.

pryti_contract-0.1.0/README.md

@@ -0,0 +1,153 @@
+# pryti-contract
+
+Your backend keeps a list of what it does. And it can't lie about it.
+
+Companion library to [pryti-semantic-reviewer](https://github.com/AnkushSinghGandhi/pryti-semantic-reviewer).
+Pryti reads code from outside and guesses. This runs inside your app and knows.
+
+## What it does
+
+While your app starts, it records:
+
+- every **route** (path, method, auth)
+- every **model** (fields, types, constraints)
+- every **outside call** (HTTP, email, payments)
+- every **background job**
+- how much of that it actually **knows** vs. couldn't figure out
+
+Then you can ask your app one question and get an answer:
+
+> "What does this app actually do?"
+
+## Why it matters
+
+AI opens a PR with 400 changed lines. You don't read them. You read this:
+
+```
+RISKY (4)
+  POST /orders         auth: user -> public
+  POST /orders         new effect: net:analytics.example.com
+  shop.Customer.email  unique: True -> False
+  shop.Customer.name   field removed (data loss)
+```
+
+Four lines instead of four hundred.
+
+## Install
+
+```bash
+pip install pryti-contract
+```
+
+## Use it — three levels
+
+### Level 1: nothing to write
+
+Works on an existing Django project with zero code changes.
+
+```bash
+pryti-contract export --settings myproject.settings -o contract.json
+```
+
+It reads Django's real router and real model registry. Routes built in loops,
+DRF routers, mixins — all found, because the app already resolved them at startup.
+
+Coverage will be partial. That's reported, not hidden:
+
+```
+wrote contract.json: 9 routes, 6 models, 0 jobs, auth known on 5/9
+```
+
+### Level 2: declare what matters
+
+```python
+from pryti_contract import contract
+
+@contract.route("POST /orders", auth="user")
+@contract.effects("net:api.stripe.com")
+def create_order(request):
+    ...
+```
+
+Eight decorators total, max. AI writes these correctly first try, because
+they look like every Django decorator it has ever seen.
+
+### Level 3: enforce it
+
+```python
+# settings.py
+MIDDLEWARE = ["pryti_contract.middleware.ContractMiddleware", ...]
+
+# conftest.py or apps.py
+from pryti_contract import guard
+guard.install(mode="error")   # off | record | warn | error
+```
+
+Now an undeclared call fails loudly:
+
+```
+shop.views.leaky_order performed undeclared effect 'net:api.stripe.com'.
+Declared: none. Add @contract.effects('net:api.stripe.com') or remove the call.
+```
+
+This is the part no linter can do. The bad code doesn't ship.
+
+**Don't know what to declare?** Run your tests in `record` mode and let it tell you:
+
+```python
+guard.install(mode="record")
+# ... run test suite ...
+json.dump(guard.suggestions(), open("observed.json", "w"))
+```
+
+```bash
+pryti-contract suggest observed.json     # prints the decorators to paste in
+```
+
+## In CI
+
+```yaml
+- run: pryti-contract export --settings myproject.settings -o head.json
+- run: git checkout ${{ github.base_ref }}
+- run: pryti-contract export --settings myproject.settings -o base.json
+- run: pryti-contract diff base.json head.json --markdown --fail-on risky
+```
+
+`--fail-on risky` exits 1 on auth weakening, new outside calls, dropped fields,
+relaxed uniqueness, or changed relations.
+
+## How the effect guard works
+
+One hook at the socket layer, not per-library. `requests`, `httpx`, `urllib`,
+`boto3`, `stripe` — all covered by the same code, including libraries that
+don't exist yet.
+
+- `socket.getaddrinfo` is checked **before** it runs, so a blocked call never leaves the process
+- `socket.socket.connect` catches direct-IP connections
+- `smtplib.SMTP.sendmail` catches email
+- localhost and unix sockets are never effects, so your database doesn't trip it
+
+Patterns support wildcards: `net:*.stripe.com`, `net:*`, `email`.
+
+## What it does not catch
+
+Worth being blunt about.
+
+- **Business logic.** If AI changes a discount from 10% to 90%, the contract is
+  identical. Routes same, models same, effects same. Tests catch that; this doesn't.
+- **Anything the router never sees.** Dead code, unmounted views.
+- **Dynamic hostnames** are caught at runtime, not at export time. The contract
+  records what you declared; the guard records what actually happened.
+
+Structural mistakes: this. Logic mistakes: your tests. You need both.
+
+## Try it
+
+```bash
+git clone ... && cd pryti-contract
+pip install -e ".[dev]"
+pytest
+cd examples/demo && pryti-contract export --settings settings --root . -o /tmp/base.json
+```
+
+MIT.

pryti_contract-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pryti-contract"
+version = "0.1.0"
+description = "Your backend keeps a list of what it does, and cannot lie about it."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = []
+
+[project.optional-dependencies]
+django = ["django>=4.2"]
+dev = ["pytest>=7", "django>=4.2"]
+
+[project.scripts]
+pryti-contract = "pryti_contract.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pryti_contract-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pryti_contract-0.1.0/src/pryti_contract/__init__.py

@@ -0,0 +1,99 @@
+"""pryti-contract — your backend keeps a list of what it does.
+
+    from pryti_contract import contract
+
+    @contract.route("POST /orders", auth="user")
+    @contract.effects("net:api.stripe.com", "email")
+    def create_order(request): ...
+
+Then::
+
+    pryti-contract export -o contract.json
+    pryti-contract diff base.json head.json
+"""
+
+from __future__ import annotations
+
+from .diff import Change, diff, render_markdown, render_text, worst
+from .guard import UndeclaredEffect, guard
+from .models import Contract, Coverage, Job, Model, Route
+from .registry import handler_name, scope
+from .registry import registry as contract
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "contract",
+    "guard",
+    "scope",
+    "handler_name",
+    "build",
+    "diff",
+    "render_text",
+    "render_markdown",
+    "worst",
+    "Change",
+    "Contract",
+    "Coverage",
+    "Route",
+    "Model",
+    "Job",
+    "UndeclaredEffect",
+    "__version__",
+]
+
+
+def build(include_django: bool = True) -> Contract:
+    """The whole contract: what Django knows at runtime, plus what you declared.
+
+    Order matters. Probing loads the URLConf, which imports your views, which is
+    what makes the decorators run. Reading the registry first would find it empty.
+    """
+    result = Contract()
+    if include_django:
+        try:
+            from django.apps import apps  # noqa: F401
+
+            from .django_probe import probe
+
+            probe(result)
+        except Exception:  # noqa: BLE001 - Django is optional; declarations still work
+            pass
+
+    _merge_declarations(result, contract.build())
+    result.recompute_coverage()
+    return result
+
+
+def _merge_declarations(runtime: Contract, declared: Contract) -> None:
+    """A declaration is a claim about a handler. The router says where it lives."""
+    by_handler: dict[str, list[str]] = {}
+    for key, route in runtime.routes.items():
+        by_handler.setdefault(route.handler, []).append(key)
+
+    for d in declared.routes.values():
+        keys = by_handler.get(d.handler, [])
+        exact = [k for k in keys if runtime.routes[k].path == d.path]
+        targets = exact or keys
+
+        if not targets:
+            # Declared but not mounted (yet). Keep it; a missing route is worth seeing.
+            runtime.routes[d.key] = d
+            continue
+
+        paths = sorted({runtime.routes[k].path for k in targets})
+        for k in targets:
+            runtime.routes.pop(k, None)
+        for path in paths:
+            merged = Route(
+                method=d.method,
+                path=path,
+                handler=d.handler,
+                auth=d.auth,
+                effects=sorted(d.effects),
+                source="declared",
+            )
+            runtime.routes[merged.key] = merged
+
+    for job in declared.jobs.values():
+        runtime.jobs[job.name] = job

pryti_contract-0.1.0/src/pryti_contract/cli.py

@@ -0,0 +1,142 @@
+"""pryti-contract command line."""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+import os
+import sys
+from pathlib import Path
+
+from . import build
+from .diff import RISKY, REVIEW, diff, render_markdown, render_text, worst
+from .models import Contract
+
+
+def _setup_django(settings: str | None) -> None:
+    if settings:
+        os.environ.setdefault("DJANGO_SETTINGS_MODULE", settings)
+    if not os.environ.get("DJANGO_SETTINGS_MODULE"):
+        return
+    import django
+
+    django.setup()
+
+
+def cmd_export(args: argparse.Namespace) -> int:
+    sys.path.insert(0, str(Path(args.root).resolve()))
+    _setup_django(args.settings)
+    for mod in args.import_module or []:
+        importlib.import_module(mod)
+
+    data = build(include_django=not args.no_django).to_dict()
+    text = json.dumps(data, indent=2, sort_keys=True)
+    if args.output:
+        Path(args.output).write_text(text + "\n", encoding="utf-8")
+        cov = data["coverage"]
+        print(
+            f"wrote {args.output}: {len(data['routes'])} routes, "
+            f"{len(data['models'])} models, {len(data['jobs'])} jobs, "
+            f"auth known on {cov['routes_with_auth']}/{cov['routes_total']}",
+            file=sys.stderr,
+        )
+        if cov["unresolved"]:
+            print(f"unresolved: {len(cov['unresolved'])}", file=sys.stderr)
+    else:
+        print(text)
+    return 0
+
+
+def cmd_diff(args: argparse.Namespace) -> int:
+    base = Contract.from_dict(json.loads(Path(args.base).read_text(encoding="utf-8")))
+    head = Contract.from_dict(json.loads(Path(args.head).read_text(encoding="utf-8")))
+    changes = diff(base, head)
+
+    print(render_markdown(changes) if args.markdown else render_text(changes))
+
+    if not changes:
+        return 0
+    level = worst(changes)
+    if args.fail_on == "risky" and level == RISKY:
+        return 1
+    if args.fail_on == "review" and level in (RISKY, REVIEW):
+        return 1
+    if args.fail_on == "any":
+        return 1
+    return 0
+
+
+def cmd_invariants(args: argparse.Namespace) -> int:
+    """Emit a confirmed-invariant corpus for pryti-semantic-reviewer --invariants."""
+    sys.path.insert(0, str(Path(args.root).resolve()))
+    _setup_django(args.settings)
+    for mod in args.import_module or []:
+        importlib.import_module(mod)
+
+    from .invariants import to_invariant_corpus
+
+    corpus = to_invariant_corpus(build(include_django=not args.no_django))
+    text = json.dumps(corpus, indent=2)
+    if args.output:
+        Path(args.output).write_text(text + "\n", encoding="utf-8")
+        dests = corpus[0]["observed"]["destinations"]
+        print(
+            f"wrote {args.output}: {len(corpus)} confirmed invariants, "
+            f"{len(dests)} egress destination(s)",
+            file=sys.stderr,
+        )
+    else:
+        print(text)
+    return 0
+
+
+def cmd_suggest(args: argparse.Namespace) -> int:
+    """Print declarations discovered by a recorded run (e.g. your test suite)."""
+    data = json.loads(Path(args.observed).read_text(encoding="utf-8"))
+    for handler, effects in sorted(data.items()):
+        joined = ", ".join(repr(e) for e in effects)
+        print(f"# {handler}")
+        print(f"@contract.effects({joined})")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="pryti-contract", description=__doc__)
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    e = sub.add_parser("export", help="write the contract as JSON")
+    e.add_argument("-o", "--output")
+    e.add_argument("--settings", help="DJANGO_SETTINGS_MODULE")
+    e.add_argument("--root", default=".", help="project root to put on sys.path")
+    e.add_argument("--import-module", action="append", help="extra modules to import")
+    e.add_argument("--no-django", action="store_true")
+    e.set_defaults(func=cmd_export)
+
+    d = sub.add_parser("diff", help="compare two contract files")
+    d.add_argument("base")
+    d.add_argument("head")
+    d.add_argument("--markdown", action="store_true", help="format for a PR comment")
+    d.add_argument("--fail-on", choices=["never", "risky", "review", "any"], default="never")
+    d.set_defaults(func=cmd_diff)
+
+    inv = sub.add_parser(
+        "invariants", help="emit a confirmed-invariant corpus for the reviewer's --invariants"
+    )
+    inv.add_argument("-o", "--output")
+    inv.add_argument("--settings", help="DJANGO_SETTINGS_MODULE")
+    inv.add_argument("--root", default=".", help="project root to put on sys.path")
+    inv.add_argument("--import-module", action="append", help="extra modules to import")
+    inv.add_argument("--no-django", action="store_true")
+    inv.set_defaults(func=cmd_invariants)
+
+    s = sub.add_parser("suggest", help="turn a recorded run into declarations")
+    s.add_argument("observed", help="JSON from guard.suggestions()")
+    s.set_defaults(func=cmd_suggest)
+
+    args = p.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())