Skip to content

feat(packages): python client (openchainbench) for PyPI#745

Merged
Flotapponnier merged 2 commits into
mainfrom
feat/pypi-python-client
Jun 26, 2026
Merged

feat(packages): python client (openchainbench) for PyPI#745
Flotapponnier merged 2 commits into
mainfrom
feat/pypi-python-client

Conversation

@Flotapponnier

Copy link
Copy Markdown
Collaborator

What

Adds a Python client package under packages/python-client/ that wraps the
public OpenChainBench API: /api/citable, /api/stat/, /api/series/.

Why

Distribution channel for the citable API. Python devs and AI agents expect
pip install openchainbench rather than DIY HTTP. Bonus: pypi.org/project/openchainbench
sidebar surfaces 4 to 5 dofollow project links to openchainbench.com (Homepage,
Documentation, Repository, Issues, Changelog).

Shape

  • Synchronous client on httpx, context-manager friendly, typed exception
    hierarchy (NotFoundError, RateLimitError, APIUnavailableError) so callers
    branch on intent not HTTP status.
  • Models are frozen dataclasses. Parsing is permissive on extras and tolerant
    of payload polymorphism (source can be str or object, methodology can be
    str or list).
  • 15 tests: 12 mocked via httpx.MockTransport, 3 hit live openchainbench.com
    (skip with OCB_SKIP_INTEGRATION=1 for offline CI).
  • python-client-ci.yml runs unit tests on Python 3.10, 3.11, 3.12, 3.13 +
    builds sdist + wheel on every PR touching the package.

Publish flow

  • Tag push python-v* triggers .github/workflows/pypi-publish.yml.
  • Workflow builds, smoke-tests the wheel on 3.10-3.13, then publishes via
    PyPI Trusted Publisher (OIDC, no token stored in the repo).
  • Namespaced python-v* so existing OCB site tags (v1.0-dataset, etc.) never
    trigger a Python release.

One-time setup required from the user before first release

Documented in packages/python-client/PUBLISHING.md. TL;DR:

  1. Create a PyPI account at https://pypi.org.
  2. Add a pending publisher at https://pypi.org/manage/account/publishing/ with:
    • Project: openchainbench
    • Owner: ChainBench
    • Repo: OpenChainBench
    • Workflow: pypi-publish.yml
    • Environment: pypi
  3. In GitHub repo Settings > Environments, create the pypi environment.
  4. Tag and push: git tag python-v0.1.0 && git push origin python-v0.1.0.

Test plan

  • pytest tests -m "not integration" green locally (12 passed)
  • pytest tests green against live API (15 passed)
  • python -m build produces wheel + sdist
  • wheel contains only openchainbench/ + dist-info + LICENSE + py.typed
  • After merge, user configures PyPI Trusted Publisher (PUBLISHING.md)
  • First tag python-v0.1.0 -> CI publishes to pypi.org/project/openchainbench/

Florent Tapponnier and others added 2 commits June 26, 2026 15:05
Wraps /api/citable, /api/stat/<slug>, /api/series/<slug> as a typed
synchronous client with frozen dataclass models and a small exception
hierarchy (NotFound, RateLimit, APIUnavailable).

Ships:
- src layout under packages/python-client/, hatchling backend
- httpx-based OpenChainBench client, list/get/series methods
- 15 tests: 12 mocked, 3 live integration (skip via OCB_SKIP_INTEGRATION=1)
- .github/workflows/python-client-ci.yml for PR tests on 3.10 to 3.13
- .github/workflows/pypi-publish.yml triggered on python-v* tags,
  publishes via PyPI Trusted Publisher (OIDC, no token in repo)
- PUBLISHING.md with the one-time PyPI Trusted Publisher setup steps
@Flotapponnier
Flotapponnier merged commit 9255ee6 into main Jun 26, 2026
5 checks passed
@Flotapponnier
Flotapponnier deleted the feat/pypi-python-client branch July 17, 2026 14:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant