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

blitz_api/__init__.py

@@ -0,0 +1,65 @@
+"""Typed Python SDK for the Blitz API.
+
+Quickstart::
+
+    from blitz_api import BlitzAPI
+
+    client = BlitzAPI()  # reads the BLITZ_API_KEY environment variable
+    result = client.enrichment.email(
+        person_linkedin_url="https://www.linkedin.com/in/example",
+    )
+    print(result.found, result.email)
+
+See https://docs.blitz-api.ai for the full API reference.
+"""
+
+from __future__ import annotations
+
+from ._client import AsyncBlitzAPI, BlitzAPI
+from ._exceptions import (
+    APIConnectionError,
+    APIResponseValidationError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BlitzError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+)
+from ._pagination_async import AsyncCursorPage, AsyncPageNumberPage
+from ._pagination_sync import CursorPage, PageNumberPage
+from ._version import __version__
+from .types import (
+    CompanyFilter,
+    Industry,
+    PeopleFilter,
+)
+
+__all__ = [
+    "__version__",
+    # clients
+    "BlitzAPI",
+    "AsyncBlitzAPI",
+    # pagination (returned by the search.* methods)
+    "CursorPage",
+    "AsyncCursorPage",
+    "PageNumberPage",
+    "AsyncPageNumberPage",
+    # exceptions
+    "BlitzError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIResponseValidationError",
+    "APIStatusError",
+    "AuthenticationError",
+    "InsufficientCreditsError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    # commonly-used types (full set under blitz_api.types)
+    "Industry",
+    "CompanyFilter",
+    "PeopleFilter",
+]

blitz_api/_base_client.py

