python-fotoware-client 0.2.0__py3-none-any.whl

fotoware_client/constants.py

@@ -0,0 +1,13 @@
+"""Constants for FotoWare API client."""
+
+# FotoWare API Accept headers for different content types
+ACCEPT_JSON = {"Accept": "application/json"}
+ACCEPT_FULL_DESCRIPTOR = {"Accept": "application/vnd.fotoware.full-api-descriptor+json"}
+ACCEPT_COLLECTIONLIST = {"Accept": "application/vnd.fotoware.collectionlist+json"}
+ACCEPT_COLLECTIONINFO = {"Accept": "application/vnd.fotoware.collectioninfo+json"}
+ACCEPT_ASSETLIST = {"Accept": "application/vnd.fotoware.assetlist+json"}
+ACCEPT_ASSET = {"Accept": "application/vnd.fotoware.asset+json"}
+ACCEPT_DOWNLOAD = {"Accept": "application/vnd.fotoware.download+json"}
+
+# Request timeouts (in seconds)
+DEFAULT_TIMEOUT = 30

fotoware_client/credentials.py

@@ -0,0 +1,59 @@
+"""Where a FotoWare client's credentials come from, when the caller does not pass them.
+
+The environment first: FOTOWARE_TENANT_URL, FOTOWARE_CLIENT_ID and
+FOTOWARE_CLIENT_SECRET. Where it lacks them, the credentials file,
+``$XDG_CONFIG_HOME/fotoware/credentials`` (``~/.config/fotoware/credentials``),
+one ``NAME=value`` per line. The file is refused when others may read it.
+
+Never from a command line: a secret there lands in the process list and the
+shell history.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from fotoware_client.exceptions import ConfigurationError
+
+ENV_TENANT_URL = "FOTOWARE_TENANT_URL"
+ENV_CLIENT_ID = "FOTOWARE_CLIENT_ID"
+ENV_CLIENT_SECRET = "FOTOWARE_CLIENT_SECRET"
+_NAMES = (ENV_TENANT_URL, ENV_CLIENT_ID, ENV_CLIENT_SECRET)
+
+
+def credentials_file() -> Path:
+    """The credentials file's place."""
+    config_home = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(config_home) / "fotoware" / "credentials"
+
+
+def load_credentials() -> tuple[str, str, str]:
+    """Tenant URL, client id and client secret.
+
+    Raises:
+        ConfigurationError: If neither the environment nor the file has all
+            three, or the file may be read by others
+    """
+    values = {name: os.environ.get(name, "") for name in _NAMES}
+    if not all(values.values()):
+        values = _read_file(credentials_file())
+    return values[ENV_TENANT_URL], values[ENV_CLIENT_ID], values[ENV_CLIENT_SECRET]
+
+
+def _read_file(path: Path) -> dict[str, str]:
+    if not path.is_file():
+        raise ConfigurationError(
+            f"No FotoWare credentials: set {', '.join(_NAMES)} or create {path}"
+        )
+    if path.stat().st_mode & 0o077:
+        raise ConfigurationError(f"{path} may be read by others; run: chmod 600 {path}")
+    values: dict[str, str] = {}
+    for line in path.read_text(encoding="utf-8").splitlines():
+        key, sep, value = line.strip().partition("=")
+        if sep and not key.startswith("#"):
+            values[key.strip()] = value.strip().strip('"')
+    missing = [name for name in _NAMES if not values.get(name)]
+    if missing:
+        raise ConfigurationError(f"{path} lacks {', '.join(missing)}")
+    return values

fotoware_client/exceptions.py

