visor-python 0.1.0__py3-none-any.whl

visor/_pagination.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, Generator
+from typing import Protocol
+
+from visor.models.dealers import DealerFilter, DealersPage, DealerSummary
+from visor.models.listings import ListingsFilter, ListingsPage, ListingSummary
+
+
+class _AsyncVisorClientProto(Protocol):
+    async def filter_listings(
+        self, filter: ListingsFilter | None = None
+    ) -> ListingsPage: ...
+
+    async def search_dealers(
+        self, filter: DealerFilter | None = None
+    ) -> DealersPage: ...
+
+
+class _SyncVisorClientProto(Protocol):
+    def filter_listings(self, filter: ListingsFilter | None = None) -> ListingsPage: ...
+
+    def search_dealers(self, filter: DealerFilter | None = None) -> DealersPage: ...
+
+
+async def paginate_listings(
+    client: _AsyncVisorClientProto,
+    filter: ListingsFilter | None = None,
+    *,
+    max_pages: int | None = None,
+) -> AsyncGenerator[ListingSummary, None]:
+    if max_pages is not None and max_pages <= 0:
+        return
+    current = filter if filter is not None else ListingsFilter()
+    pages_fetched = 0
+    while True:
+        page = await client.filter_listings(current)
+        for item in page.data:
+            yield item
+        pages_fetched += 1
+        if max_pages is not None and pages_fetched >= max_pages:
+            break
+        if page.pagination.next_offset is None:
+            break
+        current = current.model_copy(update={"offset": page.pagination.next_offset})
+
+
+async def paginate_dealers(
+    client: _AsyncVisorClientProto,
+    filter: DealerFilter | None = None,
+    *,
+    max_pages: int | None = None,
+) -> AsyncGenerator[DealerSummary, None]:
+    if max_pages is not None and max_pages <= 0:
+        return
+    current = filter if filter is not None else DealerFilter()
+    pages_fetched = 0
+    while True:
+        page = await client.search_dealers(current)
+        for item in page.data:
+            yield item
+        pages_fetched += 1
+        if max_pages is not None and pages_fetched >= max_pages:
+            break
+        if page.pagination.next_offset is None:
+            break
+        current = current.model_copy(update={"offset": page.pagination.next_offset})
+
+
+def iter_listings(
+    client: _SyncVisorClientProto,
+    filter: ListingsFilter | None = None,
+    *,
+    max_pages: int | None = None,
+) -> Generator[ListingSummary, None, None]:
+    if max_pages is not None and max_pages <= 0:
+        return
+    current = filter if filter is not None else ListingsFilter()
+    pages_fetched = 0
+    while True:
+        page = client.filter_listings(current)
+        yield from page.data
+        pages_fetched += 1
+        if max_pages is not None and pages_fetched >= max_pages:
+            break
+        if page.pagination.next_offset is None:
+            break
+        current = current.model_copy(update={"offset": page.pagination.next_offset})
+
+
+def iter_dealers(
+    client: _SyncVisorClientProto,
+    filter: DealerFilter | None = None,
+    *,
+    max_pages: int | None = None,
+) -> Generator[DealerSummary, None, None]:
+    if max_pages is not None and max_pages <= 0:
+        return
+    current = filter if filter is not None else DealerFilter()
+    pages_fetched = 0
+    while True:
+        page = client.search_dealers(current)
+        yield from page.data
+        pages_fetched += 1
+        if max_pages is not None and pages_fetched >= max_pages:
+            break
+        if page.pagination.next_offset is None:
+            break
+        current = current.model_copy(update={"offset": page.pagination.next_offset})

visor/_transport.py

@@ -0,0 +1,130 @@
+from datetime import datetime
+from email.utils import parsedate_to_datetime
+from typing import Any
+
+import httpx
+
+from visor.exceptions import (
+    AuthError,
+    ForbiddenError,
+    NotFoundError,
+    PaymentRequiredError,
+    RateLimitError,
+    ValidationError,
+    VisorAPIError,
+    VisorTransportError,
+)
+
+DEFAULT_BASE_URL = "https://api.visor.vin/v1"
+
+
+def _parse_retry_after(value: str | None) -> int | None:
+    if not value:
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        try:
+            retry_at = parsedate_to_datetime(value)
+        except (TypeError, ValueError):
+            return None
+        return max(0, int((retry_at - datetime.now(retry_at.tzinfo)).total_seconds()))
+
+
+def _handle_response(response: httpx.Response) -> dict[str, Any]:
+    if response.is_success:
+        try:
+            data: Any = response.json()
+        except ValueError as e:
+            raise VisorTransportError(f"Received malformed JSON from API: {e}") from e
+        if not isinstance(data, dict):
+            raise VisorTransportError("Received non-object JSON from API")
+        return data
+
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+
+    error: object = body.get("error") if isinstance(body, dict) else None
+    if isinstance(error, dict):
+        error_code = error.get("code", "unknown_error") or "unknown_error"
+        message = error.get("message", response.text) or response.text
+    else:
+        error_code = "unknown_error"
+        message = response.text
+
+    match response.status_code:
+        case 400:
+            raise ValidationError(400, error_code, message)
+        case 401:
+            raise AuthError(
+                401,
+                error_code,
+                message or "Invalid or missing API key. Check VISOR_API_KEY.",
+            )
+        case 402:
+            raise PaymentRequiredError(402, error_code, message)
+        case 403:
+            raise ForbiddenError(
+                403,
+                error_code,
+                message or "Access denied. Key lacks permission for this resource.",
+            )
+        case 404:
+            raise NotFoundError(404, error_code, message)
+        case 429:
+            retry_after = _parse_retry_after(response.headers.get("Retry-After"))
+            raise RateLimitError(429, error_code, message, retry_after=retry_after)
+        case _:
+            raise VisorAPIError(response.status_code, error_code, message)
+
+
+class AsyncVisorTransport:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+        )
+
+    async def get(
+        self, path: str, params: dict[str, str] | None = None
+    ) -> dict[str, Any]:
+        try:
+            response = await self._client.get(path, params=params or {})
+        except httpx.RequestError as e:
+            raise VisorTransportError(f"Request failed: {e}") from e
+        return _handle_response(response)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+
+class SyncVisorTransport:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+        )
+
+    def get(self, path: str, params: dict[str, str] | None = None) -> dict[str, Any]:
+        try:
+            response = self._client.get(path, params=params or {})
+        except httpx.RequestError as e:
+            raise VisorTransportError(f"Request failed: {e}") from e
+        return _handle_response(response)
+
+    def close(self) -> None:
+        self._client.close()