@@ -0,0 +1,191 @@
+"""Shared, IO-free request-pipeline logic for the sync and async clients.
+
+The actual network calls live in :mod:`blitz_api._client`; everything here is
+pure so both clients share identical header building, retry decisions, backoff
+computation, error mapping, and response parsing.
+"""
+
+from __future__ import annotations
+
+import os
+import random
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from enum import Enum
+from typing import Any, TypeVar, cast
+from urllib.parse import urljoin
+
+import httpx
+from pydantic import ValidationError
+
+from . import _constants as C
+from ._exceptions import (
+    APIResponseValidationError,
+    APIStatusError,
+    AuthenticationError,
+    BlitzError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+)
+from .types._models import BlitzModel
+
+ResponseT = TypeVar("ResponseT", bound=BlitzModel)
+
+# Status code -> exception class. Anything not listed that is still non-2xx
+# falls back to a generic APIStatusError (or ServerError for any 5xx).
+_STATUS_EXCEPTIONS: dict[int, type[APIStatusError]] = {
+    401: AuthenticationError,
+    402: InsufficientCreditsError,
+    404: NotFoundError,
+    429: RateLimitError,
+}
+
+
+def to_jsonable(value: Any) -> Any:
+    """Recursively prepare a request payload for JSON serialization.
+
+    Resolves :class:`enum.Enum` members to their values and drops ``None`` so
+    that optional, unset fields are simply omitted from the request body.
+    """
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, dict):
+        mapping = cast("dict[str, Any]", value)
+        return {k: to_jsonable(v) for k, v in mapping.items() if v is not None}
+    if isinstance(value, (list, tuple)):
+        sequence = cast("list[Any]", value)
+        return [to_jsonable(v) for v in sequence]
+    return value
+
+
+def _retry_after_seconds(raw: str | None) -> float:
+    """Parse a ``Retry-After`` header (delta-seconds or HTTP-date) into seconds.
+
+    Falls back to :data:`DEFAULT_RETRY_AFTER_SECONDS` when the header is absent or
+    unparseable. The caller clamps the result to a maximum.
+    """
+    if not raw:
+        return C.DEFAULT_RETRY_AFTER_SECONDS
+    raw = raw.strip()
+    try:
+        return max(0.0, float(raw))
+    except ValueError:
+        pass
+    try:
+        when = parsedate_to_datetime(raw)
+    except (TypeError, ValueError):
+        return C.DEFAULT_RETRY_AFTER_SECONDS
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=timezone.utc)
+    return max(0.0, (when - datetime.now(timezone.utc)).total_seconds())
+
+
+class BaseClient:
+    """Configuration and pure helpers shared by both clients."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None,
+        base_url: str,
+        max_retries: int,
+    ) -> None:
+        resolved = api_key if api_key is not None else os.environ.get(C.API_KEY_ENV_VAR)
+        if not resolved:
+            raise BlitzError(
+                "No API key provided. Pass api_key=... or set the "
+                f"{C.API_KEY_ENV_VAR} environment variable."
+            )
+        self.api_key = resolved
+        self.base_url = base_url.rstrip("/") + "/"
+        self.max_retries = max_retries
+
+    # -- request shaping -------------------------------------------------
+
+    def _build_url(self, path: str) -> str:
+        return urljoin(self.base_url, path.lstrip("/"))
+
+    def _build_headers(self) -> dict[str, str]:
+        return {
+            C.API_KEY_HEADER: self.api_key,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": C.USER_AGENT,
+        }
+
+    # -- retry policy ----------------------------------------------------
+
+    @staticmethod
+    def _should_retry(status_code: int) -> bool:
+        return status_code == 429 or status_code >= 500
+
+    @staticmethod
+    def _should_retry_exception(exc: httpx.RequestError) -> bool:
+        """Whether a transport-level error is safe to retry.
+
+        Only failures where the request never reached the server are retried, so a
+        retry cannot double-process (or double-bill) a request. A connect timeout,
+        connection error, or pool timeout means nothing was sent. A *read* or *write*
+        timeout means the request may already have been received and processed by the
+        server — retrying a billable POST there could charge the caller twice — so
+        those are surfaced immediately instead.
+        """
+        return isinstance(exc, (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout))
+
+    def _backoff_seconds(self, attempt: int) -> float:
+        """Exponential backoff with full jitter (attempt starts at 1)."""
+        base = min(8.0, 0.5 * 2.0 ** (attempt - 1))
+        return base + random.uniform(0.0, 0.5)
+
+    def _retry_delay(self, response: httpx.Response, attempt: int) -> float:
+        if response.status_code == 429:
+            seconds = _retry_after_seconds(response.headers.get("retry-after"))
+            return min(seconds, C.MAX_RETRY_WAIT_SECONDS)
+        return self._backoff_seconds(attempt)
+
+    # -- response handling ----------------------------------------------
+
+    @staticmethod
+    def _parse_body(response: httpx.Response) -> Any:
+        try:
+            return response.json()
+        except ValueError:
+            return response.text
+
+    def _make_status_error(self, response: httpx.Response) -> APIStatusError:
+        body: Any = self._parse_body(response)
+        message: str | None = None
+        if isinstance(body, dict):
+            mapping = cast("dict[str, Any]", body)
+            raw = mapping.get("message") or mapping.get("error")
+            if isinstance(raw, str):
+                message = raw
+        if message is None:
+            message = f"HTTP {response.status_code} from {response.request.url}"
+
+        exc_class = _STATUS_EXCEPTIONS.get(response.status_code)
+        if exc_class is None:
+            exc_class = ServerError if response.status_code >= 500 else APIStatusError
+        return exc_class(message, response=response, body=cast("Any", body))
+
+    @staticmethod
+    def _parse_model(response: httpx.Response, cast_to: type[ResponseT]) -> ResponseT:
+        try:
+            data = response.json()
+        except ValueError as exc:
+            content_type = response.headers.get("content-type", "an unknown content type")
+            raise APIResponseValidationError(
+                f"Expected a JSON response body from {response.request.url}, got {content_type}.",
+                response=response,
+            ) from exc
+        try:
+            return cast_to.model_validate(data)
+        except ValidationError as exc:
+            # Parametrized generics (e.g. CursorPage[Person]) may lack ``__name__``.
+            name = getattr(cast_to, "__name__", str(cast_to))
+            raise APIResponseValidationError(
+                f"Response body did not match {name}.",
+                response=response,
+            ) from exc

blitz_api/_client.py

@@ -0,0 +1,13 @@
+"""The public Blitz API clients: :class:`BlitzAPI` (sync) and :class:`AsyncBlitzAPI`.
+
+The async client is hand-written in :mod:`blitz_api._client_async`; the sync client in
+:mod:`blitz_api._client_sync` is generated from it by ``scripts/gen_sync.py``. This module
+re-exports both so ``from blitz_api._client import BlitzAPI`` keeps working.
+"""
+
+from __future__ import annotations
+
+from ._client_async import AsyncBlitzAPI
+from ._client_sync import BlitzAPI
+
+__all__ = ["AsyncBlitzAPI", "BlitzAPI"]

blitz_api/_client_async.py

@@ -0,0 +1,143 @@
+"""The Blitz API client implementation (async source; sync is generated alongside)."""
+
+from __future__ import annotations
+
+from functools import cached_property
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from . import _constants as C
+from ._base_client import BaseClient, ResponseT, to_jsonable
+from ._compat import AsyncSleep, TimeoutParam
+from ._exceptions import APIConnectionError, APITimeoutError
+from ._pagination_base import BasePage
+from ._rate_limit import AsyncRateLimiter
+from .resources import (
+    AsyncAccountResource,
+    AsyncEnrichmentResource,
+    AsyncSearchResource,
+    AsyncUtilsResource,
+)
+
+
+class AsyncBlitzAPI(BaseClient):
+    """Client for the Blitz API.
+
+    ``AsyncBlitzAPI`` is the async client and ``BlitzAPI`` is the sync client; both
+    expose an identical method surface. See the ``blitz_api`` package docstring for a
+    quickstart. (This docstring is shared with the generated sync client, so it stays
+    flavour-neutral.)
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = C.DEFAULT_BASE_URL,
+        timeout: float | httpx.Timeout = C.DEFAULT_TIMEOUT,
+        max_retries: int = C.DEFAULT_MAX_RETRIES,
+        rate_limit_rps: float | None = C.DEFAULT_RATE_LIMIT_RPS,
+        http_client: httpx.AsyncClient | None = None,
+        sleep: AsyncSleep | None = None,
+    ) -> None:
+        super().__init__(api_key=api_key, base_url=base_url, max_retries=max_retries)
+        if http_client is not None and timeout != C.DEFAULT_TIMEOUT:
+            raise ValueError(
+                "Pass `timeout` or `http_client`, not both: a supplied http_client carries "
+                "its own timeout. Set the timeout on your httpx client instead."
+            )
+        self._http_client = http_client or httpx.AsyncClient(timeout=timeout)
+        self._owns_http_client = http_client is None
+        self._rate_limiter = AsyncRateLimiter(rate_limit_rps)
+        if sleep is None:
+            import asyncio
+
+            sleep = asyncio.sleep
+        self._sleep = sleep
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any | None,
+        cast_to: type[ResponseT],
+        timeout: TimeoutParam = None,
+    ) -> ResponseT:
+        url = self._build_url(path)
+        headers = self._build_headers()
+        json_body = to_jsonable(body) if body is not None else None
+
+        attempt = 0
+        while True:
+            await self._rate_limiter.acquire()
+            try:
+                if timeout is None:
+                    response = await self._http_client.request(
+                        method, url, headers=headers, json=json_body
+                    )
+                else:
+                    response = await self._http_client.request(
+                        method, url, headers=headers, json=json_body, timeout=timeout
+                    )
+            except httpx.TimeoutException as exc:
+                if self._should_retry_exception(exc) and attempt < self.max_retries:
+                    attempt += 1
+                    await self._sleep(self._backoff_seconds(attempt))
+                    continue
+                raise APITimeoutError(request=exc.request) from exc
+            except httpx.RequestError as exc:
+                if self._should_retry_exception(exc) and attempt < self.max_retries:
+                    attempt += 1
+                    await self._sleep(self._backoff_seconds(attempt))
+                    continue
+                raise APIConnectionError(
+                    str(exc) or "Connection error.", request=exc.request
+                ) from exc
+
+            if response.is_success:
+                result = self._parse_model(response, cast_to)
+                if isinstance(result, BasePage):
+                    result._bind(self, method, path, json_body, timeout)
+                return result
+
+            if self._should_retry(response.status_code) and attempt < self.max_retries:
+                attempt += 1
+                await self._sleep(self._retry_delay(response, attempt))
+                continue
+
+            raise self._make_status_error(response)
+
+    async def close(self) -> None:
+        """Close the underlying HTTP connection pool (if owned by this client)."""
+        if self._owns_http_client:
+            await self._http_client.aclose()
+
+    async def __aenter__(self) -> AsyncBlitzAPI:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    @cached_property
+    def account(self) -> AsyncAccountResource:
+        return AsyncAccountResource(self)
+
+    @cached_property
+    def search(self) -> AsyncSearchResource:
+        return AsyncSearchResource(self)
+
+    @cached_property
+    def enrichment(self) -> AsyncEnrichmentResource:
+        return AsyncEnrichmentResource(self)
+
+    @cached_property
+    def utils(self) -> AsyncUtilsResource:
+        return AsyncUtilsResource(self)

