epostix 1.0.0__py3-none-any.whl

epostix/__init__.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+from . import attachments as attachments
+from . import batch as batch
+from . import models as models
+from . import overrides as overrides
+from . import webhooks as webhooks
+from ._client import (
+    DEDUPLICATION_SCOPE as DEDUPLICATION_SCOPE,
+)
+from ._client import (
+    PRODUCTION_BASE_URL as PRODUCTION_BASE_URL,
+)
+from ._client import (
+    SANDBOX_DOMAIN as SANDBOX_DOMAIN,
+)
+from ._client import (
+    STAGING_BASE_URL as STAGING_BASE_URL,
+)
+from ._client import (
+    AsyncEpostix as AsyncEpostix,
+)
+from ._client import (
+    Epostix as Epostix,
+)
+from ._client import (
+    KeyEnvironment as KeyEnvironment,
+)
+from ._client import (
+    key_environment_of as key_environment_of,
+)
+from ._codec import (
+    EpostixDecodeError as EpostixDecodeError,
+)
+from ._codec import (
+    is_known_enum_value as is_known_enum_value,
+)
+from ._errors import (
+    EpostixAccountSuspendedError as EpostixAccountSuspendedError,
+)
+from ._errors import (
+    EpostixAPIError as EpostixAPIError,
+)
+from ._errors import (
+    EpostixAuthenticationError as EpostixAuthenticationError,
+)
+from ._errors import (
+    EpostixConfigurationError as EpostixConfigurationError,
+)
+from ._errors import (
+    EpostixConflictError as EpostixConflictError,
+)
+from ._errors import (
+    EpostixContentError as EpostixContentError,
+)
+from ._errors import (
+    EpostixError as EpostixError,
+)
+from ._errors import (
+    EpostixErrorType as EpostixErrorType,
+)
+from ._errors import (
+    EpostixIdempotencyConflictError as EpostixIdempotencyConflictError,
+)
+from ._errors import (
+    EpostixIdempotencyInProgressError as EpostixIdempotencyInProgressError,
+)
+from ._errors import (
+    EpostixInvalidRequestError as EpostixInvalidRequestError,
+)
+from ._errors import (
+    EpostixNotFoundError as EpostixNotFoundError,
+)
+from ._errors import (
+    EpostixOutcomeUnknownError as EpostixOutcomeUnknownError,
+)
+from ._errors import (
+    EpostixPaginationError as EpostixPaginationError,
+)
+from ._errors import (
+    EpostixPermissionError as EpostixPermissionError,
+)
+from ._errors import (
+    EpostixQuotaExceededError as EpostixQuotaExceededError,
+)
+from ._errors import (
+    EpostixRateLimitError as EpostixRateLimitError,
+)
+from ._errors import (
+    EpostixServerError as EpostixServerError,
+)
+from ._errors import (
+    EpostixTimeoutError as EpostixTimeoutError,
+)
+from ._errors import (
+    EpostixTransportError as EpostixTransportError,
+)
+from ._errors import (
+    EpostixValidationError as EpostixValidationError,
+)
+from ._errors import (
+    EpostixWebhookVerificationError as EpostixWebhookVerificationError,
+)
+from ._errors import (
+    FieldError as FieldError,
+)
+from ._errors import (
+    PaginationFailureReason as PaginationFailureReason,
+)
+from ._errors import (
+    QuotaPeriod as QuotaPeriod,
+)
+from ._errors import (
+    TimeoutPhase as TimeoutPhase,
+)
+from ._errors import (
+    WebhookFailureReason as WebhookFailureReason,
+)
+from ._mailbox import (
+    Mailbox as Mailbox,
+)
+from ._mailbox import (
+    addr as addr,
+)
+from ._mailbox import (
+    named as named,
+)
+from ._model import (
+    Model as Model,
+)
+from ._model import (
+    response_metadata_of as response_metadata_of,
+)
+from ._model import (
+    unknown_fields_of as unknown_fields_of,
+)
+from ._pagination import (
+    AsyncPaginator as AsyncPaginator,
+)
+from ._pagination import (
+    Collection as Collection,
+)
+from ._pagination import (
+    Page as Page,
+)
+from ._pagination import (
+    Paginator as Paginator,
+)
+from ._response import (
+    AttemptRecord as AttemptRecord,
+)
+from ._response import (
+    RateLimitSnapshot as RateLimitSnapshot,
+)
+from ._response import (
+    ResponseMetadata as ResponseMetadata,
+)
+from ._response import (
+    RetriesExhaustedReason as RetriesExhaustedReason,
+)
+from ._retry import (
+    BATCH_RETRY_POLICY as BATCH_RETRY_POLICY,
+)
+from ._retry import (
+    DEFAULT_RETRY_POLICY as DEFAULT_RETRY_POLICY,
+)
+from ._retry import (
+    DISABLED_RETRY_POLICY as DISABLED_RETRY_POLICY,
+)
+from ._retry import (
+    UPLOAD_RETRY_POLICY as UPLOAD_RETRY_POLICY,
+)
+from ._retry import (
+    MutationRetryMode as MutationRetryMode,
+)
+from ._retry import (
+    RetryClass as RetryClass,
+)
+from ._retry import (
+    RetryPolicy as RetryPolicy,
+)
+from ._transport import (
+    IDEMPOTENCY_KEY_MAXIMUM_LENGTH as IDEMPOTENCY_KEY_MAXIMUM_LENGTH,
+)
+from ._transport import (
+    IDEMPOTENCY_RETENTION_HOURS as IDEMPOTENCY_RETENTION_HOURS,
+)
+from ._transport import (
+    OperationSpec as OperationSpec,
+)
+from ._transport import (
+    RequestOptions as RequestOptions,
+)
+from .attachments import (
+    ATTACHMENT_DECODED_LIMIT_BYTES as ATTACHMENT_DECODED_LIMIT_BYTES,
+)
+from .attachments import (
+    REQUEST_BODY_LIMIT_BYTES as REQUEST_BODY_LIMIT_BYTES,
+)
+from .attachments import (
+    EpostixAttachmentTooLargeError as EpostixAttachmentTooLargeError,
+)
+from .attachments import (
+    EpostixRequestTooLargeError as EpostixRequestTooLargeError,
+)
+from ._types import (
+    NOT_GIVEN as NOT_GIVEN,
+)
+from ._types import (
+    JsonValue as JsonValue,
+)
+from ._types import (
+    NotGiven as NotGiven,
+)
+
+from .overrides import (
+    AsyncRawContent as AsyncRawContent,
+)
+from .overrides import (
+    RawContent as RawContent,
+)
+
+__version__ = "1.0.0"

