How warrant-dev/warrant-python works
Project type + purpose (what you’re diagramming)
This repo is a Python SDK/client library for the Warrant SaaS API (https://warrant.dev/). It’s not a deployable service; it’s a package that application developers install (pip install warrant-python) and then call warrant.User.create(), etc. The runtime “system” therefore includes:
• Consumer application code (your user’s Python app)
• This SDK (the warrant/ package)
• Warrant HTTP API (external service, configurable via warrant.api_endpoint)
• Auth credentials (API key via warrant.api_key)
• Optional: CI/release pipeline that publishes to PyPI (GitHub Actions)
File tree analysis (what components exist)
Top-level:
• warrant/ → the SDK source package
• setup.py → packaging/distribution metadata
• test/ → tests (notably test_live.py suggests live integration tests against an API endpoint)
• .github/workflows/{ci.yaml, release.yaml} → CI and release automation
• README.md → shows configuration knobs (api_key, api_endpoint) and usage pattern
• __init__.py → package exports and likely global configuration variables (api_key, api_endpoint)
• api_resource.py → base HTTP resource/client abstraction (core request/response plumbing)
• Domain/resource modules (each likely maps to API endpoints and object types):
• user.py, tenant.py, role.py, object.py, permission.py, feature.py, pricing_tier.py, warrant.py
• Results/collections:
• list_result.py, query_result.py
• authz.py → authorization checks / helper API calls (domain-specific logic)
• constants.py → shared constants (paths, defaults, headers, etc.)
This structure strongly suggests a “resource classes wrapping REST endpoints” architecture, with APIResource as the shared base and the other modules as typed “resources”.
README signals to incorporate
Key runtime facts explicitly in README:
• Consumers set:
• warrant.api_key = "..."
• warrant.api_endpoint = "http://localhost:8000" (optional override)
• They call class methods like:
• warrant.User.create()
• warrant.Tenant.create(id="...")
• Global config in the SDK (API key + endpoint)
• Outbound HTTP(S) calls to Warrant API
• A local dev / mock endpoint possibility (endpoint override)
Python Application (Consumer)
• “calls SDK methods; provides API key; handles results/exceptions”
Warrant Python SDK (this repo)
• “resource classes, request signing/auth headers, serialization”
Warrant API Service (External)
• “REST endpoints for Users/Tenants/Roles/Permissions/etc.”
(Optional but useful) PyPI / Distribution
• “installation source” (build/release path rather than runtime path)
(Optional) Developer Local/Test Environment
• shows api_endpoint can be local (README explicitly mentions localhost)
• App → SDK: “function calls / method invocations”
• SDK → Warrant API: “HTTPS requests (Authorization: API key)”
• Warrant API → SDK: “JSON responses (entities, list/query results)”
• SDK → App: “Python objects / results / exceptions”
• (Optional) GitHub Actions → PyPI: “publish package” (release workflow)
Inside the Warrant Python SDK boundary, split into modules that mirror the repo:
Core / shared layer
• warrant/__init__.py
• global config: api_key, api_endpoint
• exports resource classes for import warrant; warrant.User...
• warrant/api_resource.py
• HTTP client base: builds URLs from api_endpoint, injects auth headers from api_key, handles request/response, errors
• warrant/constants.py
• default endpoint, header names, API version strings, etc.
Domain resources (API endpoint wrappers)
• warrant/user.py → /users endpoints
• warrant/tenant.py → /tenants
• warrant/role.py → /roles
• warrant/object.py → /objects (or object-related endpoints)
• warrant/permission.py → permission APIs
• warrant/feature.py → feature flag/entitlement APIs
• warrant/pricing_tier.py → pricing tier endpoints
• warrant/warrant.py → likely the “warrant relationship” concept in Warrant (core domain entity)
Higher-level behavior
• warrant/authz.py
• authorization checks / convenience methods that compose multiple resources or call special authz endpoints
Result wrappers
• warrant/list_result.py
• warrant/query_result.py
• Paginated lists, query responses, metadata (cursor, next page token, etc.)
• Resource modules (user.py, tenant.py, etc.) → api_resource.py: “inherit/compose base HTTP methods”
• authz.py → api_resource.py and/or → resource modules: “calls endpoints / orchestrates”
• list_result.py / query_result.py ← api_resource.py and/or resource modules: “parse JSON into result objects”
• Everything → constants.py: “uses shared constants”
• Everything reads config from __init__.py (or a config singleton) to get api_key + api_endpoint
Pick one README example, e.g. warrant.Tenant.create(id="dunder_mifflin").
Sequence should show:
api_resource.py
• reads warrant.api_endpoint
• reads warrant.api_key
• builds request headers (Authorization)
• sends HTTP request
SDK parses JSON into
• a Tenant object (or dict), possibly wrapping in ListResult/QueryResult when applicable
Architectural patterns/design principles to highlight
• Resource-oriented client library: each domain file corresponds to an API resource.
• Shared base class / abstraction (api_resource.py) centralizes HTTP behavior (DRY).
• Global configuration: warrant.api_key and warrant.api_endpoint set at package level (simple but global-state based).
• DTO/result wrappers: list_result.py, query_result.py provide typed containers for pagination/query metadata.
• External dependency boundary: Warrant API is outside the repo; the SDK is a thin wrapper with value-added typing/helpers.
Technologies to label (what matters here)
• Python package (pip installable)
• HTTP/REST + JSON communication
• API Key authentication (publishable API key)
• Configurable base URL (api_endpoint)
• GitHub Actions for CI + release (non-runtime but part of system lifecycle)
• PyPI distribution (non-runtime but critical to how the system is consumed)
This set will capture: who uses it, how it’s structured, and how it behaves at runtime—without guessing beyond what the tree and README indicate.