bitculator 1.0.0__tar.gz

bitculator-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.venv/

bitculator-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bitculator
+
+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.

bitculator-1.0.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: bitculator
+Version: 1.0.0
+Summary: Official Python SDK for the Bitculator Data API
+Project-URL: Documentation, https://bitculator.com/en/documentation/api/v1
+Project-URL: Repository, https://github.com/bitculator/bitculator-python-sdk
+Author: Bitculator
+License: MIT
+License-File: LICENSE
+Keywords: api,bitculator,crypto,cryptocurrency,market-data,sdk
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Bitculator Data API — Python SDK
+
+[bitculator.com](https://bitculator.com) · [API documentation](https://bitculator.com/en/documentation/api/v1) · [Get an API key](https://bitculator.com/user/developer/api)
+[PyPI — `bitculator`](https://pypi.org/project/bitculator/) · [GitHub](https://github.com/Bitculator/bitculator-python-sdk)
+
+The official Python SDK for the [Bitculator Data API](https://bitculator.com).
+Zero dependencies (standard-library only), typed, works on Python 3.9+.
+
+> Keep your API key server-side. It is a Bearer token with the `data-api` ability
+> and is not meant for client-side embedding.
+
+## Install
+
+```bash
+pip install bitculator
+```
+
+## Quick start
+
+```python
+import os
+from bitculator import Bitculator
+
+client = Bitculator(os.environ["BITCULATOR_API_KEY"])
+
+# Single resource — the {"data": ...} envelope is unwrapped for you.
+bitcoin = client.coins.get("bitcoin")
+print(bitcoin["price"])   # "63520.780763913" — a decimal string, never rounded
+
+# A paginated list.
+page = client.coins.list(per_page=50, sort="-marketcap")
+print(page.data, page.meta["total"])
+```
+
+## Prices are decimal strings
+
+Prices, rates, and supplies come back as **strings** (e.g. `"63520.780763913"`)
+to preserve full precision. Use `decimal.Decimal` if you need to do math — do
+**not** pass them through `float()`, which silently loses precision.
+
+## Pagination
+
+Every paginated method returns a `Page`. Read one page, or iterate to walk them all:
+
+```python
+# One page at a time.
+page = client.exchanges.list(per_page=100)
+while page is not None:
+    for exchange in page.data:
+        print(exchange["name"])
+    page = page.next_page()
+
+# Or auto-paginate across every page (iterating a Page walks all pages).
+for coin in client.coins.list(sort="-marketcap"):
+    print(coin["symbol"])
+```
+
+## Errors
+
+Every failure derives from `BitculatorError`; HTTP failures raise a status-specific
+subclass carrying the `{"error": {"code", "message", "details"}}` envelope.
+
+```python
+from bitculator import ValidationError, RateLimitError, APIError
+
+try:
+    client.coins.list(per_page=9999)  # over the plan cap -> 422
+except ValidationError as err:
+    print(err.code, err.details)
+except RateLimitError as err:
+    print("retry after", err.retry_after)
+except APIError as err:
+    print(err.status, err.message)
+```
+
+| Status | Exception |
+| ------ | --------- |
+| 401 | `AuthenticationError` |
+| 403 | `PermissionDeniedError` (plan does not include this endpoint) |
+| 404 | `NotFoundError` |
+| 422 | `ValidationError` (`.details` holds the field errors) |
+| 429 | `RateLimitError` (`.retry_after`) |
+| 5xx | `ServerError` |
+
+Timeouts raise `APITimeoutError`; network failures raise `APIConnectionError`.
+
+## Quota
+
+Every response carries `X-Quota-*` headers, surfaced on the client after each call:
+
+```python
+client.coins.list()
+print(client.quota)   # Quota(limit=..., remaining=..., reset=..., raw={...})
+```
+
+## Configuration
+
+```python
+Bitculator(
+    api_key,                          # required (positional)
+    base_url="https://bitculator.com",  # default
+    timeout=30.0,                     # seconds, default
+    max_retries=2,                    # auto-retry 429 / 5xx / network; 0 to disable
+)
+```
+
+## Passing parameters
+
+Query parameters are keyword arguments and mirror the API's names exactly
+(`per_page`, `min_price`, ...). For the reserved word `from` (in `convert`), pass
+`from_` — the SDK maps it back to `from` on the wire:
+
+```python
+client.conversion.convert(from_="btc", to="usd", amount=1)
+```
+
+## Resources
+
+`coins` · `prices` · `markets` · `exchanges` · `wallets` · `global_market` ·
+`sentiment` · `indicators` · `liquidations` · `conversion` · `calculators` ·
+`editorial` · `alarms` · `webhooks` · `meta`
+
+Full endpoint reference: <https://bitculator.com/en/documentation/api/v1>.
+
+## License
+
+MIT

bitculator-1.0.0/README.md

@@ -0,0 +1,127 @@
+# Bitculator Data API — Python SDK
+
+[bitculator.com](https://bitculator.com) · [API documentation](https://bitculator.com/en/documentation/api/v1) · [Get an API key](https://bitculator.com/user/developer/api)
+[PyPI — `bitculator`](https://pypi.org/project/bitculator/) · [GitHub](https://github.com/Bitculator/bitculator-python-sdk)
+
+The official Python SDK for the [Bitculator Data API](https://bitculator.com).
+Zero dependencies (standard-library only), typed, works on Python 3.9+.
+
+> Keep your API key server-side. It is a Bearer token with the `data-api` ability
+> and is not meant for client-side embedding.
+
+## Install
+
+```bash
+pip install bitculator
+```
+
+## Quick start
+
+```python
+import os
+from bitculator import Bitculator
+
+client = Bitculator(os.environ["BITCULATOR_API_KEY"])
+
+# Single resource — the {"data": ...} envelope is unwrapped for you.
+bitcoin = client.coins.get("bitcoin")
+print(bitcoin["price"])   # "63520.780763913" — a decimal string, never rounded
+
+# A paginated list.
+page = client.coins.list(per_page=50, sort="-marketcap")
+print(page.data, page.meta["total"])
+```
+
+## Prices are decimal strings
+
+Prices, rates, and supplies come back as **strings** (e.g. `"63520.780763913"`)
+to preserve full precision. Use `decimal.Decimal` if you need to do math — do
+**not** pass them through `float()`, which silently loses precision.
+
+## Pagination
+
+Every paginated method returns a `Page`. Read one page, or iterate to walk them all:
+
+```python
+# One page at a time.
+page = client.exchanges.list(per_page=100)
+while page is not None:
+    for exchange in page.data:
+        print(exchange["name"])
+    page = page.next_page()
+
+# Or auto-paginate across every page (iterating a Page walks all pages).
+for coin in client.coins.list(sort="-marketcap"):
+    print(coin["symbol"])
+```
+
+## Errors
+
+Every failure derives from `BitculatorError`; HTTP failures raise a status-specific
+subclass carrying the `{"error": {"code", "message", "details"}}` envelope.
+
+```python
+from bitculator import ValidationError, RateLimitError, APIError
+
+try:
+    client.coins.list(per_page=9999)  # over the plan cap -> 422
+except ValidationError as err:
+    print(err.code, err.details)
+except RateLimitError as err:
+    print("retry after", err.retry_after)
+except APIError as err:
+    print(err.status, err.message)
+```
+
+| Status | Exception |
+| ------ | --------- |
+| 401 | `AuthenticationError` |
+| 403 | `PermissionDeniedError` (plan does not include this endpoint) |
+| 404 | `NotFoundError` |
+| 422 | `ValidationError` (`.details` holds the field errors) |
+| 429 | `RateLimitError` (`.retry_after`) |
+| 5xx | `ServerError` |
+
+Timeouts raise `APITimeoutError`; network failures raise `APIConnectionError`.
+
+## Quota
+
+Every response carries `X-Quota-*` headers, surfaced on the client after each call:
+
+```python
+client.coins.list()
+print(client.quota)   # Quota(limit=..., remaining=..., reset=..., raw={...})
+```
+
+## Configuration
+
+```python
+Bitculator(
+    api_key,                          # required (positional)
+    base_url="https://bitculator.com",  # default
+    timeout=30.0,                     # seconds, default
+    max_retries=2,                    # auto-retry 429 / 5xx / network; 0 to disable
+)
+```
+
+## Passing parameters
+
+Query parameters are keyword arguments and mirror the API's names exactly
+(`per_page`, `min_price`, ...). For the reserved word `from` (in `convert`), pass
+`from_` — the SDK maps it back to `from` on the wire:
+
+```python
+client.conversion.convert(from_="btc", to="usd", amount=1)
+```
+
+## Resources
+
+`coins` · `prices` · `markets` · `exchanges` · `wallets` · `global_market` ·
+`sentiment` · `indicators` · `liquidations` · `conversion` · `calculators` ·
+`editorial` · `alarms` · `webhooks` · `meta`
+
+Full endpoint reference: <https://bitculator.com/en/documentation/api/v1>.
+
+## License
+
+MIT

bitculator-1.0.0/examples/quickstart.py

@@ -0,0 +1,43 @@
+"""
+Run with: BITCULATOR_API_KEY=... python examples/quickstart.py
+(against local dev, add BITCULATOR_BASE_URL=http://localhost)
+"""
+
+import os
+
+from bitculator import APIError, Bitculator
+
+client = Bitculator(
+    os.environ.get("BITCULATOR_API_KEY", ""),
+    base_url=os.environ.get("BITCULATOR_BASE_URL", "https://bitculator.com"),
+)
+
+
+def main() -> None:
+    client.meta.ping()
+
+    # Single resource — the {"data": ...} envelope is unwrapped for you.
+    bitcoin = client.coins.get("bitcoin")
+    print("BTC price:", bitcoin["price"])  # "63520.780763913" — a decimal string, never rounded
+
+    # Top 5 coins by marketcap.
+    top = client.coins.list(per_page=5, sort="-marketcap")
+    for coin in top.data:
+        print(f"#{coin['rank']}", coin["symbol"], coin["price"])
+
+    # Auto-paginate the first ~40 gainers.
+    for i, coin in enumerate(client.coins.gainers(per_page=20)):
+        print("gainer:", coin["symbol"], coin["change_24h"])
+        if i >= 39:
+            break
+
+    # A technical indicator.
+    print("RSI(14):", client.indicators.rsi("bitcoin", period=14))
+    print("quota:", client.quota)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except APIError as err:
+        print(f"API {err.status}: {err.code} {err.message}")

bitculator-1.0.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bitculator"
+dynamic = ["version"]
+description = "Official Python SDK for the Bitculator Data API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Bitculator" }]
+keywords = ["bitculator", "crypto", "cryptocurrency", "market-data", "api", "sdk"]
+dependencies = []
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Office/Business :: Financial",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Documentation = "https://bitculator.com/en/documentation/api/v1"
+Repository = "https://github.com/bitculator/bitculator-python-sdk"
+
+[tool.hatch.version]
+path = "src/bitculator/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bitculator"]

bitculator-1.0.0/src/bitculator/__init__.py

@@ -0,0 +1,37 @@
+"""Official Python SDK for the Bitculator Data API."""
+
+from ._http import Quota
+from ._version import __version__
+from .client import Bitculator
+from .errors import (
+    APIConnectionError,
+    APIDecodeError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    BitculatorError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .pagination import Page
+
+__all__ = [
+    "Bitculator",
+    "Page",
+    "Quota",
+    "BitculatorError",
+    "APIError",
+    "APITimeoutError",
+    "APIConnectionError",
+    "APIDecodeError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    "__version__",
+]

bitculator-1.0.0/src/bitculator/_http.py

@@ -0,0 +1,214 @@
+"""
+The DRY transport core. Every request in the SDK flows through
+``HttpClient._request``: URL + query building, auth headers, JSON
+(de)serialization, the response envelope, quota capture, retries with backoff,
+timeouts, and error mapping all live here — nowhere else. Uses only the standard
+library (``urllib``) so the SDK has zero runtime dependencies.
+"""
+
+from __future__ import annotations
+
+import decimal
+import http.client
+import json
+import random
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Callable, Optional
+
+from .errors import APIConnectionError, APIDecodeError, APIError, APITimeoutError, BitculatorError
+from .pagination import Page
+
+
+@dataclass
+class Quota:
+    """Quota headers (``X-Quota-*``) from the most recent response."""
+
+    limit: Optional[int]
+    remaining: Optional[int]
+    reset: Optional[int]
+    raw: dict
+
+
+class HttpClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        timeout: float,
+        max_retries: int,
+        user_agent: str,
+        on_quota: Callable[[Quota], None],
+        opener: Optional[urllib.request.OpenerDirector] = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._user_agent = user_agent
+        self._on_quota = on_quota
+        self._opener = opener or urllib.request.build_opener()
+
+    def get(self, path: str, params: Optional[dict] = None) -> Any:
+        return _unwrap(self._request("GET", path, params=params))
+
+    def post(self, path: str, body: Any = None, params: Optional[dict] = None) -> Any:
+        return _unwrap(self._request("POST", path, params=params, body=body))
+
+    def delete(self, path: str, params: Optional[dict] = None) -> Any:
+        return _unwrap(self._request("DELETE", path, params=params))
+
+    def get_page(self, path: str, params: Optional[dict] = None) -> Page:
+        envelope = self._request("GET", path, params=params)
+        return Page(self, path, params or {}, envelope)
+
+    def _request(self, method: str, path: str, params: Optional[dict] = None, body: Any = None) -> Any:
+        url = self._base_url + path + _query(params)
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": self._user_agent,
+        }
+        data: Optional[bytes] = None
+        if body is not None:
+            try:
+                data = json.dumps(_snake_keys(body)).encode("utf-8")
+            except (TypeError, ValueError) as exc:
+                raise BitculatorError(f"Failed to encode request body: {exc}") from exc
+            headers["Content-Type"] = "application/json"
+
+        # Idempotency gate: GET/DELETE are safe to auto-retry; POST is NOT, so a
+        # POST the server may already have processed is never re-sent on a 5xx or
+        # a network/timeout error. A 429 means the server rejected it before
+        # processing, so it stays retryable for every method.
+        is_idempotent = method in ("GET", "DELETE")
+
+        attempt = 0
+        while True:
+            request = urllib.request.Request(url, data=data, headers=headers, method=method)
+            try:
+                with self._opener.open(request, timeout=self._timeout) as response:
+                    self._on_quota(_parse_quota(response.headers))
+                    raw = response.read()
+                    if not raw:
+                        return None
+                    try:
+                        return json.loads(raw)
+                    except (ValueError, TypeError) as exc:
+                        raise APIDecodeError(f"Failed to decode response from {path}: {exc}") from exc
+            except urllib.error.HTTPError as exc:
+                self._on_quota(_parse_quota(exc.headers))
+                raw = exc.read()
+                payload = _safe_json(raw)
+                status = exc.code
+                retryable = status == 429 or (status >= 500 and is_idempotent)
+                if retryable and attempt < self._max_retries:
+                    time.sleep(_retry_delay(exc.headers, attempt))
+                    attempt += 1
+                    continue
+                raise APIError.from_response(status, payload, exc.headers) from None
+            except (urllib.error.URLError, http.client.HTTPException, TimeoutError, OSError) as exc:
+                if is_idempotent and attempt < self._max_retries:
+                    time.sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                reason = getattr(exc, "reason", exc)
+                if isinstance(reason, TimeoutError) or "timed out" in str(reason).lower():
+                    raise APITimeoutError(f"Request to {path} timed out after {self._timeout}s") from exc
+                raise APIConnectionError(f"Network error requesting {path}: {reason}") from exc
+
+
+# ── helpers (all pure; the single place these concerns are implemented) ──────
+
+
+def _unwrap(envelope: Any) -> Any:
+    """Unwrap the ``{"data": ...}`` envelope; pass through bodies with no data key."""
+    if isinstance(envelope, dict) and "data" in envelope:
+        return envelope["data"]
+    return envelope
+
+
+def _query(params: Optional[dict]) -> str:
+    """Serialize params: drop ``None``, lists→CSV, bools→true/false, trailing ``_`` stripped (``from_``→``from``)."""
+    if not params:
+        return ""
+    pairs = []
+    for key, value in params.items():
+        if value is None:
+            continue
+        name = key[:-1] if key.endswith("_") else key
+        if isinstance(value, (list, tuple)):
+            if not value:
+                continue
+            pairs.append((name, ",".join(str(item) for item in value)))
+        elif isinstance(value, bool):
+            pairs.append((name, "true" if value else "false"))
+        elif isinstance(value, float):
+            # Plain-decimal form (0.0000001, not 1e-07) — keeps the wire format
+            # identical across the SDK family.
+            pairs.append((name, format(decimal.Decimal(repr(value)), "f")))
+        else:
+            pairs.append((name, str(value)))
+    return "?" + urllib.parse.urlencode(pairs) if pairs else ""
+
+
+def _snake_keys(body: Any) -> Any:
+    """Strip a trailing underscore from body keys (``from_``→``from``); leave the rest as-is."""
+    if not isinstance(body, dict):
+        return body
+    return {(key[:-1] if key.endswith("_") else key): value for key, value in body.items()}
+
+
+def _parse_quota(headers: Any) -> Quota:
+    raw = {}
+    if headers is not None:
+        for key, value in headers.items():
+            lowered = key.lower()
+            if lowered.startswith("x-quota-"):
+                raw[lowered] = value
+
+    def num(name: str) -> Optional[int]:
+        value = raw.get(name)
+        if value in (None, ""):
+            return None
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return None
+
+    return Quota(
+        limit=num("x-quota-limit"),
+        remaining=num("x-quota-remaining"),
+        reset=num("x-quota-reset"),
+        raw=raw,
+    )
+
+
+def _retry_delay(headers: Any, attempt: int) -> float:
+    retry_after = headers.get("retry-after") if headers is not None else None
+    try:
+        seconds = int(retry_after)
+        if seconds > 0:
+            # Cap at 60s: a misbehaving proxy must not block a synchronous call for an hour.
+            return float(min(seconds, 60))
+    except (TypeError, ValueError):
+        pass
+    return _backoff(attempt)
+
+
+def _backoff(attempt: int) -> float:
+    """Exponential backoff with jitter, capped at 8s."""
+    return min(8.0, 0.25 * (2 ** attempt)) + random.uniform(0.0, 0.1)
+
+
+def _safe_json(raw: bytes) -> Any:
+    if not raw:
+        return None
+    try:
+        return json.loads(raw)
+    except (ValueError, TypeError):
+        return None

bitculator-1.0.0/src/bitculator/_version.py

@@ -0,0 +1,3 @@
+"""SDK version, sent in the User-Agent header. Single source of truth — pyproject.toml reads it via [tool.hatch.version]."""
+
+__version__ = "1.0.0"