meteroid 0.27.0__py3-none-any.whl

meteroid/__init__.py

@@ -0,0 +1,56 @@
+# ruff: noqa: I001  (the import order depends on the client name)
+from ._version import __version__
+from .api import (
+    APIResponse,
+    AsyncMeteroid,
+    AsyncPage,
+    AsyncPaginator,
+    AsyncStream,
+    Meteroid,
+    Stream,
+    SyncPage,
+)
+from .errors import (
+    MeteroidError,
+    APIConnectionError,
+    APIError,
+    APIResponseValidationError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    InternalServerError,
+    ModelParseError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    UnprocessableEntityError,
+)
+
+__all__ = [
+    "Meteroid",
+    "MeteroidError",
+    "APIConnectionError",
+    "APIError",
+    "APIResponse",
+    "APIResponseValidationError",
+    "APIStatusError",
+    "APITimeoutError",
+    "AsyncMeteroid",
+    "AsyncPage",
+    "AsyncPaginator",
+    "AsyncStream",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConflictError",
+    "InternalServerError",
+    "ModelParseError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "Stream",
+    "SyncPage",
+    "UnprocessableEntityError",
+    "__version__",
+]

meteroid/_exceptions.py

@@ -0,0 +1,93 @@
+# this file is @generated by Perseid; edit the shared runtime template.
+"""The errors of a request that got no usable response.
+
+Errors carrying an HTTP status are in :mod:`meteroid.api`, as
+:class:`~meteroid.api.APIStatusError` subclasses. Every error derives
+from :class:`MeteroidError`.
+"""
+
+from __future__ import annotations
+
+import httpx
+
+from .serialization import MeteroidError, ModelParseError
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APIResponseValidationError",
+    "APITimeoutError",
+    "MeteroidError",
+    "ModelParseError",
+]
+
+
+class APIError(MeteroidError):
+    """An error of a request to the API."""
+
+    message: str
+    request: httpx.Request | None
+    """The request that failed, when it was built."""
+
+    def __init__(self, message: str, request: httpx.Request | None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.request = request
+
+
+class APIConnectionError(APIError):
+    """The request got no response, after retries: connection failure, reset or timeout."""
+
+    def __init__(
+        self, request: httpx.Request | None, message: str = "Connection error."
+    ) -> None:
+        super().__init__(message, request)
+
+
+class APITimeoutError(APIConnectionError):
+    """The request timed out, after retries."""
+
+    def __init__(self, request: httpx.Request | None) -> None:
+        super().__init__(request, "Request timed out.")
+
+
+class APIResponseValidationError(APIError):
+    """A successful response was not valid JSON, or did not match its model."""
+
+    response: httpx.Response
+    status_code: int
+
+    def __init__(self, response: httpx.Response, reason: str) -> None:
+        super().__init__(
+            f"Could not decode response ({response.status_code}): {reason}",
+            request_of(response),
+        )
+        self.response = response
+        self.status_code = response.status_code
+
+    @property
+    def raw_body(self) -> bytes:
+        """The response body, empty when it was streamed."""
+        try:
+            return self.response.content
+        except httpx.ResponseNotRead:
+            return b""
+
+
+def request_of(response: httpx.Response) -> httpx.Request | None:
+    """The request of a response, which a middleware may have built without one."""
+    try:
+        return response.request
+    except RuntimeError:
+        return None
+
+
+def connection_error(error: httpx.RequestError) -> APIConnectionError:
+    """The SDK error for a transport error of ``httpx``."""
+    try:
+        request: httpx.Request | None = error.request
+    except RuntimeError:
+        request = None
+    if isinstance(error, httpx.TimeoutException):
+        return APITimeoutError(request)
+    return APIConnectionError(request, str(error) or "Connection error.")

meteroid/_version.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("meteroid")
+except PackageNotFoundError:
+    __version__ = "0+uninstalled"

meteroid/api/__init__.py

@@ -0,0 +1,188 @@
+# this file is @generated
+"""Meteroid API resources."""
+
+from __future__ import annotations
+
+import importlib
+import typing as t
+
+from .._exceptions import (
+    APIConnectionError,
+    APIError,
+    APIResponseValidationError,
+    APITimeoutError,
+)
+from ..serialization import MeteroidError
+from ._errors import (
+    APIStatusError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    ErrorBody,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    UnprocessableEntityError,
+)
+from ._pagination import AsyncPage, AsyncPaginator, SyncPage
+from ._response import APIResponse
+from ._streaming import (
+    AsyncEventStream,
+    AsyncStream,
+    EventStream,
+    SseEvent,
+    Stream,
+    Upload,
+)
+from .client import AsyncMeteroid, Meteroid
+
+if t.TYPE_CHECKING:
+    from .add_ons import AddOns, AsyncAddOns
+    from .batch_jobs import AsyncBatchJobs, BatchJobs
+    from .checkout_sessions import AsyncCheckoutSessions, CheckoutSessions
+    from .connect import AsyncConnect, Connect
+    from .coupons import AsyncCoupons, Coupons
+    from .credit_notes import AsyncCreditNotes, CreditNotes
+    from .custom_properties import AsyncCustomProperties, CustomProperties
+    from .customers import AsyncCustomers, Customers
+    from .entitlements import AsyncEntitlements, Entitlements
+    from .events import AsyncEvents, Events
+    from .features import AsyncFeatures, Features
+    from .invoices import AsyncInvoices, Invoices
+    from .metrics import AsyncMetrics, Metrics
+    from .oauth import AsyncOauth, Oauth
+    from .oauth_apps import AsyncOauthApps, OauthApps
+    from .plans import AsyncPlans, Plans
+    from .product_families import AsyncProductFamilies, ProductFamilies
+    from .products import AsyncProducts, Products
+    from .subscriptions import AsyncSubscriptions, Subscriptions
+    from .usage import AsyncUsage, Usage
+
+# Each resource's module is imported the first time it is used.
+_MODULES: dict[str, str] = {
+    "AsyncAddOns": "add_ons",
+    "AddOns": "add_ons",
+    "AsyncBatchJobs": "batch_jobs",
+    "BatchJobs": "batch_jobs",
+    "AsyncCheckoutSessions": "checkout_sessions",
+    "CheckoutSessions": "checkout_sessions",
+    "AsyncConnect": "connect",
+    "Connect": "connect",
+    "AsyncCoupons": "coupons",
+    "Coupons": "coupons",
+    "AsyncCreditNotes": "credit_notes",
+    "CreditNotes": "credit_notes",
+    "AsyncCustomProperties": "custom_properties",
+    "CustomProperties": "custom_properties",
+    "AsyncCustomers": "customers",
+    "Customers": "customers",
+    "AsyncEntitlements": "entitlements",
+    "Entitlements": "entitlements",
+    "AsyncEvents": "events",
+    "Events": "events",
+    "AsyncFeatures": "features",
+    "Features": "features",
+    "AsyncInvoices": "invoices",
+    "Invoices": "invoices",
+    "AsyncMetrics": "metrics",
+    "Metrics": "metrics",
+    "AsyncOauth": "oauth",
+    "Oauth": "oauth",
+    "AsyncOauthApps": "oauth_apps",
+    "OauthApps": "oauth_apps",
+    "AsyncPlans": "plans",
+    "Plans": "plans",
+    "AsyncProductFamilies": "product_families",
+    "ProductFamilies": "product_families",
+    "AsyncProducts": "products",
+    "Products": "products",
+    "AsyncSubscriptions": "subscriptions",
+    "Subscriptions": "subscriptions",
+    "AsyncUsage": "usage",
+    "Usage": "usage",
+}
+
+
+def __getattr__(name: str) -> t.Any:
+    module = _MODULES.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(importlib.import_module(f".{module}", __name__), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals(), *_MODULES})
+
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APIResponse",
+    "APIResponseValidationError",
+    "APITimeoutError",
+    "AsyncMeteroid",
+    "AsyncEventStream",
+    "AsyncPage",
+    "AsyncPaginator",
+    "AsyncStream",
+    "EventStream",
+    "Meteroid",
+    "MeteroidError",
+    "SseEvent",
+    "Stream",
+    "SyncPage",
+    "Upload",
+    "APIStatusError",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConflictError",
+    "ErrorBody",
+    "InternalServerError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "UnprocessableEntityError",
+    "AsyncAddOns",
+    "AddOns",
+    "AsyncBatchJobs",
+    "BatchJobs",
+    "AsyncCheckoutSessions",
+    "CheckoutSessions",
+    "AsyncConnect",
+    "Connect",
+    "AsyncCoupons",
+    "Coupons",
+    "AsyncCreditNotes",
+    "CreditNotes",
+    "AsyncCustomProperties",
+    "CustomProperties",
+    "AsyncCustomers",
+    "Customers",
+    "AsyncEntitlements",
+    "Entitlements",
+    "AsyncEvents",
+    "Events",
+    "AsyncFeatures",
+    "Features",
+    "AsyncInvoices",
+    "Invoices",
+    "AsyncMetrics",
+    "Metrics",
+    "AsyncOauth",
+    "Oauth",
+    "AsyncOauthApps",
+    "OauthApps",
+    "AsyncPlans",
+    "Plans",
+    "AsyncProductFamilies",
+    "ProductFamilies",
+    "AsyncProducts",
+    "Products",
+    "AsyncSubscriptions",
+    "Subscriptions",
+    "AsyncUsage",
+    "Usage",
+]

