Skip to main content

forge-dashboard-sdk-python

CI PyPI Codecov License: MIT docs

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_version and 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/v1/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:

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.

Metadata

Release files for forge-dashboard-sdk 15.0.14

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for forge-dashboard-sdk 15.0.14
File Size Uploaded Provenance Actions
forge_dashboard_sdk-15.0.14.tar.gz 376.5 kB With provenance Details for forge_dashboard_sdk-15.0.14.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for forge-dashboard-sdk 15.0.14
File Interpreter ABI Platform Actions
forge_dashboard_sdk-15.0.14-py3-none-any.whl Python 3 none any Details for forge_dashboard_sdk-15.0.14-py3-none-any.whl

Total release size: 671.3 kB

Release files / forge_dashboard_sdk-15.0.14.tar.gz

Download URL forge_dashboard_sdk-15.0.14.tar.gz
Size 376.5 kB
Tags Source
SHA-256 checksum
How to use checksums
669d4328b4c5ad03434a922c81d4b95e8fd509af603e0b191557576653427fd6
BLAKE2b-256 checksum
How to use checksums
73d9782f42ddd6ebaa499e32213574c23d7ff5caa02ec601892130feecc3a342
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 12, 2026.

Transparency log

Release files / forge_dashboard_sdk-15.0.14-py3-none-any.whl

Download URL forge_dashboard_sdk-15.0.14-py3-none-any.whl
Size 294.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9665a3146d5dc14f0655d8641ac6ef25f223ccac4120510597f678a29ea4ad7e
BLAKE2b-256 checksum
How to use checksums
6239f3b916c509beeb2f986e42ad95a7c0f1b7a20737fd3532a388652b01a1e2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 12, 2026.

Transparency log

Security for forge-dashboard-sdk 15.0.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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for forge_dashboard_sdk-15.0.14.tar.gz

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 Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

15.0.14 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page