visor/exceptions.py

@@ -0,0 +1,72 @@
+class VisorError(Exception):
+    """Base exception for all visor-python errors."""
+
+
+class VisorAPIError(VisorError):
+    """Raised when the API returns a 4xx or 5xx response."""
+
+    def __init__(self, status_code: int, error_code: str, message: str) -> None:
+        self.status_code = status_code
+        self.error_code = error_code
+        self.message = message
+        super().__init__(f"[{status_code}] {error_code}: {message}")
+
+
+class AuthError(VisorAPIError):
+    """HTTP 401 — the request was not authenticated.
+
+    Raised when the API key is missing, malformed, or invalid. Check that
+    ``VISOR_API_KEY`` is set to a valid key, or pass ``api_key`` explicitly
+    when constructing the client.
+    """
+
+
+class ForbiddenError(VisorAPIError):
+    """HTTP 403 — the request was authenticated but not authorized.
+
+    Raised when a valid API key does not have permission to access the
+    requested resource or perform the requested action. Contact Visor support
+    if you believe you should have access.
+    """
+
+
+class NotFoundError(VisorAPIError):
+    """404 — resource not found."""
+
+
+class ValidationError(VisorAPIError):
+    """400 — unknown_query_parameter or validation_error."""
+
+
+class PaymentRequiredError(VisorAPIError):
+    """402 — quota exceeded / payment required."""
+
+
+class RateLimitError(VisorAPIError):
+    """HTTP 429 — the API rate limit has been exceeded.
+
+    Attributes:
+        retry_after: Number of seconds to wait before retrying, or ``None``
+            if the API did not include a usable ``Retry-After`` header. When
+            present the value is derived from an integer seconds value or an
+            HTTP-date header, whichever the API provides. Build your retry
+            loop around this value:
+
+                except RateLimitError as e:
+                    wait = e.retry_after if e.retry_after is not None else 2 ** attempt
+                    time.sleep(wait)
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        error_code: str,
+        message: str,
+        retry_after: int | None = None,
+    ) -> None:
+        self.retry_after = retry_after
+        super().__init__(status_code, error_code, message)
+
+
+class VisorTransportError(VisorError):
+    """Raised on network-level failures (timeout, connection refused)."""

visor/models/__init__.py

@@ -0,0 +1,82 @@
+from visor.models._base import (
+    BBox,
+    DealerRef,
+    InventoryMode,
+    Pagination,
+    PriceHistoryEntry,
+    SortOrder,
+    VehicleBuild,
+    VehicleOption,
+    VehicleRecord,
+    VisorRequestModel,
+    VisorResponseModel,
+)
+from visor.models.dealers import (
+    DealerAddress,
+    DealerDetail,
+    DealerFilter,
+    DealersPage,
+    DealerSummary,
+)
+from visor.models.facets import (
+    FacetBucket,
+    FacetsData,
+    FacetsFilter,
+    FacetsMeta,
+    FacetsResponse,
+    FieldStats,
+    RangeBucket,
+    RangeFacet,
+)
+from visor.models.listings import (
+    ListingDetail,
+    ListingsFilter,
+    ListingSnapshot,
+    ListingsPage,
+    ListingSummary,
+)
+from visor.models.usage import UsageMeta, UsageRecord, UsageSummary, UsageTotals
+from visor.models.vins import VinDetail
+
+__all__ = [
+    # base
+    "BBox",
+    "DealerRef",
+    "InventoryMode",
+    "Pagination",
+    "PriceHistoryEntry",
+    "SortOrder",
+    "VehicleBuild",
+    "VehicleOption",
+    "VehicleRecord",
+    "VisorRequestModel",
+    "VisorResponseModel",
+    # dealers
+    "DealerAddress",
+    "DealerDetail",
+    "DealerFilter",
+    "DealersPage",
+    "DealerSummary",
+    # facets
+    "FacetBucket",
+    "FacetsData",
+    "FacetsMeta",
+    "FacetsFilter",
+    "FacetsResponse",
+    "FieldStats",
+    "RangeBucket",
+    "RangeFacet",
+    # listings
+    "ListingDetail",
+    "ListingsFilter",
+    "ListingsPage",
+    "ListingSnapshot",
+    "ListingSummary",
+    # usage
+    "UsageMeta",
+    "UsageRecord",
+    "UsageSummary",
+    "UsageTotals",
+    # vins
+    "VinDetail",
+]