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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: objectstore-client
-Version: 0.2.0
+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.0 → 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.0 → objectstore_client-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "objectstore-client"
-version = "0.2.0"
+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.0 → 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
@@ -354,14 +379,14 @@ class Session:
             headers[HEADER_EXPIRATION] = format_expiration(expiration_policy)
 
         if origin:
-            headers[HEADER_ORIGIN] = origin
+            headers[HEADER_ORIGIN] = utils.encode_header_value(origin)
 
         if filename is not None:
-            headers[HEADER_FILENAME] = filename
+            headers[HEADER_FILENAME] = utils.encode_header_value(filename)
 
         if metadata:
             for k, v in metadata.items():
-                headers[f"{HEADER_META_PREFIX}{k}"] = v
+                headers[f"{HEADER_META_PREFIX}{k}"] = utils.encode_header_value(v)
 
         if key == "":
             key = None
@@ -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(
@@ -619,14 +645,14 @@ class Session:
             headers[HEADER_EXPIRATION] = format_expiration(expiration_policy)
 
         if origin:
-            headers[HEADER_ORIGIN] = origin
+            headers[HEADER_ORIGIN] = utils.encode_header_value(origin)
 
         if filename is not None:
-            headers[HEADER_FILENAME] = filename
+            headers[HEADER_FILENAME] = utils.encode_header_value(filename)
 
         if metadata:
             for k, v in metadata.items():
-                headers[f"{HEADER_META_PREFIX}{k}"] = v
+                headers[f"{HEADER_META_PREFIX}{k}"] = utils.encode_header_value(v)
 
         if key == "":
             key = None

{objectstore_client-0.2.0 → objectstore_client-0.2.2}/src/objectstore_client/metadata.py

@@ -7,6 +7,8 @@ from dataclasses import dataclass
 from datetime import datetime, timedelta
 from typing import Literal, TypeVar, cast
 
+from objectstore_client.utils import decode_header_value
+
 Compression = Literal["zstd"] | Literal["none"]
 
 HEADER_EXPIRATION = "x-sn-expiration"
@@ -14,6 +16,7 @@ HEADER_TIME_CREATED = "x-sn-time-created"
 HEADER_TIME_EXPIRES = "x-sn-time-expires"
 HEADER_ORIGIN = "x-sn-origin"
 HEADER_FILENAME = "x-sn-filename"
+HEADER_SIZE = "x-sn-size"
 HEADER_META_PREFIX = "x-snme-"
 
 
@@ -70,6 +73,17 @@ class Metadata:
     prompting browsers and download tools to save the file under this name.
     """
 
+    size: int | None
+    """
+    The size of the complete stored object in bytes.
+
+    This is always the size of the whole object, even when only a range of it was
+    requested. For a compressed object it is the compressed size, matching the bytes on
+    the wire.
+
+    This field is computed by the server, it cannot be set by clients.
+    """
+
     custom: dict[str, str]
 
     @classmethod
@@ -81,6 +95,7 @@ class Metadata:
         time_expires = None
         origin = None
         filename = None
+        size = None
         custom_metadata = {}
 
         for k, v in headers.items():
@@ -95,11 +110,13 @@ class Metadata:
             elif k == HEADER_TIME_EXPIRES:
                 time_expires = datetime.fromisoformat(v)
             elif k == HEADER_ORIGIN:
-                origin = v
+                origin = decode_header_value(v)
             elif k == HEADER_FILENAME:
-                filename = v
+                filename = decode_header_value(v)
+            elif k == HEADER_SIZE:
+                size = int(v)
             elif k.startswith(HEADER_META_PREFIX):
-                custom_metadata[k[len(HEADER_META_PREFIX) :]] = v
+                custom_metadata[k[len(HEADER_META_PREFIX) :]] = decode_header_value(v)
 
         return Metadata(
             content_type=content_type,
@@ -109,6 +126,7 @@ class Metadata:
             time_expires=time_expires,
             origin=origin,
             filename=filename,
+            size=size,
             custom=custom_metadata,
         )
 

{objectstore_client-0.2.0 → objectstore_client-0.2.2}/src/objectstore_client/utils.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import io
 from typing import IO, Any
-from urllib.parse import quote
+from urllib.parse import quote, unquote
 
 import filetype  # type: ignore[import-untyped]
 from zstandard import ZstdCompressionReader
@@ -22,6 +22,16 @@ from zstandard import ZstdCompressionReader
 _PATH_SAFE = "/:@!$&'()*+,;="
 _QUERY_SAFE = _PATH_SAFE + "?"
 
+# Characters left unescaped in a metadata header value: every visible ASCII
+# character except "%". Non-ASCII, the C0 controls, and DEL are escaped because a
+# header value cannot carry them; "%" is escaped so that a literal percent sign in
+# a value can never be confused with an escape sequence when decoding.
+#
+# This is byte-for-byte identical to the Rust `HEADER_ESCAPE` set (see
+# `objectstore-types/src/headers.rs`), so both clients and the server agree on the
+# wire form. Values that are already plain ASCII are left untouched.
+_HEADER_VALUE_SAFE = "".join(chr(b) for b in range(0x20, 0x7F) if b != ord("%"))
+
 
 def encode_path(path: str) -> str:
     """Percent-encodes a request path as it will appear on the wire.
@@ -42,6 +52,27 @@ def encode_query(query: str) -> str:
     return quote(query, safe=_QUERY_SAFE)
 
 
+def encode_header_value(value: str) -> str:
+    """Percent-encodes a free-form metadata string for an HTTP header value.
+
+    HTTP header values carry only visible ASCII, so anything outside that range has
+    to be escaped to survive the transport (see :data:`_HEADER_VALUE_SAFE`). This is
+    the inverse of :func:`decode_header_value`; only the transport representation is
+    escaped, never the logical string held in :class:`Metadata`.
+    """
+    return quote(value, safe=_HEADER_VALUE_SAFE)
+
+
+def decode_header_value(value: str) -> str:
+    """Decodes a percent-encoded HTTP header value into its logical string.
+
+    Inverse of :func:`encode_header_value`. Values without escape sequences are
+    returned unchanged, so headers written before the encoding existed still read
+    back as-is.
+    """
+    return unquote(value, errors="strict")
+
+
 def parse_accept_encoding(header: str) -> list[str]:
     """Parse an Accept-Encoding header value for use in objectstore GET requests.