renidly 0.1.0__py3-none-any.whl

renidly/__init__.py

@@ -0,0 +1,51 @@
+"""Renidly — the official Python SDK for the Renidly B2B professional data APIs.
+
+    from renidly import Renidly
+
+    r = Renidly("rnd_...")
+    for tier in r.account.tiers():
+        print(tier.name, tier.limit_per_minute)
+"""
+from __future__ import annotations
+
+from ._client import AsyncRenidly, Renidly
+from ._config import RenidlyConfig
+from ._errors import (
+    APIConnectionError,
+    APIStatusError,
+    AuthenticationError,
+    InsufficientCreditsError,
+    InternalServerError,
+    InvalidRequestError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    RenidlyError,
+    ServiceUnavailableError,
+)
+from ._models import APIResponse, LastResponse, RenidlyModel
+from ._pagination import AsyncRenidlyList, RenidlyList
+from ._version import __version__
+
+__all__ = [
+    "Renidly",
+    "AsyncRenidly",
+    "RenidlyConfig",
+    "RenidlyModel",
+    "APIResponse",
+    "LastResponse",
+    "RenidlyList",
+    "AsyncRenidlyList",
+    "RenidlyError",
+    "APIConnectionError",
+    "APIStatusError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "InvalidRequestError",
+    "InsufficientCreditsError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServiceUnavailableError",
+    "InternalServerError",
+    "__version__",
+]

renidly/_batch.py

