openchainbench 0.1.0__tar.gz

openchainbench-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.coverage
+htmlcov/

openchainbench-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenChainBench contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openchainbench-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: openchainbench
+Version: 0.1.0
+Summary: Python client for OpenChainBench live crypto infrastructure benchmarks
+Project-URL: Homepage, https://openchainbench.com
+Project-URL: Documentation, https://openchainbench.com/docs
+Project-URL: Repository, https://github.com/ChainBench/OpenChainBench
+Project-URL: Issues, https://github.com/ChainBench/OpenChainBench/issues
+Project-URL: Changelog, https://github.com/ChainBench/OpenChainBench/releases
+Author-email: OpenChainBench <hello@openchainbench.com>
+License: MIT
+License-File: LICENSE
+Keywords: benchmark,blockchain,crypto,ethereum,infrastructure,openchainbench,rpc,solana
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# openchainbench
+
+Official Python client for [OpenChainBench](https://openchainbench.com), the live, reproducible benchmark suite for crypto infrastructure (RPC latency, bridge fees, perp venues, oracle deviation, and more).
+
+[![PyPI version](https://img.shields.io/pypi/v/openchainbench.svg)](https://pypi.org/project/openchainbench/)
+[![Python versions](https://img.shields.io/pypi/pyversions/openchainbench.svg)](https://pypi.org/project/openchainbench/)
+[![Downloads](https://img.shields.io/pypi/dm/openchainbench.svg)](https://pypi.org/project/openchainbench/)
+[![License](https://img.shields.io/pypi/l/openchainbench.svg)](https://github.com/ChainBench/OpenChainBench/blob/main/LICENSE)
+
+The data served by openchainbench.com is published under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/). Attribute with a link back to the benchmark page (`pageUrl` on every payload).
+
+## Install
+
+```bash
+pip install openchainbench
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```python
+from openchainbench import OpenChainBench
+
+with OpenChainBench() as ocb:
+    for bench in ocb.list_benchmarks():
+        if bench.leader:
+            print(f"{bench.title}: {bench.leader.name} -> {bench.value}")
+```
+
+### Fetch one benchmark
+
+```python
+from openchainbench import OpenChainBench
+
+with OpenChainBench() as ocb:
+    bench = ocb.get_benchmark("bridge-fee")
+    print(bench.headline)
+    for row in bench.rankings[:3]:
+        print(row.slug, row.ms.p50, row.success_rate)
+```
+
+### Fetch a time series
+
+```python
+from openchainbench import OpenChainBench
+
+with OpenChainBench() as ocb:
+    series = ocb.get_series("bridge-fee", range="24h")
+    for provider in series.providers:
+        print(provider.name, provider.values[-1])
+```
+
+### Filter by chain or region
+
+```python
+bench = ocb.get_benchmark("network-fees", chain="ethereum")
+series = ocb.get_series("network-fees", range="7d", chain="ethereum", region="eu-west")
+```
+
+## Error handling
+
+The client maps HTTP responses to a typed exception hierarchy so callers
+can react to intent rather than status codes.
+
+```python
+from openchainbench import (
+    OpenChainBench,
+    NotFoundError,
+    RateLimitError,
+    APIUnavailableError,
+)
+
+with OpenChainBench() as ocb:
+    try:
+        ocb.get_benchmark("not-a-real-slug")
+    except NotFoundError:
+        ...
+    except RateLimitError as exc:
+        print(f"retry after {exc.retry_after_sec}s")
+    except APIUnavailableError:
+        # cold cache or Prom blackout, retry later
+        ...
+```
+
+## API reference
+
+| Method | Endpoint | Returns |
+|---|---|---|
+| `list_benchmarks()` | `GET /api/citable` | `list[BenchmarkSummary]` |
+| `fetch_citable_index()` | `GET /api/citable` | `CitableIndex` |
+| `get_benchmark(slug, *, chain=None, region=None)` | `GET /api/stat/<slug>` | `Benchmark` |
+| `get_series(slug, *, range="24h", chain=None, region=None, providers=None)` | `GET /api/series/<slug>` | `Series` |
+
+All models are immutable dataclasses (`frozen=True`).
+
+## Rate limits
+
+The public API allows 60 requests per minute per IP. The client surfaces
+HTTP 429 as a `RateLimitError` with a `retry_after_sec` attribute.
+
+## Citation
+
+If you use the data in a paper, post, or product, please link the
+benchmark page. The license is CC-BY-4.0. Every payload includes a
+ready-to-paste `quote` field that already contains the attribution.
+
+## Links
+
+- Site: <https://openchainbench.com>
+- Docs: <https://openchainbench.com/docs>
+- Repository: <https://github.com/ChainBench/OpenChainBench>
+- Issues: <https://github.com/ChainBench/OpenChainBench/issues>
+
+## License
+
+MIT. The data fetched from the API stays under CC-BY-4.0; this client
+license only covers the code.

openchainbench-0.1.0/README.md

@@ -0,0 +1,118 @@
+# openchainbench
+
+Official Python client for [OpenChainBench](https://openchainbench.com), the live, reproducible benchmark suite for crypto infrastructure (RPC latency, bridge fees, perp venues, oracle deviation, and more).
+
+[![PyPI version](https://img.shields.io/pypi/v/openchainbench.svg)](https://pypi.org/project/openchainbench/)
+[![Python versions](https://img.shields.io/pypi/pyversions/openchainbench.svg)](https://pypi.org/project/openchainbench/)
+[![Downloads](https://img.shields.io/pypi/dm/openchainbench.svg)](https://pypi.org/project/openchainbench/)
+[![License](https://img.shields.io/pypi/l/openchainbench.svg)](https://github.com/ChainBench/OpenChainBench/blob/main/LICENSE)
+
+The data served by openchainbench.com is published under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/). Attribute with a link back to the benchmark page (`pageUrl` on every payload).
+
+## Install
+
+```bash
+pip install openchainbench
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```python
+from openchainbench import OpenChainBench
+
+with OpenChainBench() as ocb:
+    for bench in ocb.list_benchmarks():
+        if bench.leader:
+            print(f"{bench.title}: {bench.leader.name} -> {bench.value}")
+```
+
+### Fetch one benchmark
+
+```python
+from openchainbench import OpenChainBench
+
+with OpenChainBench() as ocb:
+    bench = ocb.get_benchmark("bridge-fee")
+    print(bench.headline)
+    for row in bench.rankings[:3]:
+        print(row.slug, row.ms.p50, row.success_rate)
+```
+
+### Fetch a time series
+
+```python
+from openchainbench import OpenChainBench
+
+with OpenChainBench() as ocb:
+    series = ocb.get_series("bridge-fee", range="24h")
+    for provider in series.providers:
+        print(provider.name, provider.values[-1])
+```
+
+### Filter by chain or region
+
+```python
+bench = ocb.get_benchmark("network-fees", chain="ethereum")
+series = ocb.get_series("network-fees", range="7d", chain="ethereum", region="eu-west")
+```
+
+## Error handling
+
+The client maps HTTP responses to a typed exception hierarchy so callers
+can react to intent rather than status codes.
+
+```python
+from openchainbench import (
+    OpenChainBench,
+    NotFoundError,
+    RateLimitError,
+    APIUnavailableError,
+)
+
+with OpenChainBench() as ocb:
+    try:
+        ocb.get_benchmark("not-a-real-slug")
+    except NotFoundError:
+        ...
+    except RateLimitError as exc:
+        print(f"retry after {exc.retry_after_sec}s")
+    except APIUnavailableError:
+        # cold cache or Prom blackout, retry later
+        ...
+```
+
+## API reference
+
+| Method | Endpoint | Returns |
+|---|---|---|
+| `list_benchmarks()` | `GET /api/citable` | `list[BenchmarkSummary]` |
+| `fetch_citable_index()` | `GET /api/citable` | `CitableIndex` |
+| `get_benchmark(slug, *, chain=None, region=None)` | `GET /api/stat/<slug>` | `Benchmark` |
+| `get_series(slug, *, range="24h", chain=None, region=None, providers=None)` | `GET /api/series/<slug>` | `Series` |
+
+All models are immutable dataclasses (`frozen=True`).
+
+## Rate limits
+
+The public API allows 60 requests per minute per IP. The client surfaces
+HTTP 429 as a `RateLimitError` with a `retry_after_sec` attribute.
+
+## Citation
+
+If you use the data in a paper, post, or product, please link the
+benchmark page. The license is CC-BY-4.0. Every payload includes a
+ready-to-paste `quote` field that already contains the attribution.
+
+## Links
+
+- Site: <https://openchainbench.com>
+- Docs: <https://openchainbench.com/docs>
+- Repository: <https://github.com/ChainBench/OpenChainBench>
+- Issues: <https://github.com/ChainBench/OpenChainBench/issues>
+
+## License
+
+MIT. The data fetched from the API stays under CC-BY-4.0; this client
+license only covers the code.

openchainbench-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openchainbench"
+version = "0.1.0"
+description = "Python client for OpenChainBench live crypto infrastructure benchmarks"
+authors = [{ name = "OpenChainBench", email = "hello@openchainbench.com" }]
+license = { text = "MIT" }
+requires-python = ">=3.10"
+readme = "README.md"
+keywords = [
+  "openchainbench",
+  "blockchain",
+  "benchmark",
+  "rpc",
+  "crypto",
+  "ethereum",
+  "solana",
+  "infrastructure",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "pytest-cov>=5",
+  "build>=1.2",
+]
+
+[project.urls]
+Homepage = "https://openchainbench.com"
+Documentation = "https://openchainbench.com/docs"
+Repository = "https://github.com/ChainBench/OpenChainBench"
+Issues = "https://github.com/ChainBench/OpenChainBench/issues"
+Changelog = "https://github.com/ChainBench/OpenChainBench/releases"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openchainbench"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/openchainbench",
+  "tests",
+  "README.md",
+  "LICENSE",
+  "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra -q"
+markers = [
+  "integration: hits the live openchainbench.com API (skipped when OCB_SKIP_INTEGRATION=1)",
+]

openchainbench-0.1.0/src/openchainbench/__init__.py

@@ -0,0 +1,48 @@
+"""Official Python client for OpenChainBench.
+
+OpenChainBench (https://openchainbench.com) publishes live, reproducible
+benchmarks of crypto infrastructure: RPC latency, bridge fees, perp venue
+performance, oracle deviation, and more. This package wraps the public,
+CC-BY-4.0 licensed JSON API so that Python applications, notebooks, and
+agents can cite live numbers without scraping HTML.
+"""
+
+from .client import DEFAULT_BASE_URL, OpenChainBench
+from .exceptions import (
+    APIUnavailableError,
+    NotFoundError,
+    OpenChainBenchError,
+    RateLimitError,
+)
+from .models import (
+    Benchmark,
+    BenchmarkSummary,
+    CitableIndex,
+    Latency,
+    Leader,
+    ProviderResult,
+    Series,
+    SeriesProvider,
+    Source,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "OpenChainBench",
+    "OpenChainBenchError",
+    "NotFoundError",
+    "RateLimitError",
+    "APIUnavailableError",
+    "Benchmark",
+    "BenchmarkSummary",
+    "CitableIndex",
+    "Latency",
+    "Leader",
+    "ProviderResult",
+    "Series",
+    "SeriesProvider",
+    "Source",
+    "__version__",
+]

openchainbench-0.1.0/src/openchainbench/client.py

@@ -0,0 +1,202 @@
+"""Synchronous HTTP client for the public OpenChainBench API.
+
+Wraps three endpoints:
+
+* ``GET /api/citable`` -> :meth:`OpenChainBench.list_benchmarks`
+* ``GET /api/stat/<slug>`` -> :meth:`OpenChainBench.get_benchmark`
+* ``GET /api/series/<slug>?range=...`` -> :meth:`OpenChainBench.get_series`
+
+The client keeps a long-lived ``httpx.Client`` and supports the context
+manager protocol. Errors are mapped to a typed hierarchy in
+:mod:`openchainbench.exceptions` so callers can ``except`` on intent rather
+than HTTP status codes.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+import httpx
+
+from .exceptions import (
+    APIUnavailableError,
+    NotFoundError,
+    OpenChainBenchError,
+    RateLimitError,
+)
+from .models import Benchmark, BenchmarkSummary, CitableIndex, Series
+
+DEFAULT_BASE_URL = "https://openchainbench.com"
+DEFAULT_TIMEOUT = 30.0
+USER_AGENT = "openchainbench-python/0.1.0"
+
+_SUPPORTED_RANGES = ("24h", "7d", "30d")
+
+
+def _parse_retry_after(value: Optional[str]) -> Optional[int]:
+    if not value:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    if response.status_code < 400:
+        return
+
+    body: Any
+    try:
+        body = response.json()
+    except ValueError:
+        body = {}
+
+    message = (
+        body.get("error")
+        if isinstance(body, dict) and body.get("error")
+        else f"HTTP {response.status_code} from {response.request.url}"
+    )
+
+    if response.status_code == 404:
+        raise NotFoundError(str(message))
+    if response.status_code == 429:
+        retry = _parse_retry_after(response.headers.get("retry-after"))
+        if retry is None and isinstance(body, dict):
+            retry = body.get("retryAfterSec")
+        raise RateLimitError(str(message), retry_after_sec=retry)
+    if response.status_code == 503:
+        retry = _parse_retry_after(response.headers.get("retry-after"))
+        if retry is None and isinstance(body, dict):
+            retry = body.get("retryAfterSec")
+        raise APIUnavailableError(str(message), retry_after_sec=retry)
+
+    raise OpenChainBenchError(str(message), status_code=response.status_code)
+
+
+class OpenChainBench:
+    """Synchronous client for openchainbench.com.
+
+    Example:
+        >>> from openchainbench import OpenChainBench
+        >>> with OpenChainBench() as ocb:
+        ...     for bench in ocb.list_benchmarks():
+        ...         print(bench.slug, bench.value)
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        user_agent: str = USER_AGENT,
+        client: Optional[httpx.Client] = None,
+    ) -> None:
+        self._owns_client = client is None
+        self._client = client or httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            headers={
+                "User-Agent": user_agent,
+                "Accept": "application/json",
+            },
+        )
+
+    def list_benchmarks(self) -> List[BenchmarkSummary]:
+        """Return every live benchmark with its current headline figure.
+
+        Wraps the ``CitableIndex`` envelope and returns the list directly
+        for ergonomic iteration. Use :meth:`fetch_citable_index` if you
+        need the site metadata as well.
+        """
+        return list(self.fetch_citable_index().benchmarks)
+
+    def fetch_citable_index(self) -> CitableIndex:
+        """Return the full ``/api/citable`` payload including site metadata."""
+        data = self._get("/api/citable")
+        return CitableIndex.from_dict(data)
+
+    def get_benchmark(
+        self,
+        slug: str,
+        *,
+        chain: Optional[str] = None,
+        region: Optional[str] = None,
+    ) -> Benchmark:
+        """Return the full benchmark detail.
+
+        Args:
+            slug: Benchmark slug, e.g. ``"bridge-fee"``.
+            chain: Optional chain filter (e.g. ``"ethereum"``).
+            region: Optional region filter (e.g. ``"eu-west"``).
+
+        Raises:
+            NotFoundError: The slug does not exist or is not live.
+        """
+        params: dict[str, str] = {}
+        if chain:
+            params["chain"] = chain
+        if region:
+            params["region"] = region
+        data = self._get(f"/api/stat/{slug}", params=params or None)
+        return Benchmark.from_dict(data)
+
+    def get_series(
+        self,
+        slug: str,
+        *,
+        range: str = "24h",
+        chain: Optional[str] = None,
+        region: Optional[str] = None,
+        providers: Optional[List[str]] = None,
+    ) -> Series:
+        """Return the per-provider time series for a benchmark.
+
+        Args:
+            slug: Benchmark slug.
+            range: One of ``"24h"``, ``"7d"``, ``"30d"``.
+            chain: Optional chain filter.
+            region: Optional region filter.
+            providers: Optional list of provider slugs to restrict the result to.
+
+        Raises:
+            ValueError: ``range`` is not supported.
+            NotFoundError: The slug does not exist or has no data for ``range``.
+        """
+        if range not in _SUPPORTED_RANGES:
+            raise ValueError(
+                f"range must be one of {_SUPPORTED_RANGES}, got {range!r}"
+            )
+        params: dict[str, str] = {"range": range}
+        if chain:
+            params["chain"] = chain
+        if region:
+            params["region"] = region
+        if providers:
+            params["providers"] = ",".join(providers)
+        data = self._get(f"/api/series/{slug}", params=params)
+        return Series.from_dict(data)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client (if owned)."""
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "OpenChainBench":
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()
+
+    def _get(self, path: str, *, params: Optional[dict[str, str]] = None) -> Any:
+        try:
+            response = self._client.get(path, params=params)
+        except httpx.HTTPError as exc:
+            raise OpenChainBenchError(f"HTTP request failed: {exc}") from exc
+        _raise_for_status(response)
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise OpenChainBenchError(
+                f"Response was not valid JSON: {exc}"
+            ) from exc

openchainbench-0.1.0/src/openchainbench/exceptions.py

@@ -0,0 +1,41 @@
+"""Exception hierarchy for the OpenChainBench client."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class OpenChainBenchError(Exception):
+    """Base error for every failure surfaced by this client."""
+
+    def __init__(self, message: str, *, status_code: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class NotFoundError(OpenChainBenchError):
+    """Raised when a benchmark slug or range does not exist."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, status_code=404)
+
+
+class RateLimitError(OpenChainBenchError):
+    """Raised when the API returns HTTP 429.
+
+    Attributes:
+        retry_after_sec: Seconds the caller should wait before retrying,
+            parsed from the ``Retry-After`` header or the response body.
+    """
+
+    def __init__(self, message: str, *, retry_after_sec: Optional[int] = None) -> None:
+        super().__init__(message, status_code=429)
+        self.retry_after_sec = retry_after_sec
+
+
+class APIUnavailableError(OpenChainBenchError):
+    """Raised when the API returns HTTP 503 (no live snapshot available)."""
+
+    def __init__(self, message: str, *, retry_after_sec: Optional[int] = None) -> None:
+        super().__init__(message, status_code=503)
+        self.retry_after_sec = retry_after_sec