dragoneye-python 0.3.0__tar.gz → 0.4.1__tar.gz

dragoneye_python-0.4.1/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: dragoneye-python
+Version: 0.4.1
+License-Expression: MIT
+Requires-Python: >=3.8
+Requires-Dist: requests
+Requires-Dist: pydantic>=2
+Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: backoff>=2.0.0
+Requires-Dist: aiohttp

dragoneye_python-0.4.1/dragoneye_python.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: dragoneye-python
+Version: 0.4.1
+License-Expression: MIT
+Requires-Python: >=3.8
+Requires-Dist: requests
+Requires-Dist: pydantic>=2
+Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: backoff>=2.0.0
+Requires-Dist: aiohttp

dragoneye_python-0.4.1/dragoneye_python.egg-info/requires.txt

@@ -0,0 +1,5 @@
+requests
+pydantic>=2
+typing-extensions>=4.0.0
+backoff>=2.0.0
+aiohttp

{dragoneye_python-0.3.0 → dragoneye_python-0.4.1}/pyproject.toml

@@ -1,12 +1,16 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
 [project]
 name = "dragoneye-python"
-version = "0.3.0"
+version = "0.4.1"
 requires-python = ">=3.8"
 dynamic = ["dependencies"]
-license = {text = "MIT"}
+license = "MIT"
 
 [tool.setuptools.dynamic]
 dependencies = {file = ["requirements.txt"]}
 
 [tool.setuptools.package-dir]
-dragoneye = "src/dragoneye"
+dragoneye = "src/dragoneye"

dragoneye_python-0.4.1/requirements.txt

@@ -0,0 +1,5 @@
+requests
+pydantic>=2
+typing-extensions>=4.0.0
+backoff>=2.0.0
+aiohttp

{dragoneye_python-0.3.0 → dragoneye_python-0.4.1}/src/dragoneye/classification.py

@@ -1,8 +1,10 @@
 import asyncio
+import logging
 import time
-from typing import TYPE_CHECKING, Any, Literal, overload
+from typing import TYPE_CHECKING, Any, Dict, List, Literal, Optional, Union, overload
 
 import aiohttp
+import backoff
 from aiohttp import ClientError
 from pydantic import BaseModel
 
@@ -33,7 +35,7 @@ if TYPE_CHECKING:
 
 class _PresignedPostRequest(BaseModel):
     url: str
-    fields: dict[str, Any]
+    fields: Dict[str, Any]
 
 
 class _MediaUploadUrl(BaseModel):
@@ -44,7 +46,7 @@ class _MediaUploadUrl(BaseModel):
 class _PredictionTaskBeginResponse(BaseModel):
     prediction_task_uuid: PredictionTaskUUID
     prediction_type: PredictionType
-    signed_urls: list[_MediaUploadUrl]
+    signed_urls: List[_MediaUploadUrl]
 
 
 def _is_task_successful(status: PredictionTaskState) -> bool:
@@ -68,17 +70,41 @@ class Classification:
     def __init__(self, client: "Dragoneye"):
         self._client = client
 