@@ -0,0 +1,177 @@
+"""Batch job handles for the async enrichment / verify / find endpoints.
+
+``submit`` returns a job id immediately; the handle then lets you either block
+with ``.wait()`` or consume results lazily with ``.stream()`` (a generator that
+yields items as pages resolve). Results page by an integer ``after`` cursor until
+``next_cursor`` stops advancing and ``status`` is terminal.
+"""
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Dict, Iterator, List, Optional, Type
+
+from ._models import RenidlyModel
+
+
+class BatchResult:
+    """Everything a finished (or drained) job produced."""
+
+    def __init__(self, status: str, total: int, resolved: int, errors: int, results: List[Any], not_found: List[str]):
+        self.status = status
+        self.total = total
+        self.resolved = resolved
+        self.errors = errors
+        self.results = results
+        self.not_found = not_found
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"BatchResult(status={self.status!r}, resolved={self.resolved}/{self.total}, errors={self.errors})"
+
+
+def _rows(data: Dict[str, Any], results_key: str, keyed: bool, model: Type[RenidlyModel]) -> List[Any]:
+    container = data.get(results_key)
+    out: List[Any] = []
+    if keyed and isinstance(container, dict):
+        for k, v in container.items():
+            payload = {**v, "matched_input": k} if isinstance(v, dict) else {"value": v, "matched_input": k}
+            out.append(model._build(payload, None))
+    elif isinstance(container, list):
+        for item in container:
+            out.append(model._build(item, None))
+    return out
+
+
+class _BaseJob:
+    """Shared state + cursor helpers for sync/async batch job handles."""
+
+    def __init__(self, client, service, path, job_id, *, results_key, keyed, model, options=None):
+        self._client = client
+        self._service = service
+        self._path = path
+        self.id = job_id
+        self._results_key = results_key
+        self._keyed = keyed
+        self._model = model
+        self._options = options
+
+    def _params(self, after: int) -> Dict[str, Any]:
+        return {"job_id": self.id, "after": after}
+
+
+class BatchJob(_BaseJob):
+    """A handle to an async batch job. Collect results with :meth:`wait` or :meth:`stream`."""
+
+    def _poll(self, after: int) -> Dict[str, Any]:
+        r = self._client._transport.request(
+            "GET", self._service, self._path, params=self._params(after), options=self._options
+        )
+        if r.error is not None:
+            raise r.error
+        return r.data or {}
+
+    def status(self) -> Dict[str, Any]:
+        """Current job meta (status / total / resolved / errors) without collecting."""
+        d = self._poll(0)
+        return {k: d.get(k) for k in ("status", "total", "resolved", "errors")}
+
+    def stream(self, *, poll_interval: float = 1.5, timeout: Optional[float] = None) -> Iterator[Any]:
+        """Yield each result as it resolves (a generator).
+
+        Polls the job and yields rows as pages complete, returning when the job
+        is finished. Use this to process results progressively instead of
+        blocking for the whole job with :meth:`wait`.
+
+        Example::
+
+            for row in client.emails.verify_batch(emails).stream():
+                print(row.email, row.deliverable)
+        """
+        after = 0
+        deadline = None if timeout is None else time.monotonic() + timeout
+        not_found: List[str] = []
+        while True:
+            d = self._poll(after)
+            for row in _rows(d, self._results_key, self._keyed, self._model):
+                yield row
+            for nf in d.get("not_found") or []:
+                not_found.append(nf)
+            self._last_meta = d
+            nc = d.get("next_cursor")
+            if nc is not None and nc != after:
+                after = nc
+                continue
+            if d.get("status") in ("completed", "error"):
+                self._not_found = not_found
+                return
+            if deadline is not None and time.monotonic() >= deadline:
+                self._not_found = not_found
+                return
+            time.sleep(poll_interval)
+
+    def wait(self, *, poll_interval: float = 1.5, timeout: Optional[float] = None, on_progress=None) -> BatchResult:
+        """Block until the job finishes, returning all results."""
+        results: List[Any] = []
+        for row in self.stream(poll_interval=poll_interval, timeout=timeout):
+            results.append(row)
+            if on_progress is not None:
+                on_progress(len(results))
+        m = getattr(self, "_last_meta", {})
+        return BatchResult(
+            m.get("status", "unknown"), m.get("total", 0), m.get("resolved", len(results)),
+            m.get("errors", 0), results, getattr(self, "_not_found", []),
+        )
+
+
+class AsyncBatchJob(_BaseJob):
+    """Async handle to a batch job. See :class:`BatchJob`."""
+
+    async def _poll(self, after: int) -> Dict[str, Any]:
+        r = await self._client._transport.request(
+            "GET", self._service, self._path, params=self._params(after), options=self._options
+        )
+        if r.error is not None:
+            raise r.error
+        return r.data or {}
+
+    async def status(self) -> Dict[str, Any]:
+        """Current job meta (status/total/resolved/errors). See :meth:`BatchJob.status`."""
+        d = await self._poll(0)
+        return {k: d.get(k) for k in ("status", "total", "resolved", "errors")}
+
+    async def stream(self, *, poll_interval: float = 1.5, timeout: Optional[float] = None):
+        """Async generator yielding results as they resolve. See :meth:`BatchJob.stream`."""
+        after = 0
+        deadline = None if timeout is None else time.monotonic() + timeout
+        not_found: List[str] = []
+        while True:
+            d = await self._poll(after)
+            for row in _rows(d, self._results_key, self._keyed, self._model):
+                yield row
+            for nf in d.get("not_found") or []:
+                not_found.append(nf)
+            self._last_meta = d
+            nc = d.get("next_cursor")
+            if nc is not None and nc != after:
+                after = nc
+                continue
+            if d.get("status") in ("completed", "error"):
+                self._not_found = not_found
+                return
+            if deadline is not None and time.monotonic() >= deadline:
+                self._not_found = not_found
+                return
+            await asyncio.sleep(poll_interval)
+
+    async def wait(self, *, poll_interval: float = 1.5, timeout: Optional[float] = None, on_progress=None) -> BatchResult:
+        """Await until the job finishes, returning all results. See :meth:`BatchJob.wait`."""
+        results: List[Any] = []
+        async for row in self.stream(poll_interval=poll_interval, timeout=timeout):
+            results.append(row)
+            if on_progress is not None:
+                on_progress(len(results))
+        m = getattr(self, "_last_meta", {})
+        return BatchResult(
+            m.get("status", "unknown"), m.get("total", 0), m.get("resolved", len(results)),
+            m.get("errors", 0), results, getattr(self, "_not_found", []),
+        )

renidly/_client.py

