magic_hour 0.8.0__py3-none-any.whl

magic_hour/core/request.py

@@ -0,0 +1,158 @@
+from typing import Any, Dict, Type, Union, Sequence, List
+from urllib.parse import quote_plus
+import httpx
+from typing_extensions import TypedDict, Required, NotRequired
+from pydantic import TypeAdapter, BaseModel
+from .type_utils import NotGiven
+
+"""
+Request configuration and utility functions for handling HTTP requests.
+This module provides type definitions and helper functions for building
+and processing HTTP requests in a type-safe manner.
+"""
+
+# Type alias for query parameters that can handle both primitive data and sequences
+QueryParams = Dict[
+    str, Union[httpx._types.PrimitiveData, Sequence[httpx._types.PrimitiveData]]
+]
+
+
+class RequestConfig(TypedDict):
+    """
+    Configuration for HTTP requests.
+
+    Defines all possible parameters that can be passed to an HTTP request,
+    including required method and URL, as well as optional parameters like
+    content, headers, authentication, etc.
+    """
+
+    method: Required[str]
+    url: Required[httpx._types.URLTypes]
+    content: NotRequired[httpx._types.RequestContent]
+    data: NotRequired[httpx._types.RequestData]
+    files: NotRequired[httpx._types.RequestFiles]
+    json: NotRequired[Any]
+    params: NotRequired[QueryParams]
+    headers: NotRequired[Dict[str, str]]
+    cookies: NotRequired[Dict[str, str]]
+    auth: NotRequired[httpx._types.AuthTypes]
+    follow_redirects: NotRequired[bool]
+    timeout: NotRequired[httpx._types.TimeoutTypes]
+    extensions: NotRequired[httpx._types.RequestExtensions]
+
+
+class RequestOptions(TypedDict):
+    """
+    Additional options for customizing request behavior.
+
+    Provides configuration for timeouts and additional headers/parameters
+    that should be included with requests.
+
+    Attributes:
+        timeout: Number of seconds to await an API call before timing out
+        additional_headers: Extra headers to include in the request
+        additional_params: Extra query parameters to include in the request
+    """
+
+    timeout: NotRequired[int]
+    additional_headers: NotRequired[Dict[str, str]]
+    additional_params: NotRequired[QueryParams]
+
+
+def default_request_options() -> RequestOptions:
+    """
+    Provides default request options.
+
+    Returns an empty dictionary as the base configuration, allowing defaults
+    to be handled by the underlying HTTP client.
+    """
+    return {}
+
+
+def model_dump(item: Any) -> Any:
+    """
+    Recursively converts Pydantic models to dictionaries.
+
+    Handles nested structures including lists and individual models,
+    preserving alias information and excluding unset values.
+    """
+    if isinstance(item, list):
+        return [model_dump(i) for i in item]
+    if isinstance(item, BaseModel):
+        return item.model_dump(exclude_unset=True, by_alias=True)
+    else:
+        return item
+
+
+def to_encodable(
+    *, item: Any, dump_with: Union[Type, Union[Type, Any], List[Type]]
+) -> Any:
+    """
+    Validates and converts an item to an encodable format using a specified type.
+    Uses Pydantic's TypeAdapter for validation and converts the result
+    to a format suitable for encoding in requests.
+    """
+    filtered_item = filter_not_given(item)
+    adapter: TypeAdapter = TypeAdapter(dump_with)
+    validated_item = adapter.validate_python(filtered_item)
+    return model_dump(validated_item)
+
+
+def to_content(*, file: httpx._types.FileTypes) -> httpx._types.RequestContent:
+    """
+    Converts the various ways files can be provided to something that is accepted by
+    the httpx.request content kwarg
+    """
+    if isinstance(file, tuple):
+        file_content: httpx._types.FileContent = file[1]
+    else:
+        file_content = file
+
+    if hasattr(file_content, "read") and callable(file_content.read):
+        return file_content.read()
+    else:
+        return file_content
+
+
+def encode_param(
+    value: Any, explode: bool
+) -> Union[httpx._types.PrimitiveData, Sequence[httpx._types.PrimitiveData]]:
+    """
+    Encodes parameter values for use in URLs.
+
+    Handles both simple values and collections, with special handling for
+    unexploded collections (combining them with commas) versus exploded ones.
+
+    Args:
+        explode: Whether to explode collections into separate parameters
+    """
+    if isinstance(value, (list, dict)) and not explode:
+        return quote_plus(",".join(map(str, value)))
+    else:
+        return value
+
+
+def filter_not_given(value: Any) -> Any:
+    """Helper function to recursively filter out NotGiven values"""
+    if isinstance(value, NotGiven):
+        return None  # This will trigger filtering at the container level
+    elif isinstance(value, dict):
+        return {
+            k: filter_not_given(v)
+            for k, v in value.items()
+            if not isinstance(v, NotGiven)
+        }
+    elif isinstance(value, (list, tuple)):
+        return type(value)(
+            filter_not_given(item) for item in value if not isinstance(item, NotGiven)
+        )
+    return value
+
+
+def _get_default_for_type(value_type: Any) -> Any:
+    """Helper to provide appropriate default values for required fields"""
+    if value_type is dict or isinstance(value_type, dict):
+        return {}
+    elif value_type is list or isinstance(value_type, list):
+        return []
+    return None