epostix/_client.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import random as _random
+import time
+from types import TracebackType
+from typing import Callable, Literal, Mapping, TypeAlias
+from urllib.parse import urlparse
+
+import httpx
+
+from ._errors import EpostixConfigurationError
+from ._generated.resources import build_async_resources, build_resources
+from ._generated.resources.analytics import AnalyticsResource, AsyncAnalyticsResource
+from ._generated.resources.api_keys import ApiKeysResource, AsyncApiKeysResource
+from ._generated.resources.broadcasts import AsyncBroadcastsResource, BroadcastsResource
+from ._generated.resources.contacts import AsyncContactsResource, ContactsResource
+from ._generated.resources.domains import AsyncDomainsResource, DomainsResource
+from ._generated.resources.emails import AsyncEmailsResource, EmailsResource
+from ._generated.resources.events import AsyncEventsResource, EventsResource
+from ._generated.resources.suppressions import AsyncSuppressionsResource, SuppressionsResource
+from ._generated.resources.tags import AsyncTagsResource, TagsResource
+from ._generated.resources.templates import AsyncTemplatesResource, TemplatesResource
+from ._generated.resources.webhooks import AsyncWebhooksResource, WebhooksResource
+from ._retry import DEFAULT_RETRY_POLICY, RetryPolicy
+from ._transport import (
+    AsyncTransport,
+    TransportConfig,
+    Transport,
+    build_async_http_client,
+    build_http_client,
+)
+from .overrides import (
+    AsyncAttachmentsResource,
+    AsyncInboundResource,
+    AttachmentsResource,
+    InboundResource,
+)
+
+PRODUCTION_BASE_URL = "https://api.epostix.com/v1"
+STAGING_BASE_URL = "https://api.staging.epostix.com/v1"
+SANDBOX_DOMAIN = "epostix.dev"
+DEDUPLICATION_SCOPE = "api_key + environment + method + path + key, 24h"
+USER_AGENT = "epostix-python/1.0.0"
+
+KeyEnvironment: TypeAlias = Literal["live", "test", "unrecognized"]
+
+
+def key_environment_of(api_key: str) -> KeyEnvironment:
+    if api_key.startswith("tix_live_"):
+        return "live"
+
+    if api_key.startswith("tix_test_"):
+        return "test"
+
+    return "unrecognized"
+
+
+def _build_config(
+    api_key: str,
+    base_url: str,
+    retry_policy: RetryPolicy,
+    default_headers: Mapping[str, str] | None,
+    user_agent_suffix: str | None,
+    automatic_idempotency_keys: bool,
+    random: Callable[[], float] | None,
+    now: Callable[[], float] | None,
+) -> TransportConfig:
+    if not api_key or not api_key.strip():
+        raise EpostixConfigurationError("an API key is required")
+
+    if api_key.startswith("Bearer "):
+        raise EpostixConfigurationError(
+            "pass the API key alone; the client adds the Bearer prefix itself"
+        )
+
+    parsed = urlparse(base_url)
+    if parsed.scheme not in ("http", "https") or not parsed.netloc:
+        raise EpostixConfigurationError(f"base_url is not a valid URL: {base_url}")
+
+    return TransportConfig(
+        api_key=api_key,
+        base_url=base_url.rstrip("/"),
+        retry_policy=retry_policy,
+        user_agent=USER_AGENT + (f" {user_agent_suffix}" if user_agent_suffix else ""),
+        automatic_idempotency_keys=automatic_idempotency_keys,
+        default_headers=dict(default_headers or {}),
+        random=random or _random.random,
+        now=now or time.monotonic,
+    )
+
+
+class Epostix:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = PRODUCTION_BASE_URL,
+        retry_policy: RetryPolicy = DEFAULT_RETRY_POLICY,
+        http_client: httpx.Client | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        user_agent_suffix: str | None = None,
+        automatic_idempotency_keys: bool = True,
+        random: Callable[[], float] | None = None,
+        now: Callable[[], float] | None = None,
+    ) -> None:
+        config = _build_config(
+            api_key,
+            base_url,
+            retry_policy,
+            default_headers,
+            user_agent_suffix,
+            automatic_idempotency_keys,
+            random,
+            now,
+        )
+
+        owns_client = http_client is None
+        client = http_client if http_client is not None else build_http_client(retry_policy)
+
+        self._transport = Transport(config, client, owns_client)
+        resources = build_resources(self._transport)
+
+        self.analytics: AnalyticsResource = resources.analytics
+        self.api_keys: ApiKeysResource = resources.api_keys
+        self.attachments = AttachmentsResource(self._transport)
+        self.broadcasts: BroadcastsResource = resources.broadcasts
+        self.contacts: ContactsResource = resources.contacts
+        self.domains: DomainsResource = resources.domains
+        self.emails: EmailsResource = resources.emails
+        self.events: EventsResource = resources.events
+        self.inbound = InboundResource(self._transport)
+        self.suppressions: SuppressionsResource = resources.suppressions
+        self.tags: TagsResource = resources.tags
+        self.templates: TemplatesResource = resources.templates
+        self.webhooks: WebhooksResource = resources.webhooks
+
+    @property
+    def key_environment(self) -> KeyEnvironment:
+        return key_environment_of(self._transport.config.api_key)
+
+    @property
+    def deduplication_scope(self) -> str:
+        return DEDUPLICATION_SCOPE
+
+    def with_api_key(self, api_key: str) -> Epostix:
+        config = self._transport.config
+
+        return Epostix(
+            api_key,
+            base_url=config.base_url,
+            retry_policy=config.retry_policy,
+            http_client=self._transport.http_client,
+            default_headers=config.default_headers,
+            automatic_idempotency_keys=config.automatic_idempotency_keys,
+            random=config.random,
+            now=config.now,
+        )
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> Epostix:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncEpostix:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = PRODUCTION_BASE_URL,
+        retry_policy: RetryPolicy = DEFAULT_RETRY_POLICY,
+        http_client: httpx.AsyncClient | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        user_agent_suffix: str | None = None,
+        automatic_idempotency_keys: bool = True,
+        random: Callable[[], float] | None = None,
+        now: Callable[[], float] | None = None,
+    ) -> None:
+        config = _build_config(
+            api_key,
+            base_url,
+            retry_policy,
+            default_headers,
+            user_agent_suffix,
+            automatic_idempotency_keys,
+            random,
+            now,
+        )
+
+        owns_client = http_client is None
+        client = http_client if http_client is not None else build_async_http_client(retry_policy)
+
+        self._transport = AsyncTransport(config, client, owns_client)
+        resources = build_async_resources(self._transport)
+
+        self.analytics: AsyncAnalyticsResource = resources.analytics
+        self.api_keys: AsyncApiKeysResource = resources.api_keys
+        self.attachments = AsyncAttachmentsResource(self._transport)
+        self.broadcasts: AsyncBroadcastsResource = resources.broadcasts
+        self.contacts: AsyncContactsResource = resources.contacts
+        self.domains: AsyncDomainsResource = resources.domains
+        self.emails: AsyncEmailsResource = resources.emails
+        self.events: AsyncEventsResource = resources.events
+        self.inbound = AsyncInboundResource(self._transport)
+        self.suppressions: AsyncSuppressionsResource = resources.suppressions
+        self.tags: AsyncTagsResource = resources.tags
+        self.templates: AsyncTemplatesResource = resources.templates
+        self.webhooks: AsyncWebhooksResource = resources.webhooks
+
+    @property
+    def key_environment(self) -> KeyEnvironment:
+        return key_environment_of(self._transport.config.api_key)
+
+    @property
+    def deduplication_scope(self) -> str:
+        return DEDUPLICATION_SCOPE
+
+    def with_api_key(self, api_key: str) -> AsyncEpostix:
+        config = self._transport.config
+
+        return AsyncEpostix(
+            api_key,
+            base_url=config.base_url,
+            retry_policy=config.retry_policy,
+            http_client=self._transport.http_client,
+            default_headers=config.default_headers,
+            automatic_idempotency_keys=config.automatic_idempotency_keys,
+            random=config.random,
+            now=config.now,
+        )
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> AsyncEpostix:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()

