gunspec 0.1.0__py3-none-any.whl

gunspec/__init__.py

@@ -0,0 +1,57 @@
+"""GunSpec.io Python SDK."""
+
+from __future__ import annotations
+
+from gunspec._client import AsyncGunSpec, GunSpec
+from gunspec._core._errors import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConnectError,
+    GunSpecError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    RequestTimeoutError,
+)
+from gunspec._core._http_client import (
+    APIResponse,
+    HttpClientConfig,
+    PaginatedResponse,
+    PaginationMeta,
+    RateLimitInfo,
+)
+from gunspec._core._pagination import AsyncPage, SyncPage
+from gunspec._core._retry import RetryConfig
+from gunspec._version import __version__
+
+__all__ = [
+    # Client
+    "GunSpec",
+    "AsyncGunSpec",
+    # Version
+    "__version__",
+    # Config
+    "HttpClientConfig",
+    "RetryConfig",
+    # Response types
+    "APIResponse",
+    "PaginatedResponse",
+    "PaginationMeta",
+    "RateLimitInfo",
+    # Pagination
+    "SyncPage",
+    "AsyncPage",
+    # Errors
+    "GunSpecError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "BadRequestError",
+    "RateLimitError",
+    "InternalServerError",
+    "ConnectError",
+    "RequestTimeoutError",
+]

gunspec/_client.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from ._core._http_client import (
+    AsyncHttpClient,
+    HttpClientConfig,
+    SyncHttpClient,
+)
+from ._core._retry import RetryConfig
+from ._resources import (
+    Ammunition,
+    AsyncAmmunition,
+    AsyncCalibers,
+    AsyncCategories,
+    AsyncConflicts,
+    AsyncCountries,
+    AsyncDataQuality,
+    AsyncFavorites,
+    AsyncFirearms,
+    AsyncGame,
+    AsyncGameStats_,
+    AsyncManufacturers,
+    AsyncReports,
+    AsyncStats,
+    AsyncSupport,
+    AsyncUsage,
+    AsyncWebhooks,
+    Calibers,
+    Categories,
+    Conflicts,
+    Countries,
+    DataQuality,
+    Favorites,
+    Firearms,
+    Game,
+    GameStats_,
+    Manufacturers,
+    Reports,
+    Stats,
+    Support,
+    Usage,
+    Webhooks,
+)
+from ._version import __version__
+
+
+class GunSpec:
+    """Synchronous GunSpec.io API client.
+
+    Example::
+
+        from gunspec import GunSpec
+
+        client = GunSpec(api_key="gs_...")
+
+        # List firearms
+        result = client.firearms.list({"category": "pistol"})
+        for firearm in result.data:
+            print(firearm)
+
+        # Context manager for clean shutdown
+        with GunSpec() as client:
+            data = client.firearms.get("glock-g17")
+    """
+
+    firearms: Firearms
+    manufacturers: Manufacturers
+    calibers: Calibers
+    categories: Categories
+    stats: Stats
+    game: Game
+    game_stats: GameStats_
+    ammunition: Ammunition
+    countries: Countries
+    conflicts: Conflicts
+    data_quality: DataQuality
+    favorites: Favorites
+    reports: Reports
+    support: Support
+    webhooks: Webhooks
+    usage: Usage
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+        retry: Optional[RetryConfig] = None,
+        default_headers: Optional[dict[str, str]] = None,
+    ) -> None:
+        config = HttpClientConfig(
+            base_url=base_url or "https://api.gunspec.io",
+            timeout=timeout or 30.0,
+            api_key=api_key,
+            retry=retry or RetryConfig(),
+            headers={
+                **(default_headers or {}),
+                "User-Agent": f"gunspec-sdk/python/{__version__}",
+                "X-SDK-Version": __version__,
+                "X-SDK-Language": "python",
+            },
+        )
+        self._client = SyncHttpClient(config)
+
+        self.firearms = Firearms(self._client)
+        self.manufacturers = Manufacturers(self._client)
+        self.calibers = Calibers(self._client)
+        self.categories = Categories(self._client)
+        self.stats = Stats(self._client)
+        self.game = Game(self._client)
+        self.game_stats = GameStats_(self._client)
+        self.ammunition = Ammunition(self._client)
+        self.countries = Countries(self._client)
+        self.conflicts = Conflicts(self._client)
+        self.data_quality = DataQuality(self._client)
+        self.favorites = Favorites(self._client)
+        self.reports = Reports(self._client)
+        self.support = Support(self._client)
+        self.webhooks = Webhooks(self._client)
+        self.usage = Usage(self._client)
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._client.close()
+
+    def __enter__(self) -> GunSpec:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+class AsyncGunSpec:
+    """Asynchronous GunSpec.io API client.
+
+    Example::
+
+        from gunspec import AsyncGunSpec
+
+        async with AsyncGunSpec(api_key="gs_...") as client:
+            result = await client.firearms.list({"category": "rifle"})
+            for firearm in result.data:
+                print(firearm)
+    """
+
+    firearms: AsyncFirearms
+    manufacturers: AsyncManufacturers
+    calibers: AsyncCalibers
+    categories: AsyncCategories
+    stats: AsyncStats
+    game: AsyncGame
+    game_stats: AsyncGameStats_
+    ammunition: AsyncAmmunition
+    countries: AsyncCountries
+    conflicts: AsyncConflicts
+    data_quality: AsyncDataQuality
+    favorites: AsyncFavorites
+    reports: AsyncReports
+    support: AsyncSupport
+    webhooks: AsyncWebhooks
+    usage: AsyncUsage
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+        retry: Optional[RetryConfig] = None,
+        default_headers: Optional[dict[str, str]] = None,
+    ) -> None:
+        config = HttpClientConfig(
+            base_url=base_url or "https://api.gunspec.io",
+            timeout=timeout or 30.0,
+            api_key=api_key,
+            retry=retry or RetryConfig(),
+            headers={
+                **(default_headers or {}),
+                "User-Agent": f"gunspec-sdk/python/{__version__}",
+                "X-SDK-Version": __version__,
+                "X-SDK-Language": "python",
+            },
+        )
+        self._client = AsyncHttpClient(config)
+
+        self.firearms = AsyncFirearms(self._client)
+        self.manufacturers = AsyncManufacturers(self._client)
+        self.calibers = AsyncCalibers(self._client)
+        self.categories = AsyncCategories(self._client)
+        self.stats = AsyncStats(self._client)
+        self.game = AsyncGame(self._client)
+        self.game_stats = AsyncGameStats_(self._client)
+        self.ammunition = AsyncAmmunition(self._client)
+        self.countries = AsyncCountries(self._client)
+        self.conflicts = AsyncConflicts(self._client)
+        self.data_quality = AsyncDataQuality(self._client)
+        self.favorites = AsyncFavorites(self._client)
+        self.reports = AsyncReports(self._client)
+        self.support = AsyncSupport(self._client)
+        self.webhooks = AsyncWebhooks(self._client)
+        self.usage = AsyncUsage(self._client)
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncGunSpec:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()

