magic_hour 0.35.0__py3-none-any.whl → 0.36.1__py3-none-any.whl

magic_hour/resources/v1/image_projects/client_test.py

@@ -0,0 +1,527 @@
+import datetime
+import pytest
+import httpx
+from pathlib import Path
+from typing import Any, Generator, Literal, Union, List
+from unittest.mock import Mock, AsyncMock
+
+from magic_hour.types import models
+from magic_hour.resources.v1.image_projects.client import (
+    ImageProjectsClient,
+    AsyncImageProjectsClient,
+)
+
+
+class DummyResponse(models.V1ImageProjectsGetResponse):
+    """Helper response with defaults"""
+
+    def __init__(
+        self,
+        *,
+        status: Literal[
+            "complete", "queued", "rendering", "error", "canceled"
+        ] = "complete",
+        download_url: Union[str, None] = None,
+        error: Union[str, None] = None,
+    ):
+        # Create error object if error string is provided
+        error_obj = None
+        if error:
+            error_obj = models.V1ImageProjectsGetResponseError(
+                code="TEST_ERROR", message=error
+            )
+
+        super().__init__(
+            id="test-id",
+            created_at=datetime.datetime.now().isoformat(),
+            credits_charged=0,
+            enabled=True,
+            image_count=0,
+            name="test-name",
+            total_frame_cost=0,
+            type="test-type",
+            status=status,
+            downloads=[
+                models.V1ImageProjectsGetResponseDownloadsItem(
+                    url=download_url, expires_at="2024-01-01T00:00:00Z"
+                )
+            ]
+            if download_url
+            else [],
+            error=error_obj,
+        )
+
+
+@pytest.fixture
+def mock_base_client() -> Generator[Mock, None, None]:
+    yield Mock()
+
+
+@pytest.fixture
+def mock_async_base_client() -> Generator[AsyncMock, None, None]:
+    yield AsyncMock()
+
+
+def test_delete_calls_base_client(mock_base_client: Mock) -> None:
+    client = ImageProjectsClient(base_client=mock_base_client)
+    client.delete(id="123")
+
+    mock_base_client.request.assert_called_once()
+    call = mock_base_client.request.call_args[1]
+    assert call["method"] == "DELETE"
+    assert "/v1/image-projects/123" in call["path"]
+
+
+def test_get_calls_base_client(mock_base_client: Mock) -> None:
+    client = ImageProjectsClient(base_client=mock_base_client)
+    mock_base_client.request.return_value = DummyResponse()
+
+    resp = client.get(id="abc")
+
+    mock_base_client.request.assert_called_once()
+    assert isinstance(resp, models.V1ImageProjectsGetResponse)
+    assert resp.id == "test-id"
+
+
+def test_check_result_no_wait_no_download(mock_base_client: Mock) -> None:
+    client = ImageProjectsClient(base_client=mock_base_client)
+    mock_base_client.request.return_value = DummyResponse(status="queued")
+
+    resp = client.check_result(
+        id="xyz",
+        wait_for_completion=False,
+        download_outputs=False,
+    )
+
+    assert resp.downloaded_paths is None
+
+
+def test_check_result_wait_until_complete(
+    monkeypatch: Any, mock_base_client: Mock
+) -> None:
+    client = ImageProjectsClient(base_client=mock_base_client)
+
+    # First calls return queued, then complete
+    mock_base_client.request.side_effect = [
+        DummyResponse(status="queued"),
+        DummyResponse(status="queued"),
+        DummyResponse(status="complete"),
+    ]
+
+    monkeypatch.setattr("time.sleep", lambda _: None)  # type: ignore
+
+    resp = client.check_result(
+        id="xyz", wait_for_completion=True, download_outputs=False
+    )
+
+    assert resp.status == "complete"
+    assert resp.downloaded_paths is None
+
+
+def test_check_result_download_outputs(
+    tmp_path: Path, mock_base_client: Mock, monkeypatch: Any
+) -> None:
+    client = ImageProjectsClient(base_client=mock_base_client)
+
+    file_url = "https://example.com/file.png"
+    mock_base_client.request.return_value = DummyResponse(
+        status="complete",
+        download_url=file_url,
+    )
+
+    # Create a mock response for httpx
+    mock_request = httpx.Request("GET", "https://example.com/file.png")
+    mock_response = httpx.Response(200, content=b"fake png", request=mock_request)
+
+    # Mock the httpx.Client class
+    class MockClient:
+        def __init__(self):
+            pass
+
+        def __enter__(self) -> "MockClient":
+            return self
+
+        def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+            pass
+
+        def get(self, url: str) -> httpx.Response:
+            return mock_response
+
+    monkeypatch.setattr(httpx, "Client", MockClient)
+
+    resp = client.check_result(
+        id="xyz",
+        wait_for_completion=True,
+        download_outputs=True,
+        download_directory=str(tmp_path),
+    )
+
+    assert resp.status == "complete"
+    assert resp.downloaded_paths
+    saved_file = Path(resp.downloaded_paths[0])
+    assert saved_file.exists()
+    assert saved_file.read_bytes() == b"fake png"
+
+
+def test_check_result_error_status(mock_base_client: Mock) -> None:
+    client = ImageProjectsClient(base_client=mock_base_client)
+    mock_base_client.request.return_value = DummyResponse(status="error", error="Boom!")
+
+    resp = client.check_result(
+        id="err", wait_for_completion=True, download_outputs=False
+    )
+    assert resp.status == "error"
+    assert resp.error is not None
+    assert resp.error.message == "Boom!"
+    assert resp.downloaded_paths is None
+
+
+def test_check_result_canceled_status(mock_base_client: Mock) -> None:
+    client = ImageProjectsClient(base_client=mock_base_client)
+    mock_base_client.request.return_value = DummyResponse(status="canceled")
+
+    resp = client.check_result(
+        id="cancel", wait_for_completion=True, download_outputs=False
+    )
+    assert resp.status == "canceled"
+    assert resp.downloaded_paths is None
+
+
+def test_check_result_poll_interval_default(
+    mock_base_client: Mock, monkeypatch: Any
+) -> None:
+    client = ImageProjectsClient(base_client=mock_base_client)
+
+    # First calls return queued, then complete
+    mock_base_client.request.side_effect = [
+        DummyResponse(status="queued"),
+        DummyResponse(status="complete"),
+    ]
+
+    # Mock time.sleep to track calls
+    sleep_calls: List[float] = []
+
+    def mock_sleep(seconds: float) -> None:
+        sleep_calls.append(seconds)
+
+    monkeypatch.setattr("time.sleep", mock_sleep)
+
+    resp = client.check_result(
+        id="xyz", wait_for_completion=True, download_outputs=False
+    )
+
+    assert resp.status == "complete"
+    # Should have slept once with default interval (0.5)
+    assert len(sleep_calls) == 1
+    assert sleep_calls[0] == 0.5
+
+
+def test_check_result_poll_interval_custom(
+    mock_base_client: Mock, monkeypatch: Any
+) -> None:
+    client = ImageProjectsClient(base_client=mock_base_client)
+
+    # Set custom poll interval
+    monkeypatch.setenv("MAGIC_HOUR_POLL_INTERVAL", "1.0")
+
+    # First calls return queued, then complete
+    mock_base_client.request.side_effect = [
+        DummyResponse(status="queued"),
+        DummyResponse(status="complete"),
+    ]
+
+    # Mock time.sleep to track calls
+    sleep_calls: List[float] = []
+
+    def mock_sleep(seconds: float) -> None:
+        sleep_calls.append(seconds)
+
+    monkeypatch.setattr("time.sleep", mock_sleep)
+
+    resp = client.check_result(
+        id="xyz", wait_for_completion=True, download_outputs=False
+    )
+
+    assert resp.status == "complete"
+    # Should have slept once with custom interval (1.0)
+    assert len(sleep_calls) == 1
+    assert sleep_calls[0] == 1.0
+
+
+def test_check_result_poll_interval_multiple_polls(
+    mock_base_client: Mock, monkeypatch: Any
+) -> None:
+    client = ImageProjectsClient(base_client=mock_base_client)
+
+    # Set custom poll interval
+    monkeypatch.setenv("MAGIC_HOUR_POLL_INTERVAL", "0.1")
+
+    # Multiple calls return queued before complete
+    mock_base_client.request.side_effect = [
+        DummyResponse(status="queued"),
+        DummyResponse(status="queued"),
+        DummyResponse(status="queued"),
+        DummyResponse(status="complete"),
+    ]
+
+    # Mock time.sleep to track calls
+    sleep_calls: List[float] = []
+
+    def mock_sleep(seconds: float) -> None:
+        sleep_calls.append(seconds)
+
+    monkeypatch.setattr("time.sleep", mock_sleep)
+
+    resp = client.check_result(
+        id="xyz", wait_for_completion=True, download_outputs=False
+    )
+
+    assert resp.status == "complete"
+    # Should have slept 3 times with custom interval (0.1)
+    assert len(sleep_calls) == 3
+    assert all(sleep_time == 0.1 for sleep_time in sleep_calls)
+
+
+@pytest.mark.asyncio
+async def test_async_delete_calls_base_client(
+    mock_async_base_client: AsyncMock,
+) -> None:
+    client = AsyncImageProjectsClient(base_client=mock_async_base_client)
+    await client.delete(id="456")
+
+    mock_async_base_client.request.assert_called_once()
+    call = mock_async_base_client.request.call_args[1]
+    assert call["method"] == "DELETE"
+    assert "/v1/image-projects/456" in call["path"]
+
+
+@pytest.mark.asyncio
+async def test_async_get_calls_base_client(mock_async_base_client: AsyncMock) -> None:
+    client = AsyncImageProjectsClient(base_client=mock_async_base_client)
+    mock_async_base_client.request.return_value = DummyResponse()
+
+    resp = await client.get(id="zzz")
+
+    mock_async_base_client.request.assert_called_once()
+    assert isinstance(resp, models.V1ImageProjectsGetResponse)
+    assert resp.id == "test-id"
+
+
+@pytest.mark.asyncio
+async def test_async_check_result_no_wait_no_download(
+    mock_async_base_client: AsyncMock,
+) -> None:
+    client = AsyncImageProjectsClient(base_client=mock_async_base_client)
+    mock_async_base_client.request.return_value = DummyResponse(status="queued")
+
+    resp = await client.check_result(
+        id="xyz",
+        wait_for_completion=False,
+        download_outputs=False,
+    )
+
+    assert resp.downloaded_paths is None
+
+
+@pytest.mark.asyncio
+async def test_async_check_result_wait_until_complete(
+    mock_async_base_client: AsyncMock, monkeypatch: Any
+) -> None:
+    client = AsyncImageProjectsClient(base_client=mock_async_base_client)
+
+    # First calls return queued, then complete
+    mock_async_base_client.request.side_effect = [
+        DummyResponse(status="queued"),
+        DummyResponse(status="queued"),
+        DummyResponse(status="complete"),
+    ]
+
+    sleep_calls: List[float] = []
+
+    async def async_mock_sleep(seconds: float) -> None:
+        sleep_calls.append(seconds)
+
+    monkeypatch.setattr("asyncio.sleep", async_mock_sleep)
+
+    resp = await client.check_result(
+        id="xyz", wait_for_completion=True, download_outputs=False
+    )
+
+    assert resp.status == "complete"
+    assert resp.downloaded_paths is None
+
+
+@pytest.mark.asyncio
+async def test_async_check_result_download_outputs(
+    tmp_path: Path, mock_async_base_client: AsyncMock, monkeypatch: Any
+) -> None:
+    client = AsyncImageProjectsClient(base_client=mock_async_base_client)
+
+    file_url = "https://example.com/file.png"
+    mock_async_base_client.request.return_value = DummyResponse(
+        status="complete",
+        download_url=file_url,
+    )
+
+    # Create a mock response for httpx
+    mock_request = httpx.Request("GET", "https://example.com/file.png")
+    mock_response = httpx.Response(200, content=b"fake png", request=mock_request)
+
+    # Mock the httpx.AsyncClient class
+    class MockAsyncClient:
+        def __init__(self):
+            pass
+
+        async def __aenter__(self) -> "MockAsyncClient":
+            return self
+
+        async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+            pass
+
+        async def get(self, url: str) -> httpx.Response:
+            return mock_response
+
+    monkeypatch.setattr(httpx, "AsyncClient", MockAsyncClient)
+
+    resp = await client.check_result(
+        id="xyz",
+        wait_for_completion=True,
+        download_outputs=True,
+        download_directory=str(tmp_path),
+    )
+
+    assert resp.status == "complete"
+    assert resp.downloaded_paths
+    saved_file = Path(resp.downloaded_paths[0])
+    assert saved_file.exists()
+    assert saved_file.read_bytes() == b"fake png"
+
+
+@pytest.mark.asyncio
+async def test_async_check_result_error_status(
+    mock_async_base_client: AsyncMock,
+) -> None:
+    client = AsyncImageProjectsClient(base_client=mock_async_base_client)
+    mock_async_base_client.request.return_value = DummyResponse(
+        status="error", error="Boom!"
+    )
+
+    resp = await client.check_result(
+        id="err", wait_for_completion=True, download_outputs=False
+    )
+    assert resp.status == "error"
+    assert resp.error is not None
+    assert resp.error.message == "Boom!"
+    assert resp.downloaded_paths is None
+
+
+@pytest.mark.asyncio
+async def test_async_check_result_canceled_status(
+    mock_async_base_client: AsyncMock,
+) -> None:
+    client = AsyncImageProjectsClient(base_client=mock_async_base_client)
+    mock_async_base_client.request.return_value = DummyResponse(status="canceled")
+
+    resp = await client.check_result(
+        id="cancel", wait_for_completion=True, download_outputs=False
+    )
+    assert resp.status == "canceled"
+    assert resp.downloaded_paths is None
+
+
+@pytest.mark.asyncio
+async def test_async_check_result_poll_interval_default(
+    mock_async_base_client: AsyncMock, monkeypatch: Any
+) -> None:
+    client = AsyncImageProjectsClient(base_client=mock_async_base_client)
+
+    # First calls return queued, then complete
+    mock_async_base_client.request.side_effect = [
+        DummyResponse(status="queued"),
+        DummyResponse(status="complete"),
+    ]
+
+    # Mock time.sleep to track calls
+    sleep_calls: List[float] = []
+
+    async def async_mock_sleep(seconds: float) -> None:
+        sleep_calls.append(seconds)
+
+    monkeypatch.setattr("asyncio.sleep", async_mock_sleep)
+
+    resp = await client.check_result(
+        id="xyz", wait_for_completion=True, download_outputs=False
+    )
+
+    assert resp.status == "complete"
+    # Should have slept once with default interval (0.5)
+    assert len(sleep_calls) == 1
+    assert sleep_calls[0] == 0.5
+
+
+@pytest.mark.asyncio
+async def test_async_check_result_poll_interval_custom(
+    mock_async_base_client: AsyncMock, monkeypatch: Any
+) -> None:
+    client = AsyncImageProjectsClient(base_client=mock_async_base_client)
+
+    # Set custom poll interval
+    monkeypatch.setenv("MAGIC_HOUR_POLL_INTERVAL", "2.0")
+
+    # First calls return queued, then complete
+    mock_async_base_client.request.side_effect = [
+        DummyResponse(status="queued"),
+        DummyResponse(status="complete"),
+    ]
+
+    # Mock time.sleep to track calls
+    sleep_calls: List[float] = []
+
+    async def async_mock_sleep(seconds: float) -> None:
+        sleep_calls.append(seconds)
+
+    monkeypatch.setattr("asyncio.sleep", async_mock_sleep)
+
+    resp = await client.check_result(
+        id="xyz", wait_for_completion=True, download_outputs=False
+    )
+
+    assert resp.status == "complete"
+    # Should have slept once with custom interval (2.0)
+    assert len(sleep_calls) == 1
+    assert sleep_calls[0] == 2.0
+
+
+@pytest.mark.asyncio
+async def test_async_check_result_poll_interval_multiple_polls(
+    mock_async_base_client: AsyncMock, monkeypatch: Any
+) -> None:
+    client = AsyncImageProjectsClient(base_client=mock_async_base_client)
+
+    # Set custom poll interval
+    monkeypatch.setenv("MAGIC_HOUR_POLL_INTERVAL", "0.3")
+
+    # Multiple calls return queued before complete
+    mock_async_base_client.request.side_effect = [
+        DummyResponse(status="queued"),
+        DummyResponse(status="queued"),
+        DummyResponse(status="queued"),
+        DummyResponse(status="complete"),
+    ]
+
+    # Mock time.sleep to track calls
+    sleep_calls: List[float] = []
+
+    async def async_mock_sleep(seconds: float) -> None:
+        sleep_calls.append(seconds)
+
+    monkeypatch.setattr("asyncio.sleep", async_mock_sleep)
+
+    resp = await client.check_result(
+        id="xyz", wait_for_completion=True, download_outputs=False
+    )
+
+    assert resp.status == "complete"
+    # Should have slept 3 times with custom interval (0.3)
+    assert len(sleep_calls) == 3
+    assert all(sleep_time == 0.3 for sleep_time in sleep_calls)

