goldprice-dev 0.1.0__tar.gz

goldprice_dev-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 — 2026-10-09
+
+- Synchronous and asynchronous clients for precious metal prices.
+- Spot prices, history, conversion, bars, ratios, and account usage.
+- Exact decimals, typed errors, bounded retries, and response metadata.
+- Bar and ratio pagination iterators, with page metadata exposed as `meta_`.

goldprice_dev-0.1.0/LICENSE

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

goldprice_dev-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.5
+Name: goldprice-dev
+Version: 0.1.0
+Summary: Typed clients for the goldprice.dev API
+Project-URL: Homepage, https://goldprice.dev/docs
+Author-email: "Nusantara Ventures, LLC" <hello@goldprice.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,commodities,decimal,gold,precious-metals,sdk,silver
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Description-Content-Type: text/markdown
+
+# Goldprice for Python
+
+Python clients for precious metal prices from goldprice.dev. Read spot prices,
+price history, bars, ratios, and account usage. Conversion methods cover amounts
+and carat values. The package provides synchronous and asynchronous access.
+
+## Install
+
+Requires Python 3.10 or newer.
+
+```sh
+pip install goldprice-dev
+```
+
+## Quickstart
+
+Set `GOLDPRICE_API_KEY` in your environment, then run:
+
+```python
+from goldprice_dev import Goldprice
+
+with Goldprice() as client:
+    spot = client.prices.spot("XAU-USD-SPOT")
+    print(spot.price)
+    print(spot.meta.request_id)
+```
+
+The context manager closes the client. `AsyncGoldprice` provides asynchronous
+access. Supply `api_key=` to configure a key explicitly. The default base URL
+is `https://api.goldprice.dev`; override it with `GOLDPRICE_BASE_URL`.
+
+Use `prices.list()` for price listings and `prices.history(...)` for a symbol's
+history. `bars.latest(symbol=...)` and `ratios.latest(pair=...)` return the latest
+bar or ratio. `account.usage()` reads account usage. History queries accept
+`from_` and `to` keyword arguments.
+
+## Decimals
+
+Prices and other decimal values use exact `decimal.Decimal` objects, never
+floats. Pass conversion amounts as strings to preserve decimal input.
+
+Every response carries `meta` with `request_id` and rate-limit values from
+headers. Bar and ratio pages expose the wire field named `meta` as `meta_`.
+Use `meta_` for page data and `meta` for response information.
+
+## Errors and retries
+
+`errors.Unauthorized`, `errors.RateLimited`, `errors.NotFound`, and
+`errors.BadRequest` extend `errors.ApiError`. API errors expose `status`, `code`,
+`detail`, and `request_id`. `errors.RateLimited` also carries `retry_after`.
+All client errors derive from `errors.GoldpriceError`. Import `errors` from
+`goldprice_dev` when handling these exceptions.
+
+Requests retry up to twice by default for short-window rate limits and temporary
+unavailability. Quota exhaustion is not retried.
+
+## Pagination iterators
+
+Use `bars.list_iter(...)` and `ratios.list_iter(...)` to consume items across
+pages. Use `for` with `Goldprice` and `async for` with `AsyncGoldprice`.
+The corresponding `list(...)` methods return a single page.
+
+Links: [Documentation](https://goldprice.dev/docs)
+
+MIT licensed

goldprice_dev-0.1.0/README.md

@@ -0,0 +1,65 @@
+# Goldprice for Python
+
+Python clients for precious metal prices from goldprice.dev. Read spot prices,
+price history, bars, ratios, and account usage. Conversion methods cover amounts
+and carat values. The package provides synchronous and asynchronous access.
+
+## Install
+
+Requires Python 3.10 or newer.
+
+```sh
+pip install goldprice-dev
+```
+
+## Quickstart
+
+Set `GOLDPRICE_API_KEY` in your environment, then run:
+
+```python
+from goldprice_dev import Goldprice
+
+with Goldprice() as client:
+    spot = client.prices.spot("XAU-USD-SPOT")
+    print(spot.price)
+    print(spot.meta.request_id)
+```
+
+The context manager closes the client. `AsyncGoldprice` provides asynchronous
+access. Supply `api_key=` to configure a key explicitly. The default base URL
+is `https://api.goldprice.dev`; override it with `GOLDPRICE_BASE_URL`.
+
+Use `prices.list()` for price listings and `prices.history(...)` for a symbol's
+history. `bars.latest(symbol=...)` and `ratios.latest(pair=...)` return the latest
+bar or ratio. `account.usage()` reads account usage. History queries accept
+`from_` and `to` keyword arguments.
+
+## Decimals
+
+Prices and other decimal values use exact `decimal.Decimal` objects, never
+floats. Pass conversion amounts as strings to preserve decimal input.
+
+Every response carries `meta` with `request_id` and rate-limit values from
+headers. Bar and ratio pages expose the wire field named `meta` as `meta_`.
+Use `meta_` for page data and `meta` for response information.
+
+## Errors and retries
+
+`errors.Unauthorized`, `errors.RateLimited`, `errors.NotFound`, and
+`errors.BadRequest` extend `errors.ApiError`. API errors expose `status`, `code`,
+`detail`, and `request_id`. `errors.RateLimited` also carries `retry_after`.
+All client errors derive from `errors.GoldpriceError`. Import `errors` from
+`goldprice_dev` when handling these exceptions.
+
+Requests retry up to twice by default for short-window rate limits and temporary
+unavailability. Quota exhaustion is not retried.
+
+## Pagination iterators
+
+Use `bars.list_iter(...)` and `ratios.list_iter(...)` to consume items across
+pages. Use `for` with `Goldprice` and `async for` with `AsyncGoldprice`.
+The corresponding `list(...)` methods return a single page.
+
+Links: [Documentation](https://goldprice.dev/docs)
+
+MIT licensed

goldprice_dev-0.1.0/hatch_build.py

@@ -0,0 +1,14 @@
+"""Keep repository ignore files out of the source distribution."""
+
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version, build_data):
+        if self.target_name == "sdist":
+            forced = build_data["force_include"]
+            for path in list(forced):
+                if Path(path).name in {".gitignore", ".hgignore"}:
+                    del forced[path]

goldprice_dev-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "goldprice-dev"
+version = "0.1.0"
+description = "Typed clients for the goldprice.dev API"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Nusantara Ventures, LLC", email = "hello@goldprice.dev" }]
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["httpx>=0.27,<1"]
+keywords = ["api", "sdk", "gold", "silver", "precious-metals", "commodities", "decimal"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+    "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",
+    "Programming Language :: Python :: 3.14",
+    "License :: OSI Approved :: MIT License",
+]
+
+[project.urls]
+Homepage = "https://goldprice.dev/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/goldprice_dev"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/goldprice_dev", "README.md", "CHANGELOG.md", "LICENSE", "pyproject.toml"]
+
+[tool.hatch.build.hooks.custom]

goldprice_dev-0.1.0/src/goldprice_dev/__init__.py

@@ -0,0 +1,16 @@
+"""Typed clients for the goldprice.dev API."""
+
+from . import errors, models
+from ._client import AsyncGoldprice, Goldprice
+from ._meta import RateLimit, ResponseMeta
+from ._version import __version__
+
+__all__ = [
+    "AsyncGoldprice",
+    "Goldprice",
+    "RateLimit",
+    "ResponseMeta",
+    "__version__",
+    "errors",
+    "models",
+]

goldprice_dev-0.1.0/src/goldprice_dev/_client.py

@@ -0,0 +1,122 @@
+"""Connection-owning synchronous and asynchronous clients."""
+
+import asyncio
+import random
+import time
+from collections.abc import Awaitable, Callable, Mapping
+from types import TracebackType
+from typing import TypeVar
+
+import httpx
+
+from ._generated.operations import (
+    LIVE_SPEC_SHA,
+    AsyncStableOperations,
+    StableOperations,
+)
+from ._transport import AsyncTransport, Settings, SyncTransport
+
+SyncClient = TypeVar("SyncClient", bound="Goldprice")
+AsyncClient = TypeVar("AsyncClient", bound="AsyncGoldprice")
+
+
+class Goldprice(StableOperations):
+    """Share one client across threads and close it when finished."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        proxy: str | None = None,
+        timeout: float = 30,
+        max_retries: int = 2,
+        max_retry_wait: float = 30,
+        extra_headers: Mapping[str, str] | None = None,
+        transport: httpx.BaseTransport | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+        clock: Callable[[], float] = time.monotonic,
+        random_fraction: Callable[[], float] = random.random,
+    ) -> None:
+        settings = Settings(
+            api_key=api_key,
+            base_url=base_url,
+            proxy=proxy,
+            timeout=timeout,
+            max_retries=max_retries,
+            max_retry_wait=max_retry_wait,
+            extra_headers=extra_headers,
+            clock=clock,
+            random_fraction=random_fraction,
+            spec_sha=LIVE_SPEC_SHA,
+        )
+        self._transport = SyncTransport(settings, transport=transport, sleep=sleep)
+        super().__init__(self._transport)
+
+    def __repr__(self) -> str:
+        return "Goldprice(api_key=<redacted>)"
+
+    def close(self) -> None:
+        self._transport.http.close()
+
+    def __enter__(self: SyncClient) -> SyncClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncGoldprice(AsyncStableOperations):
+    """Use one client per event loop and close it with async with."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        proxy: str | None = None,
+        timeout: float = 30,
+        max_retries: int = 2,
+        max_retry_wait: float = 30,
+        extra_headers: Mapping[str, str] | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+        sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+        clock: Callable[[], float] = time.monotonic,
+        random_fraction: Callable[[], float] = random.random,
+    ) -> None:
+        settings = Settings(
+            api_key=api_key,
+            base_url=base_url,
+            proxy=proxy,
+            timeout=timeout,
+            max_retries=max_retries,
+            max_retry_wait=max_retry_wait,
+            extra_headers=extra_headers,
+            clock=clock,
+            random_fraction=random_fraction,
+            spec_sha=LIVE_SPEC_SHA,
+        )
+        self._transport = AsyncTransport(settings, transport=transport, sleep=sleep)
+        super().__init__(self._transport)
+
+    def __repr__(self) -> str:
+        return "AsyncGoldprice(api_key=<redacted>)"
+
+    async def aclose(self) -> None:
+        await self._transport.http.aclose()
+
+    async def __aenter__(self: AsyncClient) -> AsyncClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()

