python-fotoware-client 0.2.1__tar.gz → 0.2.3__tar.gz

{python_fotoware_client-0.2.1/src/python_fotoware_client.egg-info → python_fotoware_client-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-fotoware-client
-Version: 0.2.1
+Version: 0.2.3
 Summary: A thin, honest client for the FotoWare API: one call, one request; refuses queries FotoWare would answer wrongly; counts what each request costs
 Author: Michael Hoppe
 License-Expression: MIT

{python_fotoware_client-0.2.1 → python_fotoware_client-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-fotoware-client"
-version = "0.2.1"
+version = "0.2.3"
 description = "A thin, honest client for the FotoWare API: one call, one request; refuses queries FotoWare would answer wrongly; counts what each request costs"
 readme = "README.md"
 requires-python = ">=3.14,<3.15"

{python_fotoware_client-0.2.1 → python_fotoware_client-0.2.3}/src/fotoware_client/__init__.py

@@ -23,7 +23,7 @@ from fotoware_client.models import Archive, Asset, SearchResult
 from fotoware_client.retry import NO_RETRY, STANDARD_RETRY, RetryConfig
 from fotoware_client.settings import ServerSettings
 
-__version__ = "0.2.1"
+__version__ = "0.2.3"
 
 __all__ = [
     # Client

{python_fotoware_client-0.2.1 → python_fotoware_client-0.2.3}/src/fotoware_client/client.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import logging
 import time
-from collections.abc import Iterator
+from collections.abc import Callable, Iterator
 from typing import Any, BinaryIO
 from urllib.parse import urljoin
 
@@ -161,9 +161,7 @@ class FotoWareClient:
             NotFoundError: If there is no such asset
             APIError: If the request fails
         """
-        response = self._request("GET", self.resolve(asset_href), headers=ACCEPT_ASSET)
-        asset = Asset.from_json(response.json())
-        response.close()
+        asset = Asset.from_json(self._get_json(self.resolve(asset_href), headers=ACCEPT_ASSET))
         return asset
 
     def cost_snapshot(self) -> dict[str, object]:
@@ -194,9 +192,9 @@ class FotoWareClient:
         me_url = urljoin(self.tenant_url + "/", self.settings.api_descriptor_path.lstrip("/"))
 
         try:
-            response = self._request("GET", me_url, headers=ACCEPT_FULL_DESCRIPTOR)
-            response.json()  # Validate response is valid JSON
-            response.close()
+            self._get_json(
+                me_url, headers=ACCEPT_FULL_DESCRIPTOR
+            )  # Validate response is valid JSON
             logger.debug("FotoWare API connection validated successfully")
         except Exception as e:
             logger.error("FotoWare API connection validation failed: %s", e)
@@ -211,6 +209,19 @@ class FotoWareClient:
         token = self._auth.get_access_token()
         return {"Authorization": f"Bearer {token}"}
 
+    def _get_json(self, url: str, **kwargs: Any) -> Any:
+        """GET *url* and return its JSON; the response is closed either way.
+
+        Raises:
+            requests.JSONDecodeError: If the answer is no JSON
+            The errors of _request
+        """
+        response = self._request("GET", url, **kwargs)
+        try:
+            return response.json()
+        finally:
+            response.close()
+
     def _request(
         self,
         method: str,
@@ -324,17 +335,13 @@ class FotoWareClient:
 
         # The API descriptor names the archives list, as a path on the tenant
         me_url = urljoin(self.tenant_url + "/", self.settings.api_descriptor_path.lstrip("/"))
-        response = self._request("GET", me_url, headers=ACCEPT_FULL_DESCRIPTOR)
-        archives_path = response.json().get("archives")
-        response.close()
+        archives_path = self._get_json(me_url, headers=ACCEPT_FULL_DESCRIPTOR).get("archives")
         if not isinstance(archives_path, str) or not archives_path:
             raise APIError("No archives link found in API descriptor")
         archives_href = urljoin(self.tenant_url + "/", archives_path)
 
         # Fetch archives
-        response = self._request("GET", archives_href, headers=ACCEPT_COLLECTIONLIST)
-        archives_data = response.json()
-        response.close()
+        archives_data = self._get_json(archives_href, headers=ACCEPT_COLLECTIONLIST)
 
         # Parse archives
         archives = []
@@ -363,17 +370,13 @@ class FotoWareClient:
                 editor lists no fields
             KeyError: If the editor's answer has another shape
         """
-        response = self._request("GET", self.resolve(archive_href), headers=ACCEPT_COLLECTIONINFO)
-        archive = response.json()
-        response.close()
+        archive = self._get_json(self.resolve(archive_href), headers=ACCEPT_COLLECTIONINFO)
         editor_href = (archive.get("metadataEditor") or {}).get("href")
         if not editor_href:
             raise APIError(f"Archive {archive_href} links no metadata editor")
 
         editor_url = urljoin(self.tenant_url + "/", editor_href.lstrip("/"))
-        response = self._request("GET", editor_url, headers=ACCEPT_JSON)
-        editor = response.json()
-        response.close()
+        editor = self._get_json(editor_url, headers=ACCEPT_JSON)
 
         labels: dict[str, str] = {}
         for region in editor["detailRegions"]:
@@ -428,9 +431,9 @@ class FotoWareClient:
             page = self.next_page(page)
 
     def _search_page(self, url: str, *, params: dict[str, str] | None = None) -> SearchResult:
-        response = self._request("GET", url, params=params, headers=ACCEPT_ASSETLIST)
-        result = SearchResult.from_json(response.json())
-        response.close()
+        result = SearchResult.from_json(
+            self._get_json(url, params=params, headers=ACCEPT_ASSETLIST)
+        )
         self._counters.count_search_page(empty=not result.assets)
         return result
 
@@ -454,9 +457,7 @@ class FotoWareClient:
 
         try:
             # Get asset with download info
-            response = self._request("GET", self.resolve(asset_href), headers=ACCEPT_DOWNLOAD)
-            data = response.json()
-            response.close()
+            data = self._get_json(self.resolve(asset_href), headers=ACCEPT_DOWNLOAD)
 
             # Look for direct URL in attributes
             if "attributes" in data and "downloadUrl" in data["attributes"]:
@@ -469,9 +470,7 @@ class FotoWareClient:
                     download_href = link.get("href")
                     if download_href:
                         # Fetch presigned URL
-                        response = self._request("GET", download_href, headers=ACCEPT_DOWNLOAD)
-                        download_data = response.json()
-                        response.close()
+                        download_data = self._get_json(download_href, headers=ACCEPT_DOWNLOAD)
                         result_url: str | None = download_data.get("url") or download_data.get(
                             "href"
                         )
@@ -511,6 +510,57 @@ class FotoWareClient:
         *,
         timeout: int | None = None,
         rendition: str | None = None,
+    ) -> str:
+        """The URL a prepared rendition can be downloaded from, the original's
+        unless *rendition* names another.
+
+        FotoWare prepares the file in a background task and serves it under
+        that task's address for a limited time; download it promptly.
+
+        Raises:
+            APIError: If the asset has no such rendition, or a request fails
+        """
+        return self._renewing_gone_rendition(
+            lambda: self._get_rendition_url_once(asset_href, timeout=timeout, rendition=rendition)
+        )
+
+    def download_original(self, asset_href: str, *, timeout: int | None = None) -> bytes:
+        """The original file of an asset, in memory.
+
+        Raises:
+            APIError: If the request or download fails
+        """
+        return self._renewing_gone_rendition(
+            lambda: self._download_original_once(asset_href, timeout=timeout)
+        )
+
+    def _renewing_gone_rendition[T](self, attempt: Callable[[], T]) -> T:
+        """Run a rendition *attempt*; if FotoWare says its result is gone, once more.
+
+        A rendition is prepared in a background task, and FotoWare answers
+        410 Gone once that task's result has been cleaned up. The address is
+        dead then; asking it again is pointless, but a new rendition request
+        starts a new task. Seen on 2026-10-24 for a few renditions in a hundred
+        while FotoWare was otherwise healthy. The repeat counts as a retry.
+
+        A 410 arrives before any byte is written, so a destination file is
+        still untouched when the attempt is repeated.
+        """
+        try:
+            return attempt()
+        except APIError as exc:
+            if exc.status_code != 410:
+                raise
+            logger.info("Rendition gone (410); requesting it anew: %s", exc)
+            self._counters.count_retry(410, None, 0.0)
+            return attempt()
+
+    def _get_rendition_url_once(
+        self,
+        asset_href: str,
+        *,
+        timeout: int | None = None,
+        rendition: str | None = None,
     ) -> str:
         """Get download URL using FotoWare rendition API.
 
@@ -548,9 +598,7 @@ class FotoWareClient:
         logger.debug("get_rendition_url: Starting for asset=%s", asset_href)
 
         # Step 1: Get asset metadata with renditions
-        response = self._request("GET", self.resolve(asset_href), headers=ACCEPT_ASSET)
-        asset_data = response.json()
-        response.close()
+        asset_data = self._get_json(self.resolve(asset_href), headers=ACCEPT_ASSET)
 
         # Step 2: Find the rendition asked for, the original unless named
         renditions = asset_data.get("renditions", [])
@@ -588,9 +636,7 @@ class FotoWareClient:
 
         # Step 3: Get rendition service URL
         me_url = urljoin(self.tenant_url + "/", self.settings.api_descriptor_path.lstrip("/"))
-        response = self._request("GET", me_url, headers=ACCEPT_FULL_DESCRIPTOR)
-        me_data = response.json()
-        response.close()
+        me_data = self._get_json(me_url, headers=ACCEPT_FULL_DESCRIPTOR)
 
         rendition_service_url = me_data.get("services", {}).get("rendition_request")
         if not rendition_service_url:
@@ -618,11 +664,10 @@ class FotoWareClient:
         )
 
         # Get polling URL from Location header or response body
-        polling_url = response.headers.get("Location")
-        if not polling_url:
-            response_data = response.json()
+        try:
+            polling_url = response.headers.get("Location") or response.json().get("href")
+        finally:
             response.close()
-            polling_url = response_data.get("href")
 
         if not polling_url:
             raise APIError(
@@ -677,7 +722,7 @@ class FotoWareClient:
                     context={"asset_href": asset_href, "polling_url": polling_url},
                 )
 
-    def download_original(self, asset_href: str, *, timeout: int | None = None) -> bytes:
+    def _download_original_once(self, asset_href: str, *, timeout: int | None = None) -> bytes:
         """Download original file using FotoWare rendition API (atomic operation).
 
         This is the recommended way to download original files. It handles the
@@ -713,9 +758,7 @@ class FotoWareClient:
         logger.debug("download_original: Starting for asset=%s", asset_href)
 
         # Step 1: Get asset metadata with renditions
-        response = self._request("GET", self.resolve(asset_href), headers=ACCEPT_ASSET)
-        asset_data = response.json()
-        response.close()
+        asset_data = self._get_json(self.resolve(asset_href), headers=ACCEPT_ASSET)
 
         # Step 2: Find the original rendition
         renditions = asset_data.get("renditions", [])
@@ -750,9 +793,7 @@ class FotoWareClient:
 
         # Step 3: Get rendition service URL
         me_url = urljoin(self.tenant_url + "/", self.settings.api_descriptor_path.lstrip("/"))
-        response = self._request("GET", me_url, headers=ACCEPT_FULL_DESCRIPTOR)
-        me_data = response.json()
-        response.close()
+        me_data = self._get_json(me_url, headers=ACCEPT_FULL_DESCRIPTOR)
 
         rendition_service_url = me_data.get("services", {}).get("rendition_request")
         if not rendition_service_url:
@@ -781,11 +822,10 @@ class FotoWareClient:
         )
 
         # Get polling URL from Location header or response body
-        polling_url = response.headers.get("Location")
-        if not polling_url:
-            response_data = response.json()
+        try:
+            polling_url = response.headers.get("Location") or response.json().get("href")
+        finally:
             response.close()
-            polling_url = response_data.get("href")
 
         if not polling_url:
             raise APIError(
@@ -863,11 +903,13 @@ class FotoWareClient:
             APIError: If rendition request or download fails
             NotFoundError: If asset or original rendition not found
         """
-        self._stream_to_file(
-            self.get_rendition_url(asset_href, timeout=timeout),
-            destination,
-            timeout=timeout,
-            chunk_size=chunk_size,
+        self._renewing_gone_rendition(
+            lambda: self._stream_to_file(
+                self._get_rendition_url_once(asset_href, timeout=timeout),
+                destination,
+                timeout=timeout,
+                chunk_size=chunk_size,
+            )
         )
 
     def download_rendition_to_file(
@@ -886,11 +928,13 @@ class FotoWareClient:
             APIError: If the asset has no such rendition, or its request or
                 download fails
         """
-        self._stream_to_file(
-            self.get_rendition_url(asset_href, timeout=timeout, rendition=rendition),
-            destination,
-            timeout=timeout,
-            chunk_size=chunk_size,
+        self._renewing_gone_rendition(
+            lambda: self._stream_to_file(
+                self._get_rendition_url_once(asset_href, timeout=timeout, rendition=rendition),
+                destination,
+                timeout=timeout,
+                chunk_size=chunk_size,
+            )
         )
 
     def _stream_to_file(

{python_fotoware_client-0.2.1 → python_fotoware_client-0.2.3/src/python_fotoware_client.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-fotoware-client
-Version: 0.2.1
+Version: 0.2.3
 Summary: A thin, honest client for the FotoWare API: one call, one request; refuses queries FotoWare would answer wrongly; counts what each request costs
 Author: Michael Hoppe
 License-Expression: MIT

{python_fotoware_client-0.2.1 → python_fotoware_client-0.2.3}/tests/test_client.py

@@ -4,6 +4,7 @@ import io
 from unittest.mock import Mock, patch
 
 import pytest
+import requests
 
 from fotoware_client.client import FotoWareClient
 from fotoware_client.exceptions import APIError, ConfigurationError
@@ -416,7 +417,7 @@ class TestFotoWareClientDownloadOriginalToFile:
         with (
             patch.object(
                 client,
-                "get_rendition_url",
+                "_get_rendition_url_once",
                 return_value="https://fotoware.example.com/renditions/file.bin",
             ) as mock_get_rendition_url,
             patch.object(
@@ -460,7 +461,7 @@ class TestFotoWareClientDownloadOriginalToFile:
         with (
             patch.object(
                 client,
-                "get_rendition_url",
+                "_get_rendition_url_once",
                 return_value="https://fotoware.example.com/renditions/medium.jpg",
             ) as mock_get_rendition_url,
             patch.object(client, "_request", return_value=response),
@@ -508,3 +509,116 @@ class TestFotoWareClientRenditionChoice:
             pytest.raises(APIError, match="No Large rendition"),
         ):
             client.get_rendition_url("https://fotoware.example.com/asset/1.info", rendition="Large")
+
+
+class TestResponsesAreClosed:
+    """Every response goes back to the pool, whatever its body holds."""
+
+    @patch("fotoware_client.client.OAuthAuthenticator")
+    def test_an_unreadable_answer_is_closed(self, mock_auth: Mock) -> None:
+        client = FotoWareClient("https://fotoware.example.com", "id", "secret")
+        response = Mock()
+        response.json.side_effect = requests.JSONDecodeError("invalid json", "", 0)
+
+        with patch.object(client, "_request", return_value=response):
+            with pytest.raises(requests.JSONDecodeError):
+                client.get_asset("/a/1.jpg.info")
+
+        response.close.assert_called_once()
+
+    @patch("fotoware_client.client.OAuthAuthenticator")
+    def test_a_rendition_request_answered_with_a_location_is_closed(self, mock_auth: Mock) -> None:
+        client = FotoWareClient("https://fotoware.example.com", "id", "secret")
+        asset = Mock()
+        asset.json.return_value = {"renditions": [{"original": True, "href": "/r/1"}]}
+        descriptor = Mock()
+        descriptor.json.return_value = {
+            "services": {"rendition_request": "/fotoweb/services/renditions"}
+        }
+        requested = Mock(status_code=202, headers={"Location": "/fotoweb/poll/1"})
+        ready = Mock(status_code=200)
+
+        with patch.object(client, "_request", side_effect=[asset, descriptor, requested, ready]):
+            client.get_rendition_url("/a/1.jpg.info")
+
+        requested.close.assert_called_once()
+        requested.json.assert_not_called()
+
+
+class TestGoneRenditions:
+    """A rendition whose background task is gone (410) is requested anew, once."""
+
+    @staticmethod
+    def _gone() -> APIError:
+        return APIError("HTTP 410 error", status_code=410)
+
+    @patch("fotoware_client.client.OAuthAuthenticator")
+    def test_a_gone_rendition_is_requested_anew(self, mock_auth: Mock) -> None:
+        client = FotoWareClient("https://fotoware.example.com", "id", "secret")
+        destination = io.BytesIO()
+
+        def stream(url: str, dest: io.BytesIO, **_: object) -> None:
+            if url.endswith("/task-1/file.jpg"):
+                raise self._gone()
+            dest.write(b"jpeg")
+
+        with (
+            patch.object(
+                client,
+                "_get_rendition_url_once",
+                side_effect=["https://f/task-1/file.jpg", "https://f/task-2/file.jpg"],
+            ) as rendition_url,
+            patch.object(client, "_stream_to_file", side_effect=stream),
+        ):
+            client.download_rendition_to_file(
+                "/a/1.jpg.info", destination, rendition="Medium (JPG, 3000px)"
+            )
+
+        assert rendition_url.call_count == 2
+        assert destination.getvalue() == b"jpeg"
+        assert client.cost_snapshot()["retries_by_status"] == {"410": 1}
+
+    @patch("fotoware_client.client.OAuthAuthenticator")
+    def test_a_rendition_gone_twice_is_an_error(self, mock_auth: Mock) -> None:
+        client = FotoWareClient("https://fotoware.example.com", "id", "secret")
+
+        with (
+            patch.object(client, "_get_rendition_url_once", return_value="https://f/t/x.jpg"),
+            patch.object(client, "_stream_to_file", side_effect=self._gone()) as stream,
+        ):
+            with pytest.raises(APIError) as exc_info:
+                client.download_original_to_file("/a/1.jpg.info", io.BytesIO())
+
+        assert exc_info.value.status_code == 410
+        assert stream.call_count == 2
+
+    @patch("fotoware_client.client.OAuthAuthenticator")
+    def test_other_errors_are_not_repeated(self, mock_auth: Mock) -> None:
+        client = FotoWareClient("https://fotoware.example.com", "id", "secret")
+
+        with (
+            patch.object(client, "_get_rendition_url_once", return_value="https://f/t/x.jpg"),
+            patch.object(
+                client,
+                "_stream_to_file",
+                side_effect=APIError("HTTP 403 error", status_code=403),
+            ) as stream,
+        ):
+            with pytest.raises(APIError):
+                client.download_original_to_file("/a/1.jpg.info", io.BytesIO())
+
+        assert stream.call_count == 1
+
+    @patch("fotoware_client.client.OAuthAuthenticator")
+    def test_a_rendition_gone_while_polling_is_requested_anew(self, mock_auth: Mock) -> None:
+        client = FotoWareClient("https://fotoware.example.com", "id", "secret")
+
+        with patch.object(
+            client,
+            "_get_rendition_url_once",
+            side_effect=[self._gone(), "https://f/task-2/file.jpg"],
+        ):
+            assert client.get_rendition_url("/a/1.jpg.info") == "https://f/task-2/file.jpg"
+
+        with patch.object(client, "_download_original_once", side_effect=[self._gone(), b"bytes"]):
+            assert client.download_original("/a/1.jpg.info") == b"bytes"