meteroid/api/_auth.py

@@ -0,0 +1,231 @@
+# this file is @generated by Perseid; edit the shared runtime template.
+"""Security schemes: bearer tokens, HTTP basic credentials and API keys."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import threading
+import time
+import typing as t
+import urllib.parse
+
+import httpx
+
+__all__ = [
+    "OAuthTokens",
+    "Security",
+    "SecurityScheme",
+    "TokenProvider",
+    "apply_auth",
+    "async_token",
+    "chosen_schemes",
+    "needs_token_provider",
+    "oauth_scheme",
+    "sync_token",
+    "token_url",
+]
+
+TokenProvider = t.Callable[[], str | t.Awaitable[str]]
+"""Returns a fresh bearer token; the async client also accepts coroutine functions."""
+
+Security = t.Sequence[t.Sequence[str]]
+"""Alternatives of scheme names: the first one whose credentials are all configured is sent."""
+
+
+class SecurityScheme(t.NamedTuple):
+    """How the API reads one kind of credentials."""
+
+    kind: str
+    """``bearer``, ``basic`` or ``api_key``."""
+    location: str = ""
+    param: str = ""
+    token_url: str = ""
+    """OAuth2 token endpoint of the client credentials flow, absolute or relative to the base URL."""
+    scope: str = ""
+    """Space-separated scopes asked for with the access token."""
+
+
+_EXPIRY_MARGIN = 60.0
+"""Seconds before its expiry that an access token is renewed, or half its life when shorter."""
+
+_COOKIE_OCTETS = "!#$%&'()*+-./0123456789:<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[]^_`abcdefghijklmnopqrstuvwxyz{|}~"
+"""Every RFC 6265 cookie-octet, so that an opaque API key is sent as is."""
+
+
+class OAuthTokens:
+    """OAuth2 client credentials: an access token per token URL and scope, kept until it is about to expire.
+
+    The client fetches a token on first use with :attr:`client_id` and :attr:`client_secret`,
+    sending them in an HTTP basic header (``client_auth="basic"``) or as form fields (``"body"``).
+    The lock makes concurrent callers share one token request.
+    """
+
+    def __init__(
+        self, client_id: str, client_secret: str, client_auth: str = "basic"
+    ) -> None:
+        if client_auth not in ("basic", "body"):
+            raise ValueError("oauth_client_auth must be 'basic' or 'body'")
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.client_auth = client_auth
+        self.lock = threading.Lock()
+        self._async_lock: asyncio.Lock | None = None
+        self._tokens: dict[str, tuple[str, float]] = {}
+
+    def async_lock(self) -> asyncio.Lock:
+        if self._async_lock is None:
+            self._async_lock = asyncio.Lock()
+        return self._async_lock
+
+    def cached(self, url: str) -> str | None:
+        """The access token kept under ``url``, unless it is about to expire."""
+        entry = self._tokens.get(url)
+        return entry[0] if entry is not None and entry[1] > time.monotonic() else None
+
+    def store(self, url: str, token: str, expires_in: float | None) -> str:
+        """Keeps ``token``, which lives ``expires_in`` seconds, forever when ``None``."""
+        life = float("inf") if expires_in is None else max(expires_in, 0.0)
+        self._tokens[url] = (
+            token,
+            time.monotonic() + life - min(_EXPIRY_MARGIN, life / 2),
+        )
+        return token
+
+    def invalidate(self, url: str, token: str) -> None:
+        """Forgets ``token`` after the API rejected it, unless a newer one replaced it."""
+        entry = self._tokens.get(url)
+        if entry is not None and entry[0] == token:
+            del self._tokens[url]
+
+    def request_parts(self, scope: str) -> tuple[list[tuple[str, str]], dict[str, str]]:
+        """The form fields and headers of a token request."""
+        form = [("grant_type", "client_credentials")]
+        if scope:
+            form.append(("scope", scope))
+        if self.client_auth == "body":
+            form += [
+                ("client_id", self.client_id),
+                ("client_secret", self.client_secret),
+            ]
+            return form, {}
+        # RFC 6749 2.3.1: both are form-encoded before the base64.
+        raw = f"{urllib.parse.quote_plus(self.client_id)}:{urllib.parse.quote_plus(self.client_secret)}"
+        return form, {
+            "authorization": f"Basic {base64.b64encode(raw.encode()).decode()}"
+        }
+
+
+def token_url(base_path: str, url: str) -> str:
+    """``url`` as an absolute URL: an absolute-path reference is resolved against the origin of
+    the base URL, any other relative one is joined under it."""
+    if "://" in url:
+        return url
+    if url.startswith("/"):
+        parts = urllib.parse.urlsplit(base_path)
+        return f"{parts.scheme}://{parts.netloc}{url}"
+    return f"{base_path}/{url}"
+
+
+class _Credentials(t.Protocol):
+    bearer_access_token: str | None
+    token_provider: TokenProvider | None
+    basic_auth: tuple[str, str] | None
+    api_keys: t.Mapping[str, str]
+    security_schemes: t.Mapping[str, SecurityScheme]
+    oauth: OAuthTokens | None
+
+
+def _configured(cfg: _Credentials, name: str) -> bool:
+    scheme = cfg.security_schemes.get(name)
+    if scheme is None:
+        return False
+    if scheme.kind == "bearer":
+        return (
+            cfg.token_provider is not None
+            or bool(cfg.bearer_access_token)
+            or (bool(scheme.token_url) and cfg.oauth is not None)
+        )
+    if scheme.kind == "basic":
+        return cfg.basic_auth is not None
+    return bool(cfg.api_keys.get(name) or cfg.bearer_access_token)
+
+
+def chosen_schemes(cfg: _Credentials, security: Security) -> list[str]:
+    """The schemes of the first alternative of ``security`` whose credentials are all set."""
+    for names in security:
+        if names and all(_configured(cfg, name) for name in names):
+            return list(names)
+    return []
+
+
+def needs_token_provider(cfg: _Credentials, names: t.Sequence[str]) -> bool:
+    """Whether the token provider must be called for the schemes ``names``."""
+    return cfg.token_provider is not None and any(
+        cfg.security_schemes[name].kind == "bearer" for name in names
+    )
+
+
+def oauth_scheme(cfg: _Credentials, names: t.Sequence[str]) -> SecurityScheme | None:
+    """The OAuth2 scheme among ``names`` whose token the client fetches, when neither a token
+    provider nor a token is set."""
+    if cfg.oauth is None or cfg.token_provider is not None or cfg.bearer_access_token:
+        return None
+    for name in names:
+        scheme = cfg.security_schemes[name]
+        if scheme.kind == "bearer" and scheme.token_url:
+            return scheme
+    return None
+
+
+def sync_token(cfg: _Credentials) -> str:
+    """A token from the provider, which must not be a coroutine function."""
+    assert cfg.token_provider is not None
+    token = cfg.token_provider()
+    if not isinstance(token, str):
+        raise TypeError("an async token_provider needs the async client")
+    return token
+
+
+async def async_token(cfg: _Credentials) -> str:
+    """A token from the provider, awaited when it returns an awaitable."""
+    assert cfg.token_provider is not None
+    token = cfg.token_provider()
+    return token if isinstance(token, str) else await token
+
+
+def apply_auth(
+    cfg: _Credentials,
+    names: t.Sequence[str],
+    provided_token: str | None,
+    headers: httpx.Headers,
+    params: list[tuple[str, str]],
+) -> None:
+    """Sets the credentials of the schemes ``names`` on a request's headers and query."""
+    for name in names:
+        scheme = cfg.security_schemes[name]
+        if scheme.kind == "bearer":
+            token = (
+                provided_token
+                if provided_token is not None
+                else cfg.bearer_access_token
+            )
+            headers["authorization"] = f"Bearer {token}"
+        elif scheme.kind == "basic":
+            assert cfg.basic_auth is not None
+            raw = ":".join(cfg.basic_auth).encode()
+            headers["authorization"] = f"Basic {base64.b64encode(raw).decode()}"
+        else:
+            key = cfg.api_keys.get(name) or cfg.bearer_access_token or ""
+            if scheme.location == "query":
+                params.append((scheme.param, key))
+            elif scheme.location == "cookie":
+                cookie = (
+                    f"{scheme.param}={urllib.parse.quote(key, safe=_COOKIE_OCTETS)}"
+                )
+                previous = headers.get("cookie")
+                headers["cookie"] = (
+                    cookie if previous is None else f"{previous}; {cookie}"
+                )
+            else:
+                headers[scheme.param.lower()] = key

