ref(clients): Rename "put" to "insert"

Author: jan-auer

clients/python/README.md

@@ -53,11 +53,11 @@ session = client.session(
 # The following operations will raise an exception on failure
 
 # Write an object and metadata
-object_key = session.put(
+object_key = session.insert(
     b"Hello, world!",
     # You can pass in your own identifier for the object to decide where to store the file.
     # Otherwise, Objectstore will pick an identifier and return it.
-    # A put request to an existing identifier overwrites the contents and metadata.
+    # An insert request to an existing identifier overwrites the contents and metadata.
     # id="hello",
     metadata={"key": "value"},
     # Overrides the default defined at the Usecase level

clients/python/src/objectstore_client/client.py

@@ -212,7 +212,7 @@ def _make_url(self, key: str | None, full: bool = False) -> str:
         else:
             return f"{base_path}"
 
-    def put(
+    def insert(
         self,
         contents: bytes | IO[bytes],
         key: str | None = None,

clients/python/src/objectstore_client/metadata.py

@@ -35,7 +35,7 @@ class Metadata:
     time_created: datetime | None
     """
     Timestamp indicating when the object was created or the last time it was replaced.
-    This means that a PUT request to an existing object causes this value to be bumped.
+    This means that an insert request to an existing object causes this value to be bumped.
     This field is computed by the server, it cannot be set by clients.
     """
 

clients/python/tests/test_e2e.py

@@ -103,14 +103,14 @@ def test_full_cycle(server_url: str) -> None:
 
     session = client.session(test_usecase, org=42, project=1337)
 
-    object_key = session.put(b"test data")
+    object_key = session.insert(b"test data")
     assert object_key is not None
 
     retrieved = session.get(object_key)
     assert retrieved.payload.read() == b"test data"
     assert retrieved.metadata.time_created is not None
 
-    new_key = session.put(b"new data", key=object_key)
+    new_key = session.insert(b"new data", key=object_key)
     assert new_key == object_key
     retrieved = session.get(object_key)
     assert retrieved.payload.read() == b"new data"
@@ -135,7 +135,7 @@ def test_full_cycle_uncompressed(server_url: str) -> None:
     compressor = zstandard.ZstdCompressor()
     compressed_data = compressor.compress(data)
 
-    object_key = session.put(compressed_data, compression="none")
+    object_key = session.insert(compressed_data, compression="none")
     assert object_key is not None
 
     retrieved = session.get(object_key)

clients/rust/README.md

@@ -17,10 +17,10 @@ async fn example_basic() -> Result<()> {
         .for_project(42, 1337)
         .session(&client)?;
 
-    let response = session.put("Hello, world!")
+    let response = session.insert("Hello, world!")
         .send()
         .await
-        .expect("put to succeed");
+        .expect("insert to succeed");
 
     let object = session
         .get(&response.key)
@@ -68,7 +68,7 @@ async fn example() -> Result<()> {
     let session = OBJECTSTORE_CLIENT
         .session(ATTACHMENTS.for_project(42, 1337))?;
 
-    let response = session.put("Hello, world!").send().await?;
+    let response = session.insert("Hello, world!").send().await?;
 
     let object = session
         .get(&response.key)

clients/rust/src/client.rs

@@ -356,7 +356,7 @@ pub(crate) struct ClientInner {
 ///
 /// let session = client.session(usecase.for_project(12345, 1337))?;
 ///
-/// let response = session.put("hello world").send().await?;
+/// let response = session.insert("hello world").send().await?;
 ///
 /// # Ok(())
 /// # }
@@ -406,7 +406,7 @@ pub struct Session {
     pub(crate) client: Arc<ClientInner>,
 }
 
-/// The type of [`Stream`](futures_util::Stream) to be used for a PUT request.
+/// The type of [`Stream`](futures_util::Stream) to be used for an insert request.
 pub type ClientStream = BoxStream<'static, io::Result<Bytes>>;
 
 impl Session {

clients/rust/src/get.rs

@@ -45,7 +45,7 @@ impl fmt::Debug for GetResponse {
 }
 
 impl Session {
-    /// Requests the object with the given `key`.
+    /// Retrieves the object with the given `key`.
     pub fn get(&self, key: &str) -> GetBuilder {
         GetBuilder {
             session: self.clone(),

clients/rust/src/put.rs clients/rust/src/insert.rsclients/rust/src/put.rs renamed to clients/rust/src/insert.rs

@@ -15,70 +15,70 @@ pub use objectstore_types::{Compression, ExpirationPolicy};
 
 use crate::{ClientStream, Session};
 
-/// The response returned from the service after uploading an object.
+/// The response returned from the service after inserting an object.
 #[derive(Debug, Deserialize)]
-pub struct PutResponse {
+pub struct InsertResponse {
     /// The key of the object, as stored.
     pub key: String,
 }
 
-pub(crate) enum PutBody {
+pub(crate) enum InsertBody {
     Buffer(Bytes),
     Stream(ClientStream),
 }
 
-impl fmt::Debug for PutBody {
+impl fmt::Debug for InsertBody {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.debug_tuple("PutBody").finish_non_exhaustive()
+        f.debug_tuple("InsertBody").finish_non_exhaustive()
     }
 }
 
 impl Session {
-    fn put_body(&self, body: PutBody) -> PutBuilder {
+    fn insert_body(&self, body: InsertBody) -> InsertBuilder {
         let metadata = Metadata {
             expiration_policy: self.scope.usecase().expiration_policy(),
             compression: Some(self.scope.usecase().compression()),
             ..Default::default()
         };
 
-        PutBuilder {
+        InsertBuilder {
             session: self.clone(),
             metadata,
             key: None,
             body,
         }
     }
 
-    /// Creates a PUT request for a [`Bytes`]-like type.
-    pub fn put(&self, body: impl Into<Bytes>) -> PutBuilder {
-        self.put_body(PutBody::Buffer(body.into()))
+    /// Creates or replaces an object using a [`Bytes`]-like payload.
+    pub fn insert(&self, body: impl Into<Bytes>) -> InsertBuilder {
+        self.insert_body(InsertBody::Buffer(body.into()))
     }
 
-    /// Creates a PUT request with a stream.
-    pub fn put_stream(&self, body: ClientStream) -> PutBuilder {
-        self.put_body(PutBody::Stream(body))
+    /// Creates or replaces an object using a streaming payload.
+    pub fn insert_stream(&self, body: ClientStream) -> InsertBuilder {
+        self.insert_body(InsertBody::Stream(body))
     }
 
-    /// Creates a PUT request with an [`AsyncRead`] type.
-    pub fn put_read<R>(&self, body: R) -> PutBuilder
+    /// Creates or replaces an object using an [`AsyncRead`] payload.
+    pub fn insert_read<R>(&self, body: R) -> InsertBuilder
     where
         R: AsyncRead + Send + Sync + 'static,
     {
         let stream = ReaderStream::new(body).boxed();
-        self.put_body(PutBody::Stream(stream))
+        self.insert_body(InsertBody::Stream(stream))
     }
 }
 
-/// A PUT request builder.
+/// An insert request builder.
 #[derive(Debug)]
-pub struct PutBuilder {
+pub struct InsertBuilder {
     session: Session,
     metadata: Metadata,
     key: Option<String>,
-    body: PutBody,
+    body: InsertBody,
 }
 
-impl PutBuilder {
+impl InsertBuilder {
     /// Sets an explicit object key.
     ///
     /// If a key is specified, the object will be stored under that key. Otherwise, the Objectstore
@@ -135,9 +135,9 @@ impl PutBuilder {
 // TODO: instead of a separate `send` method, it would be nice to just implement `IntoFuture`.
 // However, `IntoFuture` needs to define the resulting future as an associated type,
 // and "impl trait in associated type position" is not yet stable :-(
-impl PutBuilder {
-    /// Sends the built PUT request to the upstream service.
-    pub async fn send(self) -> crate::Result<PutResponse> {
+impl InsertBuilder {
+    /// Sends the built insert request to the upstream service.
+    pub async fn send(self) -> crate::Result<InsertResponse> {
         let method = match self.key {
             Some(_) => reqwest::Method::PUT,
             None => reqwest::Method::POST,
@@ -148,20 +148,20 @@ impl PutBuilder {
             .request(method, self.key.as_deref().unwrap_or_default());
 
         let body = match (self.metadata.compression, self.body) {
-            (Some(Compression::Zstd), PutBody::Buffer(bytes)) => {
+            (Some(Compression::Zstd), InsertBody::Buffer(bytes)) => {
                 let cursor = Cursor::new(bytes);
                 let encoder = ZstdEncoder::new(cursor);
                 let stream = ReaderStream::new(encoder);
                 Body::wrap_stream(stream)
             }
-            (Some(Compression::Zstd), PutBody::Stream(stream)) => {
+            (Some(Compression::Zstd), InsertBody::Stream(stream)) => {
                 let stream = StreamReader::new(stream);
                 let encoder = ZstdEncoder::new(stream);
                 let stream = ReaderStream::new(encoder);
                 Body::wrap_stream(stream)
             }
-            (None, PutBody::Buffer(bytes)) => bytes.into(),
-            (None, PutBody::Stream(stream)) => Body::wrap_stream(stream),
+            (None, InsertBody::Buffer(bytes)) => bytes.into(),
+            (None, InsertBody::Stream(stream)) => Body::wrap_stream(stream),
             // _ => todo!("compression algorithms other than `zstd` are currently not supported"),
         };
 

clients/rust/src/lib.rs

@@ -6,7 +6,7 @@ mod client;
 mod delete;
 mod error;
 mod get;
-mod put;
+mod insert;
 pub mod utils;
 
 pub use objectstore_types::{Compression, ExpirationPolicy};
@@ -15,7 +15,7 @@ pub use client::*;
 pub use delete::*;
 pub use error::*;
 pub use get::*;
-pub use put::*;
+pub use insert::*;
 
 #[cfg(test)]
 mod tests;

clients/rust/src/tests.rs

@@ -22,7 +22,7 @@ async fn stores_uncompressed() {
     let body = "oh hai!";
 
     let stored_id = session
-        .put(body)
+        .insert(body)
         .compression(None)
         .send()
         .await
@@ -46,7 +46,7 @@ async fn uses_zstd_by_default() {
     let session = client.session(usecase.for_organization(12345)).unwrap();
 
     let body = "oh hai!";
-    let stored_id = session.put(body).send().await.unwrap().key;
+    let stored_id = session.insert(body).send().await.unwrap().key;
 
     // when the user indicates that it can deal with zstd, it gets zstd
     let GetResponse { metadata, stream } = session
@@ -79,7 +79,7 @@ async fn deletes_stores_stuff() {
     let session = client.session(usecase.for_project(12345, 1337)).unwrap();
 
     let body = "oh hai!";
-    let stored_id = session.put(body).send().await.unwrap().key;
+    let stored_id = session.insert(body).send().await.unwrap().key;
 
     session.delete(&stored_id).send().await.unwrap();
 
@@ -97,7 +97,7 @@ async fn stores_under_given_key() {
 
     let body = "oh hai!";
     let stored_id = session
-        .put(body)
+        .insert(body)
         .key("test-key123!!")
         .send()
         .await
@@ -115,9 +115,9 @@ async fn overwrites_existing_key() {
     let usecase = Usecase::new("usecase");
     let session = client.session(usecase.for_project(12345, 1337)).unwrap();
 
-    let stored_id = session.put("initial body").send().await.unwrap().key;
+    let stored_id = session.insert("initial body").send().await.unwrap().key;
     let overwritten_id = session
-        .put("new body")
+        .insert("new body")
         .key(&stored_id)
         .send()
         .await