blitz_api/_client_sync.py

@@ -0,0 +1,145 @@
+# This file is @generated by scripts/gen_sync.py from src/blitz_api/_client_async.py.
+# Do not edit by hand — edit the async source and run `python scripts/gen_sync.py`.
+"""The Blitz API client implementation (async source; sync is generated alongside)."""
+
+from __future__ import annotations
+
+from functools import cached_property
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from . import _constants as C
+from ._base_client import BaseClient, ResponseT, to_jsonable
+from ._compat import SyncSleep, TimeoutParam
+from ._exceptions import APIConnectionError, APITimeoutError
+from ._pagination_base import BasePage
+from ._rate_limit import RateLimiter
+from .resources import (
+    AccountResource,
+    EnrichmentResource,
+    SearchResource,
+    UtilsResource,
+)
+
+
+class BlitzAPI(BaseClient):
+    """Client for the Blitz API.
+
+    ``AsyncBlitzAPI`` is the async client and ``BlitzAPI`` is the sync client; both
+    expose an identical method surface. See the ``blitz_api`` package docstring for a
+    quickstart. (This docstring is shared with the generated sync client, so it stays
+    flavour-neutral.)
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = C.DEFAULT_BASE_URL,
+        timeout: float | httpx.Timeout = C.DEFAULT_TIMEOUT,
+        max_retries: int = C.DEFAULT_MAX_RETRIES,
+        rate_limit_rps: float | None = C.DEFAULT_RATE_LIMIT_RPS,
+        http_client: httpx.Client | None = None,
+        sleep: SyncSleep | None = None,
+    ) -> None:
+        super().__init__(api_key=api_key, base_url=base_url, max_retries=max_retries)
+        if http_client is not None and timeout != C.DEFAULT_TIMEOUT:
+            raise ValueError(
+                "Pass `timeout` or `http_client`, not both: a supplied http_client carries "
+                "its own timeout. Set the timeout on your httpx client instead."
+            )
+        self._http_client = http_client or httpx.Client(timeout=timeout)
+        self._owns_http_client = http_client is None
+        self._rate_limiter = RateLimiter(rate_limit_rps)
+        if sleep is None:
+            import time
+
+            sleep = time.sleep
+        self._sleep = sleep
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any | None,
+        cast_to: type[ResponseT],
+        timeout: TimeoutParam = None,
+    ) -> ResponseT:
+        url = self._build_url(path)
+        headers = self._build_headers()
+        json_body = to_jsonable(body) if body is not None else None
+
+        attempt = 0
+        while True:
+            self._rate_limiter.acquire()
+            try:
+                if timeout is None:
+                    response = self._http_client.request(
+                        method, url, headers=headers, json=json_body
+                    )
+                else:
+                    response = self._http_client.request(
+                        method, url, headers=headers, json=json_body, timeout=timeout
+                    )
+            except httpx.TimeoutException as exc:
+                if self._should_retry_exception(exc) and attempt < self.max_retries:
+                    attempt += 1
+                    self._sleep(self._backoff_seconds(attempt))
+                    continue
+                raise APITimeoutError(request=exc.request) from exc
+            except httpx.RequestError as exc:
+                if self._should_retry_exception(exc) and attempt < self.max_retries:
+                    attempt += 1
+                    self._sleep(self._backoff_seconds(attempt))
+                    continue
+                raise APIConnectionError(
+                    str(exc) or "Connection error.", request=exc.request
+                ) from exc
+
+            if response.is_success:
+                result = self._parse_model(response, cast_to)
+                if isinstance(result, BasePage):
+                    result._bind(self, method, path, json_body, timeout)
+                return result
+
+            if self._should_retry(response.status_code) and attempt < self.max_retries:
+                attempt += 1
+                self._sleep(self._retry_delay(response, attempt))
+                continue
+
+            raise self._make_status_error(response)
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool (if owned by this client)."""
+        if self._owns_http_client:
+            self._http_client.close()
+
+    def __enter__(self) -> BlitzAPI:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    @cached_property
+    def account(self) -> AccountResource:
+        return AccountResource(self)
+
+    @cached_property
+    def search(self) -> SearchResource:
+        return SearchResource(self)
+
+    @cached_property
+    def enrichment(self) -> EnrichmentResource:
+        return EnrichmentResource(self)
+
+    @cached_property
+    def utils(self) -> UtilsResource:
+        return UtilsResource(self)