goldprice_dev-0.1.0/src/goldprice_dev/_deadline.py

@@ -0,0 +1,180 @@
+"""Per-attempt synchronous I/O deadlines, without threads or event loops."""
+
+from collections.abc import Callable, Iterable
+from contextvars import ContextVar
+from ssl import SSLContext
+from typing import Protocol, cast
+
+import httpx
+
+RESPONSE_STARTED = "goldprice_dev.response_started"
+SocketOption = tuple[int, int, int | bytes] | tuple[int, int, None, int]
+
+
+class Deadline:
+    def __init__(self, timeout: float, clock: Callable[[], float]) -> None:
+        self.clock = clock
+        self.expires = clock() + timeout
+
+    def remaining(self) -> float:
+        return max(0.0, self.expires - self.clock())
+
+
+active_deadline: ContextVar[Deadline | None] = ContextVar(
+    "goldprice_dev_deadline", default=None
+)
+
+
+def io_timeout(timeout: float | None) -> float | None:
+    deadline = active_deadline.get()
+    if deadline is None:
+        return timeout
+    remaining = deadline.remaining()
+    if remaining <= 0:
+        raise httpx.ReadTimeout("Attempt deadline exceeded")
+    return remaining if timeout is None else min(timeout, remaining)
+
+
+class NetworkStream(Protocol):
+    def read(self, max_bytes: int, timeout: float | None = None) -> bytes: ...
+    def write(self, buffer: bytes, timeout: float | None = None) -> None: ...
+    def close(self) -> None: ...
+    def start_tls(
+        self,
+        ssl_context: SSLContext,
+        server_hostname: str | None = None,
+        timeout: float | None = None,
+    ) -> "NetworkStream": ...
+    def get_extra_info(self, info: str) -> object: ...
+
+
+class NetworkBackend(Protocol):
+    def connect_tcp(
+        self,
+        host: str,
+        port: int,
+        timeout: float | None = None,
+        local_address: str | None = None,
+        socket_options: Iterable[SocketOption] | None = None,
+    ) -> NetworkStream: ...
+    def connect_unix_socket(
+        self,
+        path: str,
+        timeout: float | None = None,
+        socket_options: Iterable[SocketOption] | None = None,
+    ) -> NetworkStream: ...
+    def sleep(self, seconds: float) -> None: ...
+
+
+class _Stream:
+    def __init__(self, inner: NetworkStream) -> None:
+        self.inner = inner
+
+    def read(self, max_bytes: int, timeout: float | None = None) -> bytes:
+        return self.inner.read(max_bytes, timeout=io_timeout(timeout))
+
+    def write(self, buffer: bytes, timeout: float | None = None) -> None:
+        self.inner.write(buffer, timeout=io_timeout(timeout))
+
+    def close(self) -> None:
+        self.inner.close()
+
+    def start_tls(
+        self,
+        ssl_context: SSLContext,
+        server_hostname: str | None = None,
+        timeout: float | None = None,
+    ) -> "_Stream":
+        return _Stream(
+            self.inner.start_tls(
+                ssl_context,
+                server_hostname=server_hostname,
+                timeout=io_timeout(timeout),
+            )
+        )
+
+    def get_extra_info(self, info: str) -> object:
+        return self.inner.get_extra_info(info)
+
+
+class _Backend:
+    def __init__(self, inner: NetworkBackend) -> None:
+        self.inner = inner
+
+    def connect_tcp(
+        self,
+        host: str,
+        port: int,
+        timeout: float | None = None,
+        local_address: str | None = None,
+        socket_options: Iterable[SocketOption] | None = None,
+    ) -> NetworkStream:
+        return _Stream(
+            self.inner.connect_tcp(
+                host,
+                port,
+                timeout=io_timeout(timeout),
+                local_address=local_address,
+                socket_options=socket_options,
+            )
+        )
+
+    def connect_unix_socket(
+        self,
+        path: str,
+        timeout: float | None = None,
+        socket_options: Iterable[SocketOption] | None = None,
+    ) -> NetworkStream:
+        return _Stream(
+            self.inner.connect_unix_socket(
+                path, timeout=io_timeout(timeout), socket_options=socket_options
+            )
+        )
+
+    def sleep(self, seconds: float) -> None:
+        self.inner.sleep(seconds)
+
+
+class _Pool(Protocol):
+    _network_backend: NetworkBackend
+
+
+class _ClientTransports(Protocol):
+    _transport: httpx.BaseTransport
+    _mounts: dict[object, httpx.BaseTransport | None]
+
+
+def install_deadlines(client: httpx.Client) -> None:
+    """Adapt native pools, including environment and explicit proxy pools.
+
+    This is the sole boundary using transport internals. The underlying HTTP codec
+    caches the body timeout, so mutating the request timeout between chunks alone
+    does not bound slow responses. Native-codec tests verify this adapter against
+    the locked dependency. Injected transports can read request timeout extensions.
+    """
+    transports = cast(_ClientTransports, client)
+    for transport in (transports._transport, *transports._mounts.values()):
+        if isinstance(transport, httpx.HTTPTransport):
+            pool = cast(_Pool, transport._pool)
+            if not isinstance(pool._network_backend, _Backend):
+                pool._network_backend = _Backend(pool._network_backend)
+
+
+def read_response(
+    response: httpx.Response, request: httpx.Request, deadline: Deadline
+) -> httpx.Response:
+    if response.is_stream_consumed:
+        return response
+    timeouts = cast(dict[str, float | None], request.extensions["timeout"])
+    chunks = []
+    for chunk in response.iter_raw():
+        chunks.append(chunk)
+        # Do not raise after a received chunk: it may be the last one. A next
+        # network read is where expiry becomes a transport failure.
+        timeouts["read"] = deadline.remaining()
+    return httpx.Response(
+        response.status_code,
+        headers=response.headers,
+        content=b"".join(chunks),
+        request=request,
+    )