@@ -0,0 +1,110 @@
+"""Exception hierarchy for FotoWare client.
+
+All exceptions inherit from FotoWareError for easy catching.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class FotoWareError(Exception):
+    """Base exception for all FotoWare client errors."""
+
+    def __init__(self, message: str, *, context: dict[str, Any] | None = None) -> None:
+        """Initialize error with message and optional context.
+
+        Args:
+            message: Human-readable error message
+            context: Optional dict with additional error context
+        """
+        super().__init__(message)
+        self.message = message
+        self.context = context or {}
+
+    def __str__(self) -> str:
+        if self.context:
+            ctx_str = ", ".join(f"{k}={v}" for k, v in self.context.items())
+            return f"{self.message} ({ctx_str})"
+        return self.message
+
+
+class AuthenticationError(FotoWareError):
+    """OAuth authentication failed."""
+
+    pass
+
+
+class RateLimitError(FotoWareError):
+    """API rate limit exceeded (HTTP 429)."""
+
+    pass
+
+
+class NotFoundError(FotoWareError):
+    """Resource not found (HTTP 404)."""
+
+    pass
+
+
+class APIError(FotoWareError):
+    """HTTP error from FotoWare API."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        response_text: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize API error with HTTP details.
+
+        Args:
+            message: Human-readable error message
+            status_code: HTTP status code
+            response_text: Response body text
+            context: Optional dict with additional error context
+        """
+        ctx = context or {}
+        if status_code:
+            ctx["status_code"] = status_code
+        if response_text:
+            ctx["response_text"] = response_text[:200]  # Truncate to 200 chars
+        super().__init__(message, context=ctx)
+        self.status_code = status_code
+        self.response_text = response_text
+
+
+class ConfigurationError(FotoWareError):
+    """Invalid client configuration."""
+
+    pass
+
+
+class RetryExhaustedError(FotoWareError):
+    """All retry attempts failed."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        attempts: int,
+        last_error: Exception | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize retry exhausted error.
+
+        Args:
+            message: Human-readable error message
+            attempts: Number of attempts made
+            last_error: The last exception that occurred
+            context: Optional dict with additional error context
+        """
+        ctx = context or {}
+        ctx["attempts"] = attempts
+        if last_error:
+            ctx["last_error"] = str(last_error)
+        super().__init__(message, context=ctx)
+        self.attempts = attempts
+        self.last_error = last_error

fotoware_client/limits.py

@@ -0,0 +1,133 @@
+"""What a FotoWare search may ask, and what it cost.
+
+Measured on 2026-10-23 against a FotoWeb 8.1.1223.0 tenant. Check these again
+when the server version changes; an installation that differs passes its own
+values in fotoware_client.ServerSettings.
+
+- **The answers came in pages of 25**, and ``pageSize`` was ignored. FotoWare
+  guarantees no page size ("do not assume the number of elements per page"),
+  so the client counts nothing and follows ``paging.next`` until it ends.
+- **The cost is per answer, not per asset.** An answer with hits took about
+  0.4 s one after another and about 1 s at 15 in parallel, whether it held 1
+  asset or 25. An empty answer took 130-220 ms.
+- **The search has a size limit, and over it FotoWare answers wrongly.** The
+  limit applies to FotoWare's internal translation of the query, about 2,000
+  characters ("search query string is limited to 2000 characters" in its
+  documentation). Over it the answer is HTTP 500 or, worse, HTTP 200 with an
+  empty list, which looks exactly like "no hits". Nothing in the answer tells
+  them apart, so the only remedy is not to send such a query:
+  :func:`estimate_query_size` estimates it and the client refuses a query over
+  :data:`QUERY_SIZE_BUDGET` with :class:`QueryTooLargeError`.
+
+The estimate: every term costs the length of its value plus
+:data:`TERM_OVERHEAD`. With 13-digit EANs 40 terms worked and 42 did not, with
+2-digit values 52 and 56; both edges sit at about 2,000 by this count. Other
+query forms (wildcards, ranges, full text) were not measured.
+"""
+
+from __future__ import annotations
+
+import re
+import threading
+from dataclasses import dataclass, field
+
+from fotoware_client.exceptions import FotoWareError
+
+TERM_OVERHEAD = 33
+"""What a term adds to the translated query besides its value (measured default)."""
+
+QUERY_SIZE_LIMIT = 2000
+"""Where FotoWare starts to answer wrongly, by :func:`estimate_query_size`."""
+
+QUERY_SIZE_BUDGET = 1500
+"""The largest estimate the client sends, kept well below the limit."""
+
+_OPERATORS = frozenset({"AND", "OR", "NOT"})
+_TOKEN = re.compile(r"[^\s()]+")
+
+
+def estimate_query_size(query: str, term_overhead: int = TERM_OVERHEAD) -> int:
+    """The size FotoWare's translation of *query* will have, estimated.
+
+    Each term counts the length of its value (after ``field:``, if it has one)
+    plus *term_overhead*. Operators, brackets and spaces count nothing.
+    """
+    size = 0
+    for token in _TOKEN.findall(query):
+        if token in _OPERATORS:
+            continue
+        _, _, value = token.rpartition(":")
+        size += len(value) + term_overhead
+    return size
+
+
+class QueryTooLargeError(FotoWareError):
+    """A search the client refuses to send, because FotoWare would answer it wrongly."""
+
+    def __init__(self, *, estimated_size: int, budget: int) -> None:
+        super().__init__(
+            "Search query too large for FotoWare: an answer to it may be empty or a 500 "
+            "although assets match. Split it into smaller queries.",
+            context={"estimated_size": estimated_size, "budget": budget},
+        )
+        self.estimated_size = estimated_size
+        self.budget = budget
+
+
+def check_query_size(
+    query: str, budget: int = QUERY_SIZE_BUDGET, term_overhead: int = TERM_OVERHEAD
+) -> None:
+    """Raise :class:`QueryTooLargeError` when *query* is estimated over *budget*."""
+    size = estimate_query_size(query, term_overhead)
+    if size > budget:
+        raise QueryTooLargeError(estimated_size=size, budget=budget)
+
+
+@dataclass
+class RequestCounters:
+    """What the client has asked of FotoWare so far. Thread-safe.
+
+    ``requests`` counts calls, ``retries`` the repeats on top of them, so the
+    HTTP requests sent are their sum. ``search_pages`` and ``empty_search_pages``
+    are the search answers among the requests; an empty one is cheap, a full or
+    partial one costs the same.
+    """
+
+    requests: int = 0
+    retries: int = 0
+    errors: int = 0
+    search_pages: int = 0
+    empty_search_pages: int = 0
+    retries_by_status: dict[str, int] = field(default_factory=dict)
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False, compare=False)
+
+    def count_request(self) -> None:
+        with self._lock:
+            self.requests += 1
+
+    def count_error(self) -> None:
+        with self._lock:
+            self.errors += 1
+
+    def count_search_page(self, *, empty: bool) -> None:
+        with self._lock:
+            self.search_pages += 1
+            if empty:
+                self.empty_search_pages += 1
+
+    def count_retry(self, status: int | None, error: str | None, delay: float) -> None:
+        key = str(status) if status is not None else (error or "network")
+        with self._lock:
+            self.retries += 1
+            self.retries_by_status[key] = self.retries_by_status.get(key, 0) + 1
+
+    def snapshot(self) -> dict[str, object]:
+        with self._lock:
+            return {
+                "requests": self.requests,
+                "retries": self.retries,
+                "errors": self.errors,
+                "search_pages": self.search_pages,
+                "empty_search_pages": self.empty_search_pages,
+                "retries_by_status": dict(self.retries_by_status),
+            }

fotoware_client/models.py

@@ -0,0 +1,190 @@
+"""Data models for FotoWare API responses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Archive:
+    """Represents a FotoWare archive.
+
+    Attributes:
+        href: Full URL to the archive
+        name: Human-readable archive name
+        data: Complete raw JSON data from API
+    """
+
+    href: str
+    name: str
+    data: dict[str, Any] = field(repr=False)
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> Archive:
+        """Create Archive from API JSON response.
+
+        Args:
+            data: Raw JSON data from FotoWare API
+
+        Returns:
+            Archive instance
+
+        Raises:
+            KeyError: If required fields are missing
+        """
+        return cls(
+            href=data["href"],
+            name=data.get("name", data.get("displayName", "Unknown")),
+            data=data,
+        )
+
+
+@dataclass
+class Asset:
+    """Represents a FotoWare asset (image, document, etc.).
+
+    Attributes:
+        href: Full URL to the asset
+        filename: Asset filename
+        fields: Metadata fields (dict mapping field IDs to values)
+        mimetype: MIME type (e.g., 'image/jpeg', 'application/pdf')
+        data: Complete raw JSON data from API
+    """
+
+    href: str
+    filename: str
+    fields: dict[str, Any]
+    mimetype: str | None
+    data: dict[str, Any] = field(repr=False)
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> Asset:
+        """Create Asset from API JSON response.
+
+        Args:
+            data: Raw JSON data from FotoWare API
+
+        Returns:
+            Asset instance
+
+        Raises:
+            KeyError: If required fields are missing
+        """
+        # Extract filename from metadata
+        filename = data.get("filename", "unknown")
+
+        # Extract and flatten metadata fields
+        fields: dict[str, Any] = {}
+        metadata = data.get("metadata", {})
+
+        # Handle both direct field values and nested structures
+        for field_id, field_data in metadata.items():
+            if isinstance(field_data, dict):
+                # Extract value from nested structure
+                value = field_data.get("value")
+                if value is not None:
+                    fields[field_id] = value
+            else:
+                # Direct value
+                fields[field_id] = field_data
+
+        # Get MIME type
+        mimetype = data.get("mimetype") or data.get("attributes", {}).get("mimetype")
+
+        return cls(
+            href=data["href"],
+            filename=filename,
+            fields=fields,
+            mimetype=mimetype,
+            data=data,
+        )
+
+    def get_field(self, field_id: str, default: Any = None) -> Any:
+        """Get metadata field value by field ID.
+
+        Args:
+            field_id: FotoWare field ID (e.g., '631' for EAN)
+            default: Default value if field not found
+
+        Returns:
+            Field value or default
+        """
+        return self.fields.get(field_id, default)
+
+    def get_field_values(self, field_id: str) -> list[Any]:
+        """Get metadata field values as list (handles multi-value fields).
+
+        Args:
+            field_id: FotoWare field ID
+
+        Returns:
+            List of values (empty list if field not found)
+        """
+        value = self.fields.get(field_id)
+        if value is None:
+            return []
+        if isinstance(value, list):
+            return value
+        return [value]
+
+    @property
+    def doctype(self) -> str | None:
+        """Get asset doctype (e.g., 'image', 'document', 'graphic').
+
+        Returns:
+            Doctype string or None if not present
+        """
+        return self.data.get("doctype")
+
+
+@dataclass
+class SearchResult:
+    """Represents paginated search results from FotoWare.
+
+    Attributes:
+        assets: List of Asset instances
+        total_count: Total number of matching assets
+        next_href: URL to fetch next page (None if last page)
+        data: Complete raw JSON data from API
+    """
+
+    assets: list[Asset]
+    total_count: int
+    next_href: str | None
+    data: dict[str, Any] = field(repr=False)
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> SearchResult:
+        """Create SearchResult from API JSON response.
+
+        Args:
+            data: Raw JSON data from FotoWare API
+
+        Returns:
+            SearchResult instance
+        """
+        # Parse assets from data
+        assets = []
+        for asset_data in data.get("data", []):
+            try:
+                assets.append(Asset.from_json(asset_data))
+            except KeyError, TypeError:
+                # Skip malformed assets
+                continue
+
+        # Get total count
+        paging = data.get("paging") or {}
+        total_count = paging.get("totalAssets", len(assets))
+
+        # Get next page link from paging object
+        next_href = paging.get("next") or None
+        if next_href == "":  # Empty string means no next page
+            next_href = None
+
+        return cls(
+            assets=assets,
+            total_count=total_count,
+            next_href=next_href,
+            data=data,
+        )

