python-fotoware-client 0.2.0__tar.gz

python_fotoware_client-0.2.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,139 @@
+# 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/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "python-fotoware-client"
+version = "0.2.0"
+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"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["fotoware", "fotoweb", "api", "client"]
+authors = [{ name = "Michael Hoppe" }]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "requests>=2.31.0",
+    "urllib3>=2.6.3,<3",
+]
+
+[project.urls]
+Homepage = "https://github.com/hoppefamily/python-fotoware-client"
+Source = "https://github.com/hoppefamily/python-fotoware-client"
+Issues = "https://github.com/hoppefamily/python-fotoware-client/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+fotoware_client = ["py.typed"]
+
+[tool.vulture]
+# src/ and any scripts, deliberately without tests/: a function whose only
+# caller is its own test then has no caller at all and gets reported. With
+# tests/ in this list it would look used, which is how such code survives --
+# coverage counts a test as an execution, so it even reads as fully covered.
+# Add every other directory that holds callers (scripts/, utility/, ...), or
+# their code will be reported as dead.
+paths = ["src", "vulture_whitelist.py"]
+# 60, because that is where vulture reports an unused *function*. At 80 it
+# only states what it is certain of -- unused imports, unreachable code, dead
+# variables -- and ruff already catches most of that, so a gate at 80 lets an
+# uncalled function straight through. Tried and measured, not assumed.
+#
+# 60 also guesses. In a repo that starts here the guesses are few; in one that
+# adopts this later, run `vulture --make-whitelist` once and commit the result
+# as a baseline, so the gate speaks only about code written from then on.
+min_confidence = 60
+sort_by_size = true

python_fotoware_client-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

python_fotoware_client-0.2.0/src/fotoware_client/__init__.py

@@ -0,0 +1,62 @@
+"""FotoWare API Client - Layer 1: Pure API."""
+
+from fotoware_client.auth import OAuthAuthenticator, OAuthToken
+from fotoware_client.client import FotoWareClient
+from fotoware_client.constants import DEFAULT_TIMEOUT
+from fotoware_client.credentials import credentials_file, load_credentials
+from fotoware_client.exceptions import (
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    FotoWareError,
+    NotFoundError,
+    RateLimitError,
+    RetryExhaustedError,
+)
+from fotoware_client.limits import (
+    QUERY_SIZE_BUDGET,
+    QUERY_SIZE_LIMIT,
+    QueryTooLargeError,
+    estimate_query_size,
+)
+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.0"
+
+__all__ = [
+    # Client
+    "FotoWareClient",
+    # Models
+    "Archive",
+    "Asset",
+    "SearchResult",
+    # Auth
+    "OAuthAuthenticator",
+    "OAuthToken",
+    # Exceptions
+    "FotoWareError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NotFoundError",
+    "APIError",
+    "ConfigurationError",
+    "RetryExhaustedError",
+    "QueryTooLargeError",
+    # Installation
+    "ServerSettings",
+    # Credentials
+    "credentials_file",
+    "load_credentials",
+    # Limits
+    "QUERY_SIZE_BUDGET",
+    "QUERY_SIZE_LIMIT",
+    "estimate_query_size",
+    # Retry
+    "RetryConfig",
+    "STANDARD_RETRY",
+    "NO_RETRY",
+    # Constants
+    "DEFAULT_TIMEOUT",
+]