+        # Create a reusable backoff decorator for 429 rate limit errors
+        def _should_retry_429(exception: Exception) -> bool:
+            """Check if exception is a 429 rate limit error"""
+            return (
+                isinstance(exception, aiohttp.ClientResponseError)
+                and exception.status == 429
+            )
+
+        # Store the backoff decorator as an instance method
+        self._backoff_on_429 = backoff.on_exception(
+            wait_gen=backoff.expo,
+            exception=aiohttp.ClientResponseError,
+            max_tries=client.max_retries,
+            max_time=client.max_backoff_time,
+            on_backoff=lambda e: logging.info(
+                f"Rate limit exceeded - backing off: {e}"
+            ),
+            on_giveup=lambda e: logging.info(f"Rate limit exceeded - giving up: {e}"),
+            giveup=lambda e: not _should_retry_429(e),
+            jitter=client.backoff_jitter,
+        )
+
     async def predict_image(
         self,
         media: Image,
         model_name: str,
-        timeout_seconds: int | None = None,
+        timeout_seconds: Optional[int] = None,
+        **kwargs: Any,
     ) -> ClassificationPredictImageResponse:
         return await self._predict_unified(
             media=media,
             model_name=model_name,
             frames_per_second=None,
             timeout_seconds=timeout_seconds,
+            **kwargs,
         )
 
     async def predict_video(
@@ -86,13 +112,15 @@ class Classification:
         media: Video,
         model_name: str,
         frames_per_second: int = 1,
-        timeout_seconds: int | None = None,
+        timeout_seconds: Optional[int] = None,
+        **kwargs: Any,
     ) -> ClassificationPredictVideoResponse:
         return await self._predict_unified(
             media=media,
             model_name=model_name,
             frames_per_second=frames_per_second,
             timeout_seconds=timeout_seconds,
+            **kwargs,
         )
 
     async def status(
@@ -104,11 +132,15 @@ class Classification:
         url = f"{BASE_API_URL}/prediction-task/status?predictionTaskUuid={prediction_task_uuid}"
         headers = {"Authorization": f"Bearer {self._client.api_key}"}
 
-        async with aiohttp.ClientSession() as session:
-            async with session.get(url, headers=headers) as resp:
-                resp.raise_for_status()
-                payload = await resp.json()
+        @self._backoff_on_429
+        async def _make_request():
+            async with aiohttp.ClientSession() as session:
+                async with session.get(url, headers=headers) as resp:
+                    resp.raise_for_status()
+                    payload = await resp.json()
+            return payload
 
+        payload = await _make_request()
         return PredictionTaskStatusResponse.model_validate(payload)
 
     async def get_image_results(
@@ -148,19 +180,26 @@ class Classification:
         self,
         prediction_task_uuid: PredictionTaskUUID,
         prediction_type: PredictionType,
-    ) -> ClassificationPredictImageResponse | ClassificationPredictVideoResponse: ...
+    ) -> Union[
+        ClassificationPredictImageResponse, ClassificationPredictVideoResponse
+    ]: ...
 
     async def _get_results_unified(
         self, prediction_task_uuid: PredictionTaskUUID, prediction_type: PredictionType
-    ) -> ClassificationPredictImageResponse | ClassificationPredictVideoResponse:
+    ) -> Union[ClassificationPredictImageResponse, ClassificationPredictVideoResponse]:
         url = f"{BASE_API_URL}/prediction-task/results?predictionTaskUuid={prediction_task_uuid}"
         headers = {"Authorization": f"Bearer {self._client.api_key}"}
 
-        try:
+        @self._backoff_on_429
+        async def _make_request():
             async with aiohttp.ClientSession() as session:
                 async with session.get(url, headers=headers) as resp:
                     resp.raise_for_status()
                     payload = await resp.json()
+            return payload
+
+        try:
+            payload = await _make_request()
         except ClientError as error:
             raise PredictionTaskResultsUnavailableError(
                 f"Error getting prediction task results: {error}"
@@ -169,13 +208,12 @@ class Classification:
         # Add the prediction task uuid to the response before returning
         payload["prediction_task_uuid"] = prediction_task_uuid
 
-        match prediction_type:
-            case "image":
-                return ClassificationPredictImageResponse.model_validate(payload)
-            case "video":
-                return ClassificationPredictVideoResponse.model_validate(payload)
-            case _:  # pyright: ignore [reportUnnecessaryComparison]
-                raise ValueError(f"Unsupported prediction type: {prediction_type}")
+        if prediction_type == "image":
+            return ClassificationPredictImageResponse.model_validate(payload)
+        elif prediction_type == "video":
+            return ClassificationPredictVideoResponse.model_validate(payload)
+        else:
+            raise ValueError(f"Unsupported prediction type: {prediction_type}")
 
     ##### Internal API methods #####
     @overload
@@ -183,8 +221,9 @@ class Classification:
         self,
         media: Image,
         model_name: str,
-        frames_per_second: int | None,
-        timeout_seconds: int | None = None,
+        frames_per_second: Optional[int],
+        timeout_seconds: Optional[int] = None,
+        **kwargs: Any,
     ) -> ClassificationPredictImageResponse: ...
 
     @overload