fotoware_client/retry.py

@@ -0,0 +1,166 @@
+"""Retry policy for FotoWare requests, run by urllib3.
+
+:class:`RetryConfig` says what is retried and how long to wait; urllib3's
+``Retry``, mounted on the client's session, does the retrying. That is the
+standard for ``requests``, and it honours ``Retry-After``. :class:`ObservedRetry`
+adds a callback per retry, because a retry that succeeds is otherwise invisible
+to the caller and to the cost counters.
+
+**500 is not retried.** Measured on FotoWeb 8.1.1223.0 (2026-10-23): a 500
+never appeared below the query size limit and always reappeared above it, so a
+repeat only costs time. 429 and 502/503/504 are transient and are retried.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from types import TracebackType
+from typing import Any, Self
+
+from urllib3.connectionpool import ConnectionPool
+from urllib3.exceptions import InvalidHeader
+from urllib3.response import BaseHTTPResponse
+from urllib3.util.retry import Retry
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class RetryConfig:
+    """What is retried, and how long to wait in between.
+
+    Attributes:
+        max_attempts: Total attempts, the first one included. 1 means no retry.
+        base_delay: Wait before the first retry, in seconds; doubled for each
+            further one.
+        max_delay: Longest wait between two attempts, in seconds.
+        retry_on_status: Status codes retried. 500 deliberately not, see above.
+        max_retry_after: Longest ``Retry-After`` honoured, in seconds; a longer
+            one is cut to this.
+    """
+
+    max_attempts: int = 3
+    base_delay: float = 1.0
+    max_delay: float = 30.0
+    retry_on_status: frozenset[int] = field(default_factory=lambda: frozenset({429, 502, 503, 504}))
+    max_retry_after: float = 60.0
+
+    def __post_init__(self) -> None:
+        if self.max_attempts < 1:
+            raise ValueError(f"max_attempts must be >= 1, got {self.max_attempts}")
+        if self.base_delay < 0 or self.max_delay < 0 or self.max_retry_after < 0:
+            raise ValueError("delays must be >= 0")
+
+    def delay(self, retry_number: int) -> float:
+        """The wait before retry *retry_number* (1 for the first)."""
+        return float(min(self.max_delay, self.base_delay * 2 ** (retry_number - 1)))
+
+
+STANDARD_RETRY = RetryConfig()
+NO_RETRY = RetryConfig(max_attempts=1)
+
+# Called once per retry, before the wait: the status that caused it (None for a
+# network error), the error's type name (None for a status), and the wait in
+# seconds.
+RetryListener = Callable[[int | None, str | None, float], None]
+
+
+class ObservedRetry(Retry):
+    """urllib3's ``Retry`` with a :class:`RetryConfig`'s waits and a callback.
+
+    A ``Retry-After`` the server sends takes precedence over the backoff, up to
+    ``config.max_retry_after``; one that cannot be read is logged and the
+    backoff used instead. Only ``config.retry_on_status`` is retried: urllib3
+    would also retry a 413, 429 or 503 whenever it carries a ``Retry-After``,
+    whatever the status list says; that is switched off.
+    """
+
+    RETRY_AFTER_STATUS_CODES = frozenset()
+
+    def __init__(
+        self,
+        *args: Any,
+        config: RetryConfig,
+        on_retry: RetryListener | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self.config = config
+        self.on_retry = on_retry
+        # Fixed when the retry is decided, so the wait reported and the wait
+        # slept are the same number.
+        self.planned_delay: float | None = None
+
+    def new(self, **kw: Any) -> Self:
+        kw.setdefault("config", self.config)
+        kw.setdefault("on_retry", self.on_retry)
+        return super().new(**kw)
+
+    def get_retry_after(self, response: BaseHTTPResponse) -> float | None:
+        # urllib3 raises on a header it cannot parse, which would turn a 503
+        # into a network error. increment() logs it; here it is just absent.
+        try:
+            return super().get_retry_after(response)
+        except InvalidHeader:
+            return None
+
+    def get_backoff_time(self) -> float:
+        if self.planned_delay is not None:
+            return self.planned_delay
+        return self.config.delay(len(self.history))
+
+    def increment(
+        self,
+        method: str | None = None,
+        url: str | None = None,
+        response: BaseHTTPResponse | None = None,
+        error: Exception | None = None,
+        _pool: ConnectionPool | None = None,
+        _stacktrace: TracebackType | None = None,
+    ) -> Self:
+        # Raises MaxRetryError when the budget is spent; nothing to report then.
+        retried = super().increment(method, url, response, error, _pool, _stacktrace)
+        retry_after = retried.get_retry_after(response) if response is not None else None
+        if retry_after is None and response is not None and response.headers.get("Retry-After"):
+            logger.warning(
+                "Unreadable Retry-After %r, backing off instead",
+                response.headers.get("Retry-After"),
+            )
+        delay = retry_after if retry_after is not None else self.config.delay(len(retried.history))
+        # Also for a Retry-After of 0, which urllib3 treats as "not slept" and
+        # falls back to the backoff for.
+        retried.planned_delay = delay
+        if self.on_retry is not None:
+            self.on_retry(
+                response.status if response is not None else None,
+                type(error).__name__ if error is not None else None,
+                delay,
+            )
+        return retried
+
+
+def urllib3_retry(config: RetryConfig, on_retry: RetryListener | None = None) -> ObservedRetry:
+    """The urllib3 policy a :class:`RetryConfig` describes.
+
+    Every method is retried: the client only reads, and its one POST asks for a
+    rendition, which FotoWare prepares again without harm. Once the retries are
+    spent the last response is returned, not raised, so the client maps its
+    status like any other.
+    """
+    retries = config.max_attempts - 1
+    return ObservedRetry(
+        total=retries,
+        connect=retries,
+        read=retries,
+        status=retries,
+        other=retries,
+        allowed_methods=None,
+        status_forcelist=config.retry_on_status,
+        respect_retry_after_header=True,
+        retry_after_max=config.max_retry_after,
+        raise_on_status=False,
+        config=config,
+        on_retry=on_retry,
+    )