blitz-api-py 0.1.0__py3-none-any.whl

blitz_api/_exceptions.py

@@ -0,0 +1,113 @@
+"""Exception hierarchy raised by the Blitz API SDK.
+
+::
+
+    BlitzError
+    ├── APIConnectionError        # request never completed (network / timeout)
+    │   └── APITimeoutError
+    ├── APIResponseValidationError  # a 2xx body was not valid JSON / not the expected shape
+    └── APIStatusError            # a non-2xx HTTP response was received
+        ├── AuthenticationError       # 401
+        ├── InsufficientCreditsError  # 402
+        ├── NotFoundError             # 404
+        ├── RateLimitError            # 429 (after retries are exhausted)
+        └── ServerError               # 5xx (after retries are exhausted)
+
+Catch :class:`BlitzError` to handle anything this SDK raises.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import httpx
+
+
+class BlitzError(Exception):
+    """Base class for every error raised by this SDK."""
+
+
+class APIConnectionError(BlitzError):
+    """The request could not be completed (connection error, DNS, etc.)."""
+
+    def __init__(
+        self, message: str = "Connection error.", *, request: httpx.Request | None = None
+    ) -> None:
+        super().__init__(message)
+        self.request = request
+
+
+class APITimeoutError(APIConnectionError):
+    """The request timed out."""
+
+    def __init__(self, *, request: httpx.Request | None = None) -> None:
+        super().__init__("Request timed out.", request=request)
+
+
+class APIResponseValidationError(BlitzError):
+    """A 2xx response body could not be parsed into the expected model.
+
+    Raised when the server returns success but the body is not valid JSON (e.g. an
+    HTML error page from a proxy, or an empty body) or does not match the response
+    model. This keeps a successful-status surprise inside the :class:`BlitzError`
+    hierarchy instead of leaking a raw ``json``/``pydantic`` error.
+
+    Attributes:
+        response: The underlying :class:`httpx.Response`.
+        status_code: The HTTP status code (a 2xx).
+        request_id: The value of the ``x-request-id`` response header, if any.
+    """
+
+    def __init__(self, message: str, *, response: httpx.Response) -> None:
+        super().__init__(message)
+        self.message = message
+        self.response = response
+        self.status_code = response.status_code
+        self.request_id = response.headers.get("x-request-id")
+
+
+class APIStatusError(BlitzError):
+    """The API returned a non-success HTTP status code.
+
+    Attributes:
+        status_code: The HTTP status code of the response.
+        body: The parsed JSON body, or the raw text if it was not JSON.
+        message: A human-readable message extracted from the body when present.
+        request_id: The value of the ``x-request-id`` response header, if any.
+        response: The underlying :class:`httpx.Response`.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        response: httpx.Response,
+        body: Any | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.response = response
+        self.status_code = response.status_code
+        self.body = body
+        self.request_id = response.headers.get("x-request-id")
+
+
+class AuthenticationError(APIStatusError):
+    """401 — the API key is missing or invalid."""
+
+
+class InsufficientCreditsError(APIStatusError):
+    """402 — the key is valid but the account is out of credits."""
+
+
+class NotFoundError(APIStatusError):
+    """404 — the API key or resource does not exist."""
+
+
+class RateLimitError(APIStatusError):
+    """429 — too many requests (raised only after retries are exhausted)."""
+
+
+class ServerError(APIStatusError):
+    """5xx — the API failed (raised only after retries are exhausted)."""

blitz_api/_pagination_async.py