@@ -192,20 +231,23 @@ class Classification:
         self,
         media: Video,
         model_name: str,
-        frames_per_second: int | None,
-        timeout_seconds: int | None = None,
+        frames_per_second: Optional[int],
+        timeout_seconds: Optional[int] = None,
+        **kwargs: Any,
     ) -> ClassificationPredictVideoResponse: ...
 
     async def _predict_unified(
         self,
-        media: Image | Video,
+        media: Union[Image, Video],
         model_name: str,
-        frames_per_second: int | None,
-        timeout_seconds: int | None = None,
-    ) -> ClassificationPredictImageResponse | ClassificationPredictVideoResponse:
+        frames_per_second: Optional[int],
+        timeout_seconds: Optional[int] = None,
+        **kwargs: Any,
+    ) -> Union[ClassificationPredictImageResponse, ClassificationPredictVideoResponse]:
         prediction_task_begin_response = await self._begin_prediction_task(
             mime_type=media.mime_type,
             frames_per_second=frames_per_second,
+            file_name=media.name,
         )
 
         await self._upload_media_to_prediction_task(
@@ -216,16 +258,22 @@ class Classification:
         predict_data = {
             "model_name": model_name,
             "prediction_task_uuid": prediction_task_begin_response.prediction_task_uuid,
+            **kwargs,
         }
         predict_headers = {
             "Authorization": f"Bearer {self._client.api_key}",
         }
-        try:
+
+        @self._backoff_on_429
+        async def _make_request():
             async with aiohttp.ClientSession() as session:
                 async with session.post(
                     predict_url, data=predict_data, headers=predict_headers
                 ) as resp:
                     resp.raise_for_status()
+
+        try:
+            await _make_request()
         except ClientError as error:
             raise PredictionTaskError("Error initiating prediction:", error)
 
@@ -246,7 +294,7 @@ class Classification:
         self,
         prediction_task_uuid: PredictionTaskUUID,
         polling_interval: float = 1.0,
-        timeout_seconds: int | None = None,
+        timeout_seconds: Optional[int] = None,
     ) -> PredictionTaskStatusResponse:
         start_time = time.monotonic()
         while True:
@@ -299,12 +347,16 @@ class Classification:
     async def _begin_prediction_task(
         self,
         mime_type: str,
-        frames_per_second: int | None,
+        frames_per_second: Optional[int],
+        file_name: Optional[str],
     ) -> _PredictionTaskBeginResponse:
         url = f"{BASE_API_URL}/prediction-task/begin"
 
         form_data = aiohttp.FormData()
         form_data.add_field("mimetype", mime_type)
+        if file_name is not None:
+            form_data.add_field("file_name", file_name)
+
         if frames_per_second is not None:
             form_data.add_field("frames_per_second", str(frames_per_second))
 
@@ -312,11 +364,16 @@ class Classification:
             "Authorization": f"Bearer {self._client.api_key}",
         }
 
-        try:
+        @self._backoff_on_429
+        async def _make_request():
             async with aiohttp.ClientSession() as session:
                 async with session.post(url, data=form_data, headers=headers) as resp:
                     resp.raise_for_status()
                     payload = await resp.json()
+            return payload
+
+        try:
+            payload = await _make_request()
         except ClientError as error:
             raise PredictionTaskBeginError("Error beginning prediction task:", error)
 

dragoneye_python-0.4.1/src/dragoneye/client.py

@@ -0,0 +1,29 @@
+import os
+from typing import Callable, Optional
+
+import backoff
+
+from dragoneye.classification import Classification
+
+
+class Dragoneye:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        max_retries: int = 10,
+        max_backoff_time: int = 120,
+        backoff_jitter: Callable[[float], float] = backoff.full_jitter,
+    ):
+        if api_key is None:
+            api_key = os.getenv("DRAGONEYE_API_KEY")
+
+        assert api_key is not None, (
+            "API key is required - set the DRAGONEYE_API_KEY environment variable or pass it to the [Dragoneye] constructor"
+        )
+
+        self.api_key = api_key
+        self.max_retries = max_retries
+        self.max_backoff_time = max_backoff_time
+        self.backoff_jitter = backoff_jitter
+
+        self.classification = Classification(self)