magic_hour/core/response.py

@@ -0,0 +1,293 @@
+import json
+from typing import Any, Union, Dict, Type, TypeVar, List, Generic, Optional
+from pydantic import BaseModel
+import httpx
+
+"""
+Provides functionality for handling Server-Sent Events (SSE) streams and response data encoding.
+Includes utilities for both synchronous and asynchronous stream processing.
+"""
+
+EncodableT = TypeVar(
+    "EncodableT",
+    bound=Union[
+        object,
+        str,
+        int,
+        float,
+        None,
+        BaseModel,
+        List[Any],
+        Dict[str, Any],
+    ],
+)
+
+
+def from_encodable(*, data: Any, load_with: Type[EncodableT]) -> Any:
+    """
+    Converts raw data into a specified type using Pydantic validation.
+
+    Uses a dynamic Pydantic model to validate and convert incoming data
+    into the specified target type.
+    """
+
+    class Caster(BaseModel):
+        data: load_with  # type: ignore
+
+    return Caster(data=data).data
+
+
+T = TypeVar("T")
+
+
+class StreamResponse(Generic[T]):
+    """
+    Handles synchronous streaming of Server-Sent Events (SSE).
+
+    Processes a streaming HTTP response by buffering chunks of data
+    and parsing them according to SSE format, converting each event
+    into the specified type.
+    """
+
+    def __init__(self, response: httpx.Response, stream_context, cast_to: Type[T]):
+        """
+        Initialize the stream processor with response and conversion settings.
+
+        Args:
+            response: The HTTP response containing the SSE stream
+            stream_context: Context manager for the stream
+            cast_to: Target type for converting parsed events
+        """
+        self.response = response
+        self._context = stream_context
+        self.cast_to = cast_to
+        self.iterator = response.iter_bytes()
+        self.buffer = bytearray()
+        self.position = 0
+
+    def __iter__(self):
+        """Enables iteration over the stream events."""
+        return self
+
+    def __next__(self) -> T:
+        """
+        Retrieves and processes the next event from the stream.
+
+        Buffers incoming data and processes it according to SSE format,
+        converting each complete event into the specified type.
+
+        Raises:
+            StopIteration: When the stream is exhausted
+        """
+        try:
+            while True:
+                event = self._process_buffer()
+                if event:
+                    return event
+
+                chunk = next(self.iterator)
+                self.buffer += chunk
+
+        except StopIteration:
+            event = self._process_buffer(final=True)
+            if event:
+                return event
+            self._context.__exit__(None, None, None)
+            raise
+
+    def _process_buffer(self, final=False) -> Optional[T]:
+        """
+        Processes the current buffer to extract complete SSE events.
+
+        Searches for event boundaries and parses complete events,
+        handling both JSON and non-JSON payloads.
+
+        Args:
+            final: Whether this is the final processing of the buffer
+        """
+        while self.position < len(self.buffer):
+            for boundary in [b"\r\n\r\n", b"\n\n", b"\r\r"]:
+                if (self.position + len(boundary)) <= len(self.buffer):
+                    if (
+                        self.buffer[self.position : self.position + len(boundary)]
+                        == boundary
+                    ):
+                        message = self.buffer[: self.position].decode()
+                        self.buffer = self.buffer[self.position + len(boundary) :]
+                        self.position = 0
+
+                        data = self._parse_sse(message)
+                        if data:
+                            try:
+                                parsed_data = json.loads(data)
+                                if (
+                                    not isinstance(parsed_data, dict)
+                                    or "data" not in parsed_data
+                                ):
+                                    parsed_data = {"data": parsed_data}
+                                return from_encodable(
+                                    data=parsed_data, load_with=self.cast_to
+                                )
+                            except json.JSONDecodeError:
+                                return from_encodable(
+                                    data={"data": data}, load_with=self.cast_to
+                                )
+                        return None
+
+            self.position += 1
+
+        if final and self.buffer:
+            message = self.buffer.decode()
+            data = self._parse_sse(message)
+            if data:
+                try:
+                    parsed_data = json.loads(data)
+                    if not isinstance(parsed_data, dict) or "data" not in parsed_data:
+                        parsed_data = {"data": parsed_data}
+                    return from_encodable(data=parsed_data, load_with=self.cast_to)
+                except json.JSONDecodeError:
+                    return from_encodable(data={"data": data}, load_with=self.cast_to)
+
+        return None
+
+    def _parse_sse(self, message: str) -> Optional[str]:
+        """
+        Parses an SSE message to extract the data field.
+
+        Handles multi-line data fields and empty data fields according
+        to the SSE specification.
+        """
+        data = []
+        for line in message.split("\n"):
+            if line.startswith("data:"):
+                data.append(line[5:].strip())
+            elif line.strip() == "data:":  # Handle empty data field
+                data.append("")
+
+        if data:
+            return "\n".join(data)
+        return None
+
+
+class AsyncStreamResponse(Generic[T]):
+    """
+    Handles asynchronous streaming of Server-Sent Events (SSE).
+
+    Asynchronous version of StreamResponse, providing the same functionality
+    but compatible with async/await syntax.
+    """
+
+    def __init__(self, response: httpx.Response, stream_context, cast_to: Type[T]):
+        """
+        Initialize the async stream processor.
+
+        Args:
+            response: The HTTP response containing the SSE stream
+            stream_context: Async context manager for the stream
+            cast_to: Target type for converting parsed events
+        """
+        self.response = response
+        self._context = stream_context
+        self.cast_to = cast_to
+        self.iterator = response.aiter_bytes()
+        self.buffer = bytearray()
+        self.position = 0
+
+    def __aiter__(self):
+        """Enables async iteration over the stream events."""
+        return self
+
+    async def __anext__(self) -> T:
+        """
+        Asynchronously retrieves and processes the next event from the stream.
+
+        Similar to synchronous version but uses async/await syntax for
+        iteration and context management.
+
+        Raises:
+            StopAsyncIteration: When the stream is exhausted
+        """
+        try:
+            while True:
+                event = self._process_buffer()
+                if event:
+                    return event
+
+                chunk = await self.iterator.__anext__()
+                self.buffer += chunk
+
+        except StopAsyncIteration:
+            event = self._process_buffer(final=True)
+            if event:
+                return event
+            await self._context.__aexit__(None, None, None)
+            raise
+
+    def _process_buffer(self, final=False) -> Optional[T]:
+        """
+        Processes the current buffer to extract complete SSE events.
+
+        Identical to the synchronous version's buffer processing.
+        """
+        while self.position < len(self.buffer):
+            for boundary in [b"\r\n\r\n", b"\n\n", b"\r\r"]:
+                if (self.position + len(boundary)) <= len(self.buffer):
+                    if (
+                        self.buffer[self.position : self.position + len(boundary)]
+                        == boundary
+                    ):
+                        message = self.buffer[: self.position].decode()
+                        self.buffer = self.buffer[self.position + len(boundary) :]
+                        self.position = 0
+
+                        data = self._parse_sse(message)
+                        if data:
+                            try:
+                                parsed_data = json.loads(data)
+                                if (
+                                    not isinstance(parsed_data, dict)
+                                    or "data" not in parsed_data
+                                ):
+                                    parsed_data = {"data": parsed_data}
+                                return from_encodable(
+                                    data=parsed_data, load_with=self.cast_to
+                                )
+                            except json.JSONDecodeError:
+                                return from_encodable(
+                                    data={"data": data}, load_with=self.cast_to
+                                )
+                        return None
+
+            self.position += 1
+
+        if final and self.buffer:
+            message = self.buffer.decode()
+            data = self._parse_sse(message)
+            if data:
+                try:
+                    parsed_data = json.loads(data)
+                    if not isinstance(parsed_data, dict) or "data" not in parsed_data:
+                        parsed_data = {"data": parsed_data}
+                    return from_encodable(data=parsed_data, load_with=self.cast_to)
+                except json.JSONDecodeError:
+                    return from_encodable(data={"data": data}, load_with=self.cast_to)
+
+        return None
+
+    def _parse_sse(self, message: str) -> Optional[str]:
+        """
+        Parses an SSE message to extract the data field.
+
+        Identical to the synchronous version's SSE parsing.
+        """
+        data = []
+        for line in message.split("\n"):
+            line = line.strip()
+            if line.startswith("data:"):
+                data.append(line[5:].strip())
+            elif line == "data:":  # Handle empty data field
+                data.append("")
+
+        if data:
+            return "\n".join(data)
+        return None