gunspec/_core/__init__.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from ._auth import build_auth_headers, resolve_api_key
+from ._errors import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConnectError,
+    GunSpecError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    RequestTimeoutError,
+    create_api_error,
+)
+from ._http_client import (
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    SDK_USER_AGENT,
+    APIResponse,
+    AsyncHttpClient,
+    HttpClientConfig,
+    PaginatedResponse,
+    PaginationMeta,
+    RateLimitInfo,
+    SyncHttpClient,
+    serialize_query,
+)
+from ._pagination import AsyncPage, SyncPage
+from ._retry import RetryConfig, async_with_retry, compute_delay, is_retryable, with_retry
+
+__all__ = [
+    # Errors
+    "GunSpecError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "BadRequestError",
+    "RateLimitError",
+    "InternalServerError",
+    "ConnectError",
+    "RequestTimeoutError",
+    "create_api_error",
+    # Auth
+    "resolve_api_key",
+    "build_auth_headers",
+    # HTTP client
+    "SyncHttpClient",
+    "AsyncHttpClient",
+    "HttpClientConfig",
+    "APIResponse",
+    "PaginatedResponse",
+    "PaginationMeta",
+    "RateLimitInfo",
+    "serialize_query",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TIMEOUT",
+    "SDK_USER_AGENT",
+    # Pagination
+    "SyncPage",
+    "AsyncPage",
+    # Retry
+    "RetryConfig",
+    "is_retryable",
+    "compute_delay",
+    "with_retry",
+    "async_with_retry",
+]

gunspec/_core/_auth.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import os
+from typing import Dict, Optional
+
+
+def resolve_api_key(api_key: Optional[str] = None) -> Optional[str]:
+    """Resolve the API key from the explicit parameter or GUNSPEC_API_KEY env var.
+
+    Resolution order:
+    1. Explicit ``api_key`` parameter.
+    2. ``GUNSPEC_API_KEY`` environment variable.
+    3. ``None`` (anonymous / unauthenticated).
+    """
+    if api_key is not None and api_key != "":
+        return api_key
+    return os.environ.get("GUNSPEC_API_KEY") or None
+
+
+def build_auth_headers(api_key: Optional[str] = None) -> Dict[str, str]:
+    """Build the authentication headers for a request.
+
+    Returns ``{"X-API-Key": key}`` when a key is available, or an empty dict
+    for anonymous mode.
+    """
+    if api_key is not None and api_key != "":
+        return {"X-API-Key": api_key}
+    return {}