{dragoneye_python-0.3.0 → dragoneye_python-0.4.1}/src/dragoneye/models.py

@@ -1,4 +1,4 @@
-from typing import Sequence
+from typing import Dict, Sequence
 
 from pydantic import BaseModel
 
@@ -38,12 +38,11 @@ class ClassificationPredictImageResponse(BaseModel):
 
 class ClassificationVideoObjectPrediction(ClassificationObjectPrediction):
     frame_id: str
-    frame_index: int
     timestamp_microseconds: int
 
 
 class ClassificationPredictVideoResponse(BaseModel):
-    timestamp_us_to_predictions: dict[
+    timestamp_us_to_predictions: Dict[
         int, Sequence[ClassificationVideoObjectPrediction]
     ]
     frames_per_second: int

{dragoneye_python-0.3.0 → dragoneye_python-0.4.1}/src/dragoneye/types/media.py

@@ -5,7 +5,9 @@ import os
 from dataclasses import dataclass
 from io import BufferedReader, BytesIO
 from pathlib import Path
-from typing import BinaryIO, ClassVar, Self, Union
+from typing import BinaryIO, ClassVar, Optional, Tuple, Union
+
+from typing_extensions import Self
 
 
 @dataclass(frozen=True)
@@ -13,10 +15,11 @@ class Media:
     """Generic binary media + mime_type with conservative, non-destructive access."""
 
     file_or_bytes: Union[bytes, BytesIO, BinaryIO, BufferedReader]
+    name: Optional[str]
     mime_type: str
 
     # Subclasses set this to enforce a family of mimetypes, e.g. ("image/",)
-    ACCEPT_PREFIXES: ClassVar[tuple[str, ...]] = ()
+    ACCEPT_PREFIXES: ClassVar[Tuple[str, ...]] = ()
 
     def __post_init__(self) -> None:
         # Enforce subtype-specific mimetype families when specified.
@@ -31,23 +34,41 @@ class Media:
     # ---------- Convenience constructors ----------
 
     @classmethod
-    def from_bytes(cls, data: bytes, mime_type: str) -> Self:
-        return cls(file_or_bytes=data, mime_type=mime_type)
+    def from_bytes(
+        cls, data: bytes, mime_type: str, name: Optional[str] = None
+    ) -> Self:
+        """
+        Create a Media (or subclass) from raw bytes.
+
+        - `data`: Raw bytes of the media content.
+        - `mime_type`: The MIME type of the media (e.g., 'image/jpeg').
+        - `name`: Optional non-unique descriptive identifier provided by the user
+          for identifying or tracking responses to inputs.
+        """
+        return cls(file_or_bytes=data, mime_type=mime_type, name=name)
 
     @classmethod
-    def from_stream(cls, stream: BinaryIO, *, mime_type: str) -> Self:
+    def from_stream(
+        cls, stream: BinaryIO, *, mime_type: str, name: Optional[str] = None
+    ) -> Self:
         """
         Accepts any readable binary stream (e.g., open('file', 'rb')).
         Keeps the stream as-is; reading is deferred to bytes_io().
+
+        - `stream`: A readable binary stream.
+        - `mime_type`: The MIME type of the media (e.g., 'image/jpeg').
+        - `name`: Optional non-unique descriptive identifier provided by the user
+          for identifying or tracking responses to inputs.
         """
-        return cls(file_or_bytes=stream, mime_type=mime_type)
+        return cls(file_or_bytes=stream, mime_type=mime_type, name=name)
 
     @classmethod
     def from_path(
         cls,
         path: Union[str, os.PathLike[str]],
         *,
-        mime_type: str | None = None,
+        mime_type: Optional[str] = None,
+        name: Optional[str] = None,
         guess_from_extension: bool = True,
         read_into_memory: bool = False,
     ) -> Self:
@@ -57,6 +78,9 @@ class Media:
         - `path`: Path to the file on disk.
         - `mime_type`: Explicit mime type. If omitted and `guess_from_extension=True`,
            we'll try to guess from the file extension.
+        - `name`: Optional non-unique descriptive identifier provided by the user
+          for identifying or tracking responses to inputs. If not provided, will
+          default to the filename from the path.
         - `read_into_memory=True`: load file bytes into memory (closes file immediately).
           Otherwise, keep an open file stream.
         """
@@ -72,12 +96,15 @@ class Media:
                 f"mime_type is required for {path} (no extension-based guess available)."
             )
 
+        # Use provided name or extract from path
+        media_name = name if name is not None else path.name
+
         if read_into_memory:
             data = path.read_bytes()
-            return cls(file_or_bytes=data, mime_type=mt)
+            return cls(file_or_bytes=data, mime_type=mt, name=media_name)
         else:
             f = path.open("rb")
-            return cls(file_or_bytes=f, mime_type=mt)
+            return cls(file_or_bytes=f, mime_type=mt, name=media_name)
 
     # ---------- Utilities ----------
 
@@ -118,7 +145,7 @@ class Media:
             "Invalid media source: expected bytes, BytesIO, or a readable binary stream."
         )
 
-    def size_bytes(self) -> int | None:
+    def size_bytes(self) -> Optional[int]:
         """
         Best-effort size inference without consuming the stream.
         Returns None if size can't be determined cheaply.
@@ -152,20 +179,20 @@ class Media:
 class Image(Media):
     """Media restricted to image/* mimetypes."""
 
-    ACCEPT_PREFIXES: ClassVar[tuple[str, ...]] = ("image/",)
+    ACCEPT_PREFIXES: ClassVar[Tuple[str, ...]] = ("image/",)
 
 
 @dataclass(frozen=True)
 class Video(Media):
     """Media restricted to video/* mimetypes."""
 
-    ACCEPT_PREFIXES: ClassVar[tuple[str, ...]] = ("video/",)
+    ACCEPT_PREFIXES: ClassVar[Tuple[str, ...]] = ("video/",)
 
 
 # ---------- Helpers ----------
 
 
-def _tell_safe(stream: BinaryIO) -> int | None:
+def _tell_safe(stream: BinaryIO) -> Optional[int]:
     try:
         if hasattr(stream, "tell"):
             return stream.tell()
@@ -174,7 +201,7 @@ def _tell_safe(stream: BinaryIO) -> int | None:
     return None
 
 
-def _seek_safe(stream: BinaryIO, pos: int | None) -> None:
+def _seek_safe(stream: BinaryIO, pos: Optional[int]) -> None:
     if pos is None:
         return
     try:

dragoneye_python-0.3.0/PKG-INFO

@@ -1,7 +0,0 @@
-Metadata-Version: 2.4
-Name: dragoneye-python
-Version: 0.3.0
-License: MIT
-Requires-Python: >=3.8
-Requires-Dist: requests
-Requires-Dist: pydantic>=2

dragoneye_python-0.3.0/dragoneye_python.egg-info/PKG-INFO

@@ -1,7 +0,0 @@
-Metadata-Version: 2.4
-Name: dragoneye-python
-Version: 0.3.0
-License: MIT
-Requires-Python: >=3.8
-Requires-Dist: requests
-Requires-Dist: pydantic>=2

dragoneye_python-0.3.0/dragoneye_python.egg-info/requires.txt

@@ -1,2 +0,0 @@
-requests
-pydantic>=2

dragoneye_python-0.3.0/requirements.txt

@@ -1,2 +0,0 @@
-requests
-pydantic>=2

dragoneye_python-0.3.0/src/dragoneye/client.py

@@ -1,18 +0,0 @@
-import os
-from typing import Optional
-
-from dragoneye.classification import Classification
-
-
-class Dragoneye:
-    def __init__(self, api_key: Optional[str] = None):
-        if api_key is None:
-            api_key = os.getenv("DRAGONEYE_API_KEY")
-
-        assert (
-            api_key is not None
-        ), "API key is required - set the DRAGONEYE_API_KEY environment variable or pass it to the [Dragoneye] constructor"
-
-        self.api_key = api_key
-
-        self.classification = Classification(self)