epostix/_codec.py

@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Any, Callable, Sequence
+
+from ._errors import EpostixConfigurationError, EpostixError
+from ._mailbox import Mailbox
+from ._model import Model
+from ._types import NOT_GIVEN, NotGiven
+
+
+class EpostixDecodeError(EpostixError):
+    pass
+
+
+class Codec(ABC):
+    @abstractmethod
+    def encode(self, value: Any) -> Any: ...
+
+    @abstractmethod
+    def decode(self, value: Any) -> Any: ...
+
+
+class _Passthrough(Codec):
+    def encode(self, value: Any) -> Any:
+        return value
+
+    def decode(self, value: Any) -> Any:
+        return value
+
+
+def format_datetime(value: datetime) -> str:
+    text = value.isoformat()
+
+    if text.endswith("+00:00"):
+        return text[:-6] + "Z"
+
+    return text
+
+
+class _DateTime(Codec):
+    def encode(self, value: Any) -> Any:
+        if isinstance(value, datetime):
+            return format_datetime(value)
+
+        return value
+
+    def decode(self, value: Any) -> Any:
+        if isinstance(value, str):
+            try:
+                return datetime.fromisoformat(value)
+            except ValueError:
+                return value
+
+        return value
+
+
+PASSTHROUGH: Codec = _Passthrough()
+DATETIME: Codec = _DateTime()
+
+
+class ArrayCodec(Codec):
+    def __init__(self, inner: Callable[[], Codec]) -> None:
+        self._inner = inner
+
+    def encode(self, value: Any) -> Any:
+        if isinstance(value, (list, tuple)):
+            inner = self._inner()
+            return [inner.encode(item) for item in value]
+
+        return value
+
+    def decode(self, value: Any) -> Any:
+        if isinstance(value, list):
+            inner = self._inner()
+            return [inner.decode(item) for item in value]
+
+        return value
+
+
+class MapCodec(Codec):
+    def __init__(self, inner: Callable[[], Codec]) -> None:
+        self._inner = inner
+
+    def encode(self, value: Any) -> Any:
+        if isinstance(value, dict):
+            inner = self._inner()
+            return {key: inner.encode(item) for key, item in value.items()}
+
+        return value
+
+    def decode(self, value: Any) -> Any:
+        if isinstance(value, dict):
+            inner = self._inner()
+            return {key: inner.decode(item) for key, item in value.items()}
+
+        return value
+
+
+class EnumCodec(Codec):
+    def __init__(self, enum_class: type[Enum]) -> None:
+        self._enum_class = enum_class
+
+    def encode(self, value: Any) -> Any:
+        if isinstance(value, Enum):
+            return value.value
+
+        return value
+
+    def decode(self, value: Any) -> Any:
+        if not isinstance(value, str):
+            return value
+
+        try:
+            return self._enum_class(value)
+        except ValueError:
+            return value
+
+
+def is_known_enum_value(enum_class: type[Enum], value: str) -> bool:
+    try:
+        enum_class(value)
+    except ValueError:
+        return False
+
+    return True
+
+
+class ScalarOrArrayCodec(Codec):
+    def encode(self, value: Any) -> Any:
+        if isinstance(value, str):
+            return [value]
+
+        if isinstance(value, (list, tuple)):
+            return list(value)
+
+        return value
+
+    def decode(self, value: Any) -> Any:
+        return value
+
+
+class MailboxCodec(Codec):
+    def encode(self, value: Any) -> Any:
+        if isinstance(value, Mailbox):
+            if not value.name:
+                return value.email
+
+            return {"email": value.email, "name": value.name}
+
+        return value
+
+    def decode(self, value: Any) -> Any:
+        if isinstance(value, dict):
+            return Mailbox(email=str(value.get("email", "")), name=value.get("name"))
+
+        return value
+
+
+@dataclass(frozen=True)
+class FieldSpec:
+    wire: str
+    name: str
+    codec: Callable[[], Codec]
+    required: bool
+    nullable: bool
+
+
+class ModelCodec(Codec):
+    def __init__(self, model_class: type[Model], fields: Sequence[FieldSpec]) -> None:
+        self._model_class = model_class
+        self._fields = fields
+        self._known = frozenset(spec.wire for spec in fields)
+
+    def encode(self, value: Any) -> Any:
+        if not isinstance(value, self._model_class):
+            return value
+
+        out: dict[str, Any] = {}
+
+        for spec in self._fields:
+            raw = getattr(value, spec.name, NOT_GIVEN)
+
+            if isinstance(raw, NotGiven):
+                continue
+
+            out[spec.wire] = None if raw is None else spec.codec().encode(raw)
+
+        return out
+
+    def decode(self, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+
+        instance = self._model_class.__new__(self._model_class)
+
+        for spec in self._fields:
+            if spec.wire in value:
+                raw = value[spec.wire]
+                setattr(
+                    instance,
+                    spec.name,
+                    None if raw is None else spec.codec().decode(raw),
+                )
+            else:
+                setattr(instance, spec.name, NOT_GIVEN)
+
+        instance.unknown_fields = {
+            key: item for key, item in value.items() if key not in self._known
+        }
+        instance.response_metadata = None
+
+        return instance
+
+
+@dataclass(frozen=True)
+class VariantSpec:
+    discriminator: str
+    model_class: type[Model]
+    codec: Callable[[], Codec]
+
+
+class VariantCodec(Codec):
+    def __init__(self, variants: Sequence[VariantSpec], name: str) -> None:
+        self._variants = variants
+        self._name = name
+
+    def encode(self, value: Any) -> Any:
+        for variant in self._variants:
+            if isinstance(value, variant.model_class):
+                return variant.codec().encode(value)
+
+        raise EpostixConfigurationError(f"value does not match any {self._name} variant")
+
+    def decode(self, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+
+        for variant in self._variants:
+            if variant.discriminator in value:
+                return variant.codec().decode(value)
+
+        raise EpostixDecodeError(
+            f"the server returned a {self._name} shape this version does not recognise"
+        )