@@ -0,0 +1,128 @@
+"""Auto-paginating page objects (async source).
+
+The sync versions in ``_pagination_sync.py`` are generated from this file by
+``scripts/gen_sync.py`` (it strips ``async``/``await`` and renames the ``Async*`` /
+``AsyncIterator`` / ``__aiter__`` tokens). Edit this file, then run the generator.
+
+``search.people``/``search.companies`` return the cursor-based page class and
+``search.employee_finder`` the page-number-based one. Both auto-paginate over every item
+when iterated (``for``/``async for``), and also expose ``.auto_paging_iter()``,
+``.iter_pages()``, and ``.get_next_page()``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any, Generic, TypeVar, cast
+
+from typing_extensions import Self
+
+from ._pagination_base import BasePage
+
+ItemT = TypeVar("ItemT")
+
+
+class AsyncPaginator(BasePage, Generic[ItemT]):
+    """Mixes auto-pagination over items/pages onto a concrete page model."""
+
+    results: list[ItemT] = []
+
+    # ``__iter__`` (the generated sync twin of this) intentionally overrides
+    # ``BaseModel.__iter__`` to yield items instead of (field, value) pairs.
+    def __aiter__(self) -> AsyncIterator[ItemT]:  # type: ignore[override]
+        return self._auto_paging_items()
+
+    async def _auto_paging_items(self, max_items: int | None = None) -> AsyncIterator[ItemT]:
+        page = self
+        emitted = 0
+        while True:
+            for item in page.results:
+                yield item
+                emitted += 1
+                if max_items is not None and emitted >= max_items:
+                    return
+            if not page.has_next_page():
+                return
+            page = await page._fetch_next()
+
+    def auto_paging_iter(self, *, max_items: int | None = None) -> AsyncIterator[ItemT]:
+        """Iterate every item across all pages, optionally stopping after ``max_items``."""
+        return self._auto_paging_items(max_items)
+
+    async def iter_pages(self, *, max_pages: int | None = None) -> AsyncIterator[Self]:
+        """Iterate page objects across the result set, optionally capped at ``max_pages``."""
+        page = self
+        seen = 0
+        while True:
+            yield page
+            seen += 1
+            if max_pages is not None and seen >= max_pages:
+                return
+            if not page.has_next_page():
+                return
+            page = await page._fetch_next()
+
+    async def get_next_page(self) -> Self | None:
+        """Fetch the next page, or ``None`` if this is the last one."""
+        if not self.has_next_page():
+            return None
+        return await self._fetch_next()
+
+    async def _fetch_next(self) -> Self:
+        return cast(
+            "Self",
+            await self._client._request(
+                self._method,
+                self._path,
+                body=self._next_body(),
+                cast_to=type(self),
+                timeout=self._timeout,
+            ),
+        )
+
+
+class AsyncCursorPage(AsyncPaginator[ItemT], Generic[ItemT]):
+    """Cursor-paginated page (``search.people`` / ``search.companies``)."""
+
+    total_results: int | None = None
+    results_length: int | None = None
+    max_results: int | None = None
+    cursor: str | None = None
+
+    def has_next_page(self) -> bool:
+        # The API terminates the walk by returning ``cursor=null`` on the last page, so a
+        # non-null cursor is the single source of truth. We deliberately do NOT also gate
+        # on ``results`` being non-empty: a sparse intermediate page (empty results but a
+        # valid forward cursor) must keep paging, not silently truncate the result set.
+        return bool(self.cursor)
+
+    def _next_body(self) -> dict[str, Any]:
+        return {**self._body, "cursor": self.cursor}
+
+
+class AsyncPageNumberPage(AsyncPaginator[ItemT], Generic[ItemT]):
+    """Page-number-paginated page (``search.employee_finder``)."""
+
+    company_linkedin_url: str | None = None
+    max_results: int | None = None
+    results_length: int | None = None
+    page: int | None = None
+    total_pages: int | None = None
+
+    def _current_page(self) -> int:
+        # Prefer the page the server echoed; fall back to the page we requested
+        # (default 1) so iteration still advances even if the field is absent.
+        if self.page is not None:
+            return self.page
+        requested = self._body.get("page")
+        return requested if isinstance(requested, int) else 1
+
+    def has_next_page(self) -> bool:
+        return (
+            self.total_pages is not None
+            and self._current_page() < self.total_pages
+            and bool(self.results)
+        )
+
+    def _next_body(self) -> dict[str, Any]:
+        return {**self._body, "page": self._current_page() + 1}

blitz_api/_pagination_base.py

@@ -0,0 +1,52 @@
+"""Shared base for the auto-paginating page models.
+
+Field-free pagination *state* and the request context needed to fetch the next page
+live here (no ``async``, so this file is NOT processed by ``scripts/gen_sync.py``). The
+sync vs async iteration surface lives in ``_pagination_async.py`` (source) and
+``_pagination_sync.py`` (generated). Both the sync and async clients import
+:class:`BasePage` for a single, flavour-neutral ``isinstance`` check when binding context.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import PrivateAttr
+
+from .types._models import BlitzModel
+
+
+class BasePage(BlitzModel):
+    """Common pagination context. Subclasses add the page fields + iteration."""
+
+    # Bound by the client after a page is parsed, so the page can fetch the next one.
+    _client: Any = PrivateAttr(default=None)
+    _method: str = PrivateAttr(default="POST")
+    _path: str = PrivateAttr(default="")
+    _body: dict[str, Any] = PrivateAttr(default_factory=dict)
+    # The per-call timeout override the first page was fetched with, so every
+    # subsequent auto-paged request honours it too. ``Any`` (rather than
+    # ``TimeoutParam``) keeps this module from importing ``httpx`` at runtime.
+    _timeout: Any = PrivateAttr(default=None)
+
+    def _bind(
+        self,
+        client: Any,
+        method: str,
+        path: str,
+        body: dict[str, Any] | None,
+        timeout: Any = None,
+    ) -> None:
+        self._client = client
+        self._method = method
+        self._path = path
+        self._body = dict(body) if body else {}
+        self._timeout = timeout
+
+    def has_next_page(self) -> bool:
+        """Whether another page is available (overridden per pagination style)."""
+        return False
+
+    def _next_body(self) -> dict[str, Any]:
+        """The request body for the next page (overridden per pagination style)."""
+        raise NotImplementedError

