pyth-pandas 0.1.0__tar.gz

pyth_pandas-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: pyth-pandas
+Version: 0.1.0
+Summary: pandas-style client for the Pyth Pro Router (Pyth Lazer) REST + WebSocket API
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/sigma-quantiphi/pyth-pandas
+Project-URL: Documentation, https://sigma-quantiphi.github.io/pyth-pandas/
+Project-URL: Issues, https://github.com/sigma-quantiphi/pyth-pandas/issues
+Keywords: api-client,pandas,pyth,lazer,oracle,price-feeds
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: cachetools>=5.3
+Requires-Dist: httpx>=0.28
+Requires-Dist: orjson>=3.10
+Requires-Dist: pandas>=2.2
+Requires-Dist: pandera>=0.22
+Requires-Dist: tqdm>=4.66
+Provides-Extra: ws
+Requires-Dist: websocket-client>=1.8; extra == "ws"
+Requires-Dist: websockets>=13.0; extra == "ws"
+Provides-Extra: explorer
+Requires-Dist: streamlit>=1.30; extra == "explorer"
+Requires-Dist: plotly>=5.0; extra == "explorer"
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2.0; extra == "mcp"
+Requires-Dist: tabulate>=0.9; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-httpx>=0.35; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: pandas-stubs>=2.2; extra == "dev"
+Requires-Dist: types-cachetools>=5.3; extra == "dev"
+Requires-Dist: python-dotenv>=1.0; extra == "dev"
+
+# pyth-pandas
+
+> pandas-style client for the Pyth Pro Router (Pyth Lazer) REST + WebSocket API
+
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/sigma-quantiphi/pyth-pandas/HEAD?labpath=examples)
+
+Every list endpoint returns a `pandas.DataFrame`, every dict endpoint returns
+a `TypedDict`, and every shape is enforced by a `pandera` schema. Sync + async,
+plus optional WebSocket, Streamlit explorer, and FastMCP server extras.
+
+This client targets **Pyth Pro Router API v1.0.0** (per the published OpenAPI
+spec). The package version (`0.1.0`) is independent of the upstream API
+version — see the `API_VERSION` / `SUPPORTED_API_VERSIONS` class attributes
+on `PythPandas`.
+
+## Install
+
+```bash
+uv pip install pyth-pandas              # core
+uv pip install "pyth-pandas[ws]"        # + WebSocket
+uv pip install "pyth-pandas[explorer]"  # + Streamlit dashboard
+uv pip install "pyth-pandas[mcp]"       # + FastMCP server
+uv pip install "pyth-pandas[dev]"       # + test/lint toolchain
+```
+
+## Quickstart
+
+```python
+from pyth_pandas import PythPandas
+
+with PythPandas() as client:
+    df = client.fetch_latest_prices(
+        symbols=["Crypto.BTC/USD", "Crypto.ETH/USD"],
+        properties=["price", "confidence", "exponent", "publisherCount"],
+        formats=[],
+    )
+    df["humanPrice"] = df["price"] * 10 ** df["exponent"]
+    print(df[["priceFeedId", "humanPrice", "publisherCount"]])
+```
+
+The DataFrame has one row per feed. The on-chain payloads (when
+requested via `formats=["evm", ...]`) and the update timestamp are
+attached on `df.attrs`. For the raw `JsonUpdate` dict, use
+`fetch_latest_prices_raw(...)`.
+
+### Async
+
+```python
+import asyncio
+from pyth_pandas import AsyncPythPandas
+
+async def main():
+    async with AsyncPythPandas() as client:
+        df = await client.fetch_latest_prices(
+            symbols=["Crypto.BTC/USD"],
+            properties=["price", "exponent"],
+            formats=[],
+        )
+        print(df)
+
+asyncio.run(main())
+```
+
+## Authentication
+
+Pyth Pro requires a bearer access token. Set it via env var (recommended) or
+constructor arg. Copy the shipped `.env.example` to `.env` and fill in your
+key — examples and tests load it via `python-dotenv`:
+
+```bash
+cp .env.example .env
+$EDITOR .env       # set PYTH_API_KEY=...
+```
+
+Or set it in your shell:
+
+```bash
+export PYTH_API_KEY=...
+```
+
+Or pass it directly:
+
+```python
+PythPandas(api_key="...")
+```
+
+## Endpoints
+
+| Method | HTTP | Returns |
+|---|---|---|
+| `fetch_latest_prices(...)` | `POST /v1/latest_price` | `DataFrame[ParsedFeedSchema]` |
+| `fetch_latest_prices_raw(...)` | `POST /v1/latest_price` | `JsonUpdate` (TypedDict) |
+| `fetch_prices(timestamp=..., ...)` | `POST /v1/price` | `DataFrame[ParsedFeedSchema]` |
+| `fetch_prices_raw(...)` | `POST /v1/price` | `JsonUpdate` |
+| `reduce_price(payload=..., price_feed_ids=...)` | `POST /v1/reduce_price` | `DataFrame[ParsedFeedSchema]` |
+| `reduce_price_raw(...)` | `POST /v1/reduce_price` | `JsonUpdate` |
+| `get_guardian_set_upgrade()` | `GET /v1/guardian_set_upgrade` | `SignedGuardianSetUpgrade \| None` |
+
+WebSocket: `PythWebSocket` / `AsyncPythWebSocket` (extra: `ws`) → connects
+to `wss://pyth-lazer.dourolabs.app/v1/stream`.
+
+## Compatibility
+
+| pyth-pandas | Pyth Pro Router API |
+|---|---|
+| 0.1.x | 1.0.0 |
+
+## Error handling
+
+```python
+from pyth_pandas import PythAuthError, PythRateLimitError, PythAPIError
+
+try:
+    df = client.fetch_latest_prices(symbols=["Crypto.BTC/USD"], properties=["price"])
+except PythAuthError:
+    ...  # 401/403 or missing PYTH_API_KEY
+except PythRateLimitError:
+    ...  # 429
+except PythAPIError as e:
+    print(e.status_code, e.url, e.detail)
+```
+
+## Development
+
+```bash
+uv pip install -e ".[dev,ws,explorer,mcp]"
+uv run pytest tests/test_unit.py tests/test_async_unit.py -v
+uv run ruff check pyth_pandas tests
+uv run mypy pyth_pandas
+```
+
+CI runs the same checks on every push and PR via `.github/workflows/ci.yml`
+across Python 3.11, 3.12, 3.13.
+
+## Releasing
+
+Releases are cut by pushing a `v*` tag. `.github/workflows/release.yml`:
+
+1. Runs ruff + mypy + mocked pytest, then **live integration tests** against
+   the real upstream API. If the test job fails, build / publish / release
+   are all skipped.
+2. Builds sdist + wheel via `uv build`.
+3. Publishes to PyPI via [trusted publishing](https://docs.pypi.org/trusted-publishers/).
+4. Creates a GitHub release.
+
+**One-time setup:**
+
+1. Reserve `pyth-pandas` on PyPI.
+2. At <https://pypi.org/manage/account/publishing/>, add a pending publisher:
+   - Project: `pyth-pandas`
+   - Owner: your GitHub user/org
+   - Repo: `pyth-pandas`
+   - Workflow: `release.yml`
+   - Environment: `pypi`
+3. Create the `pypi` environment in GitHub repo settings.
+4. Add `PYTH_API_KEY` as an environment secret on the `pypi` environment so
+   live integration tests can run before publishing.
+5. Enable GitHub Pages with source = "GitHub Actions" so `docs.yml` can
+   deploy the Sphinx site.
+
+**To force a release if the test infra is broken:**
+
+```bash
+gh workflow run release.yml -f tag=v0.1.1 -f skip_tests=true
+```
+
+## License
+
+Apache-2.0

pyth_pandas-0.1.0/README.md

@@ -0,0 +1,169 @@
+# pyth-pandas
+
+> pandas-style client for the Pyth Pro Router (Pyth Lazer) REST + WebSocket API
+
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/sigma-quantiphi/pyth-pandas/HEAD?labpath=examples)
+
+Every list endpoint returns a `pandas.DataFrame`, every dict endpoint returns
+a `TypedDict`, and every shape is enforced by a `pandera` schema. Sync + async,
+plus optional WebSocket, Streamlit explorer, and FastMCP server extras.
+
+This client targets **Pyth Pro Router API v1.0.0** (per the published OpenAPI
+spec). The package version (`0.1.0`) is independent of the upstream API
+version — see the `API_VERSION` / `SUPPORTED_API_VERSIONS` class attributes
+on `PythPandas`.
+
+## Install
+
+```bash
+uv pip install pyth-pandas              # core
+uv pip install "pyth-pandas[ws]"        # + WebSocket
+uv pip install "pyth-pandas[explorer]"  # + Streamlit dashboard
+uv pip install "pyth-pandas[mcp]"       # + FastMCP server
+uv pip install "pyth-pandas[dev]"       # + test/lint toolchain
+```
+
+## Quickstart
+
+```python
+from pyth_pandas import PythPandas
+
+with PythPandas() as client:
+    df = client.fetch_latest_prices(
+        symbols=["Crypto.BTC/USD", "Crypto.ETH/USD"],
+        properties=["price", "confidence", "exponent", "publisherCount"],
+        formats=[],
+    )
+    df["humanPrice"] = df["price"] * 10 ** df["exponent"]
+    print(df[["priceFeedId", "humanPrice", "publisherCount"]])
+```
+
+The DataFrame has one row per feed. The on-chain payloads (when
+requested via `formats=["evm", ...]`) and the update timestamp are
+attached on `df.attrs`. For the raw `JsonUpdate` dict, use
+`fetch_latest_prices_raw(...)`.
+
+### Async
+
+```python
+import asyncio
+from pyth_pandas import AsyncPythPandas
+
+async def main():
+    async with AsyncPythPandas() as client:
+        df = await client.fetch_latest_prices(
+            symbols=["Crypto.BTC/USD"],
+            properties=["price", "exponent"],
+            formats=[],
+        )
+        print(df)
+
+asyncio.run(main())
+```
+
+## Authentication
+
+Pyth Pro requires a bearer access token. Set it via env var (recommended) or
+constructor arg. Copy the shipped `.env.example` to `.env` and fill in your
+key — examples and tests load it via `python-dotenv`:
+
+```bash
+cp .env.example .env
+$EDITOR .env       # set PYTH_API_KEY=...
+```
+
+Or set it in your shell:
+
+```bash
+export PYTH_API_KEY=...
+```
+
+Or pass it directly:
+
+```python
+PythPandas(api_key="...")
+```
+
+## Endpoints
+
+| Method | HTTP | Returns |
+|---|---|---|
+| `fetch_latest_prices(...)` | `POST /v1/latest_price` | `DataFrame[ParsedFeedSchema]` |
+| `fetch_latest_prices_raw(...)` | `POST /v1/latest_price` | `JsonUpdate` (TypedDict) |
+| `fetch_prices(timestamp=..., ...)` | `POST /v1/price` | `DataFrame[ParsedFeedSchema]` |
+| `fetch_prices_raw(...)` | `POST /v1/price` | `JsonUpdate` |
+| `reduce_price(payload=..., price_feed_ids=...)` | `POST /v1/reduce_price` | `DataFrame[ParsedFeedSchema]` |
+| `reduce_price_raw(...)` | `POST /v1/reduce_price` | `JsonUpdate` |
+| `get_guardian_set_upgrade()` | `GET /v1/guardian_set_upgrade` | `SignedGuardianSetUpgrade \| None` |
+
+WebSocket: `PythWebSocket` / `AsyncPythWebSocket` (extra: `ws`) → connects
+to `wss://pyth-lazer.dourolabs.app/v1/stream`.
+
+## Compatibility
+
+| pyth-pandas | Pyth Pro Router API |
+|---|---|
+| 0.1.x | 1.0.0 |
+
+## Error handling
+
+```python
+from pyth_pandas import PythAuthError, PythRateLimitError, PythAPIError
+
+try:
+    df = client.fetch_latest_prices(symbols=["Crypto.BTC/USD"], properties=["price"])
+except PythAuthError:
+    ...  # 401/403 or missing PYTH_API_KEY
+except PythRateLimitError:
+    ...  # 429
+except PythAPIError as e:
+    print(e.status_code, e.url, e.detail)
+```
+
+## Development
+
+```bash
+uv pip install -e ".[dev,ws,explorer,mcp]"
+uv run pytest tests/test_unit.py tests/test_async_unit.py -v
+uv run ruff check pyth_pandas tests
+uv run mypy pyth_pandas
+```
+
+CI runs the same checks on every push and PR via `.github/workflows/ci.yml`
+across Python 3.11, 3.12, 3.13.
+
+## Releasing
+
+Releases are cut by pushing a `v*` tag. `.github/workflows/release.yml`:
+
+1. Runs ruff + mypy + mocked pytest, then **live integration tests** against
+   the real upstream API. If the test job fails, build / publish / release
+   are all skipped.
+2. Builds sdist + wheel via `uv build`.
+3. Publishes to PyPI via [trusted publishing](https://docs.pypi.org/trusted-publishers/).
+4. Creates a GitHub release.
+
+**One-time setup:**
+
+1. Reserve `pyth-pandas` on PyPI.
+2. At <https://pypi.org/manage/account/publishing/>, add a pending publisher:
+   - Project: `pyth-pandas`
+   - Owner: your GitHub user/org
+   - Repo: `pyth-pandas`
+   - Workflow: `release.yml`
+   - Environment: `pypi`
+3. Create the `pypi` environment in GitHub repo settings.
+4. Add `PYTH_API_KEY` as an environment secret on the `pypi` environment so
+   live integration tests can run before publishing.
+5. Enable GitHub Pages with source = "GitHub Actions" so `docs.yml` can
+   deploy the Sphinx site.
+
+**To force a release if the test infra is broken:**
+
+```bash
+gh workflow run release.yml -f tag=v0.1.1 -f skip_tests=true
+```
+
+## License
+
+Apache-2.0

pyth_pandas-0.1.0/explorer/app.py

@@ -0,0 +1,14 @@
+"""CLI entry point for the pyth-pandas Streamlit explorer."""
+
+import os
+import sys
+from pathlib import Path
+
+
+def main() -> None:
+    home = Path(__file__).parent / "home.py"
+    os.execvp("streamlit", ["streamlit", "run", str(home), *sys.argv[1:]])
+
+
+if __name__ == "__main__":
+    main()

pyth_pandas-0.1.0/explorer/home.py

@@ -0,0 +1,30 @@
+"""pyth-pandas explorer — home page."""
+
+import streamlit as st
+
+from pyth_pandas import PythPandas
+
+st.set_page_config(page_title="pyth-pandas explorer", layout="wide")
+
+st.title("pyth-pandas explorer")
+st.caption("Interactive playground for the Pyth Pro Router (Pyth Lazer) API")
+
+with st.sidebar:
+    st.header("Client config")
+    base_url = st.text_input("Base URL", value="https://pyth-lazer.dourolabs.app/v1/")
+    api_key = st.text_input("PYTH_API_KEY", value="", type="password")
+
+if "client" not in st.session_state or st.sidebar.button("Reload client"):
+    st.session_state.client = PythPandas(
+        base_url=base_url, api_key=api_key or None, use_tqdm=False
+    )
+
+st.markdown(
+    """
+    Pick an endpoint from the sidebar pages on the left.
+
+    - **Latest prices** — point-in-time snapshot per feed
+    - **Historical price** — feed values at a specific timestamp
+    - **Guardian set upgrade** — Wormhole governance status
+    """
+)

pyth_pandas-0.1.0/explorer/pages/1_latest_prices.py

@@ -0,0 +1,46 @@
+"""Latest prices explorer page."""
+
+import streamlit as st
+
+st.title("Latest prices")
+
+client = st.session_state.get("client")
+if client is None:
+    st.warning("Configure the client on the home page first.")
+    st.stop()
+
+symbols_text = st.text_input(
+    "Symbols (comma-separated)", value="Crypto.BTC/USD, Crypto.ETH/USD"
+)
+symbols = [s.strip() for s in symbols_text.split(",") if s.strip()] or None
+
+properties = st.multiselect(
+    "Properties",
+    [
+        "price",
+        "confidence",
+        "exponent",
+        "publisherCount",
+        "bestBidPrice",
+        "bestAskPrice",
+        "emaPrice",
+        "emaConfidence",
+        "fundingRate",
+        "feedUpdateTimestamp",
+    ],
+    default=["price", "confidence", "exponent", "publisherCount"],
+)
+channel = st.selectbox(
+    "Channel",
+    ["real_time", "fixed_rate@50ms", "fixed_rate@200ms", "fixed_rate@1000ms"],
+)
+
+if st.button("Fetch"):
+    with st.spinner("Fetching..."):
+        df = client.fetch_latest_prices(
+            symbols=symbols,
+            properties=properties,
+            channel=channel,
+        )
+    st.dataframe(df, use_container_width=True)
+    st.write("attrs:", df.attrs)

pyth_pandas-0.1.0/explorer/pages/2_guardian_set_upgrade.py

@@ -0,0 +1,18 @@
+"""Guardian set upgrade status page."""
+
+import streamlit as st
+
+st.title("Guardian set upgrade")
+
+client = st.session_state.get("client")
+if client is None:
+    st.warning("Configure the client on the home page first.")
+    st.stop()
+
+if st.button("Check"):
+    with st.spinner("Fetching..."):
+        result = client.get_guardian_set_upgrade()
+    if result is None:
+        st.success("No guardian set upgrade is currently in progress.")
+    else:
+        st.json(result)

pyth_pandas-0.1.0/pyproject.toml

@@ -0,0 +1,89 @@
+[project]
+name = "pyth-pandas"
+version = "0.1.0"
+description = "pandas-style client for the Pyth Pro Router (Pyth Lazer) REST + WebSocket API"
+readme = "README.md"
+requires-python = ">=3.11,<3.14"
+license = "Apache-2.0"
+keywords = ["api-client", "pandas", "pyth", "lazer", "oracle", "price-feeds"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "cachetools>=5.3",
+    "httpx>=0.28",
+    "orjson>=3.10",
+    "pandas>=2.2",
+    "pandera>=0.22",
+    "tqdm>=4.66",
+]
+
+[project.optional-dependencies]
+ws = [
+    "websocket-client>=1.8",
+    "websockets>=13.0",
+]
+explorer = [
+    "streamlit>=1.30",
+    "plotly>=5.0",
+]
+mcp = [
+    "fastmcp>=2.0",
+    "tabulate>=0.9",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-httpx>=0.35",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.9",
+    "mypy>=1.11",
+    "pandas-stubs>=2.2",
+    "types-cachetools>=5.3",
+    "python-dotenv>=1.0",
+]
+
+[project.scripts]
+pyth-pandas-explore = "explorer.app:main"
+pyth-pandas-mcp = "pyth_pandas.mcp_server:main"
+
+[project.urls]
+Homepage = "https://github.com/sigma-quantiphi/pyth-pandas"
+Documentation = "https://sigma-quantiphi.github.io/pyth-pandas/"
+Issues = "https://github.com/sigma-quantiphi/pyth-pandas/issues"
+
+[build-system]
+requires = ["setuptools>=70"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["pyth_pandas*", "explorer*"]
+
+[tool.setuptools.package-data]
+pyth_pandas = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v"
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["B008"]
+
+[tool.mypy]
+python_version = "3.11"
+ignore_missing_imports = true
+warn_return_any = false
+warn_unused_ignores = true

pyth_pandas-0.1.0/pyth_pandas/__init__.py

@@ -0,0 +1,37 @@
+"""pyth-pandas — pandas-style client for the Pyth Pro Router (Pyth Lazer) API."""
+
+from __future__ import annotations
+
+from pyth_pandas.async_client import AsyncPythPandas
+from pyth_pandas.client import PythPandas
+from pyth_pandas.exceptions import (
+    PythAPIError,
+    PythAuthError,
+    PythError,
+    PythRateLimitError,
+)
+from pyth_pandas.schemas import ParsedFeedSchema
+from pyth_pandas.types import (
+    JsonBinaryData,
+    JsonUpdate,
+    ParsedFeedPayload,
+    ParsedPayload,
+    SignedGuardianSetUpgrade,
+    SignedMerkleRoot,
+)
+
+__all__ = [
+    "AsyncPythPandas",
+    "JsonBinaryData",
+    "JsonUpdate",
+    "ParsedFeedPayload",
+    "ParsedFeedSchema",
+    "ParsedPayload",
+    "PythAPIError",
+    "PythAuthError",
+    "PythError",
+    "PythPandas",
+    "PythRateLimitError",
+    "SignedGuardianSetUpgrade",
+    "SignedMerkleRoot",
+]