paravane 0.2.0__py3-none-any.whl

paravane/__init__.py

@@ -0,0 +1,39 @@
+"""Python SDK for the Paravane API."""
+
+from paravane._version import __version__
+from paravane.client import ParavaneClient
+from paravane.errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    ParavaneError,
+    PermissionDeniedError,
+    QuotaExceededError,
+    RateLimitError,
+    ValidationError,
+)
+from paravane.types import (
+    AnalysisProfile,
+    CompanyValidityBeta,
+    DomainSignal,
+    SmtpRsAnalysis,
+)
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "AnalysisProfile",
+    "AuthenticationError",
+    "ConfigurationError",
+    "CompanyValidityBeta",
+    "DomainSignal",
+    "ParavaneClient",
+    "ParavaneError",
+    "PermissionDeniedError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "SmtpRsAnalysis",
+    "ValidationError",
+    "__version__",
+]

paravane/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

paravane/client.py

@@ -0,0 +1,49 @@
+"""Client entrypoint for the Paravane SDK."""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+import requests
+
+from paravane.errors import ConfigurationError
+from paravane.http import HTTPClient
+from paravane.smtprs import SmtpRsResource
+
+
+class ParavaneClient:
+    """Client for Paravane APIs.
+
+    Parameters can be supplied directly or through environment variables:
+    ``PARAVANE_API_KEY`` and ``PARAVANE_BASE_URL``.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 15.0,
+        max_network_retries: int = 0,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        resolved_api_key = api_key or os.getenv("PARAVANE_API_KEY")
+        if not resolved_api_key:
+            raise ConfigurationError(
+                "Missing Paravane API key. Pass api_key=... or set PARAVANE_API_KEY."
+            )
+
+        resolved_base_url = base_url or os.getenv("PARAVANE_BASE_URL") or "https://api.paravane.io"
+        self.api_key = resolved_api_key
+        self.base_url = resolved_base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_network_retries = max_network_retries
+        self._http = HTTPClient(
+            api_key=self.api_key,
+            base_url=self.base_url,
+            timeout=self.timeout,
+            max_network_retries=max_network_retries,
+            session=session,
+        )
+        self.smtprs = SmtpRsResource(self._http)

paravane/errors.py

@@ -0,0 +1,67 @@
+"""Exception hierarchy for the Paravane SDK."""
+
+from typing import Any, Dict, Optional
+
+
+class ParavaneError(Exception):
+    """Base class for all SDK errors."""
+
+
+class ConfigurationError(ParavaneError):
+    """Raised when the client is missing required configuration."""
+
+
+class APIConnectionError(ParavaneError):
+    """Raised when the SDK cannot reach the API."""
+
+
+class APIError(ParavaneError):
+    """Raised when the API returns an unsuccessful response."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        code: Optional[str] = None,
+        response: Optional[Dict[str, Any]] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.response = response
+        self.request_id = request_id
+
+    def __str__(self) -> str:
+        details = []
+        if self.status_code:
+            details.append(f"status_code={self.status_code}")
+        if self.code:
+            details.append(f"code={self.code}")
+        if self.request_id:
+            details.append(f"request_id={self.request_id}")
+        if not details:
+            return self.message
+        return f"{self.message} ({', '.join(details)})"
+
+
+class AuthenticationError(APIError):
+    """Raised when an API key is missing or invalid."""
+
+
+class PermissionDeniedError(APIError):
+    """Raised when the API key does not have access to a resource."""
+
+
+class ValidationError(APIError):
+    """Raised when request validation fails."""
+
+
+class QuotaExceededError(APIError):
+    """Raised when a workspace has exhausted its plan quota."""
+
+
+class RateLimitError(APIError):
+    """Raised when the API rate limit is exceeded."""

paravane/http.py