goldprice_dev-0.1.0/src/goldprice_dev/_decode.py

@@ -0,0 +1,67 @@
+"""Strict wire primitives used by generated decoders."""
+
+import json
+import re
+from decimal import Decimal
+from typing import cast
+
+
+def read_object(value: object) -> dict[str, object]:
+    if not isinstance(value, dict) or any(not isinstance(k, str) for k in value):
+        raise ValueError("expected an object")
+    return cast(dict[str, object], value)
+
+
+def read_list(value: object) -> list[object]:
+    if not isinstance(value, list):
+        raise TypeError("expected an array")
+    return cast(list[object], value)
+
+
+def read_str(value: object) -> str:
+    if not isinstance(value, str):
+        raise TypeError("expected a string")
+    return value
+
+
+def read_int(value: object) -> int:
+    if type(value) is not int:
+        raise ValueError("expected an integer")
+    return value
+
+
+def read_bool(value: object) -> bool:
+    if not isinstance(value, bool):
+        raise TypeError("expected a boolean")
+    return value
+
+
+def read_decimal(value: object) -> Decimal:
+    text = read_str(value)
+    if re.fullmatch(r"-?\d+(\.\d+)?", text, re.ASCII) is None:
+        raise ValueError("expected a decimal wire string")
+    return Decimal(text)
+
+
+def read_decimal_number(value: object) -> Decimal:
+    """A decimal sent as a JSON number; `read_json` keeps its literal as a Decimal."""
+    if isinstance(value, bool) or not isinstance(value, (int, Decimal)):
+        raise TypeError("expected a JSON number")
+    if isinstance(value, Decimal) and not value.is_finite():
+        raise ValueError("expected a finite JSON number")
+    return Decimal(value)
+
+
+def reject_number(value: str) -> object:
+    raise ValueError("unexpected non-finite JSON number")
+
+
+def read_json(raw: bytes) -> object:
+    return json.loads(raw, parse_float=Decimal, parse_constant=reject_number)
+
+
+def read_cursor(value: object) -> str:
+    cursor = read_str(value)
+    if not cursor:
+        raise ValueError("next_cursor must not be empty")
+    return cursor

goldprice_dev-0.1.0/src/goldprice_dev/_generated/__init__.py

@@ -0,0 +1,2 @@
+# Generated from spec/goldprice/live/openapi.json sha256 7483e916b388f8b1a6b5c5689b0180ad8914fec2e5f28a0ffdaf041075039f65. Do not edit.
+"""Generated contract surface."""