meteroid/api/_errors.py

@@ -0,0 +1,125 @@
+# this file is @generated
+"""API errors by status, carrying the decoded error body."""
+
+from __future__ import annotations
+
+import typing as t
+
+import httpx
+
+from .. import models as _models
+from .._exceptions import APIError, request_of
+from ..serialization import JSONValue
+from ._response import request_id
+
+__all__ = [
+    "APIStatusError",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConflictError",
+    "ErrorBody",
+    "InternalServerError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "UnprocessableEntityError",
+    "error_class",
+]
+
+_MAX_DETAIL = 500
+
+ErrorBody: t.TypeAlias = _models.OAuthErrorResponse | _models.RestErrorResponse
+"""The error responses the API declares."""
+
+
+class APIStatusError(APIError):
+    """The API answered with a non-2xx status. Subclasses tell the common ones apart."""
+
+    response: httpx.Response
+    status_code: int
+    body: ErrorBody | JSONValue
+    """The error response decoded into the schema the operation declares for its
+    status; its JSON when it declares none or it does not match; else `None`."""
+
+    def __init__(self, response: httpx.Response, body: object) -> None:
+        detail = _body_text(response) or response.reason_phrase or "error"
+        super().__init__(
+            f"Error code: {response.status_code} - {detail}", request_of(response)
+        )
+        self.response = response
+        self.status_code = response.status_code
+        self.body = t.cast("ErrorBody | JSONValue", body)
+
+    @property
+    def headers(self) -> httpx.Headers:
+        """The response headers."""
+        return self.response.headers
+
+    @property
+    def request_id(self) -> str | None:
+        """The request id to quote to support, when the API sends one."""
+        return request_id(self.response.headers)
+
+    @property
+    def raw_body(self) -> bytes:
+        """The response body."""
+        return self.response.content
+
+
+def _body_text(response: httpx.Response) -> str:
+    """The start of the response body, for the error message."""
+    try:
+        text = response.text.strip()
+    except httpx.ResponseNotRead:
+        return ""
+    return text if len(text) <= _MAX_DETAIL else f"{text[:_MAX_DETAIL]}..."
+
+
+class BadRequestError(APIStatusError):
+    """400 Bad Request."""
+
+
+class AuthenticationError(APIStatusError):
+    """401 Unauthorized."""
+
+
+class PermissionDeniedError(APIStatusError):
+    """403 Forbidden."""
+
+
+class NotFoundError(APIStatusError):
+    """404 Not Found."""
+
+
+class ConflictError(APIStatusError):
+    """409 Conflict."""
+
+
+class UnprocessableEntityError(APIStatusError):
+    """422 Unprocessable Entity."""
+
+
+class RateLimitError(APIStatusError):
+    """429 Too Many Requests, once retries are exhausted."""
+
+
+class InternalServerError(APIStatusError):
+    """Any 5xx status, once retries are exhausted."""
+
+
+_BY_STATUS: dict[int, type[APIStatusError]] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: UnprocessableEntityError,
+    429: RateLimitError,
+}
+
+
+def error_class(status_code: int) -> type[APIStatusError]:
+    """The error raised for a response with this status."""
+    if status_code >= 500:
+        return InternalServerError
+    return _BY_STATUS.get(status_code, APIStatusError)