blitz_api/_pagination_sync.py

@@ -0,0 +1,130 @@
+# This file is @generated by scripts/gen_sync.py from src/blitz_api/_pagination_async.py.
+# Do not edit by hand — edit the async source and run `python scripts/gen_sync.py`.
+"""Auto-paginating page objects (async source).
+
+The sync versions in ``_pagination_sync.py`` are generated from this file by
+``scripts/gen_sync.py`` (it strips ``async``/``await`` and renames the ``Async*`` /
+``AsyncIterator`` / ``__aiter__`` tokens). Edit this file, then run the generator.
+
+``search.people``/``search.companies`` return the cursor-based page class and
+``search.employee_finder`` the page-number-based one. Both auto-paginate over every item
+when iterated (``for``/``async for``), and also expose ``.auto_paging_iter()``,
+``.iter_pages()``, and ``.get_next_page()``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any, Generic, TypeVar, cast
+
+from typing_extensions import Self
+
+from ._pagination_base import BasePage
+
+ItemT = TypeVar("ItemT")
+
+
+class Paginator(BasePage, Generic[ItemT]):
+    """Mixes auto-pagination over items/pages onto a concrete page model."""
+
+    results: list[ItemT] = []
+
+    # ``__iter__`` (the generated sync twin of this) intentionally overrides
+    # ``BaseModel.__iter__`` to yield items instead of (field, value) pairs.
+    def __iter__(self) -> Iterator[ItemT]:  # type: ignore[override]
+        return self._auto_paging_items()
+
+    def _auto_paging_items(self, max_items: int | None = None) -> Iterator[ItemT]:
+        page = self
+        emitted = 0
+        while True:
+            for item in page.results:
+                yield item
+                emitted += 1
+                if max_items is not None and emitted >= max_items:
+                    return
+            if not page.has_next_page():
+                return
+            page = page._fetch_next()
+
+    def auto_paging_iter(self, *, max_items: int | None = None) -> Iterator[ItemT]:
+        """Iterate every item across all pages, optionally stopping after ``max_items``."""
+        return self._auto_paging_items(max_items)
+
+    def iter_pages(self, *, max_pages: int | None = None) -> Iterator[Self]:
+        """Iterate page objects across the result set, optionally capped at ``max_pages``."""
+        page = self
+        seen = 0
+        while True:
+            yield page
+            seen += 1
+            if max_pages is not None and seen >= max_pages:
+                return
+            if not page.has_next_page():
+                return
+            page = page._fetch_next()
+
+    def get_next_page(self) -> Self | None:
+        """Fetch the next page, or ``None`` if this is the last one."""
+        if not self.has_next_page():
+            return None
+        return self._fetch_next()
+
+    def _fetch_next(self) -> Self:
+        return cast(
+            "Self",
+            self._client._request(
+                self._method,
+                self._path,
+                body=self._next_body(),
+                cast_to=type(self),
+                timeout=self._timeout,
+            ),
+        )
+
+
+class CursorPage(Paginator[ItemT], Generic[ItemT]):
+    """Cursor-paginated page (``search.people`` / ``search.companies``)."""
+
+    total_results: int | None = None
+    results_length: int | None = None
+    max_results: int | None = None
+    cursor: str | None = None
+
+    def has_next_page(self) -> bool:
+        # The API terminates the walk by returning ``cursor=null`` on the last page, so a
+        # non-null cursor is the single source of truth. We deliberately do NOT also gate
+        # on ``results`` being non-empty: a sparse intermediate page (empty results but a
+        # valid forward cursor) must keep paging, not silently truncate the result set.
+        return bool(self.cursor)
+
+    def _next_body(self) -> dict[str, Any]:
+        return {**self._body, "cursor": self.cursor}
+
+
+class PageNumberPage(Paginator[ItemT], Generic[ItemT]):
+    """Page-number-paginated page (``search.employee_finder``)."""
+
+    company_linkedin_url: str | None = None
+    max_results: int | None = None
+    results_length: int | None = None
+    page: int | None = None
+    total_pages: int | None = None
+
+    def _current_page(self) -> int:
+        # Prefer the page the server echoed; fall back to the page we requested
+        # (default 1) so iteration still advances even if the field is absent.
+        if self.page is not None:
+            return self.page
+        requested = self._body.get("page")
+        return requested if isinstance(requested, int) else 1
+
+    def has_next_page(self) -> bool:
+        return (
+            self.total_pages is not None
+            and self._current_page() < self.total_pages
+            and bool(self.results)
+        )
+
+    def _next_body(self) -> dict[str, Any]:
+        return {**self._body, "page": self._current_page() + 1}

blitz_api/_rate_limit.py

@@ -0,0 +1,14 @@
+"""Client-side rate limiters: re-exports the async source and its generated sync twin.
+
+The implementations live in ``_rate_limit_async.py`` (hand-written source) and
+``_rate_limit_sync.py`` (generated from it by ``scripts/gen_sync.py``); this module just
+re-exports both so ``from blitz_api._rate_limit import RateLimiter`` keeps working —
+mirroring how ``_client.py`` re-exports the two clients.
+"""
+
+from __future__ import annotations
+
+from ._rate_limit_async import AsyncRateLimiter
+from ._rate_limit_sync import RateLimiter
+
+__all__ = ["AsyncRateLimiter", "RateLimiter"]

blitz_api/_rate_limit_async.py

@@ -0,0 +1,67 @@
+"""Client-side sliding-window rate limiter (async source; sync twin generated).
+
+The API enforces a per-key request rate (5 req/s by default). This limiter throttles
+outgoing requests *before* they are sent so a single client instance stays under the
+limit proactively; the server-side 429 retry path is the backstop for bursts across
+processes.
+
+The algorithm is a sliding window: at most ``rps`` requests may begin in any rolling
+one-second window. This matches the Blitz docs ("max 5 requests per 1000 ms") and the
+official reference client. Unlike a token bucket — whose initial capacity lets a fresh
+client fire ``rps`` requests *and* refill within the same second, briefly doubling the
+rate — a sliding window never exceeds ``rps`` in any one-second window, including the
+first. ``rps`` tracks the API's integer ``max_requests_per_seconds``; a fractional value
+is floored to a per-second integer budget (minimum 1). The clock and sleep are injectable
+so tests can drive them with a fake clock.
+
+The synchronous ``RateLimiter`` in ``_rate_limit_sync.py`` is generated from this file by
+``scripts/gen_sync.py`` — edit this source, never the generated twin.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections import deque
+from collections.abc import Callable
+
+from ._compat import AsyncSleep
+
+#: Width of the rolling window, in seconds.
+_WINDOW = 1.0
+
+
+class AsyncRateLimiter:
+    """Sliding-window limiter, safe to share across concurrent callers."""
+
+    def __init__(
+        self,
+        rps: float | None,
+        *,
+        monotonic: Callable[[], float] = time.monotonic,
+        sleep: AsyncSleep = asyncio.sleep,
+    ) -> None:
+        self.rps = rps
+        # Integer request budget per window. ``rps`` is typed ``float`` for ergonomics, but
+        # the deque admission below counts whole requests, so floor it (min 1 when enabled).
+        self._budget = max(1, int(rps)) if rps else 0
+        self._sends: deque[float] = deque()
+        self._lock = asyncio.Lock()
+        self._monotonic = monotonic
+        self._sleep = sleep
+
+    async def acquire(self) -> None:
+        """Wait until a request may be sent under the rolling-window limit."""
+        if not self.rps:
+            return
+        while True:
+            async with self._lock:
+                now = self._monotonic()
+                cutoff = now - _WINDOW
+                while self._sends and self._sends[0] <= cutoff:
+                    self._sends.popleft()
+                if len(self._sends) < self._budget:
+                    self._sends.append(now)
+                    return
+                wait = self._sends[0] + _WINDOW - now
+            await self._sleep(max(0.0, wait))

