leadsets 0.1.0__py3-none-any.whl

leadsets/__init__.py

@@ -0,0 +1,58 @@
+"""Official Python SDK for the Leadsets B2B data API.
+
+>>> import os
+>>> from leadsets import Leadsets
+>>> ls = Leadsets(os.environ["LEADSETS_KEY"])
+>>> res = ls.people.search(function=["revenue"], seniority=["vp", "head"], employees="20-200",
+...                        country="US", industry="saas", limit=10)
+>>> res.items[0].match_reasons, res.usage
+"""
+
+from . import types
+from ._base import DEFAULT_BASE_URL
+from ._client import AsyncLeadsets, Leadsets
+from ._exceptions import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    FreeRecordsExhaustedError,
+    IdempotencyConflictError,
+    InternalServerError,
+    InvalidRequestError,
+    LeadsetsError,
+    NotFoundError,
+    PaymentRequiredError,
+    PermissionDeniedError,
+    RateLimitError,
+    ScrapeUnitsExhaustedError,
+    ServiceUnavailableError,
+)
+from ._exceptions import APIConnectionError as ConnectionError
+from ._exceptions import APITimeoutError as TimeoutError
+from ._version import __version__
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "APIConnectionError",
+    "APIError",
+    "APITimeoutError",
+    "AsyncLeadsets",
+    "AuthenticationError",
+    "ConnectionError",
+    "FreeRecordsExhaustedError",
+    "IdempotencyConflictError",
+    "InternalServerError",
+    "InvalidRequestError",
+    "Leadsets",
+    "LeadsetsError",
+    "NotFoundError",
+    "PaymentRequiredError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ScrapeUnitsExhaustedError",
+    "ServiceUnavailableError",
+    "TimeoutError",
+    "__version__",
+    "types",
+]

leadsets/_base.py