magic_hour/core/type_utils.py

@@ -0,0 +1,28 @@
+from typing import (
+    Union,
+)
+from typing_extensions import (
+    Literal,
+    TypeVar,
+    override,
+)
+
+_T = TypeVar("_T")
+
+
+class NotGiven:
+    """
+    Used to distinguish omitted keyword arguments from those passed explicitly
+    with the value None.
+    """
+
+    def __bool__(self) -> Literal[False]:
+        return False
+
+    @override
+    def __repr__(self) -> str:
+        return "NOT_GIVEN"
+
+
+NotGivenOr = Union[_T, NotGiven]
+NOT_GIVEN = NotGiven()

magic_hour/core/utils.py

@@ -0,0 +1,38 @@
+import typing
+import httpx
+
+
+def remove_none_from_dict(
+    original: typing.Dict[str, typing.Optional[typing.Any]],
+) -> typing.Dict[str, typing.Any]:
+    new: typing.Dict[str, typing.Any] = {}
+    for key, value in original.items():
+        if value is not None:
+            new[key] = value
+    return new
+
+
+def is_binary_content_type(content_type: str) -> bool:
+    """Check if the content type indicates binary data."""
+    binary_types = [
+        "application/octet-stream",
+        "application/pdf",
+        "application/zip",
+        "image/",
+        "audio/",
+        "video/",
+        "application/msword",
+        "application/vnd.openxmlformats-officedocument",
+        "application/x-binary",
+        "application/vnd.ms-excel",
+        "application/vnd.ms-powerpoint",
+    ]
+    return any(binary_type in content_type for binary_type in binary_types)
+
+
+def get_content_type(headers: httpx.Headers) -> str:
+    """Get content type in a case-insensitive manner."""
+    for key, value in headers.items():
+        if key.lower() == "content-type":
+            return value.lower()
+    return ""

