Document bytes stream timeout

Author: kylebarron

docs/api/get.md

@@ -8,6 +8,7 @@
 ::: obstore.get_ranges_async
 ::: obstore.GetOptions
 ::: obstore.GetResult
-::: obstore.Buffer
+::: obstore.BytesStream
+::: obstore.Bytes
 ::: obstore.OffsetRange
 ::: obstore.SuffixRange

obstore/python/obstore/_buffer.pyi

@@ -5,7 +5,7 @@ if sys.version_info >= (3, 12):
 else:
     from typing_extensions import Buffer as _Buffer
 
-class Buffer(_Buffer):
+class Bytes(_Buffer):
     """
     A buffer implementing the Python buffer protocol, allowing zero-copy access to the
     underlying memory provided by Rust.
@@ -15,4 +15,5 @@ class Buffer(_Buffer):
 
     def to_bytes(self) -> bytes:
         """Copy this buffer into a Python `bytes` object."""
+    def __repr__(self) -> str: ...
     def __len__(self) -> int: ...

obstore/python/obstore/_get.pyi

@@ -2,7 +2,7 @@ from datetime import datetime
 from typing import List, Sequence, Tuple, TypedDict
 
 from ._attributes import Attributes
-from ._buffer import Buffer
+from ._buffer import Bytes
 from ._list import ObjectMeta
 from .store import ObjectStore
 
@@ -199,7 +199,30 @@ class GetResult:
         """
 
 class BytesStream:
-    """An async stream of bytes."""
+    """An async stream of bytes.
+
+    !!! note "Request timeouts"
+        The underlying stream needs to stay alive until the last chunk is polled. If the
+        file is large, it may exceed the default timeout of 30 seconds. In this case,
+        you may see an error like:
+
+        ```
+        GenericError: Generic {
+            store: "HTTP",
+            source: reqwest::Error {
+                kind: Decode,
+                source: reqwest::Error {
+                    kind: Body,
+                    source: TimedOut,
+                },
+            },
+        }
+        ```
+
+        To fix this, set the `timeout` parameter in the `client_options` passed to the
+        initial `get` or `get_async` call. See
+        [ClientConfigKey][obstore.store.ClientConfigKey].
+    """
 
     def __aiter__(self) -> BytesStream:
         """Return `Self` as an async iterator."""
@@ -235,7 +258,7 @@ async def get_async(
     Refer to the documentation for [get][obstore.get].
     """
 
-def get_range(store: ObjectStore, path: str, start: int, end: int) -> Buffer:
+def get_range(store: ObjectStore, path: str, start: int, end: int) -> Bytes:
     """
     Return the bytes that are stored at the specified location in the given byte range.
 
@@ -251,21 +274,19 @@ def get_range(store: ObjectStore, path: str, start: int, end: int) -> Buffer:
         end: The end of the byte range (exclusive).
 
     Returns:
-        A `Buffer` object implementing the Python buffer protocol, allowing
+        A `Bytes` object implementing the Python buffer protocol, allowing
             zero-copy access to the underlying memory provided by Rust.
     """
 
-async def get_range_async(
-    store: ObjectStore, path: str, start: int, end: int
-) -> Buffer:
+async def get_range_async(store: ObjectStore, path: str, start: int, end: int) -> Bytes:
     """Call `get_range` asynchronously.
 
     Refer to the documentation for [get_range][obstore.get_range].
     """
 
 def get_ranges(
     store: ObjectStore, path: str, starts: Sequence[int], ends: Sequence[int]
-) -> List[Buffer]:
+) -> List[Bytes]:
     """
     Return the bytes that are stored at the specified location in the given byte ranges
 
@@ -281,14 +302,14 @@ def get_ranges(
         ends: A sequence of `int` where each offset ends (exclusive).
 
     Returns:
-        A sequence of `Buffer`, one for each range. This `Buffer` object implements the
+        A sequence of `Bytes`, one for each range. This `Bytes` object implements the
             Python buffer protocol, allowing zero-copy access to the underlying memory
             provided by Rust.
     """
 
 async def get_ranges_async(
     store: ObjectStore, path: str, starts: Sequence[int], ends: Sequence[int]
-) -> List[Buffer]:
+) -> List[Bytes]:
     """Call `get_ranges` asynchronously.
 
     Refer to the documentation for [get_ranges][obstore.get_ranges].

obstore/python/obstore/_obstore.pyi

@@ -8,7 +8,8 @@ from ._copy import copy as copy
 from ._copy import copy_async as copy_async
 from ._delete import delete as delete
 from ._delete import delete_async as delete_async
-from ._get import Buffer as Buffer
+from ._get import Bytes as Bytes
+from ._get import BytesStream as BytesStream
 from ._get import GetOptions as GetOptions
 from ._get import GetResult as GetResult
 from ._get import OffsetRange as OffsetRange