@@ -0,0 +1,122 @@
+"""The public clients: ``Renidly`` (sync) and ``AsyncRenidly`` (async).
+
+Same surface, same method names; the async client just needs ``await``. Product
+namespaces hang off the client: ``r.data``, ``r.live``, ``r.emails``, ``r.account``.
+
+Configuration goes through one object, :class:`RenidlyConfig`, so there is a
+single place (with autocomplete) for every option::
+
+    from renidly import Renidly, RenidlyConfig
+    client = Renidly("rnd-...", config=RenidlyConfig(timeout=10, auto_rate_limit=True))
+
+``api_key`` may be passed positionally for convenience; it overrides
+``config.api_key`` and falls back to the ``RENIDLY_API_KEY`` env var.
+"""
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import Any, Dict, Optional
+
+import httpx
+
+from ._config import RenidlyConfig
+from ._models import APIResponse
+from ._ratelimit import build_async_limiter, build_sync_limiter
+from ._transport import AsyncTransport, SyncTransport
+from .resources.account import Account, AsyncAccount
+from .resources.data import AsyncData, Data
+from .resources.emails import AsyncEmails, Emails
+from .resources.live import AsyncLive, Live
+
+
+def _resolve(api_key: Optional[str], config: Optional[RenidlyConfig]) -> RenidlyConfig:
+    cfg = replace(config) if config is not None else RenidlyConfig()  # copy; never mutate the caller's
+    if api_key is not None:
+        cfg.api_key = api_key
+    return cfg
+
+
+class Renidly:
+    """Synchronous Renidly client. See :class:`RenidlyConfig` for all options."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        config: Optional[RenidlyConfig] = None,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self._config = _resolve(api_key, config)
+        self._transport = SyncTransport(self._config, client=http_client)
+        self._transport._limiter = build_sync_limiter(self._config, self._transport)
+        self.account = Account(self)
+        self.data = Data(self)
+        self.emails = Emails(self)
+        self.live = Live(self)
+
+    def raw_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        service: str = "data",
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+        options: Optional[Dict[str, Any]] = None,
+    ) -> APIResponse:
+        """Escape hatch: call any endpoint directly; returns the raw envelope."""
+        r = self._transport.request(method, service, path, params=params, json=json, options=options)
+        return APIResponse._build(r.envelope, r.last_response)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client and release its connections."""
+        self._transport.close()
+
+    def __enter__(self) -> "Renidly":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+class AsyncRenidly:
+    """Asynchronous Renidly client. See :class:`RenidlyConfig` for all options."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        config: Optional[RenidlyConfig] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._config = _resolve(api_key, config)
+        self._transport = AsyncTransport(self._config, client=http_client)
+        self._transport._limiter = build_async_limiter(self._config, self._transport)
+        self.account = AsyncAccount(self)
+        self.data = AsyncData(self)
+        self.emails = AsyncEmails(self)
+        self.live = AsyncLive(self)
+
+    async def raw_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        service: str = "data",
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+        options: Optional[Dict[str, Any]] = None,
+    ) -> APIResponse:
+        """Async escape hatch — call any endpoint directly. See :meth:`Renidly.raw_request`."""
+        r = await self._transport.request(method, service, path, params=params, json=json, options=options)
+        return APIResponse._build(r.envelope, r.last_response)
+
+    async def close(self) -> None:
+        """Close the underlying async HTTP client."""
+        await self._transport.close()
+
+    async def __aenter__(self) -> "AsyncRenidly":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()

renidly/_config.py

@@ -0,0 +1,86 @@
+"""Client configuration and the service routing table.
+
+``RenidlyConfig`` is the public, user-facing config object — build it with just
+the fields you care about and pass ``Renidly(config=...)``. The four products
+live under one host but different path prefixes, and the Account product uses a
+*different* auth header (``X-AUTHAPI-Key``); the SDK hides that entirely.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+
+DEFAULT_BASE_URL = "https://renidly.com"
+DATA_HEADER = "X-renidly-apikey"
+ACCOUNT_HEADER = "X-AUTHAPI-Key"
+
+# service -> (path prefix, auth header)
+SERVICES: Dict[str, tuple] = {
+    "data": ("/api/data/v1", DATA_HEADER),
+    "live": ("/api/v2", DATA_HEADER),
+    "emails": ("/api/emails/v1", DATA_HEADER),
+    "account": ("/api/panel", ACCOUNT_HEADER),
+}
+
+
+@dataclass
+class RenidlyConfig:
+    """Client configuration. Every field is optional and has a sensible default.
+
+    Build only what you need::
+
+        from renidly import Renidly, RenidlyConfig
+        cfg = RenidlyConfig(timeout=10, max_retries=5, auto_rate_limit=True)
+        client = Renidly("rnd-...", config=cfg)
+    """
+
+    api_key: Optional[str] = None
+    """API key. Falls back to the ``RENIDLY_API_KEY`` env var. The client's
+    positional ``api_key`` argument, if given, takes precedence over this."""
+    timeout: float = 30.0
+    """Per-request timeout in seconds."""
+    max_retries: int = 2
+    """Auto-retries on 429 / 503 / connection errors (exponential backoff + jitter)."""
+    backoff_factor: float = 0.5
+    """Base seconds for the exponential backoff between retries."""
+    base_url: str = DEFAULT_BASE_URL
+    """Override the API host (e.g. a staging environment)."""
+    proxy: Optional[str] = None
+    """HTTP(S) proxy URL."""
+    default_headers: Dict[str, str] = field(default_factory=dict)
+    """Extra headers sent on every request."""
+
+    # ── Behavior flags ──
+    unwrap_data_obj: bool = True
+    """Return the unwrapped ``data`` model. If False, return the full envelope."""
+    raise_on_not_found: bool = False
+    """Single lookups: raise ``NotFoundError`` instead of returning ``None`` when empty."""
+    raise_on_api_error: bool = True
+    """Map ``success:false`` responses to typed exceptions."""
+
+    # ── Built-in client-side rate limiting ──
+    auto_rate_limit: bool = False
+    """Throttle requests to stay under your per-minute limit automatically."""
+    rate_limit_per_minute: Optional[int] = None
+    """Fixed per-minute limit. REQUIRED for enterprise keys; optional override otherwise."""
+    rate_limit_safety: float = 1.0
+    """Fraction of the limit to target (e.g. 0.9 leaves headroom for clock skew)."""
+    rate_limit_refresh: float = 300.0
+    """Seconds between tier re-fetches for auto-fetched (non-fixed) limits."""
+
+    def __post_init__(self) -> None:
+        if self.api_key is None:
+            self.api_key = os.environ.get("RENIDLY_API_KEY")
+        self.base_url = self.base_url.rstrip("/")
+
+    def _url_for(self, service: str, path: str) -> str:
+        prefix, _ = SERVICES[service]
+        return f"{self.base_url}{prefix}{path}"
+
+    def _auth_header_for(self, service: str) -> str:
+        _, header = SERVICES[service]
+        return header
+
+
+Config = RenidlyConfig  # internal alias