blitz_api/_rate_limit_sync.py

@@ -0,0 +1,69 @@
+# This file is @generated by scripts/gen_sync.py from src/blitz_api/_rate_limit_async.py.
+# Do not edit by hand — edit the async source and run `python scripts/gen_sync.py`.
+"""Client-side sliding-window rate limiter (async source; sync twin generated).
+
+The API enforces a per-key request rate (5 req/s by default). This limiter throttles
+outgoing requests *before* they are sent so a single client instance stays under the
+limit proactively; the server-side 429 retry path is the backstop for bursts across
+processes.
+
+The algorithm is a sliding window: at most ``rps`` requests may begin in any rolling
+one-second window. This matches the Blitz docs ("max 5 requests per 1000 ms") and the
+official reference client. Unlike a token bucket — whose initial capacity lets a fresh
+client fire ``rps`` requests *and* refill within the same second, briefly doubling the
+rate — a sliding window never exceeds ``rps`` in any one-second window, including the
+first. ``rps`` tracks the API's integer ``max_requests_per_seconds``; a fractional value
+is floored to a per-second integer budget (minimum 1). The clock and sleep are injectable
+so tests can drive them with a fake clock.
+
+The synchronous ``RateLimiter`` in ``_rate_limit_sync.py`` is generated from this file by
+``scripts/gen_sync.py`` — edit this source, never the generated twin.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections import deque
+from collections.abc import Callable
+
+from ._compat import SyncSleep
+
+#: Width of the rolling window, in seconds.
+_WINDOW = 1.0
+
+
+class RateLimiter:
+    """Sliding-window limiter, safe to share across concurrent callers."""
+
+    def __init__(
+        self,
+        rps: float | None,
+        *,
+        monotonic: Callable[[], float] = time.monotonic,
+        sleep: SyncSleep = time.sleep,
+    ) -> None:
+        self.rps = rps
+        # Integer request budget per window. ``rps`` is typed ``float`` for ergonomics, but
+        # the deque admission below counts whole requests, so floor it (min 1 when enabled).
+        self._budget = max(1, int(rps)) if rps else 0
+        self._sends: deque[float] = deque()
+        self._lock = threading.Lock()
+        self._monotonic = monotonic
+        self._sleep = sleep
+
+    def acquire(self) -> None:
+        """Wait until a request may be sent under the rolling-window limit."""
+        if not self.rps:
+            return
+        while True:
+            with self._lock:
+                now = self._monotonic()
+                cutoff = now - _WINDOW
+                while self._sends and self._sends[0] <= cutoff:
+                    self._sends.popleft()
+                if len(self._sends) < self._budget:
+                    self._sends.append(now)
+                    return
+                wait = self._sends[0] + _WINDOW - now
+            self._sleep(max(0.0, wait))

blitz_api/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"  # x-release-please-version

blitz_api/resources/__init__.py

@@ -0,0 +1,27 @@
+"""Namespaced API resources, grouped by the Blitz API's OpenAPI tags.
+
+The ``Async*`` classes are hand-written in ``resources/_async``; the sync classes in
+``resources/_sync`` are generated from them by ``scripts/gen_sync.py``.
+"""
+
+from __future__ import annotations
+
+from ._async.account import AsyncAccountResource
+from ._async.enrichment import AsyncEnrichmentResource
+from ._async.search import AsyncSearchResource
+from ._async.utils import AsyncUtilsResource
+from ._sync.account import AccountResource
+from ._sync.enrichment import EnrichmentResource
+from ._sync.search import SearchResource
+from ._sync.utils import UtilsResource
+
+__all__ = [
+    "AccountResource",
+    "AsyncAccountResource",
+    "SearchResource",
+    "AsyncSearchResource",
+    "EnrichmentResource",
+    "AsyncEnrichmentResource",
+    "UtilsResource",
+    "AsyncUtilsResource",
+]

blitz_api/resources/_async/__init__.py

@@ -0,0 +1 @@
+"""Blitz API resource classes, grouped by the API's OpenAPI tags."""

blitz_api/resources/_async/account.py

@@ -0,0 +1,27 @@
+"""The Account resource: ``client.account``."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..._compat import TimeoutParam
+from ...types.account import KeyInfo
+
+if TYPE_CHECKING:
+    from ..._client import AsyncBlitzAPI
+
+_KEY_INFO_PATH = "/v2/account/key-info"
+
+
+class AsyncAccountResource:
+    def __init__(self, client: AsyncBlitzAPI) -> None:
+        self._client = client
+
+    async def key_info(self, *, timeout: TimeoutParam = None) -> KeyInfo:
+        """Check the API key's validity, credit balance, and rate limit.
+
+        A cheap health check to run before a batch job.
+        """
+        return await self._client._request(
+            "GET", _KEY_INFO_PATH, body=None, cast_to=KeyInfo, timeout=timeout
+        )