magic_hour 0.8.0__py3-none-any.whl

magic_hour/__init__.py

@@ -0,0 +1,6 @@
+from .core import ApiError, BinaryResponse
+from .client import AsyncClient, Client
+from .environment import Environment
+
+
+__all__ = ["ApiError", "AsyncClient", "BinaryResponse", "Client", "Environment"]

magic_hour/client.py

@@ -0,0 +1,61 @@
+import httpx
+import typing
+
+from magic_hour.core import AsyncBaseClient, AuthBearer, SyncBaseClient
+from magic_hour.environment import Environment
+from magic_hour.resources.v1 import AsyncV1Client, V1Client
+
+
+class Client:
+    def __init__(
+        self,
+        *,
+        base_url: typing.Optional[str] = None,
+        timeout: typing.Optional[float] = 60,
+        httpx_client: typing.Optional[httpx.Client] = None,
+        environment: Environment = Environment.ENVIRONMENT,
+        token: typing.Optional[str] = None,
+    ):
+        self._base_client = SyncBaseClient(
+            base_url=_get_base_url(base_url=base_url, environment=environment),
+            httpx_client=(
+                httpx.Client(timeout=timeout) if httpx_client is None else httpx_client
+            ),
+        )
+
+        self.v1 = V1Client(base_client=self._base_client)
+        self._base_client.register_auth("bearerAuth", AuthBearer(val=token))
+
+
+class AsyncClient:
+    def __init__(
+        self,
+        *,
+        base_url: typing.Optional[str] = None,
+        timeout: typing.Optional[float] = 60,
+        httpx_client: typing.Optional[httpx.AsyncClient] = None,
+        environment: Environment = Environment.ENVIRONMENT,
+        token: typing.Optional[str] = None,
+    ):
+        self._base_client = AsyncBaseClient(
+            base_url=_get_base_url(base_url=base_url, environment=environment),
+            httpx_client=(
+                httpx.AsyncClient(timeout=timeout)
+                if httpx_client is None
+                else httpx_client
+            ),
+        )
+
+        self.v1 = AsyncV1Client(base_client=self._base_client)
+        self._base_client.register_auth("bearerAuth", AuthBearer(val=token))
+
+
+def _get_base_url(
+    *, base_url: typing.Optional[str] = None, environment: Environment
+) -> str:
+    if base_url is not None:
+        return base_url
+    elif environment is not None:
+        return environment.value
+    else:
+        raise Exception("Must include a base_url or environment arguments")

magic_hour/core/__init__.py

@@ -0,0 +1,53 @@
+from .api_error import ApiError
+from .auth import (
+    AuthKeyQuery,
+    AuthBasic,
+    AuthBearer,
+    AuthProvider,
+    AuthKeyCookie,
+    AuthKeyHeader,
+    GrantType,
+    OAuth2,
+    OAuth2ClientCredentialsForm,
+    OAuth2PasswordForm,
+)
+from .base_client import AsyncBaseClient, BaseClient, SyncBaseClient
+from .binary_response import BinaryResponse
+from .request import (
+    encode_param,
+    filter_not_given,
+    to_content,
+    to_encodable,
+    RequestOptions,
+    default_request_options,
+    QueryParams,
+)
+from .response import from_encodable, AsyncStreamResponse, StreamResponse
+
+__all__ = [
+    "ApiError",
+    "AsyncBaseClient",
+    "BaseClient",
+    "BinaryResponse",
+    "RequestOptions",
+    "default_request_options",
+    "SyncBaseClient",
+    "AuthKeyQuery",
+    "AuthBasic",
+    "AuthBearer",
+    "AuthProvider",
+    "AuthKeyCookie",
+    "AuthKeyHeader",
+    "GrantType",
+    "OAuth2",
+    "OAuth2ClientCredentialsForm",
+    "OAuth2PasswordForm",
+    "to_encodable",
+    "filter_not_given",
+    "to_content",
+    "encode_param",
+    "from_encodable",
+    "AsyncStreamResponse",
+    "StreamResponse",
+    "QueryParams",
+]

magic_hour/core/api_error.py

@@ -0,0 +1,48 @@
+import typing
+
+
+class ApiError(Exception):
+    """
+    A custom exception class for handling API-related errors.
+
+    This class extends the base Exception class to provide additional context
+    for API errors, including the HTTP status code and response body.
+
+    Attributes:
+        status_code: The HTTP status code associated with the error.
+            None if no status code is applicable.
+        body: The response body or error message content.
+            Can be any type depending on the API response format.
+    """
+
+    status_code: typing.Optional[int]
+    body: typing.Any
+
+    def __init__(
+        self, *, status_code: typing.Optional[int] = None, body: typing.Any = None
+    ) -> None:
+        """
+        Initialize the ApiError with optional status code and body.
+
+        Args:
+            status_code: The HTTP status code of the error.
+                Defaults to None.
+            body: The response body or error message content.
+                Defaults to None.
+
+        Note:
+            The asterisk (*) in the parameters forces keyword arguments,
+            making the instantiation more explicit.
+        """
+        self.status_code = status_code
+        self.body = body
+
+    def __str__(self) -> str:
+        """
+        Return a string representation of the ApiError.
+
+        Returns:
+            str: A formatted string containing the status code and body.
+                Format: "status_code: {status_code}, body: {body}"
+        """
+        return f"status_code: {self.status_code}, body: {self.body}"

