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.9

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.9
File Size Uploaded Provenance Actions
forge_dashboard_sdk-15.0.9.tar.gz 373.1 kB With provenance Details for forge_dashboard_sdk-15.0.9.tar.gz

Built distribution (wheel)

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

Total release size: 664.3 kB

Release files / forge_dashboard_sdk-15.0.9.tar.gz

Download URL forge_dashboard_sdk-15.0.9.tar.gz
Size 373.1 kB
Tags Source
SHA-256 checksum
How to use checksums
91e5bf8e2c7b563245c5474cbcd807d9951e59ad29182d8bc8b78c0cc1bfd8f8
BLAKE2b-256 checksum
How to use checksums
8cbab3d1d98e71a70b9afd290fec2fe70428424f99528195ca87838bcc413c40
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 11, 2026.

Transparency log

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

Download URL forge_dashboard_sdk-15.0.9-py3-none-any.whl
Size 291.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
69c283e4c8cce13305043c3a114c3e9478d7c1c3364733d55dad0a03393c172e
BLAKE2b-256 checksum
How to use checksums
cce0e900d986aa2cda1272c2a8624e20c852168ac371e5f2f38005bd74270629
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 11, 2026.

Transparency log

Security for forge-dashboard-sdk 15.0.9

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.9.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 11, 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.9 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