blitz_api/_compat.py

@@ -0,0 +1,26 @@
+"""Type aliases that differ between the async source and the generated sync code.
+
+The async client takes an awaitable sleep callable; the sync client takes a plain
+one. ``scripts/gen_sync.py`` rewrites the token ``AsyncSleep`` to ``SyncSleep`` when
+it transliterates the async source, so both flavours stay precisely typed without the
+generator having to rewrite a subscripted generic (which token-level renaming can't do).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Union
+
+if TYPE_CHECKING:
+    import httpx
+
+#: Sleep callable accepted by ``AsyncBlitzAPI`` (e.g. ``asyncio.sleep``).
+AsyncSleep = Callable[[float], Awaitable[None]]
+
+#: Sleep callable accepted by ``BlitzAPI`` (e.g. ``time.sleep``).
+SyncSleep = Callable[[float], None]
+
+#: Per-call timeout override: a number of seconds, an :class:`httpx.Timeout`, or
+#: ``None`` to fall back to the client-wide timeout. (Defined with ``Union`` and a
+#: forward reference so importing it never forces ``httpx`` to load at runtime.)
+TimeoutParam = Union[float, "httpx.Timeout", None]

blitz_api/_constants.py

@@ -0,0 +1,36 @@
+"""Internal defaults shared by the sync and async clients."""
+
+from __future__ import annotations
+
+from ._version import __version__
+
+#: Production API base URL.
+DEFAULT_BASE_URL = "https://api.blitz-api.ai"
+
+#: Environment variable read when ``api_key`` is not passed explicitly.
+API_KEY_ENV_VAR = "BLITZ_API_KEY"
+
+#: Header carrying the API key (Blitz uses ``x-api-key``, not ``Authorization``).
+API_KEY_HEADER = "x-api-key"
+
+#: Default per-request timeout, in seconds.
+DEFAULT_TIMEOUT = 30.0
+
+#: Number of retries (in addition to the first attempt) for transient failures.
+DEFAULT_MAX_RETRIES = 3
+
+#: Default client-side rate limit. The API allows 5 req/s on every plan; the
+#: per-key value is discoverable via ``client.account.key_info()``.
+DEFAULT_RATE_LIMIT_RPS = 5.0
+
+#: Seconds to wait after a 429 when the response has no ``Retry-After`` header.
+#: Matches the behaviour of the official reference client.
+DEFAULT_RETRY_AFTER_SECONDS = 60.0
+
+#: Upper bound (seconds) on any single retry wait, including a server-supplied
+#: ``Retry-After``. A safety clamp so a pathological header value (e.g.
+#: ``Retry-After: 86400``) can't make the client sleep for hours.
+MAX_RETRY_WAIT_SECONDS = 120.0
+
+#: Sent as the ``User-Agent`` header so requests are attributable to this SDK.
+USER_AGENT = f"blitz-api-py/{__version__}"