Standardize on "path" as the named arg, not "location" (#23)

* Standardize on "path" as the named arg, not "location" * Update delete kwarg * Fix sign docs page
developmentseed · Oct 21, 2024 · b369e4b · b369e4b
1 parent adbe5e3
commit b369e4b
Show file tree

Hide file tree

Showing 11 changed files with 58 additions and 72 deletions.
diff --git a/docs/api/sign.md b/docs/api/sign.md
@@ -1,6 +1,6 @@
 # Sign
 
-::: object_store_rs.sign_url
-::: object_store_rs.sign_url_async
+::: object_store_rs.sign
+::: object_store_rs.sign_async
 ::: object_store_rs.SignCapableStore
 ::: object_store_rs.HTTP_METHOD
diff --git a/object-store-rs/python/object_store_rs/_delete.pyi b/object-store-rs/python/object_store_rs/_delete.pyi
@@ -2,12 +2,12 @@ from typing import Sequence
 
 from .store import ObjectStore
 
-def delete(store: ObjectStore, locations: str | Sequence[str]) -> None:
+def delete(store: ObjectStore, paths: str | Sequence[str]) -> None:
     """Delete the object at the specified location(s).
 
     Args:
         store: The ObjectStore instance to use.
-        locations: The path or paths within the store to delete.
+        paths: The path or paths within the store to delete.
 
             When supported by the underlying store, this method will use bulk operations
             that delete more than one object per a request.
@@ -18,7 +18,7 @@ def delete(store: ObjectStore, locations: str | Sequence[str]) -> None:
             return Ok.
     """
 
-async def delete_async(store: ObjectStore, locations: str | Sequence[str]) -> None:
+async def delete_async(store: ObjectStore, paths: str | Sequence[str]) -> None:
     """Call `delete` asynchronously.
 
     Refer to the documentation for [delete][object_store_rs.delete].

diff --git a/object-store-rs/python/object_store_rs/_get.pyi b/object-store-rs/python/object_store_rs/_get.pyi
@@ -2,10 +2,6 @@ from datetime import datetime
 from typing import List, Sequence, TypedDict
 
 from ._list import ObjectMeta
-from ._sign import HTTP_METHOD as HTTP_METHOD
-from ._sign import SignCapableStore as SignCapableStore
-from ._sign import sign_url as sign_url
-from ._sign import sign_url_async as sign_url_async
 from .store import ObjectStore
 
 class GetOptions(TypedDict):
@@ -165,28 +161,28 @@ class BytesStream:
         """Return the next chunk of bytes in the stream."""
 
 def get(
-    store: ObjectStore, location: str, *, options: GetOptions | None = None
+    store: ObjectStore, path: str, *, options: GetOptions | None = None
 ) -> GetResult:
     """Return the bytes that are stored at the specified location.
 
     Args:
         store: The ObjectStore instance to use.
-        location: The path within ObjectStore to retrieve.
+        path: The path within ObjectStore to retrieve.
         options: options for accessing the file. Defaults to None.
 
     Returns:
         GetResult
     """
 
 async def get_async(
-    store: ObjectStore, location: str, *, options: GetOptions | None = None
+    store: ObjectStore, path: str, *, options: GetOptions | None = None
 ) -> GetResult:
     """Call `get` asynchronously.
 
     Refer to the documentation for [get][object_store_rs.get].
     """
 
-def get_range(store: ObjectStore, location: str, offset: int, length: int) -> bytes:
+def get_range(store: ObjectStore, path: str, offset: int, length: int) -> bytes:
     """
     Return the bytes that are stored at the specified location in the given byte range.
 
@@ -197,7 +193,7 @@ def get_range(store: ObjectStore, location: str, offset: int, length: int) -> by
 
     Args:
         store: The ObjectStore instance to use.
-        location: The path within ObjectStore to retrieve.
+        path: The path within ObjectStore to retrieve.
         offset: The start of the byte range.
         length: The number of bytes.
 
@@ -206,15 +202,15 @@ def get_range(store: ObjectStore, location: str, offset: int, length: int) -> by
     """
 
 async def get_range_async(
-    store: ObjectStore, location: str, offset: int, length: int
+    store: ObjectStore, path: str, offset: int, length: int
 ) -> bytes:
     """Call `get_range` asynchronously.
 
     Refer to the documentation for [get_range][object_store_rs.get_range].
     """
 
 def get_ranges(
-    store: ObjectStore, location: str, offsets: Sequence[int], lengths: Sequence[int]
+    store: ObjectStore, path: str, offsets: Sequence[int], lengths: Sequence[int]
 ) -> List[bytes]:
     """
     Return the bytes that are stored at the specified locationin the given byte ranges
@@ -226,7 +222,7 @@ def get_ranges(
 
     Args:
         store: The ObjectStore instance to use.
-        location: The path within ObjectStore to retrieve.
+        path: The path within ObjectStore to retrieve.
         offsets: A sequence of `int` where each offset starts.
         lengths: A sequence of `int` representing the number of bytes within each range.
 
@@ -235,7 +231,7 @@ def get_ranges(
     """
 
 async def get_ranges_async(
-    store: ObjectStore, location: str, offsets: Sequence[int], lengths: Sequence[int]
+    store: ObjectStore, path: str, offsets: Sequence[int], lengths: Sequence[int]
 ) -> List[bytes]:
     """Call `get_ranges` asynchronously.
 

diff --git a/object-store-rs/python/object_store_rs/_head.pyi b/object-store-rs/python/object_store_rs/_head.pyi
@@ -1,18 +1,18 @@
 from ._list import ObjectMeta
 from .store import ObjectStore
 
-def head(store: ObjectStore, location: str) -> ObjectMeta:
+def head(store: ObjectStore, path: str) -> ObjectMeta:
     """Return the metadata for the specified location
 
     Args:
         store: The ObjectStore instance to use.
-        location: The path within ObjectStore to retrieve.
+        path: The path within ObjectStore to retrieve.
 
     Returns:
         ObjectMeta
     """
 
-async def head_async(store: ObjectStore, location: str) -> ObjectMeta:
+async def head_async(store: ObjectStore, path: str) -> ObjectMeta:
     """Call `head` asynchronously.
 
     Refer to the documentation for [head][object_store_rs.head].

diff --git a/object-store-rs/python/object_store_rs/_list.pyi b/object-store-rs/python/object_store_rs/_list.pyi
@@ -1,16 +1,12 @@
 from datetime import datetime
 from typing import List, TypedDict
 
-from ._sign import HTTP_METHOD as HTTP_METHOD
-from ._sign import SignCapableStore as SignCapableStore
-from ._sign import sign_url as sign_url
-from ._sign import sign_url_async as sign_url_async
 from .store import ObjectStore
 
 class ObjectMeta(TypedDict):
     """The metadata that describes an object."""
 
-    location: str
+    path: str
     """The full path to the object"""
 
     last_modified: datetime

diff --git a/object-store-rs/python/object_store_rs/_put.pyi b/object-store-rs/python/object_store_rs/_put.pyi
@@ -20,7 +20,7 @@ class PutResult(TypedDict):
 
 def put(
     store: ObjectStore,
-    location: str,
+    path: str,
     file: IO[bytes] | Path | bytes,
     *,
     use_multipart: bool | None = None,
@@ -35,7 +35,7 @@ def put(
 
     Args:
         store: The ObjectStore instance to use.
-        location: The path within ObjectStore for where to save the file.
+        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.
 
@@ -47,7 +47,7 @@ def put(
 
 async def put_async(
     store: ObjectStore,
-    location: str,
+    path: str,
     file: IO[bytes] | Path | bytes,
     *,
     use_multipart: bool | None = None,

diff --git a/object-store-rs/src/delete.rs b/object-store-rs/src/delete.rs
@@ -7,15 +7,11 @@ use crate::path::PyPaths;
 use crate::runtime::get_runtime;
 
 #[pyfunction]
-pub(crate) fn delete(
-    py: Python,
-    store: PyObjectStore,
-    locations: PyPaths,
-) -> PyObjectStoreResult<()> {
+pub(crate) fn delete(py: Python, store: PyObjectStore, paths: PyPaths) -> PyObjectStoreResult<()> {
     let runtime = get_runtime(py)?;
     let store = store.into_inner();
     py.allow_threads(|| {
-        match locations {
+        match paths {
             PyPaths::One(path) => {
                 runtime.block_on(store.delete(&path))?;
             }
@@ -34,11 +30,11 @@ pub(crate) fn delete(
 pub(crate) fn delete_async(
     py: Python,
     store: PyObjectStore,
-    locations: PyPaths,
+    paths: PyPaths,
 ) -> PyResult<Bound<PyAny>> {
     let store = store.into_inner();
     pyo3_async_runtimes::tokio::future_into_py(py, async move {
-        match locations {
+        match paths {
             PyPaths::One(path) => {
                 store
                     .delete(&path)

diff --git a/object-store-rs/src/get.rs b/object-store-rs/src/get.rs
@@ -216,16 +216,16 @@ impl IntoPy<PyObject> for PyBytesWrapper {
 }
 
 #[pyfunction]
-#[pyo3(signature = (store, location, *, options = None))]
+#[pyo3(signature = (store, path, *, options = None))]
 pub(crate) fn get(
     py: Python,
     store: PyObjectStore,
-    location: String,
+    path: String,
     options: Option<PyGetOptions>,
 ) -> PyObjectStoreResult<PyGetResult> {
     let runtime = get_runtime(py)?;
     py.allow_threads(|| {
-        let path = &location.into();
+        let path = &path.into();
         let fut = if let Some(options) = options {
             store.as_ref().get_opts(path, options.into())
         } else {
@@ -237,15 +237,15 @@ pub(crate) fn get(
 }
 
 #[pyfunction]
-#[pyo3(signature = (store, location, *, options = None))]
+#[pyo3(signature = (store, path, *, options = None))]
 pub(crate) fn get_async(
     py: Python,
     store: PyObjectStore,
-    location: String,
+    path: String,
     options: Option<PyGetOptions>,
 ) -> PyResult<Bound<PyAny>> {
     pyo3_async_runtimes::tokio::future_into_py(py, async move {
-        let path = &location.into();
+        let path = &path.into();
         let fut = if let Some(options) = options {
             store.as_ref().get_opts(path, options.into())
         } else {
@@ -260,14 +260,14 @@ pub(crate) fn get_async(
 pub(crate) fn get_range(
     py: Python,
     store: PyObjectStore,
-    location: String,
+    path: String,
     offset: usize,
     length: usize,
 ) -> PyObjectStoreResult<PyBytesWrapper> {
     let runtime = get_runtime(py)?;
     let range = offset..offset + length;
     py.allow_threads(|| {
-        let out = runtime.block_on(store.as_ref().get_range(&location.into(), range))?;
+        let out = runtime.block_on(store.as_ref().get_range(&path.into(), range))?;
         Ok::<_, PyObjectStoreError>(PyBytesWrapper::new(out))
     })
 }
@@ -276,15 +276,15 @@ pub(crate) fn get_range(
 pub(crate) fn get_range_async(
     py: Python,
     store: PyObjectStore,
-    location: String,
+    path: String,
     offset: usize,
     length: usize,
 ) -> PyResult<Bound<PyAny>> {
     let range = offset..offset + length;
     pyo3_async_runtimes::tokio::future_into_py(py, async move {
         let out = store
             .as_ref()
-            .get_range(&location.into(), range)
+            .get_range(&path.into(), range)
             .await
             .map_err(PyObjectStoreError::ObjectStoreError)?;
         Ok(PyBytesWrapper::new(out))
@@ -295,7 +295,7 @@ pub(crate) fn get_range_async(
 pub(crate) fn get_ranges(
     py: Python,
     store: PyObjectStore,
-    location: String,
+    path: String,
     offsets: Vec<usize>,
     lengths: Vec<usize>,
 ) -> PyObjectStoreResult<Vec<PyBytesWrapper>> {
@@ -306,7 +306,7 @@ pub(crate) fn get_ranges(
         .map(|(offset, length)| offset..offset + length)
         .collect::<Vec<_>>();
     py.allow_threads(|| {
-        let out = runtime.block_on(store.as_ref().get_ranges(&location.into(), &ranges))?;
+        let out = runtime.block_on(store.as_ref().get_ranges(&path.into(), &ranges))?;
         Ok::<_, PyObjectStoreError>(out.into_iter().map(PyBytesWrapper::new).collect())
     })
 }
@@ -315,7 +315,7 @@ pub(crate) fn get_ranges(
 pub(crate) fn get_ranges_async(
     py: Python,
     store: PyObjectStore,
-    location: String,
+    path: String,
     offsets: Vec<usize>,
     lengths: Vec<usize>,
 ) -> PyResult<Bound<PyAny>> {
@@ -327,7 +327,7 @@ pub(crate) fn get_ranges_async(
     pyo3_async_runtimes::tokio::future_into_py(py, async move {
         let out = store
             .as_ref()
-            .get_ranges(&location.into(), &ranges)
+            .get_ranges(&path.into(), &ranges)
             .await
             .map_err(PyObjectStoreError::ObjectStoreError)?;
         Ok(out.into_iter().map(PyBytesWrapper::new).collect::<Vec<_>>())

diff --git a/object-store-rs/src/head.rs b/object-store-rs/src/head.rs
@@ -6,26 +6,22 @@ use crate::list::PyObjectMeta;
 use crate::runtime::get_runtime;
 
 #[pyfunction]
-pub fn head(
-    py: Python,
-    store: PyObjectStore,
-    location: String,
-) -> PyObjectStoreResult<PyObjectMeta> {
+pub fn head(py: Python, store: PyObjectStore, path: String) -> PyObjectStoreResult<PyObjectMeta> {
     let runtime = get_runtime(py)?;
     let store = store.into_inner();
 
     py.allow_threads(|| {
-        let meta = runtime.block_on(store.head(&location.into()))?;
+        let meta = runtime.block_on(store.head(&path.into()))?;
         Ok::<_, PyObjectStoreError>(PyObjectMeta::new(meta))
     })
 }
 
 #[pyfunction]
-pub fn head_async(py: Python, store: PyObjectStore, location: String) -> PyResult<Bound<PyAny>> {
+pub fn head_async(py: Python, store: PyObjectStore, path: String) -> PyResult<Bound<PyAny>> {
     let store = store.into_inner().clone();
     pyo3_async_runtimes::tokio::future_into_py(py, async move {
         let meta = store
-            .head(&location.into())
+            .head(&path.into())
             .await
             .map_err(PyObjectStoreError::ObjectStoreError)?;
         Ok(PyObjectMeta::new(meta))

diff --git a/object-store-rs/src/list.rs b/object-store-rs/src/list.rs
@@ -22,7 +22,9 @@ impl PyObjectMeta {
 impl IntoPy<PyObject> for PyObjectMeta {
     fn into_py(self, py: Python<'_>) -> PyObject {
         let mut dict = IndexMap::with_capacity(5);
-        dict.insert("location", self.0.location.as_ref().into_py(py));
+        // Note, this uses "path" instead of "location" because we standardize the API to accept
+        // the keyword "path" everywhere.
+        dict.insert("path", self.0.location.as_ref().into_py(py));
         dict.insert("last_modified", self.0.last_modified.into_py(py));
         dict.insert("size", self.0.size.into_py(py));
         dict.insert("e_tag", self.0.e_tag.into_py(py));