magic_hour/environment.py

@@ -0,0 +1,6 @@
+import enum
+
+
+class Environment(enum.Enum):
+    ENVIRONMENT = "https://api.magichour.ai"
+    MOCK_SERVER = "https://api.sideko.dev/v1/mock/magichour/magic-hour/0.8.0"

magic_hour/resources/v1/__init__.py

@@ -0,0 +1,4 @@
+from .client import AsyncV1Client, V1Client
+
+
+__all__ = ["AsyncV1Client", "V1Client"]

magic_hour/resources/v1/ai_clothes_changer/README.md

@@ -0,0 +1,41 @@
+
+### create <a name="create"></a>
+AI Clothes Changer
+
+Change outfits in photos in seconds with just a photo reference. Each photo costs 25 frames.
+
+**API Endpoint**: `POST /v1/ai-clothes-changer`
+
+#### Synchronous Client
+
+```python
+from magic_hour import Client
+from os import getenv
+
+client = Client(token=getenv("API_TOKEN"))
+res = client.v1.ai_clothes_changer.create(
+    assets={
+        "garment_file_path": "api-assets/id/outfit.png",
+        "garment_type": "dresses",
+        "person_file_path": "api-assets/id/model.png",
+    },
+    name="Clothes Changer image",
+)
+```
+
+#### Asynchronous Client
+
+```python
+from magic_hour import AsyncClient
+from os import getenv
+
+client = AsyncClient(token=getenv("API_TOKEN"))
+res = await client.v1.ai_clothes_changer.create(
+    assets={
+        "garment_file_path": "api-assets/id/outfit.png",
+        "garment_type": "dresses",
+        "person_file_path": "api-assets/id/model.png",
+    },
+    name="Clothes Changer image",
+)
+```

magic_hour/resources/v1/ai_clothes_changer/__init__.py

@@ -0,0 +1,4 @@
+from .client import AiClothesChangerClient, AsyncAiClothesChangerClient
+
+
+__all__ = ["AiClothesChangerClient", "AsyncAiClothesChangerClient"]