renidly/_errors.py

@@ -0,0 +1,105 @@
+"""Typed exception hierarchy, mapped from the shared response envelope.
+
+Every request that fails raises a subclass of :class:`RenidlyError`. Catch the
+specific class you care about, or ``RenidlyError`` for all of them.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class RenidlyError(Exception):
+    """Base class for every error raised by the SDK."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        error_code: Optional[str] = None,
+        errors: Optional[Dict[str, Any]] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        #: The clean, top-level server message (e.g. "Validation failed").
+        self.message = message
+        self.status_code = status_code
+        self.error_code = error_code
+        #: Field-level detail (``{field: reason}``) — the *why* behind the message.
+        self.errors = errors or {}
+        self.request_id = request_id
+        # The exception's str() includes everything, so an uncaught traceback (or
+        # a plain print/log) shows exactly what went wrong — not just "Validation
+        # failed". Example: "Validation failed — name: must be at least 3 characters
+        # (VALIDATION_ERROR, request_id=req_1)".
+        super().__init__(self._full_message())
+
+    def _full_message(self) -> str:
+        detail = self.message
+        if self.errors:
+            fields = "; ".join(f"{k}: {v}" for k, v in self.errors.items())
+            detail = f"{detail} — {fields}" if fields else detail
+        meta = []
+        if self.error_code:
+            meta.append(str(self.error_code))
+        if self.status_code:
+            meta.append(f"HTTP {self.status_code}")
+        if self.request_id:
+            meta.append(f"request_id={self.request_id}")
+        return f"{detail} ({', '.join(meta)})" if meta else detail
+
+    def __repr__(self) -> str:  # pragma: no cover - debug aid
+        return (
+            f"{type(self).__name__}(message={self.message!r}, "
+            f"status_code={self.status_code!r}, error_code={self.error_code!r})"
+        )
+
+
+class APIConnectionError(RenidlyError):
+    """The request never reached the API (network failure, timeout, DNS…)."""
+
+
+class APIStatusError(RenidlyError):
+    """The API returned a non-success response. Base of all HTTP-status errors."""
+
+
+class AuthenticationError(APIStatusError):
+    """Missing or invalid API key (HTTP 401 / 403)."""
+
+
+class PermissionDeniedError(APIStatusError):
+    """Key is valid but not allowed here — premium-gated or opted-out (HTTP 403)."""
+
+
+class InvalidRequestError(APIStatusError):
+    """Request failed validation (HTTP 400 / 422). See :attr:`field_errors`."""
+
+    @property
+    def field_errors(self) -> Dict[str, Any]:
+        return self.errors
+
+
+class InsufficientCreditsError(APIStatusError):
+    """Not enough credits for the request (HTTP 402 / 403)."""
+
+
+class NotFoundError(APIStatusError):
+    """A lookup resolved nothing, or a batch job was not found / expired."""
+
+
+class RateLimitError(APIStatusError):
+    """Per-minute rate limit for your tier exceeded (HTTP 429)."""
+
+    def __init__(self, message: str, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        meta = self.errors or {}
+        self.tier: Optional[str] = meta.get("current_tier") or meta.get("tier")
+        self.limit: Optional[int] = meta.get("current_limit") or meta.get("limit")
+        self.retry_after: Optional[float] = meta.get("retry_after")
+
+
+class ServiceUnavailableError(APIStatusError):
+    """Temporarily unavailable — safe to retry shortly (HTTP 503)."""
+
+
+class InternalServerError(APIStatusError):
+    """Unexpected server error (HTTP 5xx)."""

renidly/_models.py

@@ -0,0 +1,73 @@
+"""Base response model and envelope wrapper.
+
+Models are permissive (``extra="allow"``) so every field the API returns is
+accessible as an attribute even before a typed model is generated for it — the
+generated subclasses in ``renidly.types`` add precise typing + autocomplete on
+top of the same base.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Type, TypeVar
+
+from pydantic import BaseModel, ConfigDict, PrivateAttr
+
+T = TypeVar("T", bound="RenidlyModel")
+
+
+class LastResponse:
+    """HTTP metadata from the call that produced an object."""
+
+    __slots__ = ("status_code", "headers", "request_id")
+
+    def __init__(self, status_code: int, headers: Dict[str, str], request_id: Optional[str]) -> None:
+        self.status_code = status_code
+        self.headers = headers
+        self.request_id = request_id
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"LastResponse(status_code={self.status_code}, request_id={self.request_id!r})"
+
+
+class RenidlyModel(BaseModel):
+    """Base for every response object. Dynamic + typed."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True, arbitrary_types_allowed=True)
+
+    _last_response: Optional[LastResponse] = PrivateAttr(default=None)
+
+    @property
+    def last_response(self) -> Optional[LastResponse]:
+        """HTTP status/headers/request-id of the response that produced this object."""
+        return self._last_response
+
+    @classmethod
+    def _coerce(cls, v: Any) -> Any:
+        """Recursively wrap nested dicts/lists so ``obj.a.b`` works dynamically.
+
+        Nested values become the base ``RenidlyModel`` (typed subclasses declare
+        their own nested fields and validate natively, bypassing this)."""
+        if isinstance(v, dict):
+            return RenidlyModel.model_validate({k: RenidlyModel._coerce(val) for k, val in v.items()})
+        if isinstance(v, list):
+            return [RenidlyModel._coerce(x) for x in v]
+        return v
+
+    @classmethod
+    def _build(cls: Type[T], data: Any, last_response: Optional[LastResponse]) -> T:
+        if isinstance(data, dict):
+            obj = cls.model_validate({k: RenidlyModel._coerce(v) for k, v in data.items()})
+        else:
+            obj = cls.model_validate({"value": data})
+        obj._last_response = last_response
+        return obj
+
+
+class APIResponse(RenidlyModel):
+    """The full shared envelope, returned when ``unwrap_data_obj=False``."""
+
+    success: bool
+    status_code: Optional[int] = None
+    message: Optional[str] = None
+    error_code: Optional[str] = None
+    errors: Optional[Any] = None
+    data: Optional[Any] = None