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

fotoware_client/settings.py

@@ -0,0 +1,54 @@
+"""What a FotoWare installation may set differently, and the client must follow.
+
+The defaults are what FotoWeb 8.1.1223.0 does out of the box, measured on
+2026-10-23 (see fotoware_client.limits). An installation that renamed its
+original rendition, serves FotoWeb under another path, prepares renditions
+slowly or translates queries differently passes its own ServerSettings.
+
+What is FotoWare's API itself -- the media types, the query syntax, paging
+through ``paging.next`` -- is not here: it is the same everywhere.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from fotoware_client.limits import QUERY_SIZE_BUDGET, TERM_OVERHEAD
+
+
+@dataclass(frozen=True)
+class ServerSettings:
+    """A FotoWare installation's own settings, as the client must know them.
+
+    Attributes:
+        oauth_token_path: Where the installation issues OAuth tokens.
+        api_descriptor_path: The API descriptor, which links the archives.
+        original_rendition_name: The display name of the original-file
+            rendition. Asked only when the rendition list does not mark one
+            ``original``; display names are configurable and translated.
+        download_timeout: Seconds a file download or a rendition may take.
+        rendition_poll_interval: First wait, in seconds, while FotoWare
+            prepares a rendition; it grows by half each time.
+        rendition_poll_interval_max: Longest wait between two polls.
+        query_size_budget: Largest estimated query size sent; see
+            fotoware_client.limits.
+        term_overhead: What a search term adds to FotoWare's translated query
+            besides its value; see fotoware_client.limits.
+    """
+
+    oauth_token_path: str = "/fotoweb/oauth2/token"
+    api_descriptor_path: str = "/fotoweb/me"
+    original_rendition_name: str = "Original File"
+    download_timeout: int = 120
+    rendition_poll_interval: float = 0.1
+    rendition_poll_interval_max: float = 2.0
+    query_size_budget: int = QUERY_SIZE_BUDGET
+    term_overhead: int = TERM_OVERHEAD
+
+    def __post_init__(self) -> None:
+        if self.download_timeout <= 0:
+            raise ValueError("download_timeout must be positive")
+        if not 0 < self.rendition_poll_interval <= self.rendition_poll_interval_max:
+            raise ValueError("rendition poll intervals must satisfy 0 < first <= max")
+        if self.query_size_budget <= 0 or self.term_overhead < 0:
+            raise ValueError("query_size_budget must be positive, term_overhead >= 0")

python_fotoware_client-0.2.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: python-fotoware-client
+Version: 0.2.0
+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
+Project-URL: Homepage, https://github.com/hoppefamily/python-fotoware-client
+Project-URL: Source, https://github.com/hoppefamily/python-fotoware-client
+Project-URL: Issues, https://github.com/hoppefamily/python-fotoware-client/issues
+Keywords: fotoware,fotoweb,api,client
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: urllib3<3,>=2.6.3
+Dynamic: license-file
+
+# python-fotoware-client
+
+[![tests](https://github.com/hoppefamily/python-fotoware-client/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/hoppefamily/python-fotoware-client/actions/workflows/tests.yml)
+[![pre-commit](https://github.com/hoppefamily/python-fotoware-client/actions/workflows/pre-commit.yml/badge.svg?branch=main)](https://github.com/hoppefamily/python-fotoware-client/actions/workflows/pre-commit.yml)
+
+A thin, read-only Python client for the [FotoWare](https://www.fotoware.com/)
+API (FotoWeb). It does what the API does and shows what that costs; it knows
+nothing about any particular archive's fields.
+
+Not affiliated with or endorsed by FotoWare AS. "FotoWare" and "FotoWeb" are
+their trademarks.
+
+## What it does
+
+- **One call is one request.** `search_assets` returns one page; `next_page`
+  and `iter_search` follow `paging.next`. Nothing is batched or asked again
+  behind the caller's back. The only exception are the rendition downloads,
+  which poll until FotoWare has prepared the file.
+- **Refuses a query FotoWare would answer wrongly.** Over FotoWare's size limit
+  a search comes back as a 500 or, worse, as an empty list that looks exactly
+  like "no hits". `search_assets` estimates the query first and raises
+  `QueryTooLargeError` over the budget, without sending it.
+  `estimate_query_size` is public, so callers can batch to stay under it.
+- **Retries what is transient.** urllib3's `Retry` on the session retries 429
+  (honouring `Retry-After`) and 502/503/504, twice by default. A 500 is not
+  retried: it was always caused by the query.
+- **Counts the cost.** `cost_snapshot()` reports requests, retries, errors,
+  search pages and empty search pages.
+- OAuth client credentials with automatic token refresh; context manager.
+- **Takes hrefs as FotoWare gives them.** Answers carry paths on the tenant;
+  every call that takes an href accepts a path or a full URL.
+
+## FotoWare's limits
+
+Measured on 2026-10-23 against FotoWeb 8.1.1223.0; details and edges in
+`fotoware_client/limits.py`.
+
+| Limit | Value |
+| --- | --- |
+| Assets per search answer | 25, with `pageSize` ignored. FotoWare guarantees no page size, so the client follows `paging.next` and counts nothing |
+| Cost of an answer | ~0.4 s with hits whether 1 or 25 assets; 130–220 ms empty |
+| Search size | about 2,000 by `estimate_query_size`; budget 1,500 |
+
+So the cheapest search asks for as many terms as fit the budget and fills
+whole pages.
+
+Two search settings of an installation (Site Configuration › Searching) are out
+of the client's sight:
+
+- **Maximum number of hits** caps a result set. A search with more hits ends
+  early, without saying so.
+- **Search string modification** decides how plain words without an operator
+  are combined (AND, OR or as a phrase). Write `AND`/`OR` explicitly, and the
+  setting does not matter.
+
+## Settings of an installation
+
+What a FotoWare installation may set differently, the client takes as
+`ServerSettings`; the defaults are FotoWeb's:
+
+```python
+from fotoware_client import FotoWareClient, ServerSettings
+
+settings = ServerSettings(
+    original_rendition_name="Originaldatei",  # display names are configurable
+    download_timeout=300,  # seconds per download or rendition
+    rendition_poll_interval=0.5,  # first wait while a rendition is made
+    query_size_budget=1200,  # if the installation's limit is lower
+)
+client = FotoWareClient.from_env(settings=settings)
+```
+
+Also: `oauth_token_path`, `api_descriptor_path`, `rendition_poll_interval_max`
+and `term_overhead`. See `fotoware_client/settings.py`.
+
+## Credentials
+
+Pass them to the constructor, or let `FotoWareClient.from_env()` find them:
+
+1. the environment: `FOTOWARE_TENANT_URL`, `FOTOWARE_CLIENT_ID`,
+   `FOTOWARE_CLIENT_SECRET`;
+2. else the credentials file `~/.config/fotoware/credentials`
+   (`$XDG_CONFIG_HOME/fotoware/credentials`), one `NAME=value` per line,
+   refused unless only its owner may read it (`chmod 600`).
+
+Never on a command line, where a secret lands in the process list and the
+shell history.
+
+## Usage
+
+```python
+from fotoware_client import FotoWareClient
+
+with FotoWareClient.from_env() as client:
+    archive = next(
+        a for a in client.list_archives() if a.href.startswith("/fotoweb/archives/5000-")
+    )
+    query = "(631:4000000000001 OR 631:4000000000002) AND (dt:image OR dt:graphic)"
+    for page in client.iter_search(archive.href, query):
+        for asset in page.assets:
+            print(asset.filename)
+    print(client.cost_snapshot())
+```
+
+Other calls: `get_asset`, `get_field_labels`, `get_rendition_url`, `download_original`,
+`download_original_to_file`, `download_rendition_to_file`, `download_bytes`.
+
+## Errors
+
+All derive from `FotoWareError`:
+
+| Error | When |
+| --- | --- |
+| `QueryTooLargeError` | the query is over the size budget; nothing sent |
+| `RateLimitError` | a 429 outlasted the retries |
+| `RetryExhaustedError` | a 502/503/504, connection error or timeout outlasted the retries |
+| `NotFoundError` | a 404 |
+| `APIError` | any other error status, a 500 among them |
+| `AuthenticationError` | the token could not be fetched |
+| `ConfigurationError` | the client was set up wrongly |
+
+## Install
+
+```bash
+pip install python-fotoware-client
+```
+
+## Development
+
+```bash
+make venv
+make lint type test
+```
+
+Pre-commit hooks: `pip install pre-commit && pre-commit install`.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

python_fotoware_client-0.2.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+fotoware_client/__init__.py,sha256=_8EgMpO6Ag_mvR0IsCYmakDraXOXRFttyDzoo5pPyZc,1497
+fotoware_client/auth.py,sha256=_nTf51dx2fafwsbPVbEEAMvoOO8PSRvUV3lnQrS7NUs,10493
+fotoware_client/client.py,sha256=Ii5JV3m0RN_XVPZUEe5OuG-S0Za7illVUOwCoAfq9J4,34886
+fotoware_client/constants.py,sha256=0FaTPzxtJ-kl2OMnyujYp8LVqAEENFS6n5MnBGr21oo,663
+fotoware_client/credentials.py,sha256=EeG-oDfg8mmospOz9y0mewOvl5oExQQVR0-AeZRm7Ew,2226
+fotoware_client/exceptions.py,sha256=L9adqp2nyEBl7Iyn6fd7An1Xny-90atRES1_E7MFr28,2951
+fotoware_client/limits.py,sha256=Y_G42GtX0uF-RtNQHkMvc5oRBZa5SwxllxbuPZG3VyQ,5255
+fotoware_client/models.py,sha256=5N-jBxlznrI2g9cJorQ7qtNGNsniJzlYozWml0xeHFc,5172
+fotoware_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fotoware_client/retry.py,sha256=2eM86qGFvEsX745mMs0PBLmbQoENgTvie8uxutcz4MU,6489
+fotoware_client/settings.py,sha256=Wqy1eCxDM5SdhDlnr5Q8qns9RJVRqBNlqohmhnIiusY,2517
+python_fotoware_client-0.2.0.dist-info/licenses/LICENSE,sha256=qhRS3zWL3M_5Kh8lUh6xe-FIcZdWHcf7EliJG68Dw1U,1075
+python_fotoware_client-0.2.0.dist-info/METADATA,sha256=NRec8xNrONn8Bvkwi8kQe9MpI0Ua8LE2LyrNP3BqFcM,6311
+python_fotoware_client-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+python_fotoware_client-0.2.0.dist-info/top_level.txt,sha256=PIL52tp2K68xWUErUYhNkev0RYXHzue-EOZGLdk3sgM,16
+python_fotoware_client-0.2.0.dist-info/RECORD,,

python_fotoware_client-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

python_fotoware_client-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Michael Hoppe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_fotoware_client-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fotoware_client