gunspec/_core/_errors.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+import math
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+
+class GunSpecError(Exception):
+    """Base error class for every error raised by the GunSpec SDK."""
+
+
+class APIError(GunSpecError):
+    """An error returned by the GunSpec API with an HTTP status code."""
+
+    status: int
+    code: str
+    message: str
+    request_id: str
+    headers: Dict[str, str]
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        request_id: str,
+        headers: Dict[str, str],
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        self.headers = headers
+
+
+class AuthenticationError(APIError):
+    """Raised when the API returns 401 Unauthorized."""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        request_id: str,
+        headers: Dict[str, str],
+    ) -> None:
+        super().__init__(401, code, message, request_id, headers)
+
+
+class PermissionDeniedError(APIError):
+    """Raised when the API returns 403 Forbidden."""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        request_id: str,
+        headers: Dict[str, str],
+    ) -> None:
+        super().__init__(403, code, message, request_id, headers)
+
+
+class NotFoundError(APIError):
+    """Raised when the API returns 404 Not Found."""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        request_id: str,
+        headers: Dict[str, str],
+    ) -> None:
+        super().__init__(404, code, message, request_id, headers)
+
+
+class BadRequestError(APIError):
+    """Raised when the API returns 400 Bad Request."""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        request_id: str,
+        headers: Dict[str, str],
+    ) -> None:
+        super().__init__(400, code, message, request_id, headers)
+
+
+class RateLimitError(APIError):
+    """Raised when the API returns 429 Too Many Requests."""
+
+    retry_after: Optional[float]
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        request_id: str,
+        headers: Dict[str, str],
+        retry_after: Optional[float],
+    ) -> None:
+        super().__init__(429, code, message, request_id, headers)
+        self.retry_after = retry_after
+
+
+class InternalServerError(APIError):
+    """Raised when the API returns 500 Internal Server Error."""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        request_id: str,
+        headers: Dict[str, str],
+    ) -> None:
+        super().__init__(500, code, message, request_id, headers)
+
+
+class ConnectError(GunSpecError):
+    """Raised on network-level failures (DNS, connection reset, etc.)."""
+
+    cause: Optional[BaseException]
+
+    def __init__(self, message: str, cause: Optional[BaseException] = None) -> None:
+        super().__init__(message)
+        self.cause = cause
+
+
+class RequestTimeoutError(GunSpecError):
+    """Raised when a request exceeds the configured timeout."""
+
+    timeout_s: float
+
+    def __init__(self, timeout_s: float) -> None:
+        super().__init__(f"Request timed out after {timeout_s}s")
+        self.timeout_s = timeout_s
+
+
+def _parse_retry_after(headers: Dict[str, str]) -> Optional[float]:
+    """Parse the Retry-After header value into seconds."""
+    raw = headers.get("Retry-After") or headers.get("retry-after")
+    if raw is None:
+        return None
+
+    # Try delta-seconds first.
+    try:
+        seconds = float(raw)
+        if not math.isnan(seconds) and seconds >= 0:
+            return seconds
+    except ValueError:
+        pass
+
+    # Fall back to HTTP-date.
+    try:
+        dt = datetime.strptime(raw, "%a, %d %b %Y %H:%M:%S %Z")
+        dt = dt.replace(tzinfo=timezone.utc)
+        delta = (dt - datetime.now(timezone.utc)).total_seconds()
+        return max(delta, 0.0)
+    except ValueError:
+        pass
+
+    return None
+
+
+def create_api_error(
+    status: int,
+    body: Optional[Dict[str, Any]],
+    request_id: str,
+    headers: Dict[str, str],
+) -> APIError:
+    """Create the appropriate APIError subclass for the given HTTP status."""
+    error_data = body.get("error", {}) if body else {}
+    code: str = error_data.get("code", f"HTTP_{status}")
+    message: str = error_data.get("message", f"Request failed with status {status}")
+
+    if status == 400:
+        return BadRequestError(code, message, request_id, headers)
+    if status == 401:
+        return AuthenticationError(code, message, request_id, headers)
+    if status == 403:
+        return PermissionDeniedError(code, message, request_id, headers)
+    if status == 404:
+        return NotFoundError(code, message, request_id, headers)
+    if status == 429:
+        return RateLimitError(
+            code, message, request_id, headers, _parse_retry_after(headers)
+        )
+    if status == 500:
+        return InternalServerError(code, message, request_id, headers)
+    return APIError(status, code, message, request_id, headers)