JSON API Forge Python SDK v0.5.1

This python-library branch is the independently packaged, pure-Python client SDK. It intentionally contains no Forge server runtime, Qt Editor, example projects, deployment files or compiled binaries.

Choose a component

The four branches are separate products with their own source packages and workflows.

Install

From the branch:

python -m pip install "json-api-forge-client @ git+https://github.com/YoungLionOrganization/JSON-API-Forge.git@python-library"

For a repeatable deployment, pin a reviewed commit SHA. The Python SDK build Action produces a universal py3-none-any wheel, source distribution, source ZIP and SHA256SUMS; it does not publish to PyPI automatically.

Python 3.10–3.14 is supported. The base package depends only on httpx.

Application API client

import os

from json_api_forge import ForgeClient

with ForgeClient("https://api.example.com", api_key=os.environ["FORGE_API_KEY"]) as forge:
    notes = forge.list_items("my-service", "notes", params={"limit": 25})
    created = forge.create_item(
        "my-service",
        "notes",
        {"name": "ship v0.5.1"},
        idempotency_key="command-0192",
    )

AsyncForgeClient provides the equivalent asyncio API:

import asyncio
import os

from json_api_forge import AsyncForgeClient

async def main():
    async with AsyncForgeClient("https://api.example.com", api_key=os.environ["FORGE_API_KEY"]) as forge:
        return await forge.list_items("my-service", "notes", params={"limit": 25})

notes = asyncio.run(main())

Bounded retries are opt-in. The retry/failover policy treats GET, HEAD, OPTIONS, PUT and DELETE as idempotent HTTP methods. Other methods, including POST/PATCH, need an explicit idempotency key before replay is permitted. The server endpoint must actually support idempotency; adding a header alone does not make arbitrary side effects replay-safe.

Editor control-plane client

from getpass import getpass

from json_api_forge import EditorControlPlaneClient

with EditorControlPlaneClient("https://forge-admin.example.com") as control:
    profile = control.login("worker.name", getpass("Worker password: "))
    projects = control.projects()
    rows = control.database_rows("Billing", "primary", "invoices", limit=50)

The control-plane clients cover founder setup, invitation enrollment, profiles, roles, project/document access, validation, read-only database browsing, project areas, messages, notes, attachments, calls and audit records. Bearer sessions are held in a zeroable memory buffer and removed from returned authentication payloads.

Security defaults include HTTPS-only remote URLs, no ambient proxy inheritance, no redirects or retained cookies, strict same-origin paths, exact token formats, bounded response bodies, non-symlink attachment snapshots and atomic downloads. WebRTC call tickets are placed in a URL fragment for the local call client, never in an HTTP query.

Cluster and optional integrations

ForgeCluster and AsyncForgeCluster provide deterministic routing, circuit breakers, bounded bulk work and idempotency-gated failover across multiple Forge endpoints.

YoungLion/DDM adapters remain optional:

python -m pip install "json-api-forge-client[younglion] @ git+https://github.com/YoungLionOrganization/JSON-API-Forge.git@python-library"
# equivalent intent alias
python -m pip install "json-api-forge-client[ddm] @ git+https://github.com/YoungLionOrganization/JSON-API-Forge.git@python-library"

Develop and verify

python -m venv .venv
source .venv/bin/activate  # PowerShell: .\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
ruff format --check json_api_forge tests contract-tests scripts
ruff check json_api_forge tests contract-tests scripts
pytest -q tests
python -m build
python -m twine check dist/*

CI tests Linux x64/ARM64, Windows x64/ARM64 and macOS Intel/Apple Silicon, plus clean installs on Debian, Arch, Fedora, Rocky Linux 9/cPanel-family, openSUSE and Alpine/musl. A separate contract job checks out main and exercises this SDK against the real v0.5.1 control plane without copying server code into this branch.

See PYTHON_LIBRARY.md for the complete API and release contract.

License and contribution

JSON API Forge uses the source-available Self-Host License 1.1, identified by LicenseRef-JAF-SASH-1.1. Commercial self-hosting and private modification are permitted under its terms; redistribution and alternative distributions require the permission described there. See the license FAQ, license history, third-party notices, trademark policy and AI contribution policy.

Official distribution is controlled by Cavanşir Qurbanzadə (@Cavanshirpro) or a lawful successor/assignee. For contributions, follow CONTRIBUTING.md and the CLA. Report vulnerabilities through SECURITY.md; use GitHub issues for reproducible bugs and feature proposals. Include the component, platform and version, with secrets removed from logs.

Responses use Accept-Encoding: identity so the response limit applies before decompression. Servers and proxies must honor this request; unsolicited compressed responses raise ForgeHTTPError before their body is read. The SDK reserves this transport header.