objectstore-client 0.2.1__tar.gz → 0.2.2__tar.gz

{objectstore_client-0.2.1 → objectstore_client-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: objectstore-client
-Version: 0.2.1
+Version: 0.2.2
 Summary: Client SDK for Objectstore, the Sentry object storage platform
 Author: Sentry
 Author-email: Sentry <oss@sentry.io>
@@ -195,11 +195,15 @@ session.put(b"payload", origin="203.0.113.42")
 
 ### Compression
 
-Uploads are compressed with Zstd by default. Downloads are transparently decompressed.
-You can override compression per-upload for pre-compressed or uncompressible data.
+Uploads are compressed with Zstd by default, and downloads are transparently decompressed.
+Compression can be overridden per-upload:
 
 ```python
-session.put(already_compressed_data, compression="none")
+# upload as-is and record no encoding:
+session.put(video_data, compress="none")
+
+# upload as-is, but record the encoding so that downloads still decompress:
+session.put(zstd_data, precompressed="zstd")
 ```
 
 ### Custom Metadata
@@ -216,8 +220,8 @@ For large objects, use multipart uploads to upload parts independently and then
 assemble them into a final object.
 
 **Important:** unlike single-object uploads, multipart uploads do **not** auto-compress.
-The caller must pre-compress each part according to the compression set as part of the metadata
-when initiating the upload.
+`compression` on `initiate_multipart_upload` behaves like `precompressed` above: it only
+records the algorithm, and the caller must pre-compress each part accordingly.
 
 ```python
 from concurrent.futures import ThreadPoolExecutor

{objectstore_client-0.2.1 → objectstore_client-0.2.2}/README.md

@@ -76,11 +76,15 @@ session.put(b"payload", origin="203.0.113.42")
 
 ### Compression
 
-Uploads are compressed with Zstd by default. Downloads are transparently decompressed.
-You can override compression per-upload for pre-compressed or uncompressible data.
+Uploads are compressed with Zstd by default, and downloads are transparently decompressed.
+Compression can be overridden per-upload:
 
 ```python
-session.put(already_compressed_data, compression="none")
+# upload as-is and record no encoding:
+session.put(video_data, compress="none")
+
+# upload as-is, but record the encoding so that downloads still decompress:
+session.put(zstd_data, precompressed="zstd")
 ```
 
 ### Custom Metadata
@@ -97,8 +101,8 @@ For large objects, use multipart uploads to upload parts independently and then
 assemble them into a final object.
 
 **Important:** unlike single-object uploads, multipart uploads do **not** auto-compress.
-The caller must pre-compress each part according to the compression set as part of the metadata
-when initiating the upload.
+`compression` on `initiate_multipart_upload` behaves like `precompressed` above: it only
+records the algorithm, and the caller must pre-compress each part accordingly.
 
 ```python
 from concurrent.futures import ThreadPoolExecutor

{objectstore_client-0.2.1 → objectstore_client-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "objectstore-client"
-version = "0.2.1"
+version = "0.2.2"
 description = "Client SDK for Objectstore, the Sentry object storage platform"
 readme = "README.md"
 authors = [{ name = "Sentry", email = "oss@sentry.io" }]

{objectstore_client-0.2.1 → objectstore_client-0.2.2}/src/objectstore_client/client.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import math
+import warnings
 from collections.abc import Mapping, Sequence
 from dataclasses import asdict, dataclass
 from datetime import UTC, datetime, timedelta
@@ -310,7 +311,9 @@ class Session:
         self,
         contents: bytes | IO[bytes],
         key: str | None = None,
+        compress: Compression | None = None,
         compression: Compression | Literal["none"] | None = None,
+        precompressed: Compression | None = None,
         content_type: str | None = None,
         metadata: dict[str, str] | None = None,
         expiration_policy: ExpirationPolicy | None = None,
@@ -324,27 +327,49 @@ class Session:
         from this function.
 
         The client will select the configured `default_compression` if none is given
-        explicitly.
-        This can be overridden by explicitly giving a `compression` argument.
+        explicitly. This can be overridden by explicitly giving a `compress` argument.
         Providing `"none"` as the argument will instruct the client to not apply
         any compression to this upload, which is useful for uncompressible formats.
 
+        If `contents` is already compressed, pass the algorithm as `precompressed`
+        instead. The payload is then uploaded verbatim and the algorithm is recorded
+        in the object's metadata, so downloads decompress it transparently.
+
         You can use the utility function `objectstore_client.utils.guess_mime_type`
         to attempt to guess a `content_type` based on magic bytes.
+
+        `compression` is deprecated in favor of `compress`.
         """
-        if compression and compression not in ("none", "zstd"):
-            raise ValueError(f"Invalid compression: {compression}")
+        if compression is not None:
+            warnings.warn(
+                "`compression` is deprecated, use `compress` instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            if compress is not None:
+                raise ValueError("Cannot pass both `compress` and `compression`")
+            compress = compression
+
+        if compress is not None and precompressed is not None:
+            raise ValueError("Cannot pass both `compress` and `precompressed`")
+        if compress and compress not in ("none", "zstd"):
+            raise ValueError(f"Invalid compression: {compress}")
+        if precompressed and precompressed != "zstd":
+            raise ValueError(f"Invalid compression: {precompressed}")
 
         headers = self._make_headers()
         body = BytesIO(contents) if isinstance(contents, bytes) else contents
         original_body: IO[bytes] = body
 
-        compression = compression or self._usecase._compression
-        if compression == "zstd":
+        encoding = precompressed or compress or self._usecase._compression
+        if encoding != "none":
+            headers["Content-Encoding"] = encoding
+
+        compress_with = encoding if precompressed is None else "none"
+        if compress_with == "zstd":
             cctx = zstandard.ZstdCompressor()
             body = cctx.stream_reader(original_body)
             body = cast(IO[bytes], utils._ZstdCompressionReaderWrapper(body))
-            headers["Content-Encoding"] = "zstd"
 
         if content_type:
             headers["Content-Type"] = content_type
@@ -370,8 +395,8 @@ class Session:
             self._metrics_backend, "put", self._usecase.name
         ) as metric_emitter:
             retries = None  # by default use the pool's value, set by the Client
-            if compression == "zstd":
-                # For compressed bodies, don't attempt read retries,
+            if compress_with != "none":
+                # For on-the-fly compression, don't attempt read retries,
                 # as the stream cannot be rewound after data has been consumed.
                 pool_retries = self._pool.retries
                 if isinstance(pool_retries, urllib3.Retry):
@@ -393,9 +418,10 @@ class Session:
 
             # Must do this after streaming `body` as that's what is responsible
             # for advancing the seek position in both streams
-            metric_emitter.record_uncompressed_size(original_body.tell())
-            if compression and compression != "none":
-                metric_emitter.record_compressed_size(body.tell(), compression)
+            if precompressed is None:
+                metric_emitter.record_uncompressed_size(original_body.tell())
+            if encoding != "none":
+                metric_emitter.record_compressed_size(body.tell(), encoding)
             return res["key"]
 
     def get(