Updated put docs

Author: kylebarron

README.md

@@ -12,14 +12,15 @@ Simple, fast integration with object storage services like Amazon S3, Google Clo
 
 - Sync and async API.
 - Streaming downloads with configurable chunking.
+- Streaming uploads from async or sync iterators.
 - Streaming `list`, with no need to paginate.
 - File-like object API and [fsspec](https://github.com/fsspec/filesystem_spec) integration.
 - Support for conditional put ("put if not exists"), as well as custom tags and attributes.
 - Automatically uses [multipart uploads](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html) under the hood for large file objects.
 - Optionally return list results as [Arrow](https://arrow.apache.org/), which is faster than materializing Python `dict`/`list` objects.
 - Easy to install with no required Python dependencies.
 - The [underlying Rust library](https://docs.rs/object_store) is production quality and used in large scale production systems, such as the Rust package registry [crates.io](https://crates.io/).
-- Support for zero-copy data exchange from Rust into Python in `get_range` and `get_ranges`.
+- Zero-copy data exchange between Rust and Python in `get_range`, `get_ranges`, and `put` via the Python buffer protocol.
 - Simple API with static type checking.
 - Helpers for constructing from environment variables and `boto3.Session` objects
 
@@ -56,6 +57,10 @@ Classes to construct a store are exported from the `obstore.store` submodule:
 - [`LocalStore`](https://developmentseed.org/obstore/latest/api/store/local/): Local filesystem storage providing the same object store interface.
 - [`MemoryStore`](https://developmentseed.org/obstore/latest/api/store/memory/): A fully in-memory implementation of ObjectStore.
 
+Additionally, some middlewares exist:
+
+- [`PrefixStore`](https://developmentseed.org/obstore/latest/api/store/middleware/#obstore.store.PrefixStore): Store wrapper that applies a constant prefix to all paths handled by the store.
+
 #### Example
 
 ```py
@@ -81,7 +86,7 @@ All methods for interacting with a store are exported as **top-level functions**
 - [`get`](https://developmentseed.org/obstore/latest/api/get/): Return the bytes that are stored at the specified location.
 - [`head`](https://developmentseed.org/obstore/latest/api/head/): Return the metadata for the specified location
 - [`list`](https://developmentseed.org/obstore/latest/api/list/): List all the objects with the given prefix.
-- [`put`](https://developmentseed.org/obstore/latest/api/put/): Save the provided bytes to the specified location
+- [`put`](https://developmentseed.org/obstore/latest/api/put/): Save the provided buffer to the specified location.
 - [`rename`](https://developmentseed.org/obstore/latest/api/rename/): Move an object from one path to another in the same object store.
 
 There are a few additional APIs useful for specific use cases:

obstore/python/obstore/_put.pyi

@@ -1,3 +1,4 @@
+import sys
 from pathlib import Path
 from typing import (
     IO,
@@ -13,6 +14,11 @@ from typing import (
 from ._attributes import Attributes
 from .store import ObjectStore
 
+if sys.version_info >= (3, 12):
+    from collections.abc import Buffer
+else:
+    from typing_extensions import Buffer
+
 class UpdateVersion(TypedDict, total=False):
     """
     Uniquely identifies a version of an object to update
@@ -62,7 +68,7 @@ class PutResult(TypedDict):
 def put(
     store: ObjectStore,
     path: str,
-    file: IO[bytes] | Path | bytes | Iterator[bytes] | Iterable[bytes],
+    file: IO[bytes] | Path | bytes | Buffer | Iterator[Buffer] | Iterable[Buffer],
     *,
     attributes: Attributes | None = None,
     tags: Dict[str, str] | None = None,
@@ -80,8 +86,16 @@ def put(
     Args:
         store: The ObjectStore instance to use.
         path: The path within ObjectStore for where to save the file.
-        file: The object to upload. Can either be file-like, a `Path` to a local file,
-            or a `bytes` object.
+        file: The object to upload. Supports various input:
+
+            - A file-like object opened in binary read mode
+            - A [`Path`][pathlib.Path] to a local file
+            - A [`bytes`][] object.
+            - Any object implementing the Python [buffer
+              protocol](https://docs.python.org/3/c-api/buffer.html) (includes `bytes`
+              but also `memoryview`, numpy arrays, and more).
+            - An iterator or iterable of objects implementing the Python buffer
+              protocol.
 
     Keyword args:
         mode: Configure the `PutMode` for this operation. If this provided and is not `"overwrite"`, a non-multipart upload will be performed. Defaults to `"overwrite"`.
@@ -98,10 +112,11 @@ async def put_async(
     file: IO[bytes]
     | Path
     | bytes
-    | AsyncIterator[bytes]
-    | AsyncIterable[bytes]
-    | Iterator[bytes]
-    | Iterable[bytes],
+    | Buffer
+    | AsyncIterator[Buffer]
+    | AsyncIterable[Buffer]
+    | Iterator[Buffer]
+    | Iterable[Buffer],
     *,
     attributes: Attributes | None = None,
     tags: Dict[str, str] | None = None,
@@ -112,5 +127,19 @@ async def put_async(
 ) -> PutResult:
     """Call `put` asynchronously.
 
-    Refer to the documentation for [put][obstore.put].
+    Refer to the documentation for [`put`][obstore.put]. In addition to what the
+    synchronous `put` allows for the `file` parameter, this **also supports an async
+    iterator or iterable** of objects implementing the Python buffer protocol.
+
+    This means, for example, you can pass the result of `get_async` directly to
+    `put_async`, and the request will be streamed through Python during the put
+    operation:
+
+    ```py
+    import obstore as obs
+
+    # This only constructs the stream, it doesn't materialize the data in memory
+    resp = await obs.get_async(store1, path1)
+    await obs.put_async(store2, path2)
+    ```
     """