@@ -0,0 +1,171 @@
+"""Shared request logic for the sync and async clients."""
+
+from __future__ import annotations
+
+import os
+import platform
+import random
+import uuid
+from collections.abc import Mapping
+from typing import Any, TypeVar
+
+import httpx
+
+from ._exceptions import APIError, LeadsetsError, make_api_error, parse_retry_after
+from ._models import Model
+from ._version import __version__
+from .types import RateLimitInfo, ResponseMeta
+
+DEFAULT_BASE_URL = "https://api.leadsets.ai"
+DEFAULT_TIMEOUT = 120.0
+DEFAULT_MAX_RETRIES = 2
+DEFAULT_MAX_RETRY_DELAY = 60.0
+
+USER_AGENT = f"leadsets-sdk-python/{__version__} (Python {platform.python_version()}; httpx {httpx.__version__})"
+
+M = TypeVar("M", bound=Model)
+
+
+def _env(name: str) -> str | None:
+    v = os.environ.get(name)
+    return v.strip() if v and v.strip() else None
+
+
+def resolve_api_key(api_key: str | None) -> str:
+    key = api_key or _env("LEADSETS_API_KEY") or _env("LEADSETS_KEY")
+    if not key:
+        raise LeadsetsError(
+            "No API key. Pass one to Leadsets(api_key) or set the LEADSETS_API_KEY environment variable. "
+            "Get a free key at https://www.leadsets.ai/signup."
+        )
+    return key
+
+
+def resolve_base_url(base_url: str | None) -> str:
+    return (base_url or _env("LEADSETS_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+
+
+def new_idempotency_key() -> str:
+    return str(uuid.uuid4())
+
+
+def backoff(attempt: int) -> float:
+    """Exponential backoff with jitter: ~0.5 s, 1 s, 2 s … capped at 8 s."""
+    base: float = min(8.0, 0.5 * 2**attempt)
+    return base * (0.75 + random.random() * 0.25)
+
+
+def clean(params: Mapping[str, Any]) -> dict[str, Any]:
+    """Drop unset (None) parameters; turn tuples and other sequences into lists."""
+    out: dict[str, Any] = {}
+    for k, v in params.items():
+        if v is None:
+            continue
+        if isinstance(v, (tuple, set, frozenset)):
+            v = list(v)
+        out[k] = v
+    return out
+
+
+class BaseClient:
+    def __init__(
+        self,
+        api_key: str | None,
+        *,
+        base_url: str | None,
+        max_retries: int,
+        timeout: float | httpx.Timeout | None,
+        max_retry_delay: float,
+        default_headers: Mapping[str, str] | None,
+    ) -> None:
+        self.api_key = resolve_api_key(api_key)
+        self.base_url = resolve_base_url(base_url)
+        self.max_retries = max(0, int(max_retries))
+        self.timeout = timeout
+        self.max_retry_delay = max(0.0, float(max_retry_delay))
+        self._default_headers = dict(default_headers or {})
+
+    def _headers(
+        self, *, has_body: bool, idempotency_key: str | None, extra: Mapping[str, str] | None
+    ) -> dict[str, str]:
+        h = {
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+            **self._default_headers,
+            **(extra or {}),
+            "Authorization": f"Bearer {self.api_key}",
+        }
+        if has_body:
+            h["Content-Type"] = "application/json"
+        if idempotency_key:
+            h["Idempotency-Key"] = idempotency_key
+        return h
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}/v1{path}"
+
+    def _retry_delay(self, err: APIError | None, attempt: int) -> float | None:
+        """Seconds to wait before retrying, or None to not retry. ``err`` is None for network errors."""
+        if err is None:
+            return backoff(attempt)
+        if not (err.status_code in (408, 429) or err.status_code >= 500):
+            return None
+        if err.retry_after is not None:
+            if err.retry_after > self.max_retry_delay:
+                return None
+            return err.retry_after + random.random() * 0.25
+        return backoff(attempt)
+
+    @staticmethod
+    def _parse(cls: type[M], response: httpx.Response, idempotency_key: str | None, attempts: int) -> M:
+        try:
+            data = response.json() if response.content else {}
+        except ValueError:
+            data = {}
+        if not isinstance(data, dict):
+            data = {}
+        obj = cls.from_dict(data)
+        if hasattr(obj, "last_response"):
+            object.__setattr__(obj, "last_response", response_meta(response, data, idempotency_key, attempts))
+        return obj
+
+    @staticmethod
+    def _error(response: httpx.Response) -> APIError:
+        return make_api_error(response)
+
+
+def _int(v: str | None) -> int | None:
+    if v is None or v == "":
+        return None
+    try:
+        return int(v)
+    except ValueError:
+        try:
+            return int(float(v))
+        except ValueError:
+            return None
+
+
+def rate_limit_info(h: httpx.Headers) -> RateLimitInfo:
+    return RateLimitInfo(
+        records_remaining=_int(h.get("x-leadsets-records-remaining")),
+        requests_remaining=_int(h.get("x-leadsets-requests-remaining")),
+        weekly_remaining=_int(h.get("x-leadsets-weekly-remaining")),
+        free_remaining=_int(h.get("x-leadsets-free-remaining")),
+        retry_after=parse_retry_after(h.get("retry-after")),
+    )
+
+
+def response_meta(
+    response: httpx.Response, data: dict[str, Any], idempotency_key: str | None, attempts: int
+) -> ResponseMeta:
+    rid = data.get("request_id")
+    return ResponseMeta(
+        status_code=response.status_code,
+        headers=response.headers,
+        request_id=rid if isinstance(rid, str) else None,
+        idempotency_key=idempotency_key,
+        idempotent_replayed=response.headers.get("idempotent-replayed") == "true",
+        rate_limit=rate_limit_info(response.headers),
+        attempts=attempts,
+    )

leadsets/_client.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Mapping
+from types import TracebackType
+from typing import Any, Literal
+
+import httpx
+
+from ._base import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_MAX_RETRY_DELAY,
+    DEFAULT_TIMEOUT,
+    BaseClient,
+    M,
+    new_idempotency_key,
+)
+from ._exceptions import APIConnectionError, APIError, APITimeoutError
+from .resources.companies import AsyncCompanies, Companies
+from .resources.emails import AsyncEmails, Emails
+from .resources.jobs import AsyncJobs, Jobs
+from .resources.people import AsyncPeople, People
+from .resources.scrape import AsyncScrape, Scrape
+from .resources.usage import AsyncUsageResource, UsageResource
+
+Method = Literal["GET", "POST"]
+
+
+def _sleep(seconds: float) -> None:
+    time.sleep(seconds)
+
+
+async def _async_sleep(seconds: float) -> None:
+    await asyncio.sleep(seconds)
+
+
+class Leadsets(BaseClient):
+    """The Leadsets API client.
+
+    >>> ls = Leadsets(os.environ["LEADSETS_KEY"])
+    >>> res = ls.people.search(function=["revenue"], country="US", limit=10)
+    """
+
+    people: People
+    companies: Companies
+    emails: Emails
+    scrape: Scrape
+    jobs: Jobs
+    usage: UsageResource
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        timeout: float | httpx.Timeout | None = DEFAULT_TIMEOUT,
+        max_retry_delay: float = DEFAULT_MAX_RETRY_DELAY,
+        default_headers: Mapping[str, str] | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        """
+        Args:
+            api_key: Your API key (``ls_live_…``). Defaults to ``LEADSETS_API_KEY`` or ``LEADSETS_KEY``.
+            base_url: Defaults to https://api.leadsets.ai (or ``LEADSETS_BASE_URL``).
+            max_retries: Retries on 429, 5xx, timeouts and network errors. Default 2.
+            timeout: Per-attempt timeout in seconds. Default 120.
+            max_retry_delay: The longest ``Retry-After`` (seconds) to wait for before retrying.
+                A 429 asking for longer (a weekly limit, say) is raised at once. Default 60.
+            default_headers: Headers sent with every request.
+            http_client: Your own ``httpx.Client`` (proxies, transports…).
+        """
+        super().__init__(
+            api_key,
+            base_url=base_url,
+            max_retries=max_retries,
+            timeout=timeout,
+            max_retry_delay=max_retry_delay,
+            default_headers=default_headers,
+        )
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(timeout=timeout)
+        self.people = People(self)
+        self.companies = Companies(self)
+        self.emails = Emails(self)
+        self.scrape = Scrape(self)
+        self.jobs = Jobs(self)
+        self.usage = UsageResource(self)
+
+    def request(
+        self,
+        method: Method,
+        path: str,
+        cls: type[M],
+        *,
+        body: Mapping[str, Any] | None = None,
+        idempotent: bool = False,
+        idempotency_key: str | None = None,
+        timeout: float | httpx.Timeout | None = None,
+        max_retries: int | None = None,
+        extra_headers: Mapping[str, str] | None = None,
+    ) -> M:
+        key = idempotency_key or (new_idempotency_key() if idempotent else None)
+        headers = self._headers(has_body=body is not None, idempotency_key=key, extra=extra_headers)
+        retries = self.max_retries if max_retries is None else max(0, max_retries)
+        t = self.timeout if timeout is None else timeout
+        for attempt in range(retries + 1):
+            try:
+                res = self._client.request(method, self._url(path), json=body, headers=headers, timeout=t)
+            except httpx.TimeoutException as e:
+                if attempt < retries:
+                    _sleep(self._retry_delay(None, attempt) or 0)
+                    continue
+                raise APITimeoutError() from e
+            except httpx.TransportError as e:
+                if attempt < retries:
+                    _sleep(self._retry_delay(None, attempt) or 0)
+                    continue
+                raise APIConnectionError() from e
+            if res.is_success:
+                return self._parse(cls, res, key, attempt + 1)
+            err: APIError = self._error(res)
+            delay = self._retry_delay(err, attempt)
+            if attempt < retries and delay is not None:
+                _sleep(delay)
+                continue
+            raise err
+        raise AssertionError("unreachable")  # pragma: no cover
+
+    def close(self) -> None:
+        """Close the underlying HTTP client (if the SDK created it)."""
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> Leadsets:
+        return self
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        self.close()
+
+
+class AsyncLeadsets(BaseClient):
+    """The async Leadsets API client.
+
+    >>> async with AsyncLeadsets() as ls:
+    ...     res = await ls.people.search(function=["revenue"], country="US", limit=10)
+    """
+
+    people: AsyncPeople
+    companies: AsyncCompanies
+    emails: AsyncEmails
+    scrape: AsyncScrape
+    jobs: AsyncJobs
+    usage: AsyncUsageResource
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        timeout: float | httpx.Timeout | None = DEFAULT_TIMEOUT,
+        max_retry_delay: float = DEFAULT_MAX_RETRY_DELAY,
+        default_headers: Mapping[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        """Same arguments as :class:`Leadsets`; ``http_client`` is an ``httpx.AsyncClient``."""
+        super().__init__(
+            api_key,
+            base_url=base_url,
+            max_retries=max_retries,
+            timeout=timeout,
+            max_retry_delay=max_retry_delay,
+            default_headers=default_headers,
+        )
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(timeout=timeout)
+        self.people = AsyncPeople(self)
+        self.companies = AsyncCompanies(self)
+        self.emails = AsyncEmails(self)
+        self.scrape = AsyncScrape(self)
+        self.jobs = AsyncJobs(self)
+        self.usage = AsyncUsageResource(self)
+
+    async def request(
+        self,
+        method: Method,
+        path: str,
+        cls: type[M],
+        *,
+        body: Mapping[str, Any] | None = None,
+        idempotent: bool = False,
+        idempotency_key: str | None = None,
+        timeout: float | httpx.Timeout | None = None,
+        max_retries: int | None = None,
+        extra_headers: Mapping[str, str] | None = None,
+    ) -> M:
+        key = idempotency_key or (new_idempotency_key() if idempotent else None)
+        headers = self._headers(has_body=body is not None, idempotency_key=key, extra=extra_headers)
+        retries = self.max_retries if max_retries is None else max(0, max_retries)
+        t = self.timeout if timeout is None else timeout
+        for attempt in range(retries + 1):
+            try:
+                res = await self._client.request(method, self._url(path), json=body, headers=headers, timeout=t)
+            except httpx.TimeoutException as e:
+                if attempt < retries:
+                    await _async_sleep(self._retry_delay(None, attempt) or 0)
+                    continue
+                raise APITimeoutError() from e
+            except httpx.TransportError as e:
+                if attempt < retries:
+                    await _async_sleep(self._retry_delay(None, attempt) or 0)
+                    continue
+                raise APIConnectionError() from e
+            if res.is_success:
+                return self._parse(cls, res, key, attempt + 1)
+            err: APIError = self._error(res)
+            delay = self._retry_delay(err, attempt)
+            if attempt < retries and delay is not None:
+                await _async_sleep(delay)
+                continue
+            raise err
+        raise AssertionError("unreachable")  # pragma: no cover
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP client (if the SDK created it)."""
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncLeadsets:
+        return self
+
+    async def __aexit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        await self.aclose()