magic_hour/resources/v1/image_to_video/README.md

@@ -1,3 +1,66 @@
+# v1_image_to_video
+
+## Module Functions
+
+<!-- CUSTOM DOCS START -->
+
+### Image To Video Generate Workflow <a name="generate"></a>
+
+The workflow performs the following action
+
+1. upload local assets to Magic Hour storage. So you can pass in a local path instead of having to upload files yourself
+2. trigger a generation
+3. poll for a completion status. This is configurable
+4. if success, download the output to local directory
+
+> [!TIP]
+> This is the recommended way to use the SDK unless you have specific needs where it is necessary to split up the actions.
+
+#### Parameters
+
+In Additional to the parameters listed in the `.create` section below, `.generate` introduces 3 new parameters:
+
+- `wait_for_completion` (bool, default True): Whether to wait for the project to complete.
+- `download_outputs` (bool, default True): Whether to download the generated files
+- `download_directory` (str, optional): Directory to save downloaded files (defaults to current directory)
+
+#### Synchronous Client
+
+```python
+from magic_hour import Client
+from os import getenv
+
+client = Client(token=getenv("API_TOKEN"))
+res = client.v1.image_to_video.generate(
+    assets={"image_file_path": "/path/to/1234.png"},
+    end_seconds=5.0,
+    name="Image To Video video",
+    resolution="720p",
+    wait_for_completion=True,
+    download_outputs=True,
+    download_directory="outputs"
+)
+```
+
+#### Asynchronous Client
+
+```python
+from magic_hour import AsyncClient
+from os import getenv
+
+client = AsyncClient(token=getenv("API_TOKEN"))
+res = await client.v1.image_to_video.generate(
+    assets={"image_file_path": "/path/to/1234.png"},
+    end_seconds=5.0,
+    name="Image To Video video",
+    resolution="720p",
+    wait_for_completion=True,
+    download_outputs=True,
+    download_directory="outputs"
+)
+```
+
+<!-- CUSTOM DOCS END -->
 
 ### Image-to-Video <a name="create"></a>
 
