matelab-python-sdk 0.1.0a1__py3-none-any.whl

matelab/streaming.py

@@ -0,0 +1,82 @@
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Self
+
+import httpx
+
+from matelab.errors import MatelabUsageError
+
+
+@dataclass(frozen=True, slots=True)
+class ByteRange:
+    """One HTTP byte range from the stable subset supported by Matelab."""
+
+    start: int | None = None
+    end: int | None = None
+    suffix_length: int | None = None
+
+    def __post_init__(self) -> None:
+        if any(type(value) is not int for value in (self.start, self.end, self.suffix_length) if value is not None):
+            raise MatelabUsageError("Byte-range values must be integers.")
+        if self.suffix_length is not None:
+            if self.start is not None or self.end is not None or self.suffix_length < 1:
+                raise MatelabUsageError("A suffix byte range needs a positive length and no start or end.")
+            return
+        if self.start is None or self.start < 0:
+            raise MatelabUsageError("A byte range needs a non-negative start or a positive suffix length.")
+        if self.end is not None and (self.end < 1 or self.end < self.start):
+            raise MatelabUsageError(
+                "An explicit byte-range end must be positive and greater than or equal to the start."
+            )
+
+    @classmethod
+    def from_start(cls, start: int) -> Self:
+        return cls(start=start)
+
+    @classmethod
+    def between(cls, start: int, end: int) -> Self:
+        return cls(start=start, end=end)
+
+    @classmethod
+    def last(cls, length: int) -> Self:
+        return cls(suffix_length=length)
+
+    def to_header(self) -> str:
+        if self.suffix_length is not None:
+            return f"bytes=-{self.suffix_length}"
+        return f"bytes={self.start}-{self.end if self.end is not None else ''}"
+
+
+class DownloadStream:
+    """A Provider response whose bytes remain open until consumed or closed."""
+
+    def __init__(self, response: httpx.Response, *, content_length: int | None) -> None:
+        self._response: httpx.Response = response
+        self.status_code: int = response.status_code
+        self.content_type: str | None = response.headers.get("Content-Type")
+        self.content_length: int | None = content_length
+        self.content_range: str | None = response.headers.get("Content-Range")
+        self.accept_ranges: str | None = response.headers.get("Accept-Ranges")
+        self.content_disposition: str | None = response.headers.get("Content-Disposition")
+
+    @property
+    def is_closed(self) -> bool:
+        return self._response.is_closed
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    def __aiter__(self) -> AsyncIterator[bytes]:
+        return self.aiter_bytes()
+
+    def aiter_bytes(self, chunk_size: int | None = None) -> AsyncIterator[bytes]:
+        return self._response.aiter_bytes(chunk_size)
+
+    async def read(self) -> bytes:
+        return await self._response.aread()
+
+    async def aclose(self) -> None:
+        await self._response.aclose()