chunkr-ai 0.1.0a3__tar.gz → 0.1.0a4__tar.gz

{chunkr_ai-0.1.0a3 → chunkr_ai-0.1.0a4}/.gitignore

@@ -13,3 +13,5 @@ dist
 .envrc
 codegen.log
 Brewfile.lock.json
+
+.lh

chunkr_ai-0.1.0a4/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0-alpha.4"
+}

{chunkr_ai-0.1.0a3 → chunkr_ai-0.1.0a4}/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.0-alpha.4 (2025-08-09)
+
+Full Changelog: [v0.1.0-alpha.3...v0.1.0-alpha.4](https://github.com/lumina-ai-inc/chunkr-python/compare/v0.1.0-alpha.3...v0.1.0-alpha.4)
+
+### Features
+
+* **api:** added poll() and apoll() methods to Task ([#16](https://github.com/lumina-ai-inc/chunkr-python/issues/16)) ([da329dd](https://github.com/lumina-ai-inc/chunkr-python/commit/da329dda8ac0818e2b770e156b6b69456a5cfc72))
+* **api:** manual updates ([a704c5d](https://github.com/lumina-ai-inc/chunkr-python/commit/a704c5deed4c91af239afb58fce99091f8784210))
+
 ## 0.1.0-alpha.3 (2025-08-09)
 
 Full Changelog: [v0.1.0-alpha.2...v0.1.0-alpha.3](https://github.com/lumina-ai-inc/chunkr-python/compare/v0.1.0-alpha.2...v0.1.0-alpha.3)

{chunkr_ai-0.1.0a3 → chunkr_ai-0.1.0a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: chunkr-ai
-Version: 0.1.0a3
+Version: 0.1.0a4
 Summary: The official Python library for the chunkr API
 Project-URL: Homepage, https://github.com/lumina-ai-inc/chunkr-python
 Project-URL: Repository, https://github.com/lumina-ai-inc/chunkr-python

{chunkr_ai-0.1.0a3 → chunkr_ai-0.1.0a4}/api.md

@@ -25,7 +25,7 @@ Methods:
 Types:
 
 ```python
-from chunkr_ai.types import Delete, File, FilesPageResponse, FileURL
+from chunkr_ai.types import Delete, File, FilesListResponse, FileURL
 ```
 
 Methods:

{chunkr_ai-0.1.0a3 → chunkr_ai-0.1.0a4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "chunkr-ai"
-version = "0.1.0-alpha.3"
+version = "0.1.0-alpha.4"
 description = "The official Python library for the chunkr API"
 dynamic = ["readme"]
 license = "Apache-2.0"

{chunkr_ai-0.1.0a3 → chunkr_ai-0.1.0a4}/src/chunkr_ai/__init__.py

@@ -72,6 +72,9 @@ __all__ = [
 ]
 
 if not _t.TYPE_CHECKING:
+    # Load custom helpers that monkey-patch generated types.
+    # This keeps custom code separate from generated files, per Stainless guidance.
+    from .lib import tasks_poll as _tasks_poll  # noqa: F401
     from ._utils._resources_proxy import resources as resources
 
 _setup_logging()

{chunkr_ai-0.1.0a3 → chunkr_ai-0.1.0a4}/src/chunkr_ai/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "chunkr_ai"
-__version__ = "0.1.0-alpha.3"  # x-release-please-version
+__version__ = "0.1.0-alpha.4"  # x-release-please-version

chunkr_ai-0.1.0a4/src/chunkr_ai/lib/tasks_poll.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+"""
+Custom helpers for task polling.
+
+This module adds `Task.poll()` and `Task.apoll()` methods at runtime to the
+generated `Task` model, without modifying generated code directly.
+
+Usage:
+    task = client.tasks.get(task_id)
+    task = task.poll(client)  # blocks until terminal state
+
+    # async
+    task = await async_client.tasks.get(task_id)
+    task = await task.apoll(async_client)
+"""
+
+import time
+import asyncio
+from typing import Protocol, cast
+
+from .._types import NOT_GIVEN, NotGiven
+from .._client import Chunkr, AsyncChunkr
+from ..types.task import Task as _Task
+from .._exceptions import ChunkrError
+
+TERMINAL_STATUSES = {"Succeeded", "Failed", "Cancelled"}
+
+
+def _task_poll(
+    self: _Task,
+    client: Chunkr,
+    *,
+    interval: float = 0.5,
+    timeout: float = 600.0,
+    include_chunks: bool | NotGiven = NOT_GIVEN,
+    base64_urls: bool | NotGiven = NOT_GIVEN,
+) -> _Task:
+    """Poll the task until it reaches a terminal status.
+
+    Args:
+        client: Synchronous Chunkr client instance.
+        interval: Seconds to sleep between polls.
+        timeout: Maximum total seconds to wait before raising an error.
+        include_chunks: Whether to include chunks in the output response for each poll.
+        base64_urls: Whether to return base64 encoded URLs.
+    """
+    start_time = time.monotonic()
+    current: _Task = self
+
+    class _TasksGetProtocol(Protocol):
+        def get(
+            self,
+            task_id: str,
+            *,
+            base64_urls: bool | NotGiven = NOT_GIVEN,
+            include_chunks: bool | NotGiven = NOT_GIVEN,
+        ) -> _Task: ...
+
+    resource = cast(_TasksGetProtocol, client.tasks)
+
+    while current.status not in TERMINAL_STATUSES:
+        if time.monotonic() - start_time > timeout:
+            raise ChunkrError("Task polling timed out.")
+
+        if interval > 0:
+            time.sleep(interval)
+
+        current = resource.get(
+            current.task_id,
+            include_chunks=include_chunks,
+            base64_urls=base64_urls,
+        )
+
+    return current
+
+
+async def _task_apoll(
+    self: _Task,
+    client: AsyncChunkr,
+    *,
+    interval: float = 0.5,
+    timeout: float = 600.0,
+    include_chunks: bool | NotGiven = NOT_GIVEN,
+    base64_urls: bool | NotGiven = NOT_GIVEN,
+) -> _Task:
+    """Async poll the task until it reaches a terminal status."""
+    start_time = time.monotonic()
+    current: _Task = self
+
+    class _AsyncTasksGetProtocol(Protocol):
+        async def get(
+            self,
+            task_id: str,
+            *,
+            base64_urls: bool | NotGiven = NOT_GIVEN,
+            include_chunks: bool | NotGiven = NOT_GIVEN,
+        ) -> _Task: ...
+
+    aresource = cast(_AsyncTasksGetProtocol, client.tasks)
+
+    while current.status not in TERMINAL_STATUSES:
+        if time.monotonic() - start_time > timeout:
+            raise ChunkrError("Task polling timed out.")
+
+        if interval > 0:
+            await asyncio.sleep(interval)
+
+        current = await aresource.get(
+            current.task_id,
+            include_chunks=include_chunks,
+            base64_urls=base64_urls,
+        )
+
+    return current
+
+
+# Attach methods to the generated Task model
+_Task.poll = _task_poll  # type: ignore[attr-defined]
+_Task.apoll = _task_apoll  # type: ignore[attr-defined]
+
+

{chunkr_ai-0.1.0a3 → chunkr_ai-0.1.0a4}/src/chunkr_ai/types/__init__.py

@@ -11,5 +11,5 @@ from .task_get_params import TaskGetParams as TaskGetParams
 from .file_list_params import FileListParams as FileListParams
 from .task_list_params import TaskListParams as TaskListParams
 from .file_create_params import FileCreateParams as FileCreateParams
-from .files_page_response import FilesPageResponse as FilesPageResponse
+from .files_list_response import FilesListResponse as FilesListResponse
 from .health_check_response import HealthCheckResponse as HealthCheckResponse

chunkr_ai-0.1.0a3/src/chunkr_ai/types/files_page_response.py → chunkr_ai-0.1.0a4/src/chunkr_ai/types/files_list_response.py

@@ -6,10 +6,10 @@ from datetime import datetime
 from .file import File
 from .._models import BaseModel
 
-__all__ = ["FilesPageResponse"]
+__all__ = ["FilesListResponse"]
 
 
-class FilesPageResponse(BaseModel):
+class FilesListResponse(BaseModel):
     files: List[File]
     """List of files"""
 

chunkr_ai-0.1.0a4/tests/test_tasks_poll.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from typing import Any, List, cast
+from datetime import datetime, timezone
+
+from chunkr_ai import Chunkr, AsyncChunkr
+from chunkr_ai.types.task import Task
+
+
+def _mk_task(status: str) -> Task:
+    return Task.construct(
+        configuration={
+            "chunk_processing": {},
+            "error_handling": "Fail",
+            "llm_processing": {},
+            "ocr_strategy": "All",
+            "segment_processing": {},
+            "segmentation_strategy": "Page",
+        },
+        created_at=datetime.now(timezone.utc),
+        message="",
+        status=status,
+        task_id="task_123",
+    )
+
+
+class _TasksStub:
+    def __init__(self, responses: List[Task]) -> None:
+        self._responses = responses
+
+    def get(self, task_id: str, *, base64_urls: Any = None, include_chunks: Any = None) -> Task:  # noqa: ARG002
+        return self._responses.pop(0)
+
+
+class _AsyncTasksStub:
+    def __init__(self, responses: List[Task]) -> None:
+        self._responses = responses
+
+    async def get(self, task_id: str, *, base64_urls: Any = None, include_chunks: Any = None) -> Task:  # noqa: ARG002
+        return self._responses.pop(0)
+
+
+def test_poll_reaches_terminal_state() -> None:
+    client = Chunkr(base_url="http://127.0.0.1:4010", api_key="key", _strict_response_validation=True)
+
+    initial = _mk_task("Starting")
+    client.tasks = _TasksStub([_mk_task("Processing"), _mk_task("Succeeded")])  # type: ignore[assignment]
+
+    # avoid static type errors for monkey-patched method
+    final = cast(Any, initial).poll(client, interval=0.0, timeout=2.0)
+    assert final.status == "Succeeded"
+
+async def test_apoll_reaches_terminal_state() -> None:
+    client = AsyncChunkr(base_url="http://127.0.0.1:4010", api_key="key", _strict_response_validation=True)
+
+    initial = _mk_task("Starting")
+    client.tasks = _AsyncTasksStub([_mk_task("Processing"), _mk_task("Succeeded")])  # type: ignore[assignment]
+
+    final = await cast(Any, initial).apoll(client, interval=0.0, timeout=2.0)
+    assert final.status == "Succeeded"
+
+

chunkr_ai-0.1.0a3/.release-please-manifest.json

@@ -1,3 +0,0 @@
-{
-  ".": "0.1.0-alpha.3"
-}