@@ -10,15 +73,19 @@ Get more information about this mode at our [product page](https://magichour.ai/
 
 #### Parameters
 
-| Parameter | Required | Description | Example |
-|-----------|:--------:|-------------|--------|
-| `assets` | ✓ | Provide the assets for image-to-video. | `{"image_file_path": "api-assets/id/1234.png"}` |
-| `end_seconds` | ✓ | The total duration of the output video in seconds. | `5.0` |
-| `height` | ✗ | `height` is deprecated and no longer influences the output video's resolution.  Output resolution is determined by the **minimum** of: - The resolution of the input video - The maximum resolution allowed by your subscription tier. See our [pricing page](https://magichour.ai/pricing) for more details.  This field is retained only for backward compatibility and will be removed in a future release. | `123` |
-| `name` | ✗ | The name of video. This value is mainly used for your own identification of the video. | `"Image To Video video"` |
-| `resolution` | ✗ | Controls the output video resolution. Defaults to `720p` if not specified.  480p and 720p are available on Creator, Pro, or Business tiers. However, 1080p require Pro or Business tier.  **Options:** - `480p` - Supports only 5 or 10 second videos. Output: 24fps. Cost: 120 credits per 5 seconds. - `720p` - Supports videos between 5-60 seconds. Output: 30fps. Cost: 300 credits per 5 seconds. - `1080p` - Supports videos between 5-60 seconds. Output: 30fps. Cost: 600 credits per 5 seconds. | `"720p"` |
-| `style` | ✗ | Attributed used to dictate the style of the output | `{"prompt": "a dog running"}` |
-| `width` | ✗ | `width` is deprecated and no longer influences the output video's resolution.  Output resolution is determined by the **minimum** of: - The resolution of the input video - The maximum resolution allowed by your subscription tier. See our [pricing page](https://magichour.ai/pricing) for more details.  This field is retained only for backward compatibility and will be removed in a future release. | `123` |
+| Parameter | Required | Deprecated | Description | Example |
+|-----------|:--------:|:----------:|-------------|--------|
+| `assets` | ✓ | ✗ | Provide the assets for image-to-video. | `{"image_file_path": "api-assets/id/1234.png"}` |
+| `└─ image_file_path` | ✓ | — | The path of the image file. This value is either - a direct URL to the video file - `file_path` field from the response of the [upload urls API](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls).  Please refer to the [Input File documentation](https://docs.magichour.ai/api-reference/files/generate-asset-upload-urls#input-file) to learn more.  | `"api-assets/id/1234.png"` |
+| `end_seconds` | ✓ | ✗ | The total duration of the output video in seconds. | `5.0` |
+| `height` | ✗ | ✓ | `height` is deprecated and no longer influences the output video's resolution.  Output resolution is determined by the **minimum** of: - The resolution of the input video - The maximum resolution allowed by your subscription tier. See our [pricing page](https://magichour.ai/pricing) for more details.  This field is retained only for backward compatibility and will be removed in a future release. | `123` |
+| `name` | ✗ | ✗ | The name of video. This value is mainly used for your own identification of the video. | `"Image To Video video"` |
+| `resolution` | ✗ | ✗ | Controls the output video resolution. Defaults to `720p` if not specified.  480p and 720p are available on Creator, Pro, or Business tiers. However, 1080p require Pro or Business tier.  **Options:** - `480p` - Supports only 5 or 10 second videos. Output: 24fps. Cost: 120 credits per 5 seconds. - `720p` - Supports videos between 5-60 seconds. Output: 30fps. Cost: 300 credits per 5 seconds. - `1080p` - Supports videos between 5-60 seconds. Output: 30fps. Cost: 600 credits per 5 seconds. | `"720p"` |
+| `style` | ✗ | ✗ | Attributed used to dictate the style of the output | `{"prompt": "a dog running"}` |
+| `└─ high_quality` | ✗ | ✓ | Deprecated: Please use `resolution` instead. For backward compatibility,  * `false` maps to 720p resolution * `true` maps to 1080p resolution  This field will be removed in a future version. Use the `resolution` field to directly specify the resolution. | `True` |
+| `└─ prompt` | ✗ | — | The prompt used for the video. | `"a dog running"` |
+| `└─ quality_mode` | ✗ | ✓ | DEPRECATED: Please use `resolution` field instead. For backward compatibility: * `quick` maps to 720p resolution * `studio` maps to 1080p resolution  This field will be removed in a future version. Use the `resolution` field to directly to specify the resolution. | `"quick"` |
+| `width` | ✗ | ✓ | `width` is deprecated and no longer influences the output video's resolution.  Output resolution is determined by the **minimum** of: - The resolution of the input video - The maximum resolution allowed by your subscription tier. See our [pricing page](https://magichour.ai/pricing) for more details.  This field is retained only for backward compatibility and will be removed in a future release. | `123` |
 
 #### Synchronous Client
 
@@ -59,3 +126,4 @@ res = await client.v1.image_to_video.create(
 
 ##### Example
 `{"credits_charged": 450, "estimated_frame_cost": 450, "id": "cuid-example"}`
+