feat: Make ObjectStoreMethods public, update docs (#701)

kylebarron · web-flow · commit c1f5b763a238 · 2026-06-01T15:54:04.000-04:00
* feat: Make ObjectStoreMixin public, update docs

* remove duplicate base doc page

* rename ObjectStoreMixin to ObjectStoreMethods

* docstring

* docstring

* add ObjectStoreMethods to index

* fix docs links

* update docs

* docs
diff --git a/docs/api/copy.md b/docs/api/copy.md
@@ -1,4 +1,15 @@
 # Copy
 
+Copy operations.
+
+Obstore provides [two API designs](../method-vs-functional-api.md) for your convenience.
+
+## Method API
+
+::: obstore.store.ObjectStoreMethods.copy
+::: obstore.store.ObjectStoreMethods.copy_async
+
+## Functional API
+
 ::: obstore.copy
 ::: obstore.copy_async
diff --git a/docs/api/delete.md b/docs/api/delete.md
@@ -1,4 +1,15 @@
 # Delete
 
+Delete operations.
+
+Obstore provides [two API designs](../method-vs-functional-api.md) for your convenience.
+
+## Method API
+
+::: obstore.store.ObjectStoreMethods.delete
+::: obstore.store.ObjectStoreMethods.delete_async
+
+## Functional API
+
 ::: obstore.delete
 ::: obstore.delete_async
diff --git a/docs/api/file.md b/docs/api/file.md
@@ -4,6 +4,8 @@ Native support for reading from object stores as a file-like object.
 
 Use `obstore.open_reader` or `obstore.open_reader_async` to open readable files. Use `obstore.open_writer` or `obstore.open_writer_async` to open writable files.
 
+See [ReadableFile][obstore.ReadableFile] and [AsyncReadableFile][obstore.AsyncReadableFile] for more information on caching behavior.
+
 ::: obstore.open_reader
 ::: obstore.open_reader_async
 ::: obstore.open_writer
diff --git a/docs/api/get.md b/docs/api/get.md
@@ -1,11 +1,29 @@
 # Get
 
+Get operations.
+
+Obstore provides [two API designs](../method-vs-functional-api.md) for your convenience.
+
+## Method API
+
+::: obstore.store.ObjectStoreMethods.get
+::: obstore.store.ObjectStoreMethods.get_async
+::: obstore.store.ObjectStoreMethods.get_range
+::: obstore.store.ObjectStoreMethods.get_range_async
+::: obstore.store.ObjectStoreMethods.get_ranges
+::: obstore.store.ObjectStoreMethods.get_ranges_async
+
+## Functional API
+
 ::: obstore.get
 ::: obstore.get_async
 ::: obstore.get_range
 ::: obstore.get_range_async
 ::: obstore.get_ranges
 ::: obstore.get_ranges_async
+
+## Types
+
 ::: obstore.GetOptions
 ::: obstore.GetResult
 ::: obstore.BytesStream
diff --git a/docs/api/head.md b/docs/api/head.md
@@ -1,4 +1,15 @@
 # Head
 
+Head operations.
+
+Obstore provides [two API designs](../method-vs-functional-api.md) for your convenience.
+
+## Method API
+
+::: obstore.store.ObjectStoreMethods.head
+::: obstore.store.ObjectStoreMethods.head_async
+
+## Functional API
+
 ::: obstore.head
 ::: obstore.head_async
diff --git a/docs/api/list.md b/docs/api/list.md
@@ -1,8 +1,23 @@
 # List
 
+List operations.
+
+Obstore provides [two API designs](../method-vs-functional-api.md) for your convenience.
+
+## Method API
+
+::: obstore.store.ObjectStoreMethods.list
+::: obstore.store.ObjectStoreMethods.list_with_delimiter
+::: obstore.store.ObjectStoreMethods.list_with_delimiter_async
+
+## Functional API
+
 ::: obstore.list
 ::: obstore.list_with_delimiter
 ::: obstore.list_with_delimiter_async
+
+## Types
+
 ::: obstore.ObjectMeta
 ::: obstore.ListResult
 ::: obstore.ListStream
diff --git a/docs/api/put.md b/docs/api/put.md
@@ -1,7 +1,21 @@
 # Put
 
+Put operations.
+
+Obstore provides [two API designs](../method-vs-functional-api.md) for your convenience.
+
+## Method API
+
+::: obstore.store.ObjectStoreMethods.put
+::: obstore.store.ObjectStoreMethods.put_async
+
+## Functional API
+
 ::: obstore.put
 ::: obstore.put_async
+
+## Types
+
 ::: obstore.PutResult
 ::: obstore.UpdateVersion
 ::: obstore.PutMode
diff --git a/docs/api/rename.md b/docs/api/rename.md
@@ -1,4 +1,15 @@
 # Rename
 
+Rename operations.
+
+Obstore provides [two API designs](../method-vs-functional-api.md) for your convenience.
+
+## Method API
+
+::: obstore.store.ObjectStoreMethods.rename
+::: obstore.store.ObjectStoreMethods.rename_async
+
+## Functional API
+
 ::: obstore.rename
 ::: obstore.rename_async
diff --git a/docs/api/store/aws.md b/docs/api/store/aws.md
@@ -3,7 +3,6 @@
 ::: obstore.store.S3Store
     options:
         inherited_members: true
-        show_bases: false
 ::: obstore.store.S3Config
     options:
         show_if_no_docstring: true
diff --git a/docs/api/store/azure.md b/docs/api/store/azure.md
@@ -3,7 +3,6 @@
 ::: obstore.store.AzureStore
     options:
         inherited_members: true
-        show_bases: false
 ::: obstore.store.AzureConfig
     options:
         show_if_no_docstring: true
diff --git a/docs/api/store/gcs.md b/docs/api/store/gcs.md
@@ -3,7 +3,6 @@
 ::: obstore.store.GCSStore
     options:
         inherited_members: true
-        show_bases: false
 ::: obstore.store.GCSConfig
     options:
         show_if_no_docstring: true
diff --git a/docs/api/store/http.md b/docs/api/store/http.md
@@ -3,4 +3,3 @@
 ::: obstore.store.HTTPStore
     options:
         inherited_members: true
-        show_bases: false
diff --git a/docs/api/store/index.md b/docs/api/store/index.md
@@ -2,3 +2,8 @@
 
 ::: obstore.store.from_url
 ::: obstore.store.ObjectStore
+<!-- We document each actual method in the method-specific pages. -->
+::: obstore.store.ObjectStoreMethods
+    options:
+      members:
+        - false
diff --git a/docs/api/store/local.md b/docs/api/store/local.md
@@ -3,4 +3,3 @@
 ::: obstore.store.LocalStore
     options:
         inherited_members: true
-        show_bases: false
diff --git a/docs/api/store/memory.md b/docs/api/store/memory.md
@@ -3,4 +3,3 @@
 ::: obstore.store.MemoryStore
     options:
         inherited_members: true
-        show_bases: false
diff --git a/docs/method-vs-functional-api.md b/docs/method-vs-functional-api.md
@@ -0,0 +1,48 @@
+# Method vs Functional API
+
+Obstore presents two **nearly-identical APIs** for user convenience, a [method-based API](#method-based-api) and a [functional API](#functional-api).
+
+## Method-based API
+
+The method-based API allows for using methods on store classes.
+
+```py
+from obstore.store import S3Store
+
+store = S3Store("bucket", ...)
+buffer = store.get_range("path", start=0, end=16384)
+```
+
+This is slightly cleaner to use and less verbose than the functional API.
+
+### Obspec compatibility
+
+We also prefer the method-based API because it integrates with [Obspec], generic protocols that define the Object Storage interface. This makes it possible to write code once that works with Obstore and other arbitrary backends.
+
+See the [sibling user guide page](obspec.md) and [Obspec documentation][Obspec] for more information.
+
+[Obspec]: https://developmentseed.org/obspec/
+
+## Functional API
+
+The functional API provides top-level functions to interact with obstore operations.
+
+```py
+import obstore as obs
+from obstore.store import S3Store
+
+store = S3Store("bucket", ...)
+buffer = obs.get_range(store, "path", start=0, end=16384)
+```
+
+## Differences
+
+The main difference between the two APIs is verbosity: the functional API is more verbose because it requires passing `store` as an argument into each operation.
+
+#### Signed URLs
+
+[Creating signed URLs](api/sign.md) is only supported via the functional API because not all object stores support signing.
+
+#### File-like Objects
+
+[Creating file-like objects](api/file.md) is only supported via the functional API because we want to slightly nudge users away from that behavior, if it's possible to achieve their goals with native methods, which should provide better performance.
diff --git a/docs/obspec.md b/docs/obspec.md
@@ -1,11 +1,36 @@
 # Generic storage abstractions with Obspec
 
-Obstore provides an implementation for accessing Amazon S3, Google Cloud Storage, and Azure Storage, but some libraries may want to also support other backends, such as HTTP clients or more obscure things like SFTP or HDFS filesystems.
+Obstore supports Amazon S3, Google Cloud Storage, and Azure Storage, but some libraries may want to also support other backends, such as HTTP clients or more obscure things like SFTP or HDFS filesystems.
 
-Additionally, there's a bunch of useful behavior that could exist on top of Obstore: caching, metrics, globbing, bulk operations. While all of those operations are useful, we want to keep the core Obstore library as small as possible, tightly coupled with the underlying Rust `object_store` library.
+Additionally, there's a bunch of useful behavior that could exist on top of Obstore stores: caching, metrics, globbing, bulk operations. While all of those operations are useful, we want to keep the core Obstore library as small as possible, tightly coupled with the underlying Rust `object_store` library.
 
 [Obspec](https://developmentseed.org/obspec/) exists to provide the abstractions for generic programming against object store backends. Obspec is essentially a formalization and generalization of the Obstore API, so if you're already using Obstore, very few changes are needed to use Obspec instead.
 
 Downstream libraries can program against the Obspec API to be fully generic around what underlying backend is used at runtime.
 
+## Example
+
+To download a file generically, depend on the [Get][obspec.Get] protocol, which defines a `get` method.
+
+```py
+from obspec import Get
+
+def download_file(client: Get):
+    response = client.get("my-file.txt")
+    for buffer in response:
+        # Process each buffer chunk as needed
+        print(f"Received buffer of size: {len(memoryview(buffer))} bytes")
+```
+
+All Obstore stores implement the Obspec protocol. So you can now pass:
+
+```py
+from obstore.store import S3Store
+
+store = S3Store("bucket", ...)
+download_file(store)
+```
+
+## More Information
+
 For further information, refer to the [Obspec documentation](https://developmentseed.org/obspec/latest/) and the [Obspec announcement blog post](https://developmentseed.org/obspec/latest/blog/2025/06/25/introducing-obspec-a-python-protocol-for-interfacing-with-object-storage/).
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -27,6 +27,7 @@ nav:
   - User Guide:
       - getting-started.md
       - cookbook.md
+      - method-vs-functional-api.md
       - authentication.md
       - obspec.md
       - Integrations:
diff --git a/obstore/python/obstore/store.py b/obstore/python/obstore/store.py