@@ -0,0 +1,166 @@
+"""Low-level HTTP transport for Paravane API requests."""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, Dict, Mapping, Optional
+
+import requests
+
+from paravane._version import __version__
+from paravane.errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    PermissionDeniedError,
+    QuotaExceededError,
+    RateLimitError,
+    ValidationError,
+)
+
+
+class HTTPClient:
+    """Small requests-based HTTP client used by resource classes."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        timeout: float,
+        max_network_retries: int,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_network_retries = max(0, int(max_network_retries))
+        self.session = session or requests.Session()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Optional[Mapping[str, Any]] = None,
+        params: Optional[Mapping[str, Any]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        timeout: Optional[float] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        url = f"{self.base_url}{path}"
+        request_headers = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "User-Agent": f"paravane-python/{__version__}",
+            "X-API-Key": self.api_key,
+        }
+        if idempotency_key:
+            request_headers["Idempotency-Key"] = idempotency_key
+        if headers:
+            request_headers.update(headers)
+
+        attempt = 0
+        while True:
+            try:
+                response = self.session.request(
+                    method,
+                    url,
+                    json=dict(json_body) if json_body is not None else None,
+                    params=dict(params) if params is not None else None,
+                    headers=request_headers,
+                    timeout=self.timeout if timeout is None else timeout,
+                )
+            except requests.RequestException as exc:
+                if attempt >= self.max_network_retries:
+                    raise APIConnectionError(f"Could not connect to Paravane API: {exc}") from exc
+                self._sleep_before_retry(attempt)
+                attempt += 1
+                continue
+
+            if response.status_code < 400:
+                return self._decode_response(response)
+
+            error = self._build_api_error(response)
+            if self._should_retry(response.status_code, attempt):
+                self._sleep_before_retry(attempt)
+                attempt += 1
+                continue
+            raise error
+
+    def _decode_response(self, response: requests.Response) -> Dict[str, Any]:
+        if not response.content:
+            return {}
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise APIError(
+                "Paravane API returned a non-JSON response.",
+                status_code=response.status_code,
+                request_id=response.headers.get("X-Request-Id"),
+            ) from exc
+        if not isinstance(payload, dict):
+            return {"data": payload}
+        return payload
+
+    def _build_api_error(self, response: requests.Response) -> APIError:
+        request_id = response.headers.get("X-Request-Id")
+        payload: Dict[str, Any]
+        try:
+            decoded = response.json()
+            payload = decoded if isinstance(decoded, dict) else {"error": decoded}
+        except (ValueError, json.JSONDecodeError):
+            payload = {"error": response.text}
+
+        code = self._extract_code(payload)
+        message = self._extract_message(payload)
+        error_cls = self._error_class(response.status_code, code, message)
+        return error_cls(
+            message,
+            status_code=response.status_code,
+            code=code,
+            response=payload,
+            request_id=request_id,
+        )
+
+    def _extract_code(self, payload: Mapping[str, Any]) -> Optional[str]:
+        error = payload.get("error")
+        if isinstance(error, dict):
+            code = error.get("code") or error.get("type")
+            return str(code) if code else None
+        code = payload.get("code")
+        return str(code) if code else None
+
+    def _extract_message(self, payload: Mapping[str, Any]) -> str:
+        error = payload.get("error")
+        if isinstance(error, dict):
+            message = error.get("message") or error.get("detail")
+            if message:
+                return str(message)
+        if isinstance(error, str) and error:
+            return error
+        for key in ("message", "detail"):
+            if payload.get(key):
+                return str(payload[key])
+        return "Paravane API request failed."
+
+    def _error_class(self, status_code: int, code: Optional[str], message: str):
+        folded = f"{code or ''} {message}".lower()
+        if status_code == 400 or status_code == 422:
+            return ValidationError
+        if status_code == 401:
+            return AuthenticationError
+        if status_code == 403:
+            return PermissionDeniedError
+        if status_code == 402 or "quota" in folded or "credit_limit" in folded:
+            return QuotaExceededError
+        if status_code == 429:
+            return RateLimitError
+        return APIError
+
+    def _should_retry(self, status_code: int, attempt: int) -> bool:
+        return attempt < self.max_network_retries and (status_code == 429 or status_code >= 500)
+
+    def _sleep_before_retry(self, attempt: int) -> None:
+        time.sleep(min(0.5 * (2**attempt), 2.0))

paravane/py.typed

@@ -0,0 +1 @@
+

paravane/smtprs.py

@@ -0,0 +1,68 @@
+"""smtpRS resource helpers."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional
+
+from paravane.http import HTTPClient
+from paravane.types import AnalysisProfile, SmtpRsAnalysis
+
+
+class SmtpRsResource:
+    """Access smtpRS email risk intelligence endpoints."""
+
+    def __init__(self, http_client: HTTPClient) -> None:
+        self._http = http_client
+
+    def analyze(
+        self,
+        email: str,
+        *,
+        profile: Optional[AnalysisProfile] = None,
+        disposable_only: Optional[bool] = None,
+        strict_disposable: Optional[bool] = None,
+        guess: Optional[bool] = None,
+        run_catch_all: Optional[bool] = None,
+        company_validity_beta: Optional[bool] = None,
+        fast: Optional[bool] = None,
+        extra_params: Optional[Mapping[str, Any]] = None,
+        tenant_id: Optional[str] = None,
+        timeout: Optional[float] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> SmtpRsAnalysis:
+        """Analyze one email address with smtpRS.
+
+        ``profile`` selects a complete public analysis mode. The older Boolean
+        mode flags remain available for compatibility but are deprecated by the
+        API. ``company_validity_beta`` opts an eligible paid request into the
+        optional company-domain context.
+        Unknown future parameters can be supplied with ``extra_params``.
+        """
+
+        params: Dict[str, Any] = {
+            "profile": profile,
+            "disposable_only": disposable_only,
+            "strict_disposable": strict_disposable,
+            "guess": guess,
+            "run_catch_all": run_catch_all,
+            # Keep this absent unless explicitly set so existing callers retain
+            # the server's default, scoring-neutral behavior.
+            "company_validity_beta": company_validity_beta,
+            "fast": fast,
+        }
+        if extra_params:
+            params.update(extra_params)
+        clean_params = {key: value for key, value in params.items() if value is not None}
+        body: Dict[str, Any] = {"email": email}
+        if tenant_id is not None:
+            body["tenant_id"] = tenant_id
+
+        payload = self._http.request(
+            "POST",
+            "/v1/analyse",
+            json_body=body,
+            params=clean_params,
+            timeout=timeout,
+            idempotency_key=idempotency_key,
+        )
+        return SmtpRsAnalysis.from_dict(payload)

paravane/types.py

@@ -0,0 +1,172 @@
+"""Typed response helpers returned by the SDK."""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Literal, Mapping, Optional
+
+AnalysisProfile = Literal["quick", "standard", "adaptive", "deep", "catch_all"]
+
+
+def _optional_bool(value: Any) -> Optional[bool]:
+    return value if isinstance(value, bool) else None
+
+
+def _first_present(data: Mapping[str, Any], *keys: str) -> Any:
+    for key in keys:
+        if key in data:
+            return data[key]
+    return None
+
+
+@dataclass(frozen=True)
+class CompanyValidityBeta:
+    """Beta metadata returned when company-validity support is available."""
+
+    feature: Optional[str] = None
+    status: Optional[str] = None
+    requested: bool = False
+    enabled: bool = False
+    availability: Optional[str] = None
+    additional_credit_cost: Optional[int] = None
+    notes: List[str] = field(default_factory=list)
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, payload: Mapping[str, Any]) -> "CompanyValidityBeta":
+        data = dict(payload)
+        notes = data.get("notes") if isinstance(data.get("notes"), list) else []
+        return cls(
+            feature=data.get("feature"),
+            status=data.get("status"),
+            requested=bool(data.get("requested")),
+            enabled=bool(data.get("enabled")),
+            availability=data.get("availability"),
+            additional_credit_cost=data.get("additional_credit_cost"),
+            notes=[str(note) for note in notes],
+            raw=data,
+        )
+
+
+@dataclass(frozen=True)
+class DomainSignal:
+    """Normalized public facts about an email domain and its mail posture."""
+
+    contract_version: Optional[str] = None
+    domain: Optional[str] = None
+    registrable_domain: Optional[str] = None
+    domain_status: Optional[str] = None
+    domain_exists: Optional[bool] = None
+    mail_status: Optional[str] = None
+    mail_capable: Optional[bool] = None
+    mail_usage: Optional[str] = None
+    spf_present: Optional[bool] = None
+    dmarc_present: Optional[bool] = None
+    organization_status: Optional[str] = None
+    organization_backed: Optional[bool] = None
+    organization_known: Optional[bool] = None
+    organization_verified: Optional[bool] = None
+    organization_confidence: Optional[str] = None
+    company_valid: Optional[bool] = None
+    company_confidence: Optional[str] = None
+    company_checked_at: Optional[str] = None
+    evaluated_at: Optional[str] = None
+    reason_codes: List[str] = field(default_factory=list)
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, payload: Mapping[str, Any]) -> "DomainSignal":
+        data = dict(payload)
+        reason_codes = (
+            data.get("reason_codes") if isinstance(data.get("reason_codes"), list) else []
+        )
+        return cls(
+            contract_version=data.get("contract_version"),
+            domain=data.get("domain"),
+            registrable_domain=data.get("registrable_domain"),
+            domain_status=data.get("domain_status"),
+            domain_exists=_optional_bool(data.get("domain_exists")),
+            mail_status=data.get("mail_status"),
+            mail_capable=_optional_bool(data.get("mail_capable")),
+            mail_usage=data.get("mail_usage"),
+            spf_present=_optional_bool(data.get("spf_present")),
+            dmarc_present=_optional_bool(data.get("dmarc_present")),
+            organization_status=data.get("organization_status"),
+            organization_backed=_optional_bool(data.get("organization_backed")),
+            organization_known=_optional_bool(data.get("organization_known")),
+            organization_verified=_optional_bool(data.get("organization_verified")),
+            organization_confidence=data.get("organization_confidence"),
+            company_valid=_optional_bool(data.get("company_valid")),
+            company_confidence=data.get("company_confidence"),
+            company_checked_at=data.get("company_checked_at"),
+            evaluated_at=data.get("evaluated_at"),
+            reason_codes=[str(code) for code in reason_codes],
+            raw=data,
+        )
+
+
+@dataclass(frozen=True)
+class SmtpRsAnalysis:
+    """A normalized smtpRS analyse response with the raw payload preserved."""
+
+    email: Optional[str] = None
+    decision: Optional[str] = None
+    overall_risk: Optional[float] = None
+    tier: Optional[str] = None
+    analysis_profile: Optional[str] = None
+    response_profile: Optional[str] = None
+    credit_cost: Optional[int] = None
+    credits_charged: Optional[int] = None
+    reasons: List[str] = field(default_factory=list)
+    usage: Dict[str, Any] = field(default_factory=dict)
+    raw: Dict[str, Any] = field(default_factory=dict)
+    # Appended to preserve the positional field order of the 0.1.0 dataclass.
+    company_validity_beta: Optional[CompanyValidityBeta] = None
+    raw_risk: Optional[float] = None
+    raw_decision: Optional[str] = None
+    organization_validity_enabled: Optional[bool] = None
+    organization_adjustment: Optional[float] = None
+    domain_signal: Optional[DomainSignal] = None
+
+    @classmethod
+    def from_dict(cls, payload: Mapping[str, Any]) -> "SmtpRsAnalysis":
+        data = dict(payload)
+        usage = data.get("usage") if isinstance(data.get("usage"), dict) else {}
+        reasons = data.get("reasons") if isinstance(data.get("reasons"), list) else []
+        company_validity_data = data.get("company_validity_beta")
+        company_validity_beta = (
+            CompanyValidityBeta.from_dict(company_validity_data)
+            if isinstance(company_validity_data, Mapping)
+            else None
+        )
+        domain_signal_data = data.get("domain_signal")
+        domain_signal = (
+            DomainSignal.from_dict(domain_signal_data)
+            if isinstance(domain_signal_data, Mapping)
+            else None
+        )
+
+        return cls(
+            email=data.get("email") or data.get("input"),
+            decision=data.get("decision"),
+            overall_risk=_first_present(data, "overall_risk", "risk_score"),
+            tier=data.get("tier"),
+            analysis_profile=data.get("analysis_profile"),
+            response_profile=data.get("response_profile"),
+            credit_cost=data.get("credit_cost"),
+            credits_charged=data.get("credits_charged"),
+            company_validity_beta=company_validity_beta,
+            raw_risk=data.get("raw_risk"),
+            raw_decision=data.get("raw_decision"),
+            organization_validity_enabled=_optional_bool(
+                data.get("organization_validity_enabled")
+            ),
+            organization_adjustment=data.get("organization_adjustment"),
+            domain_signal=domain_signal,
+            reasons=[str(reason) for reason in reasons],
+            usage=dict(usage),
+            raw=data,
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the original API response payload."""
+
+        return dict(self.raw)

paravane-0.2.0.dist-info/METADATA

@@ -0,0 +1,697 @@
+Metadata-Version: 2.4
+Name: paravane
+Version: 0.2.0
+Summary: Python SDK for the Paravane API.
+Author-email: Paravane Labs <contact@paravane.io>
+License: MIT License
+        
+        Copyright (c) 2026 Paravane Labs
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://paravane.io
+Project-URL: Documentation, https://paravane.io/pages/docs/index.html
+Project-URL: Changelog, https://github.com/paravaneai/paravane-python/blob/main/CHANGELOG.md
+Project-URL: Source, https://github.com/paravaneai/paravane-python
+Project-URL: Issues, https://github.com/paravaneai/paravane-python/issues
+Keywords: paravane,smtprs,email risk,api,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.1; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: setuptools>=61.0; extra == "dev"
+Requires-Dist: tomli>=2.0.0; python_version < "3.11" and extra == "dev"
+Requires-Dist: twine>=5.1.0; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <picture>
+    <source
+      media="(prefers-color-scheme: light)"
+      srcset="https://raw.githubusercontent.com/paravaneai/paravane-python/main/doc/images/readme/paravane-smtprs-sdk-readme-banner-logo-matched-orange-dark-developer-api-upscaled-3x.png" />
+    <img
+      src="https://raw.githubusercontent.com/paravaneai/paravane-python/main/doc/images/readme/paravane-smtprs-sdk-readme-banner-logo-matched-orange-dark-developer-api-upscaled-3x.png"
+      alt="Paravane" />
+  </picture>
+</p>
+
+<h1 align="center">
+  Paravane Python Library
+</h1>
+
+<p align="center">
+  The Paravane Python library provides convenient access to the Paravane API from applications written in Python.
+  <br /><br />
+  The first supported product API is <strong>smtpRS</strong>, Paravane's email risk intelligence API.
+  smtpRS helps score email addresses for onboarding, trust, review, abuse-prevention, and operations workflows.
+  <br /><br />
+  This SDK is intentionally small at the start. It provides a stable client entrypoint,
+  request serialization, response helpers, structured errors, examples, tests, and packaging
+  conventions that can grow as Paravane adds more APIs.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/paravane/">
+    <img
+      src="https://img.shields.io/pypi/v/paravane.svg"
+      alt="PyPI" />
+  </a>
+  <a href="https://pypi.org/project/paravane/">
+    <img
+      src="https://img.shields.io/pypi/pyversions/paravane.svg"
+      alt="Supported Python versions" />
+  </a>
+  <a href="https://github.com/paravaneai/paravane-python/actions/workflows/tests.yml">
+    <img
+      src="https://github.com/paravaneai/paravane-python/actions/workflows/tests.yml/badge.svg"
+      alt="Tests" />
+  </a>
+</p>
+
+<h3 align="center">
+  <a href="#documentation">Documentation</a>
+  <span> · </span>
+  <a href="#installation">Installation</a>
+  <span> · </span>
+  <a href="#quickstart">Quickstart</a>
+  <span> · </span>
+  <a href="#examples">Examples</a>
+  <span> · </span>
+  <a href="#development">Development</a>
+</h3>
+
+## Contents
+
+- [Documentation](#documentation)
+- [Installation](#installation)
+- [Requirements](#requirements)
+- [Quickstart](#quickstart)
+- [Usage](#usage)
+- [smtpRS](#smtprs)
+- [Configuration](#configuration)
+- [Per-request options](#per-request-options)
+- [Custom HTTP sessions](#custom-http-sessions)
+- [Retries](#retries)
+- [Idempotency](#idempotency)
+- [Errors](#errors)
+- [Responses and raw data](#responses-and-raw-data)
+- [Types](#types)
+- [Logging](#logging)
+- [Examples](#examples)
+- [Development](#development)
+- [Repository layout](#repository-layout)
+- [Versioning](#versioning)
+- [Security](#security)
+- [Support](#support)
+
+## Documentation
+
+- Product docs: https://paravane.io/pages/docs/index.html
+- smtpRS docs: https://paravane.io/pages/docs/smtprs/index.html
+- Analyse endpoint: https://paravane.io/pages/docs/smtprs/analyse.html
+- Plans and limits: https://paravane.io/pages/docs/smtprs/plans-limits.html
+
+## Installation
+
+Install the latest release from PyPI:
+
+```bash
+python -m pip install --upgrade paravane
+```
+
+To install the current development version directly from GitHub:
+
+```bash
+python -m pip install "git+https://github.com/paravaneai/paravane-python.git"
+```
+
+For local development:
+
+```bash
+git clone git@github.com:paravaneai/paravane-python.git
+cd paravane-python
+python -m pip install -e ".[dev]"
+```
+
+## Requirements
+
+Python 3.8 or newer.
+
+Runtime dependency:
+
+- `requests>=2.31.0`
+
+Development dependencies are installed with:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Quickstart
+
+Set your API key:
+
+```bash
+export PARAVANE_API_KEY="pvn_live_..."
+```
+
+On Windows PowerShell:
+
+```powershell
+$env:PARAVANE_API_KEY = "pvn_live_..."
+```
+
+Call smtpRS:
+
+```python
+from paravane import ParavaneClient
+
+client = ParavaneClient()
+
+result = client.smtprs.analyze("alice@example.com")
+
+print(result.decision)
+print(result.overall_risk)
+print(result.credits_charged)
+```
+
+The SDK method is named `analyze(...)` for Python readability. The HTTP API endpoint remains:
+
+```text
+POST /v1/analyse
+```
+
+## Usage
+
+Create a client with an API key:
+
+```python
+from paravane import ParavaneClient
+
+client = ParavaneClient(api_key="pvn_live_...")
+```
+
+Or use `PARAVANE_API_KEY`:
+
+```python
+from paravane import ParavaneClient
+
+client = ParavaneClient()
+```
+
+Run an email risk analysis:
+
+```python
+result = client.smtprs.analyze("person@example.com")
+
+if result.decision == "allow":
+    print("Continue")
+else:
+    print("Review or block")
+```
+
+Inspect the normalized response:
+
+```python
+print(result.email)
+print(result.decision)
+print(result.overall_risk)
+print(result.analysis_profile)
+print(result.credit_cost)
+print(result.usage)
+```
+
+Access the original API response:
+
+```python
+raw = result.to_dict()
+print(raw)
+```
+
+## smtpRS
+
+smtpRS is available through:
+
+```python
+client.smtprs
+```
+
+### Analysis profiles
+
+smtpRS provides named profiles so applications can choose the appropriate balance of
+coverage, latency, and credit usage without configuring individual checks.
+
+| Profile | Credits | Availability | Intended use |
+| --- | ---: | --- | --- |
+| `quick` | 1 | All plans | Lightweight screening; this is the default. |
+| `standard` | 3 | Basic and above | Broader passive analysis. |
+| `adaptive` | 5 | Pro and above | Adds checks when the initial result needs more context. |
+| `deep` | 5 | Pro and above | Comprehensive analysis without catch-all probing. |
+| `catch_all` | 20 | Enterprise or entitled accounts | Deep analysis with catch-all probing. |
+
+Use the default quick profile:
+
+```python
+result = client.smtprs.analyze("person@example.com")
+```
+
+Or request another profile available to your account:
+
+```python
+result = client.smtprs.analyze(
+    "person@example.com",
+    profile="standard",
+)
+```
+
+Profile availability is enforced by the API. Requesting a profile that is not included
+with the current plan raises `PermissionDeniedError`.
+
+### Legacy mode flags
+
+The older `disposable_only`, `strict_disposable`, `guess`, and `run_catch_all` arguments
+remain available for compatibility. New integrations should use `profile` instead. Do not
+combine `profile` with an enabled legacy mode flag.
+
+For example, replace:
+
+```python
+result = client.smtprs.analyze(
+    "person@example.com",
+    strict_disposable=True,
+)
+```
+
+with:
+
+```python
+result = client.smtprs.analyze(
+    "person@example.com",
+    profile="deep",
+)
+```
+
+### Low-latency posture
+
+Use the `fast` flag when your workflow favors lower latency:
+
+```python
+result = client.smtprs.analyze(
+    "person@example.com",
+    fast=True,
+)
+```
+
+### Company Validity Beta
+
+Paid smtpRS callers can explicitly request the optional Company Validity Beta:
+
+```python
+result = client.smtprs.analyze(
+    "person@example.com",
+    profile="standard",
+    company_validity_beta=True,
+)
+
+beta = result.company_validity_beta
+if beta is not None:
+    print(beta.status)       # "beta"
+    print(beta.requested)    # True
+    print(beta.enabled)      # True when the feature was active for this request
+    print(beta.notes)
+
+signal = result.domain_signal
+if signal is not None:
+    print(signal.domain_status)
+    print(signal.mail_status)
+    print(signal.company_valid)
+```
+
+The option is omitted by default, so existing calls retain their current
+behavior. It is available only to paid smtpRS plans and provides additive
+company-domain context rather than an allowlist. It currently adds no credits
+beyond the selected profile. Free-plan requests that explicitly enable it
+receive `PermissionDeniedError`. Because the response contract is beta,
+applications can use `result.to_dict()` to retain access to newly added fields.
+
+## Configuration
+
+```python
+from paravane import ParavaneClient
+
+client = ParavaneClient(
+    api_key="pvn_live_...",
+    base_url="https://api.paravane.io",
+    timeout=20.0,
+    max_network_retries=1,
+)
+```
+
+Environment variables:
+
+| Name | Purpose | Default |
+| --- | --- | --- |
+| `PARAVANE_API_KEY` | API key used for requests. | None |
+| `PARAVANE_BASE_URL` | API base URL. | `https://api.paravane.io` |
+
+## Per-request options
+
+You can set a timeout for one request:
+
+```python
+result = client.smtprs.analyze(
+    "person@example.com",
+    timeout=5.0,
+)
+```
+
+You can pass an idempotency key:
+
+```python
+result = client.smtprs.analyze(
+    "person@example.com",
+    idempotency_key="signup-check-123",
+)
+```
+
+You can pass future or preview query parameters without waiting for a new SDK release:
+
+```python
+result = client.smtprs.analyze(
+    "person@example.com",
+    extra_params={"preview_flag": "enabled"},
+)
+```
+
+## Custom HTTP sessions
+
+The SDK uses `requests` by default. If your environment needs custom connection pooling, proxies, certificates, or adapters, pass a configured `requests.Session`:
+
+```python
+import requests
+from paravane import ParavaneClient
+
+session = requests.Session()
+session.proxies.update({
+    "https": "https://proxy.example.com:8443",
+})
+
+client = ParavaneClient(
+    api_key="pvn_live_...",
+    session=session,
+)
+```
+
+## Retries
+
+By default, the SDK does not retry network calls:
+
+```python
+client = ParavaneClient(max_network_retries=0)
+```
+
+Enable limited retries for transient network failures, `429` rate limits, and `5xx` API responses:
+
+```python
+client = ParavaneClient(max_network_retries=2)
+```
+
+When enabling retries for write-like workflows, pass an idempotency key from your application so repeated attempts can be treated safely by the API:
+
+```python
+result = client.smtprs.analyze(
+    "person@example.com",
+    idempotency_key="customer-signup-456",
+)
+```
+
+## Idempotency
+
+The SDK accepts an `idempotency_key` and sends it as:
+
+```text
+Idempotency-Key: your-key
+```
+
+Use stable keys for requests that your application may retry after timeouts or transient failures.
+
+## Errors
+
+Unsuccessful requests raise structured exceptions from `paravane.errors`.
+
+```python
+from paravane import (
+    AuthenticationError,
+    ParavaneClient,
+    QuotaExceededError,
+    RateLimitError,
+    ValidationError,
+)
+
+client = ParavaneClient()
+
+try:
+    result = client.smtprs.analyze("person@example.com")
+except AuthenticationError:
+    print("Check your API key.")
+except QuotaExceededError:
+    print("The workspace has exhausted its available credits.")
+except RateLimitError:
+    print("Slow down and retry later.")
+except ValidationError as exc:
+    print("Request was invalid:", exc)
+```
+
+Exception classes:
+
+| Class | Typical cause |
+| --- | --- |
+| `ConfigurationError` | Missing API key or invalid client setup. |
+| `APIConnectionError` | Network failure, timeout, DNS failure, or connection error. |
+| `APIError` | Generic non-success API response. |
+| `AuthenticationError` | Missing, invalid, or revoked API key. |
+| `PermissionDeniedError` | API key lacks access to the requested resource. |
+| `ValidationError` | Invalid request payload or parameters. |
+| `QuotaExceededError` | Plan or credit quota has been exhausted. |
+| `RateLimitError` | Too many requests. |
+
+API errors include useful details when available:
+
+```python
+try:
+    client.smtprs.analyze("not-an-email")
+except ValidationError as exc:
+    print(exc.status_code)
+    print(exc.code)
+    print(exc.request_id)
+    print(exc.response)
+```
+
+## Responses and raw data
+
+The SDK returns `SmtpRsAnalysis` for smtpRS analysis requests.
+
+```python
+result = client.smtprs.analyze("person@example.com")
+```
+
+Common fields:
+
+| Field | Description |
+| --- | --- |
+| `email` | Email address represented by the response, when returned by the API. |
+| `decision` | Customer-facing decision or recommendation, when returned by the API. |
+| `overall_risk` | Overall risk score, when returned by the API. |
+| `tier` | Workspace/API-key tier reflected by the response. |
+| `analysis_profile` | Analysis path used by the API. |
+| `response_profile` | Response shape, such as summary/full. |
+| `credit_cost` | Planned credit cost for the selected profile. |
+| `credits_charged` | Credits recorded for the request, when returned. |
+| `company_validity_beta` | Typed beta status, opt-in state, availability, credit cost, and API notes. |
+| `domain_signal` | Typed domain, mail, and company-context facts when returned. |
+| `reasons` | Human-readable reason strings, when returned. |
+| `usage` | Usage/quota snapshot, when returned. |
+| `raw` | Original API payload. |
+
+To avoid losing fields added by the API before the SDK is updated, the full payload is always preserved:
+
+```python
+raw = result.to_dict()
+print(raw["usage"])
+```
+
+## Types
+
+This package includes inline type hints and ships a `py.typed` marker.
+
+The response helper is a dataclass:
+
+```python
+from paravane import SmtpRsAnalysis
+
+def handle_result(result: SmtpRsAnalysis) -> None:
+    print(result.decision)
+    signal = result.domain_signal
+    if signal is not None:
+        print(signal.mail_capable)
+```
+
+Type hints are intended to describe stable SDK behavior. The raw API response may include additional fields that are not represented as first-class dataclass attributes yet.
+
+## Logging
+
+The SDK does not install or configure logging handlers. Applications should configure logging at the application boundary.
+
+For now, request failures are surfaced through exceptions. If you need detailed HTTP logging during development, configure your own `requests.Session` or enable logging in your HTTP stack.
+
+## Examples
+
+This repository includes small examples:
+
+```text
+examples/basic_analyze.py
+examples/strict_analyze.py
+examples/batch_csv.py
+```
+
+Run one with:
+
+```bash
+PARAVANE_API_KEY="pvn_live_..." python examples/basic_analyze.py
+```
+
+Windows PowerShell:
+
+```powershell
+$env:PARAVANE_API_KEY = "pvn_live_..."
+python examples/basic_analyze.py
+```
+
+## Development
+
+Create an environment:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+```
+
+Windows PowerShell:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install -e ".[dev]"
+```
+
+Run tests:
+
+```bash
+pytest
+```
+
+Run lint:
+
+```bash
+ruff check .
+```
+
+Build the package:
+
+```bash
+python -m build
+```
+
+Recommended pre-commit check:
+
+```bash
+pytest && ruff check . && python -m build
+```
+
+## Repository layout
+
+```text
+paravane-python/
+  .github/workflows/   GitHub Actions checks
+  examples/            Small runnable examples
+  src/paravane/        SDK package source
+  tests/               Unit tests
+  pyproject.toml       Packaging metadata and tool config
+  RELEASING.md         Maintainer release process
+```
+
+## Versioning
+
+Current package version:
+
+```text
+0.2.0
+```
+
+The SDK is in an early release phase. Until `1.0.0`, minor versions may refine naming, response helpers, or packaging behavior as the public API settles. Runtime-breaking changes should still be called out clearly in `CHANGELOG.md`.
+
+## Security
+
+Do not put API keys in source code, client-side apps, mobile apps, screenshots, or public repositories.
+
+Recommended handling:
+
+- load API keys from environment variables or a secret manager
+- rotate keys if they are exposed
+- create separate keys for development, staging, and production
+- revoke keys that are no longer needed
+
+Report suspected vulnerabilities privately:
+
+```text
+security@paravane.io
+```
+
+## Support
+
+For product or account support:
+
+```text
+contact@paravane.io
+```
+
+For security reports:
+
+```text
+security@paravane.io
+```

paravane-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+paravane/__init__.py,sha256=qB07T2g7D2jPtF_22rx2l0AviLA0gVUxZlgDaf7rgjA,834
+paravane/_version.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
+paravane/client.py,sha256=KGXFuFedfxB860hzjeXKIyPwm-U5Y8JJj8u2zpuwlPI,1515
+paravane/errors.py,sha256=IQOFf3pljM1X1CWei6fqICYiBIhtCwo9FOCC4BWyDiI,1810
+paravane/http.py,sha256=x4kjF0jFvwgoFLFNkcV1suSeRrYyn7-_dx9d26bCrw8,5808
+paravane/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+paravane/smtprs.py,sha256=OjMOogHzkAt7W46WZLvJvAD96v5D8sgLTPRmng7CBNg,2437
+paravane/types.py,sha256=rcivfo6bzo7ou3DsQLEkV8XubzkuwqTX8dXV0UJ4qG8,6998
+paravane-0.2.0.dist-info/licenses/LICENSE,sha256=BY5W6fvNfOx_sbPT4fL55H0nWP1K_xptQXGRaQ_4eSg,1070
+paravane-0.2.0.dist-info/METADATA,sha256=rXGftPy12EUzq1JgsTfxHC9AuSlDWzSHgm_JlxwqQxo,18288
+paravane-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+paravane-0.2.0.dist-info/top_level.txt,sha256=R-DBWERALLdrqDACB9XN4eJPEw88dIUdsaLOlgWdK60,9
+paravane-0.2.0.dist-info/RECORD,,

paravane-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

paravane-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paravane Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

paravane-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+paravane