forge-dashboard-sdk-python
A Python client for forge-dashboard's REST API, generated from its OpenAPI spec with openapi-python-client. It saves you from hand-rolling HTTP requests, auth and retries against the API yourself.
Requirements
- Python 3.12 or later.
- A running forge-dashboard instance.
- A personal API token for that instance (see "Authentication" below) —
every endpoint except
health,get_versionand the two webhook receivers needs one.
Installation
pip install forge-dashboard-sdk
Pin an exact version in your own pyproject.toml/requirements.txt rather
than tracking the latest release in anything but a quick trial.
Authentication
forge-dashboard accepts either a browser's passkey session cookie or a
personal API token — Authorization: Bearer <token> — as an alternative
that needs no WebAuthn ceremony. This SDK only speaks the token half, the
one a script can actually use. Mint one by signing into the dashboard once
and calling POST /api/tokens, then pass it to ForgeDashboardClient or
set FORGE_DASHBOARD_API_TOKEN in the environment:
import os
from forge_dashboard import ForgeDashboardClient
client = ForgeDashboardClient(
"https://forge-dashboard.example.com",
api_token=os.environ.get("FORGE_DASHBOARD_API_TOKEN"),
)
Usage
health and get_version need no token and are good first calls to prove
the client reaches the server at all:
from forge_dashboard import ForgeDashboardClient
with ForgeDashboardClient("https://forge-dashboard.example.com") as client:
version = client.get_version()
print("server version:", version.version)
The aggregated dashboard needs a token, and demonstrates error handling:
import os
from forge_dashboard import APIError, ForgeDashboardClient, decode_error
from forge_dashboard._generated.api.dashboard import get_dashboard
client = ForgeDashboardClient(
"https://forge-dashboard.example.com",
api_token=os.environ.get("FORGE_DASHBOARD_API_TOKEN"),
)
try:
response = get_dashboard.sync_detailed(client=client.raw)
if error := decode_error(response):
raise error
for pr in response.parsed.pull_requests:
print(pr.title, pr.ci)
except APIError as e:
if e.status_code == 401:
raise SystemExit("API token expired or invalid") from e
raise
Every other operation follows the generated client's pattern —
forge_dashboard._generated.api.<tag>.<operation>.sync_detailed(client=client.raw, ...)
(or asyncio_detailed for async) returns a typed Response whose .parsed
field holds the decoded body for a documented status code. Use
decode_error to turn any error response into a forge_dashboard.APIError
uniformly:
from forge_dashboard import decode_error
from forge_dashboard._generated.api.dashboard import get_dashboard
response = get_dashboard.sync_detailed(client=client.raw)
if error := decode_error(response):
raise error
dashboard = response.parsed
The client retries a 429 or 5xx response with exponential backoff and
jitter (honoring a server-sent Retry-After), and never retries any other
4xx. Tune it by passing a forge_dashboard.RetryConfig as retry=, or
swap the underlying httpx.Client/httpx.AsyncClient entirely with
httpx_client=/httpx_async_client=.
Reports
Every push to main that passes its tests publishes the reports to
apis.ryankes.eu:
- Tests: JUnit XML
- Coverage: an HTML view and Cobertura XML
Regenerating the client
See CONTRIBUTING.md — the generated code is pinned to a specific forge-dashboard commit and shouldn't drift from it silently.
Contributing
See CONTRIBUTING.md for building, testing and the release process.
License
MIT — a permissive license for the client, independent of forge-dashboard's own AGPL-3.0.
1 maintainer
Metadata
1 maintainer
Release files for forge-dashboard-sdk 2.0.17
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| forge_dashboard_sdk-2.0.17.tar.gz | 268.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| forge_dashboard_sdk-2.0.17-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 439.9 kB
Release files / forge_dashboard_sdk-2.0.17.tar.gz
| Download URL | forge_dashboard_sdk-2.0.17.tar.gz |
|---|---|
| Size | 268.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b17efd51ea1db7c5be790b6273d048508ca1d4adf06f079241769c41d566ab69
|
|
BLAKE2b-256 checksum How to use checksums |
bb90b8c157c688a5d45d5966ffbd3abb23d6b598b4cf873e2e1523f098b5c230
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.
Transparency logRelease files / forge_dashboard_sdk-2.0.17-py3-none-any.whl
| Download URL | forge_dashboard_sdk-2.0.17-py3-none-any.whl |
|---|---|
| Size | 171.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fddfd8e328ea59ed8b0ef088d6d0fc2d2ce84078cc5689c447e6b5fb4f19d016
|
|
BLAKE2b-256 checksum How to use checksums |
ae6f62c2c7d3aa19e55aab4ddc5ee43e5878aee90499a7a48b2d4eab2d938824
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.
Transparency log