magic_hour/core/auth.py

@@ -0,0 +1,314 @@
+import abc
+import datetime
+from typing import Any, Dict, TypedDict, Optional, List, Tuple, Literal
+
+import jsonpointer  # type: ignore
+import httpx
+from pydantic import BaseModel
+from .request import RequestConfig
+
+
+class AuthProvider(abc.ABC, BaseModel):
+    """
+    Abstract base class defining the interface for authentication providers.
+
+    Each concrete implementation handles a specific authentication method
+    and modifies the request configuration accordingly.
+    """
+
+    @abc.abstractmethod
+    def add_to_request(self, cfg: RequestConfig) -> RequestConfig:
+        """
+        Adds authentication details to the request configuration.
+
+        Args:
+            cfg: The request configuration to modify
+
+        Returns:
+            The modified request configuration with authentication details added
+        """
+
+    @abc.abstractmethod
+    def set_value(self, val: Optional[str]) -> None:
+        """
+        Generic method to set an auth value.
+
+        Args:
+            val: Authentication value to set
+        """
+
+
+class AuthBasic(AuthProvider):
+    """
+    Implements HTTP Basic Authentication.
+
+    Adds username and password credentials to the request using the standard
+    HTTP Basic Authentication scheme.
+    """
+
+    username: Optional[str]
+    password: Optional[str]
+
+    def add_to_request(self, cfg: RequestConfig) -> RequestConfig:
+        """
+        Adds Basic Authentication credentials to the request configuration.
+
+        Only modifies the configuration if both username and password are provided.
+        """
+        if self.username is not None and self.password is not None:
+            cfg["auth"] = (self.username, self.password)
+        return cfg
+
+    def set_value(self, val: Optional[str]) -> None:
+        """
+        Sets value as the username
+        """
+        self.username = val
+
+
+class AuthBearer(AuthProvider):
+    """
+    Implements Bearer token authentication.
+
+    Adds a Bearer token to the request's Authorization header following
+    the OAuth 2.0 Bearer Token scheme.
+    """
+
+    val: Optional[str]
+
+    def add_to_request(self, cfg: RequestConfig) -> RequestConfig:
+        """
+        Adds Bearer token to the Authorization header.
+
+        Only modifies the configuration if a token value is provided.
+        """
+        if self.val is not None:
+            headers = cfg.get("headers", dict())
+            headers["Authorization"] = f"Bearer {self.val}"
+            cfg["headers"] = headers
+        return cfg
+
+    def set_value(self, val: Optional[str]) -> None:
+        """
+        Sets value as the bearer token
+        """
+        self.val = val
+
+
+class AuthKeyQuery(AuthProvider):
+    """
+    Implements query parameter-based authentication.
+
+    Adds an authentication token or key as a query parameter with a
+    configurable parameter name.
+    """
+
+    query_name: str
+    val: Optional[str]
+
+    def add_to_request(self, cfg: RequestConfig) -> RequestConfig:
+        """
+        Adds authentication value as a query parameter.
+
+        Only modifies the configuration if a value is provided.
+        """
+        if self.val is not None:
+            params = cfg.get("params", dict())
+            params[self.query_name] = self.val
+            cfg["params"] = params
+        return cfg
+
+    def set_value(self, val: Optional[str]) -> None:
+        """
+        Sets value as the key
+        """
+        self.val = val
+
+
+class AuthKeyHeader(AuthProvider):
+    """
+    Implements header-based authentication.
+
+    Adds an authentication token or key as a custom header with a
+    configurable header name.
+    """
+
+    header_name: str
+    val: Optional[str]
+
+    def add_to_request(self, cfg: RequestConfig) -> RequestConfig:
+        """
+        Adds authentication value as a custom header.
+
+        Only modifies the configuration if a value is provided.
+        """
+        if self.val is not None:
+            headers = cfg.get("headers", {})
+            headers[self.header_name] = self.val
+            cfg["headers"] = headers
+        return cfg
+
+    def set_value(self, val: Optional[str]) -> None:
+        """
+        Sets value as the key
+        """
+        self.val = val
+
+
+class AuthKeyCookie(AuthProvider):
+    """
+    Implements cookie-based authentication.
+
+    Adds an authentication token or key as a cookie with a
+    configurable cookie name.
+    """
+
+    cookie_name: str
+    val: Optional[str]
+
+    def add_to_request(self, cfg: RequestConfig) -> RequestConfig:
+        """
+        Adds authentication value as a cookie.
+
+        Only modifies the configuration if a value is provided.
+        """
+        if self.val is not None:
+            cookies = cfg.get("cookies", dict())
+            cookies[self.cookie_name] = self.val
+            cfg["cookies"] = cookies
+        return cfg
+
+    def set_value(self, val: Optional[str]) -> None:
+        """
+        Sets value as the key
+        """
+        self.val = val
+
+
+class OAuth2PasswordForm(TypedDict, total=True):
+    """
+    OAuth2 authentication form for a password flow
+
+    Details:
+    https://datatracker.ietf.org/doc/html/rfc6749#section-4.3
+    """
+
+    username: str
+    password: str
+    client_id: Optional[str]
+    client_secret: Optional[str]
+    grant_type: Optional[str]
+    scope: Optional[List[str]]
+
+
+class OAuth2ClientCredentialsForm(TypedDict, total=True):
+    """
+    OAuth2 authentication form for a client credentials flow
+
+    Details:
+    https://datatracker.ietf.org/doc/html/rfc6749#section-4.4
+    """
+
+    client_id: str
+    client_secret: str
+    grant_type: Optional[str]
+    scope: Optional[List[str]]
+
+
+GrantType = Literal["password", "client_credentials"]
+CredentialsLocation = Literal["request_body", "basic_authorization_header"]
+BodyContent = Literal["form", "json"]
+
+
+class OAuth2(AuthProvider):
+    """
+    Implements OAuth2 token retrieval and refreshing.
+    Currently supports `password` and `client_credentials`
+    grant types.
+    """
+
+    # OAuth2 provider configuration
+    token_url: str
+    access_token_pointer: str
+    expires_in_pointer: str
+    credentials_location: CredentialsLocation
+    body_content: BodyContent
+    request_mutator: AuthProvider
+
+    # OAuth2 access token request values
+    grant_type: GrantType
+    username: Optional[str] = None
+    password: Optional[str] = None
+    client_id: Optional[str] = None
+    client_secret: Optional[str] = None
+    scope: Optional[List[str]] = None
+
+    # access_token storage
+    access_token: Optional[str] = None
+    expires_at: Optional[datetime.datetime] = None
+
+    def _refresh(self) -> Tuple[str, datetime.datetime]:
+        req_cfg: Dict[str, Any] = {"url": self.token_url}
+        req_data: Dict[str, Any] = {"grant_type": self.grant_type}
+
+        # add client credentials
+        if self.client_id is not None or self.client_secret is not None:
+            if self.credentials_location == "basic_authorization_header":
+                req_cfg["auth"] = (self.client_id, self.client_secret)
+            else:
+                req_data["client_id"] = self.client_id
+                req_data["client_secret"] = self.client_secret
+
+        # construct request data
+        if self.username is not None:
+            req_data["username"] = self.username
+        if self.password is not None:
+            req_data["password"] = self.password
+        if self.scope is not None:
+            req_data["scope"] = " ".join(self.scope)
+
+        if self.body_content == "json":
+            req_cfg["json"] = req_data
+            req_cfg["headers"] = {"content-type": "application/json"}
+        else:
+            req_cfg["data"] = req_data
+            req_cfg["headers"] = {"content-type": "application/x-www-form-urlencoded"}
+
+        # make access token request
+        token_res = httpx.post(**req_cfg)
+        token_res.raise_for_status()
+
+        # retrieve access token & optional expiry seconds
+        token_res_json: Dict[str, Any] = token_res.json()
+        access_token = str(
+            jsonpointer.resolve_pointer(token_res_json, self.access_token_pointer)
+        )
+
+        expires_in_secs = jsonpointer.resolve_pointer(
+            token_res_json, self.expires_in_pointer
+        )
+        if not isinstance(expires_in_secs, int):
+            expires_in_secs = 600
+        expires_at = datetime.datetime.now() + datetime.timedelta(
+            seconds=(
+                expires_in_secs - 60
+            )  # subtract a minute from the expiry as a buffer
+        )
+
+        return (access_token, expires_at)
+
+    def add_to_request(self, cfg: RequestConfig) -> RequestConfig:
+        token_expired = (
+            self.expires_at is not None and self.expires_at <= datetime.datetime.now()
+        )
+
+        if self.access_token is None or token_expired:
+            access_token, expires_at = self._refresh()
+            self.expires_at = expires_at
+            self.access_token = access_token
+
+        self.request_mutator.set_value(self.access_token)
+        return self.request_mutator.add_to_request(cfg)
+
+    def set_value(self, _val: Optional[str]) -> None:
+        raise NotImplementedError("an OAuth2 auth provider cannot be a request_mutator")