Add class methods wrapper (#331)

* Add class methods wrapper

* fix local tests

* Don't override store module from rust

* exceptions module

* Update imports

* fix store wrapper imports

* Re-export _store for correct type inference

* Instantiate subclasses in from_url

* Ensure from_url instantiates subclasses

* Ensure correct error raised

* Convert tests to use store api

* lint

* Add obspec validation tests

* use published obspec

* hyperlinks

Author: kylebarron

docs/api/list.md

@@ -3,6 +3,3 @@
 ::: obstore.list
 ::: obstore.list_with_delimiter
 ::: obstore.list_with_delimiter_async
-::: obstore.ListResult
-::: obstore.ListStream
-::: obstore.ListChunkType

docs/api/store/aws.md

@@ -1,6 +1,9 @@
 # AWS S3
 
 ::: obstore.store.S3Store
+    options:
+        inherited_members: true
+        show_bases: false
 ::: obstore.store.S3Config
     options:
         show_if_no_docstring: true

docs/api/store/azure.md

@@ -1,6 +1,9 @@
 # Microsoft Azure
 
 ::: obstore.store.AzureStore
+    options:
+        inherited_members: true
+        show_bases: false
 ::: obstore.store.AzureConfig
     options:
         show_if_no_docstring: true

docs/api/store/gcs.md

@@ -1,6 +1,9 @@
 # Google Cloud Storage
 
 ::: obstore.store.GCSStore
+    options:
+        inherited_members: true
+        show_bases: false
 ::: obstore.store.GCSConfig
     options:
         show_if_no_docstring: true

docs/api/store/http.md

@@ -1,3 +1,6 @@
 # HTTP
 
 ::: obstore.store.HTTPStore
+    options:
+        inherited_members: true
+        show_bases: false

docs/api/store/local.md

@@ -1,3 +1,6 @@
 # Local
 
 ::: obstore.store.LocalStore
+    options:
+        inherited_members: true
+        show_bases: false

docs/api/store/memory.md

@@ -1,3 +1,6 @@
 # Memory
 
 ::: obstore.store.MemoryStore
+    options:
+        inherited_members: true
+        show_bases: false

docs/cookbook.md

@@ -39,6 +39,19 @@ store = ... # store of your choice
 # Get a stream of Arrow RecordBatches of metadata
 list_stream = obs.list(store, prefix="data", return_arrow=True)
 for record_batch in list_stream:
+    # Perform zero-copy conversion to your arrow-backed library of choice
+    #
+    # To pyarrow:
+    # pyarrow.record_batch(record_batch)
+    #
+    # To polars:
+    # polars.DataFrame(record_batch)
+    #
+    # To pandas (with Arrow-backed data-types):
+    # pyarrow.record_batch(record_batch).to_pandas(types_mapper=pd.ArrowDtype)
+    #
+    # To arro3:
+    # arro3.core.RecordBatch(record_batch)
     print(record_batch.num_rows)
 ```
 

obstore/python/obstore/__init__.py

@@ -1,9 +1,50 @@
 from typing import TYPE_CHECKING
 
-from ._obstore import *
-from ._obstore import ___version
+from . import store
+from ._obstore import (
+    Bytes,
+    ___version,
+    copy,
+    copy_async,
+    delete,
+    delete_async,
+    get,
+    get_async,
+    get_range,
+    get_range_async,
+    get_ranges,
+    get_ranges_async,
+    head,
+    head_async,
+    list,  # noqa: A004
+    list_with_delimiter,
+    list_with_delimiter_async,
+    open_reader,
+    open_reader_async,
+    open_writer,
+    open_writer_async,
+    put,
+    put_async,
+    rename,
+    rename_async,
+    sign,
+    sign_async,
+)
 
 if TYPE_CHECKING:
-    from . import exceptions, store
-
+    from . import _store, exceptions
+    from ._obstore import (
+        HTTP_METHOD,
+        AsyncReadableFile,
+        AsyncWritableFile,
+        Bytes,
+        BytesStream,
+        GetResult,
+        ListChunkType,
+        ListResult,
+        ListStream,
+        ReadableFile,
+        SignCapableStore,
+        WritableFile,
+    )
 __version__: str = ___version()

obstore/python/obstore/_buffered.pyi

@@ -7,7 +7,7 @@ from obspec._attributes import Attributes
 
 from ._bytes import Bytes
 from ._list import ObjectMeta
-from .store import ObjectStore
+from ._store import ObjectStore
 
 if sys.version_info >= (3, 12):
     from collections.abc import Buffer