objectstore-client 0.2.5__tar.gz → 0.2.7__tar.gz

{objectstore_client-0.2.5 → objectstore_client-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: objectstore-client
-Version: 0.2.5
+Version: 0.2.7
 Summary: Client SDK for Objectstore, the Sentry object storage platform
 Author: Sentry
 Author-email: Sentry <oss@sentry.io>
@@ -183,6 +183,19 @@ usecase = Usecase("attachments", expiration_policy=TimeToIdle(timedelta(days=30)
 session.put(b"payload", expiration_policy=TimeToLive(timedelta(hours=1)))
 ```
 
+Use `Session.extend_expiry` to keep an existing object longer.
+
+```python
+from objectstore_client import ExpiryExtensionRejected
+
+try:
+    session.extend_expiry(key, from_now=timedelta(days=30))
+except ExpiryExtensionRejected:
+    print("Object could not be extended")
+```
+
+See the `Session.extend_expiry` docs for target options and error handling.
+
 ### Origin Tracking
 
 We encourage setting the `origin` on every upload to track where the payload was

{objectstore_client-0.2.5 → objectstore_client-0.2.7}/README.md

@@ -64,6 +64,19 @@ usecase = Usecase("attachments", expiration_policy=TimeToIdle(timedelta(days=30)
 session.put(b"payload", expiration_policy=TimeToLive(timedelta(hours=1)))
 ```
 
+Use `Session.extend_expiry` to keep an existing object longer.
+
+```python
+from objectstore_client import ExpiryExtensionRejected
+
+try:
+    session.extend_expiry(key, from_now=timedelta(days=30))
+except ExpiryExtensionRejected:
+    print("Object could not be extended")
+```
+
+See the `Session.extend_expiry` docs for target options and error handling.
+
 ### Origin Tracking
 
 We encourage setting the `origin` on every upload to track where the payload was

{objectstore_client-0.2.5 → objectstore_client-0.2.7}/pyproject.toml

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

{objectstore_client-0.2.5 → objectstore_client-0.2.7}/src/objectstore_client/__init__.py

@@ -5,7 +5,11 @@ from objectstore_client.client import (
     Session,
     Usecase,
 )
-from objectstore_client.errors import RequestError
+from objectstore_client.errors import (
+    ExpiryExtensionRejected,
+    ObjectNotFound,
+    RequestError,
+)
 from objectstore_client.metadata import (
     Compression,
     ExpirationPolicy,
@@ -22,6 +26,8 @@ __all__ = [
     "Session",
     "GetResponse",
     "RequestError",
+    "ObjectNotFound",
+    "ExpiryExtensionRejected",
     "Compression",
     "ExpirationPolicy",
     "Metadata",

{objectstore_client-0.2.5 → objectstore_client-0.2.7}/src/objectstore_client/client.py

@@ -17,7 +17,12 @@ from urllib3.connectionpool import HTTPConnectionPool
 
 from objectstore_client import presign, utils
 from objectstore_client.auth import Permission, SecretKey, TokenProvider
-from objectstore_client.errors import raise_for_status
+from objectstore_client.errors import (
+    ExpiryExtensionRejected,
+    ObjectNotFound,
+    RequestError,
+    raise_for_status,
+)
 from objectstore_client.metadata import (
     HEADER_EXPIRATION,
     HEADER_FILENAME,
@@ -27,6 +32,7 @@ from objectstore_client.metadata import (
     ExpirationPolicy,
     Metadata,
     format_expiration,
+    format_timedelta,
 )
 from objectstore_client.metrics import (
     MetricsBackend,
@@ -671,6 +677,89 @@ class Session:
             span.set_attribute("objectstore.found", True)
             return Metadata.from_headers(response.headers)
 
+    def extend_expiry(
+        self,
+        key: str,
+        at: datetime | None = None,
+        from_creation: timedelta | None = None,
+        from_now: timedelta | None = None,
+    ) -> None:
+        """Extend an object's expiration deadline, preserving its payload.
+
+        Supply exactly one target: ``at`` is a timezone-aware absolute datetime;
+        ``from_creation`` is total lifetime since creation or replacement; and
+        ``from_now`` is lifetime from server request start. Relative targets are
+        resolved by the server, not added to the existing deadline. Fractional
+        duration seconds are truncated; absolute deadlines round upward to seconds.
+
+        An already-sufficient deadline succeeds without being shortened. Success
+        returns no value and does not indicate whether the deadline changed.
+        Requires object-write permission.
+
+        Actual extensions adjust TTL duration to approximately match the total
+        lifetime since creation; TTI duration remains unchanged.
+
+        Raises ``ValueError`` for missing or multiple targets, naive datetimes,
+        or negative durations. Zero durations are valid. Objects observed absent
+        or expired raise ``ObjectNotFound``. Rejected extensions raise
+        ``ExpiryExtensionRejected`` for non-expiring or concurrently changed
+        objects, or missing creation metadata needed for a creation-relative
+        target. Both exceptions subclass ``RequestError``. Rejection does not
+        guarantee that the object still exists, since it may be deleted concurrently.
+        Other HTTP errors propagate normally. Retrying ``from_now`` establishes
+        a new server-time anchor and can extend the deadline further.
+
+        Example::
+
+            from objectstore_client import ExpiryExtensionRejected, ObjectNotFound
+
+            try:
+                session.extend_expiry(key, from_now=timedelta(days=30))
+            except ObjectNotFound:
+                print("Object is missing or expired")
+            except ExpiryExtensionRejected:
+                print("Extension was rejected")
+        """
+
+        if sum(value is not None for value in (at, from_creation, from_now)) != 1:
+            raise ValueError("Supply exactly one of at, from_creation, or from_now")
+
+        extension: dict[str, str]
+        if at is not None:
+            if at.utcoffset() is None:
+                raise ValueError("at must be a timezone-aware datetime")
+            extension = {"at": at.astimezone(UTC).isoformat()}
+        else:
+            delta = from_creation if from_creation is not None else from_now
+            assert delta is not None
+            if delta < timedelta(0):
+                raise ValueError("Expiry extension duration must not be negative")
+            extension = {
+                "after": format_timedelta(delta),
+                "from": "creation" if from_creation is not None else "now",
+            }
+
+        headers = self._make_headers()
+        with (
+            storage_span("extend_expiry", self._usecase, self._scope, key=key),
+            measure_storage_operation(
+                self._metrics_backend, "extend_expiry", self._usecase.name
+            ),
+        ):
+            response = self._pool.request(
+                "PATCH",
+                self._make_url(key),
+                headers=headers,
+                json={"extend_expiry": extension},
+                preload_content=True,
+            )
+            error_type: type[RequestError] = RequestError
+            if response.status == 404:
+                error_type = ObjectNotFound
+            elif response.status == 409:
+                error_type = ExpiryExtensionRejected
+            raise_for_status(response, error_type=error_type)
+
     def delete(self, key: str) -> None:
         """
         Deletes the blob with the given `key`.

objectstore_client-0.2.7/src/objectstore_client/errors.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import urllib3
+
+
+class RequestError(Exception):
+    """Exception raised if an API call to Objectstore fails."""
+
+    def __init__(self, message: str, status: int, response: str):
+        super().__init__(message)
+        self.status = status
+        self.response = response
+
+
+class ObjectNotFound(RequestError):
+    """The object was observed to be absent or expired."""
+
+
+class ExpiryExtensionRejected(RequestError):
+    """The object's expiration deadline could not be extended.
+
+    The object is non-expiring, lacks required creation metadata, or conflicts
+    with a conditional update. A conflict can result from concurrent deletion,
+    so this does not guarantee that the object still exists.
+    """
+
+
+def raise_for_status(
+    response: urllib3.BaseHTTPResponse,
+    *,
+    error_type: type[RequestError] = RequestError,
+) -> None:
+    if response.status >= 400:
+        res = (response.data or response.read() or b"").decode("utf-8", "replace")
+        raise error_type(
+            f"Objectstore request failed with status {response.status}",
+            response.status,
+            res,
+        )

{objectstore_client-0.2.5 → objectstore_client-0.2.7}/src/objectstore_client/metadata.py

@@ -53,8 +53,8 @@ class Metadata:
     When using a Time To Idle expiration policy, this value will reflect the expiration
     timestamp present prior to the current access to the object.
 
-    This field is computed by the server, it cannot be set by clients.
-    Use `expiration_policy` to set an expiration policy instead.
+    This field is computed by the server. Use `expiration_policy` to set the
+    policy on upload, or `Session.extend_expiry` to extend an existing deadline.
     """
 
     origin: str | None

objectstore_client-0.2.5/src/objectstore_client/errors.py

@@ -1,22 +0,0 @@
-from __future__ import annotations
-
-import urllib3
-
-
-class RequestError(Exception):
-    """Exception raised if an API call to Objectstore fails."""
-
-    def __init__(self, message: str, status: int, response: str):
-        super().__init__(message)
-        self.status = status
-        self.response = response
-
-
-def raise_for_status(response: urllib3.BaseHTTPResponse) -> None:
-    if response.status >= 400:
-        res = (response.data or response.read() or b"").decode("utf-8", "replace")
-        raise RequestError(
-            f"Objectstore request failed with status {response.status}",
-            response.status,
-            res,
-        )