biblindex-client 0.2.2__tar.gz

biblindex_client-0.2.2/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.3
+Name: biblindex-client
+Version: 0.2.2
+Summary: Python client for the BiblIndex API.
+Keywords: biblindex,api,client,oauth2
+Author: Pierre Hennequart
+Author-email: Pierre Hennequart <pierre@janalis.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: requests>=2.32
+Requires-Python: >=3.9
+Project-URL: Homepage, https://www.biblindex.org/api
+Project-URL: Issues, https://github.com/janalis/biblindex-client/issues
+Project-URL: Source, https://github.com/janalis/biblindex-client
+Description-Content-Type: text/markdown
+
+# BiblIndex Python client
+
+[![Python](https://img.shields.io/badge/Python-3.12+-blue?logo=python)](https://www.python.org/)
+[![uv](https://img.shields.io/badge/uv-package%20manager-111111?logo=python)](https://docs.astral.sh/uv/)
+[![Make](https://img.shields.io/badge/Make-automation-orange?logo=gnu)](https://www.gnu.org/software/make/)
+![Cross Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20WSL-lightgrey)
+[![CI](https://github.com/janalis/biblindex-python-client/actions/workflows/ci.yml/badge.svg)](https://github.com/janalis/biblindex-client/actions/workflows/ci.yml)
+
+## Maintainers
+
+| Name              | Email              |
+| ----------------- | ------------------ |
+| Pierre Hennequart | pierre@janalis.com |
+
+## Documentation
+
+https://www.biblindex.org/api
+
+## Quick Start
+
+```bash
+make setup
+make run
+```
+
+## Installation
+
+### Clone the repository
+
+```bash
+git clone <repo-url>
+cd <repo-name>
+```
+
+### Install Python environment
+
+This project uses a version-managed Python setup.
+
+```bash
+pyenv install $(cat .python-version)
+pyenv local $(cat .python-version)
+```
+
+### Install dependencies
+
+This project uses a modern Python packaging tool:
+
+```bash
+uv sync
+```
+
+### Environment variables
+
+```bash
+cp .env .env.local
+```
+
+Edit .env.local with your configuration.
+
+## Run the project
+
+### Using Make (recommended)
+
+```bash
+make help      # List all available commands
+make run
+```
+
+### Or manually
+
+```bash
+uv run python src/example.py
+```
+
+## Available commands
+
+Run `make help` to see all available commands with descriptions:
+
+```bash
+make help
+```
+
+## Platform Support
+
+| OS      | Support | Notes               |
+|---------|---------|---------------------|
+| macOS   | ✅       | Native supported    |
+| Linux   | ✅       | Native supported    |
+| Windows | ⚠️      | Use WSL or Git Bash | 
+
+## Notes
+
+* Uses pyenv for Python version management
+* Uses uv for fast dependency resolution
+* Makefile orchestrates setup + run steps
+
+## Recommended Setup
+
+For the smoothest experience:
+
+* macOS / Linux → native terminal
+* Windows → WSL2 (recommended)
+
+## Use as a library in another project
+
+Released versions are published to [PyPI](https://pypi.org/project/biblindex-client/).
+
+### With `uv`
+
+```bash
+uv add biblindex-client
+```
+
+### With `pip`
+
+```bash
+pip install biblindex-client
+```
+
+### Installing an unreleased commit
+
+To use a version that hasn't been released to PyPI yet, install directly from the
+Git repository (optionally pinned to a tag, branch or commit):
+
+```bash
+uv add "biblindex-client @ git+https://github.com/janalis/biblindex-client.git@v0.1.0"
+```
+
+### Or in `pyproject.toml`
+
+```toml
+[project]
+dependencies = [
+    "biblindex-client @ git+https://github.com/janalis/biblindex-client.git@v0.1.0",
+]
+```
+
+### Usage
+
+```python
+from biblindex_client import BiblIndexClient
+
+client = BiblIndexClient(
+    baseUrl="https://www.biblindex.org",
+    username="...",
+    password="...",
+    clientId="...",
+    clientSecret="...",
+)
+
+quotations = client.request("/api/quotations", {"page": 1})
+```
+
+### Lazy fetching
+
+API responses are automatically wrapped in lazy proxies that defer network requests until data is actually read:
+
+- **`LazyResource`** (`MutableMapping`): resource links (e.g. `/api/extracts/42`, `{"@id": "/api/works/1"}`) embedded in responses are wrapped as lazy mappings — the linked resource is fetched only when a field is accessed.
+- **`LazyCollection`** (`MutableSequence`): paginated Hydra collections and plain JSON arrays are wrapped as lazy sequences — subsequent pages are fetched on demand when iterating or indexing beyond the current page.
+
+Hydra metadata properties (`hydra:member`, `hydra:view`, `hydra:search`, `hydra:totalItems`) are not exposed through the lazy wrappers — collections are returned directly as `LazyCollection` instances.
+
+Caching ensures the same API resource is never fetched twice within a single response tree.
+
+```python
+from biblindex_client import BiblIndexClient, LazyResource
+
+client = BiblIndexClient(...)
+collection = client.request("/api/quotations", {"page": 1})
+
+# members is a LazyCollection — pages fetched lazily
+item = collection[0]           # no network call yet
+print(item["@id"])       # triggers fetch of /api/quotations/1229419
+```
+
+#### Using `application/json` (plain JSON)
+
+> **Warning:** Prefer `application/ld+json` (the default) whenever the API supports it. The Hydra JSON-LD format provides metadata (`hydra:totalItems`, `hydra:view`) that enables accurate `len()` and proper next-page resolution via `hydra:next` links. With plain `application/json`, total item count is unavailable and pagination falls back to incrementing `?page=N`, which may yield empty pages at the end.
+
+When the API returns plain JSON arrays instead of Hydra collections, configure the `accept` media type:
+
+```python
+from biblindex_client import BiblIndexClient, LazyCollection, LazyResource
+
+client = BiblIndexClient(
+    baseUrl="https://www.biblindex.org",
+    username="...",
+    password="...",
+    clientId="...",
+    clientSecret="...",
+    accept="application/json",
+)
+
+collection = client.request("/api/quotations", {"page": 1})
+
+# The array is wrapped in a LazyCollection — pages are fetched lazily
+print(type(collection))           # <class 'LazyCollection'>
+print(collection.loadedItems)     # items loaded so far (page 1)
+
+# Accessing beyond the current page triggers ?page=N
+item = collection[2]              # fetches /api/quotations?page=2
+print(item["id"])                 # reads from the fetched item
+```
+
+Pagination uses the `?page=N` query parameter automatically — each fetch increments the page number. If the API returns an empty array the collection stops fetching further pages.
+
+## Publishing a new version
+
+```bash
+make bump-patch   # or bump-minor / bump-major
+```
+
+This bumps the version in `pyproject.toml`, commits, tags (`vX.Y.Z`), and pushes to GitHub. The [Release workflow](.github/workflows/release.yml) then builds the distribution, publishes it to **TestPyPI** and then **PyPI**, and creates a GitHub Release with auto-generated release notes.
+
+Publishing uses [PyPI trusted publishing](https://docs.pypi.org/trusted-publishers/) (OIDC) via `uv publish` — no API tokens or credentials are stored or needed locally. The TestPyPI upload acts as a smoke test that gates the real PyPI release.
+
+## Contributing
+
+This project is open to contributions.
+
+We welcome pull requests following the standard GitHub flow:
+
+1. Fork the repository
+2. Create a feature branch
+3. Commit your changes
+4. Open a pull request
+
+Please ensure your changes are well tested and follow the existing code style.
+
+## API Modifications
+
+If you need changes, extensions, or adjustments to the API, please contact the maintainers.

biblindex_client-0.2.2/README.md

@@ -0,0 +1,232 @@
+# BiblIndex Python client
+
+[![Python](https://img.shields.io/badge/Python-3.12+-blue?logo=python)](https://www.python.org/)
+[![uv](https://img.shields.io/badge/uv-package%20manager-111111?logo=python)](https://docs.astral.sh/uv/)
+[![Make](https://img.shields.io/badge/Make-automation-orange?logo=gnu)](https://www.gnu.org/software/make/)
+![Cross Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20WSL-lightgrey)
+[![CI](https://github.com/janalis/biblindex-python-client/actions/workflows/ci.yml/badge.svg)](https://github.com/janalis/biblindex-client/actions/workflows/ci.yml)
+
+## Maintainers
+
+| Name              | Email              |
+| ----------------- | ------------------ |
+| Pierre Hennequart | pierre@janalis.com |
+
+## Documentation
+
+https://www.biblindex.org/api
+
+## Quick Start
+
+```bash
+make setup
+make run
+```
+
+## Installation
+
+### Clone the repository
+
+```bash
+git clone <repo-url>
+cd <repo-name>
+```
+
+### Install Python environment
+
+This project uses a version-managed Python setup.
+
+```bash
+pyenv install $(cat .python-version)
+pyenv local $(cat .python-version)
+```
+
+### Install dependencies
+
+This project uses a modern Python packaging tool:
+
+```bash
+uv sync
+```
+
+### Environment variables
+
+```bash
+cp .env .env.local
+```
+
+Edit .env.local with your configuration.
+
+## Run the project
+
+### Using Make (recommended)
+
+```bash
+make help      # List all available commands
+make run
+```
+
+### Or manually
+
+```bash
+uv run python src/example.py
+```
+
+## Available commands
+
+Run `make help` to see all available commands with descriptions:
+
+```bash
+make help
+```
+
+## Platform Support
+
+| OS      | Support | Notes               |
+|---------|---------|---------------------|
+| macOS   | ✅       | Native supported    |
+| Linux   | ✅       | Native supported    |
+| Windows | ⚠️      | Use WSL or Git Bash | 
+
+## Notes
+
+* Uses pyenv for Python version management
+* Uses uv for fast dependency resolution
+* Makefile orchestrates setup + run steps
+
+## Recommended Setup
+
+For the smoothest experience:
+
+* macOS / Linux → native terminal
+* Windows → WSL2 (recommended)
+
+## Use as a library in another project
+
+Released versions are published to [PyPI](https://pypi.org/project/biblindex-client/).
+
+### With `uv`
+
+```bash
+uv add biblindex-client
+```
+
+### With `pip`
+
+```bash
+pip install biblindex-client
+```
+
+### Installing an unreleased commit
+
+To use a version that hasn't been released to PyPI yet, install directly from the
+Git repository (optionally pinned to a tag, branch or commit):
+
+```bash
+uv add "biblindex-client @ git+https://github.com/janalis/biblindex-client.git@v0.1.0"
+```
+
+### Or in `pyproject.toml`
+
+```toml
+[project]
+dependencies = [
+    "biblindex-client @ git+https://github.com/janalis/biblindex-client.git@v0.1.0",
+]
+```
+
+### Usage
+
+```python
+from biblindex_client import BiblIndexClient
+
+client = BiblIndexClient(
+    baseUrl="https://www.biblindex.org",
+    username="...",
+    password="...",
+    clientId="...",
+    clientSecret="...",
+)
+
+quotations = client.request("/api/quotations", {"page": 1})
+```
+
+### Lazy fetching
+
+API responses are automatically wrapped in lazy proxies that defer network requests until data is actually read:
+
+- **`LazyResource`** (`MutableMapping`): resource links (e.g. `/api/extracts/42`, `{"@id": "/api/works/1"}`) embedded in responses are wrapped as lazy mappings — the linked resource is fetched only when a field is accessed.
+- **`LazyCollection`** (`MutableSequence`): paginated Hydra collections and plain JSON arrays are wrapped as lazy sequences — subsequent pages are fetched on demand when iterating or indexing beyond the current page.
+
+Hydra metadata properties (`hydra:member`, `hydra:view`, `hydra:search`, `hydra:totalItems`) are not exposed through the lazy wrappers — collections are returned directly as `LazyCollection` instances.
+
+Caching ensures the same API resource is never fetched twice within a single response tree.
+
+```python
+from biblindex_client import BiblIndexClient, LazyResource
+
+client = BiblIndexClient(...)
+collection = client.request("/api/quotations", {"page": 1})
+
+# members is a LazyCollection — pages fetched lazily
+item = collection[0]           # no network call yet
+print(item["@id"])       # triggers fetch of /api/quotations/1229419
+```
+
+#### Using `application/json` (plain JSON)
+
+> **Warning:** Prefer `application/ld+json` (the default) whenever the API supports it. The Hydra JSON-LD format provides metadata (`hydra:totalItems`, `hydra:view`) that enables accurate `len()` and proper next-page resolution via `hydra:next` links. With plain `application/json`, total item count is unavailable and pagination falls back to incrementing `?page=N`, which may yield empty pages at the end.
+
+When the API returns plain JSON arrays instead of Hydra collections, configure the `accept` media type:
+
+```python
+from biblindex_client import BiblIndexClient, LazyCollection, LazyResource
+
+client = BiblIndexClient(
+    baseUrl="https://www.biblindex.org",
+    username="...",
+    password="...",
+    clientId="...",
+    clientSecret="...",
+    accept="application/json",
+)
+
+collection = client.request("/api/quotations", {"page": 1})
+
+# The array is wrapped in a LazyCollection — pages are fetched lazily
+print(type(collection))           # <class 'LazyCollection'>
+print(collection.loadedItems)     # items loaded so far (page 1)
+
+# Accessing beyond the current page triggers ?page=N
+item = collection[2]              # fetches /api/quotations?page=2
+print(item["id"])                 # reads from the fetched item
+```
+
+Pagination uses the `?page=N` query parameter automatically — each fetch increments the page number. If the API returns an empty array the collection stops fetching further pages.
+
+## Publishing a new version
+
+```bash
+make bump-patch   # or bump-minor / bump-major
+```
+
+This bumps the version in `pyproject.toml`, commits, tags (`vX.Y.Z`), and pushes to GitHub. The [Release workflow](.github/workflows/release.yml) then builds the distribution, publishes it to **TestPyPI** and then **PyPI**, and creates a GitHub Release with auto-generated release notes.
+
+Publishing uses [PyPI trusted publishing](https://docs.pypi.org/trusted-publishers/) (OIDC) via `uv publish` — no API tokens or credentials are stored or needed locally. The TestPyPI upload acts as a smoke test that gates the real PyPI release.
+
+## Contributing
+
+This project is open to contributions.
+
+We welcome pull requests following the standard GitHub flow:
+
+1. Fork the repository
+2. Create a feature branch
+3. Commit your changes
+4. Open a pull request
+
+Please ensure your changes are well tested and follow the existing code style.
+
+## API Modifications
+
+If you need changes, extensions, or adjustments to the API, please contact the maintainers.

biblindex_client-0.2.2/pyproject.toml

@@ -0,0 +1,147 @@
+[project]
+name = "biblindex-client"
+version = "0.2.2"
+description = "Python client for the BiblIndex API."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Pierre Hennequart", email = "pierre@janalis.com" },
+]
+keywords = ["biblindex", "api", "client", "oauth2"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "requests>=2.32",
+]
+
+[project.urls]
+Homepage = "https://www.biblindex.org/api"
+Source = "https://github.com/janalis/biblindex-client"
+Issues = "https://github.com/janalis/biblindex-client/issues"
+
+[dependency-groups]
+# Used only by the example.py runner — not shipped to library consumers.
+dev = [
+    "dotenv-flow",
+    {include-group = "test"},
+    {include-group = "lint"},
+    {include-group = "typecheck"},
+]
+test = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "responses>=0.25",
+]
+lint = [
+    "ruff>=0.6",
+]
+typecheck = [
+    "mypy>=1.10",
+    "types-requests>=2.32",
+]
+release = [
+    "bump-my-version>=0.28",
+]
+
+[build-system]
+requires = ["uv_build>=0.8,<0.9"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "biblindex_client"
+module-root = "src"
+
+# TestPyPI upload target used by the release workflow's smoke-test step
+# (`uv publish --index testpypi`). `explicit` keeps it out of dependency
+# resolution — it's only ever used as a publish destination.
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+]
+filterwarnings = [
+    "error",
+]
+
+[tool.coverage.run]
+source = ["biblindex_client"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+exclude_also = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+extend-exclude = [".venv", "dist", "build"]
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "B",    # flake8-bugbear
+    "UP",   # pyupgrade
+    "SIM",  # flake8-simplify
+]
+ignore = [
+    "E501",  # line length handled by formatter
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["B011"]
+
+[tool.mypy]
+# Lowest version current mypy supports; ruff's target-version = "py39"
+# already enforces real 3.9 compatibility on the source.
+python_version = "3.10"
+strict = true
+files = ["src/biblindex_client"]
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_unreachable = true
+
+[tool.bumpversion]
+current_version = "0.2.2"
+commit = true
+tag = true
+allow_dirty = false
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+[[tool.bumpversion.files]]
+filename = "uv.lock"
+search = '''name = "biblindex-client"
+version = "{current_version}"'''
+replace = '''name = "biblindex-client"
+version = "{new_version}"'''

biblindex_client-0.2.2/src/biblindex_client/__init__.py

@@ -0,0 +1,11 @@
+"""BiblIndex API client package.
+
+Public entrypoint:
+
+    from biblindex_client import BiblIndexClient
+"""
+
+from biblindex_client.biblindex import BiblIndexClient
+from biblindex_client.lazy import LazyCollection, LazyResource
+
+__all__ = ["BiblIndexClient", "LazyCollection", "LazyResource"]

biblindex_client-0.2.2/src/biblindex_client/biblindex.py

@@ -0,0 +1,382 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import datetime, timedelta
+from typing import Any
+from urllib.parse import parse_qsl, urlencode, urlparse
+
+import requests
+
+from biblindex_client.lazy import LazyCollection, LazyResource
+
+JSON_LD_MIME_TYPE = "application/ld+json"
+
+
+class BiblIndexClient:
+    """HTTP client for interacting with the BiblIndex API.
+
+    Handles:
+    - Authentication via OAuth2 password grant
+    - Automatic token refresh
+    - Authenticated GET requests to API resources
+
+    Attributes:
+        baseUrl: Base URL of the API.
+        username: API username.
+        password: API password.
+        clientId: OAuth client ID.
+        clientSecret: OAuth client secret.
+        accept: Media type used in the ``Accept`` header for API GET requests.
+        accessToken: Current access token, or None before first auth.
+        refreshToken: Refresh token used to renew access tokens.
+        expiresIn: Expiration time of the current access token.
+        session: Reusable HTTP session.
+    """
+
+    def __init__(
+        self,
+        baseUrl: str,
+        username: str,
+        password: str,
+        clientId: str,
+        clientSecret: str,
+        accept: str = JSON_LD_MIME_TYPE,
+    ) -> None:
+        """Initialize the API client with credentials and configuration."""
+        self.baseUrl: str = baseUrl
+        self.username: str = username
+        self.password: str = password
+        self.clientId: str = clientId
+        self.clientSecret: str = clientSecret
+        self.accept: str = accept
+
+        self.accessToken: str | None = None
+        self.refreshToken: str | None = None
+        self.expiresIn: datetime | None = None
+
+        self.session: requests.Session = requests.Session()
+
+    def request(self, resource: str, params: Mapping[str, Any]) -> Any:
+        """Perform an authenticated GET request to the API.
+
+        Automatically fetches tokens if missing, and refreshes them if
+        expired before issuing the call. API resource links found in the
+        response body are wrapped in lazy resources that are fetched on access.
+
+        Args:
+            resource: API resource path. Must start with a leading slash
+                (e.g. ``/api/quotations``); a missing leading slash is
+                normalized for convenience.
+            params: Query parameters for the request.
+
+        Returns:
+            Parsed JSON response from the API.
+
+        Raises:
+            requests.HTTPError: If the HTTP request fails.
+        """
+        resource = self._normalizeResource(resource)
+        currentResource = self._resourceWithParams(resource, params)
+        data = self._requestJson(resource, params)
+        cache = {resource: data, currentResource: data}
+
+        wrapped = self._wrapLinkedResources(
+            data,
+            currentResource=currentResource,
+            cache=cache,
+        )
+        if isinstance(data, list) and isinstance(wrapped, list):
+            return LazyCollection(
+                self,
+                wrapped,
+                currentResource=currentResource,
+                nextResource=self._nextPlainJsonPageResource(currentResource),
+                totalItems=None,
+                cache=cache,
+            )
+
+        return wrapped
+
+    def _requestJson(self, resource: str, params: Mapping[str, Any]) -> Any:
+        """Perform an authenticated GET request and return the raw JSON body."""
+        if not self.accessToken:
+            self.fetchTokens()
+
+        if self.expiresIn is not None and self.expiresIn < datetime.now():
+            self.refreshTokens()
+
+        response = self.session.request(
+            "GET",
+            f"{self.baseUrl}{resource}",
+            params=dict(params),
+            headers={
+                "Authorization": f"Bearer {self.accessToken}",
+                "Accept": self.accept,
+            },
+        )
+
+        response.raise_for_status()
+        return response.json()
+
+    def _wrapLinkedResources(
+        self,
+        data: Any,
+        *,
+        currentResource: str,
+        cache: dict[str, Any],
+    ) -> Any:
+        """Wrap API links embedded in a response body with lazy resources."""
+        if isinstance(data, list):
+            wrappedItems: list[Any] = []
+            for item in data:
+                resource = (
+                    self._linkedResource(item.get("@id"))
+                    or self._resourceFromCollectionItem(item, currentResource)
+                    if isinstance(item, dict)
+                    else self._linkedResource(item)
+                )
+                if resource is not None and resource != currentResource:
+                    seed = item if isinstance(item, Mapping) else None
+                    wrappedItems.append(self._lazyResource(resource, cache, seed))
+                    continue
+
+                wrappedItems.append(
+                    self._wrapLinkedResources(
+                        item,
+                        currentResource=currentResource,
+                        cache=cache,
+                    )
+                )
+
+            return wrappedItems
+
+        if isinstance(data, dict):
+            hydraMember = data.get("hydra:member")
+            if isinstance(hydraMember, list):
+                wrappedMembers = self._wrapLinkedResources(
+                    hydraMember,
+                    currentResource=currentResource,
+                    cache=cache,
+                )
+                return LazyCollection(
+                    self,
+                    wrappedMembers,
+                    currentResource=currentResource,
+                    nextResource=self._nextPageResource(data),
+                    totalItems=(
+                        data["hydra:totalItems"]
+                        if isinstance(data.get("hydra:totalItems"), int)
+                        else None
+                    ),
+                    cache=cache,
+                )
+
+            return self._wrapLinkedResourceProperties(
+                data,
+                currentResource=currentResource,
+                cache=cache,
+            )
+
+        resource = self._linkedResource(data)
+        if resource is None:
+            return data
+
+        if resource == currentResource:
+            return data
+
+        return self._lazyResource(resource, cache)
+
+    def _wrapLinkedResourceProperties(
+        self,
+        data: dict[str, Any],
+        *,
+        currentResource: str,
+        cache: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Wrap resource links in a mapping without replacing its metadata."""
+        wrapped: dict[str, Any] = {}
+        for key, value in data.items():
+            if key in {"@id", "@type"}:
+                wrapped[key] = value
+                continue
+
+            if key in {"hydra:member", "hydra:view", "hydra:search", "hydra:totalItems"}:
+                continue
+
+            resource = self._linkedResource(value)
+            if resource is not None:
+                if resource == currentResource:
+                    wrapped[key] = value
+                    continue
+
+                wrapped[key] = self._lazyResource(resource, cache)
+                continue
+
+            if isinstance(value, dict):
+                valueResource = self._linkedResource(value.get("@id"))
+                if valueResource is not None and valueResource != currentResource:
+                    wrapped[key] = self._lazyResource(valueResource, cache, value)
+                    continue
+
+            wrapped[key] = self._wrapLinkedResources(
+                value,
+                currentResource=currentResource,
+                cache=cache,
+            )
+
+        return wrapped
+
+    def _lazyResource(
+        self,
+        resource: str,
+        cache: dict[str, Any],
+        seed: Mapping[str, Any] | None = None,
+    ) -> Any:
+        if resource in cache:
+            return cache[resource]
+
+        lazyResource = LazyResource(self, resource, cache, seed)
+        cache[resource] = lazyResource
+        return lazyResource
+
+    def _nextPageResource(self, data: Mapping[str, Any]) -> str | None:
+        view = data.get("hydra:view")
+        if not isinstance(view, Mapping):
+            return None
+
+        return self._linkedResource(view.get("hydra:next"))
+
+    def _nextPlainJsonPageResource(self, resource: str) -> str | None:
+        parsedResource = urlparse(resource)
+        query = dict(parse_qsl(parsedResource.query, keep_blank_values=True))
+        rawPage = query.get("page")
+        if rawPage is None:
+            return None
+
+        try:
+            query["page"] = str(int(rawPage) + 1)
+        except ValueError:
+            return None
+
+        nextResource = parsedResource.path
+        nextQuery = urlencode(query)
+        if nextQuery:  # pragma: no branch
+            nextResource = f"{nextResource}?{nextQuery}"
+
+        return nextResource
+
+    def _resourceFromCollectionItem(
+        self,
+        item: Mapping[str, Any],
+        currentResource: str,
+    ) -> str | None:
+        """Infer an item resource from a collection item carrying only an id."""
+        itemId = item.get("id")
+        if itemId is None:
+            return None
+
+        collectionResource = currentResource.split("?", maxsplit=1)[0].rstrip("/")
+        if not collectionResource.startswith("/api/"):
+            return None
+
+        if collectionResource.rsplit("/", maxsplit=1)[-1] == str(itemId):
+            return None
+
+        return f"{collectionResource}/{itemId}"
+
+    def _linkedResource(self, value: Any) -> str | None:
+        """Return a normalized API resource path when ``value`` is a link."""
+        if not isinstance(value, str):
+            return None
+
+        if value.startswith("http://") or value.startswith("https://"):
+            parsedBaseUrl = urlparse(self.baseUrl)
+            parsedValue = urlparse(value)
+            if (
+                parsedValue.scheme != parsedBaseUrl.scheme
+                or parsedValue.netloc != parsedBaseUrl.netloc
+            ):
+                return None
+
+            value = parsedValue.path
+            if parsedValue.query:
+                value = f"{value}?{parsedValue.query}"
+
+        if not value.startswith(("/", "api/")):
+            return None
+
+        resource = self._normalizeResource(value)
+        if resource == "/api/token" or not resource.startswith("/api/"):
+            return None
+
+        return resource
+
+    def _normalizeResource(self, resource: str) -> str:
+        """Normalize a resource path so it can be appended to ``baseUrl``."""
+        if resource.startswith(self.baseUrl):
+            resource = resource[len(self.baseUrl) :]
+
+        if not resource.startswith("/"):
+            resource = "/" + resource
+
+        if not resource.startswith("/api"):
+            resource = "/api" + resource
+
+        return resource
+
+    def _resourceWithParams(self, resource: str, params: Mapping[str, Any]) -> str:
+        if not params:
+            return resource
+
+        query = urlencode(dict(params), doseq=True)
+        separator = "&" if "?" in resource else "?"
+
+        return f"{resource}{separator}{query}"
+
+    def fetchTokens(self) -> None:
+        """Fetch initial OAuth access and refresh tokens using password grant.
+
+        Updates :attr:`accessToken`, :attr:`refreshToken`, :attr:`expiresIn`.
+        """
+        response = self.session.post(
+            f"{self.baseUrl}/api/token",
+            data={
+                "grant_type": "password",
+                "username": self.username,
+                "password": self.password,
+                "client_id": self.clientId,
+                "client_secret": self.clientSecret,
+            },
+        )
+
+        data = response.json()
+
+        self.accessToken = data["access_token"]
+        self.refreshToken = data["refresh_token"]
+        self.expiresIn = datetime.now() + timedelta(seconds=data["expires_in"])
+
+    def refreshTokens(self) -> None:
+        """Refresh the OAuth access token using the stored refresh token.
+
+        Updates :attr:`accessToken`, :attr:`refreshToken`, :attr:`expiresIn`.
+
+        Note:
+            Renamed from ``refreshToken`` to ``refreshTokens`` so it no
+            longer collides with the ``refreshToken`` attribute set after
+            authentication.
+        """
+        response = self.session.post(
+            f"{self.baseUrl}/api/token",
+            data={
+                "grant_type": "refresh_token",
+                "refresh_token": self.refreshToken,
+                "client_id": self.clientId,
+                "client_secret": self.clientSecret,
+            },
+        )
+
+        data = response.json()
+
+        self.accessToken = data["access_token"]
+        self.refreshToken = data["refresh_token"]
+        self.expiresIn = datetime.now() + timedelta(seconds=data["expires_in"])

biblindex_client-0.2.2/src/biblindex_client/lazy.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping, MutableMapping, MutableSequence
+from typing import Any, Protocol
+
+
+class ResourceClient(Protocol):
+    """Client behavior required by lazy resources and collections."""
+
+    def _requestJson(self, resource: str, params: Mapping[str, Any]) -> Any: ...
+
+    def _wrapLinkedResources(
+        self,
+        data: Any,
+        *,
+        currentResource: str,
+        cache: dict[str, Any],
+    ) -> Any: ...
+
+    def _nextPlainJsonPageResource(self, resource: str) -> str | None: ...
+
+    def _nextPageResource(self, data: Mapping[str, Any]) -> str | None: ...
+
+
+_HYDRA_KEYS = frozenset(
+    {
+        "hydra:member",
+        "hydra:view",
+        "hydra:search",
+        "hydra:totalItems",
+    }
+)
+
+
+class LazyResource(MutableMapping[str, Any]):
+    """Mapping proxy that fetches an API resource when its data is read."""
+
+    def __init__(
+        self,
+        client: ResourceClient,
+        resource: str,
+        cache: dict[str, Any],
+        seed: Mapping[str, Any] | None = None,
+    ) -> None:
+        self._client = client
+        self._resource = resource
+        self._cache = cache
+        self._seed = dict(seed or {})
+        self._data: dict[str, Any] | None = None
+        self._loading = False
+
+    @property
+    def resource(self) -> str:
+        """Normalized API path represented by this lazy resource."""
+        return self._resource
+
+    def _load(self) -> dict[str, Any]:
+        if self._data is not None:
+            return self._data
+
+        if self._loading:
+            return self._seed
+
+        self._loading = True
+        try:
+            raw = self._client._requestJson(self._resource, {})
+            self._data = self._client._wrapLinkedResources(
+                raw,
+                currentResource=self._resource,
+                cache=self._cache,
+            )
+        finally:
+            self._loading = False
+
+        return self._data
+
+    def __getitem__(self, key: str) -> Any:
+        if key in _HYDRA_KEYS:
+            raise KeyError(key)
+
+        if self._data is None and key in {"@id", "@type", "id"} and key in self._seed:
+            return self._seed[key]
+
+        return self._load()[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        if key in _HYDRA_KEYS:
+            raise KeyError(key)
+        self._load()[key] = value
+
+    def __delitem__(self, key: str) -> None:
+        if key in _HYDRA_KEYS:
+            raise KeyError(key)
+        del self._load()[key]
+
+    def __iter__(self) -> Iterator[str]:
+        for key in self._load():
+            if key not in _HYDRA_KEYS:
+                yield key
+
+    def __len__(self) -> int:
+        data = self._load()
+        return len(data) - len(_HYDRA_KEYS & data.keys())
+
+    def __repr__(self) -> str:
+        if self._data is None:
+            return f"LazyResource({self._resource!r})"
+
+        return repr(self._data)
+
+
+class LazyCollection(MutableSequence[Any]):
+    """List-like collection that fetches following Hydra pages on demand."""
+
+    def __init__(
+        self,
+        client: ResourceClient,
+        items: list[Any],
+        *,
+        currentResource: str,
+        nextResource: str | None,
+        totalItems: int | None,
+        cache: dict[str, Any],
+    ) -> None:
+        self._client = client
+        self._items = items
+        self._currentResource = currentResource
+        self._nextResource = nextResource
+        self._totalItems = totalItems
+        self._cache = cache
+
+    @property
+    def loadedItems(self) -> int:
+        """Number of items already loaded locally."""
+        return len(self._items)
+
+    def _fetchNextPage(self) -> bool:
+        if self._nextResource is None:
+            return False
+
+        nextResource = self._nextResource
+        page = self._client._requestJson(nextResource, {})
+        if isinstance(page, list):
+            if not page:
+                self._nextResource = None
+                return False
+
+            wrappedItems = self._client._wrapLinkedResources(
+                page,
+                currentResource=nextResource,
+                cache=self._cache,
+            )
+            self._items.extend(wrappedItems)
+            self._currentResource = nextResource
+            self._nextResource = self._client._nextPlainJsonPageResource(nextResource)
+            return True
+
+        if not isinstance(page, dict):
+            self._nextResource = None
+            return False
+
+        members = page.get("hydra:member", [])
+        if isinstance(members, list):
+            wrappedMembers = self._client._wrapLinkedResources(
+                members,
+                currentResource=nextResource,
+                cache=self._cache,
+            )
+            self._items.extend(wrappedMembers)
+
+        self._currentResource = nextResource
+        self._nextResource = self._client._nextPageResource(page)
+        return True
+
+    def _fetchUntilIndex(self, index: int) -> None:
+        while index >= len(self._items) and self._fetchNextPage():
+            pass
+
+    def __getitem__(self, index: int | slice) -> Any:
+        if isinstance(index, slice):
+            stop = index.stop
+            if stop is None:
+                self._fetchAllPages()
+            elif stop > 0:
+                self._fetchUntilIndex(stop - 1)
+            return self._items[index]
+
+        if index < 0:
+            self._fetchAllPages()
+        else:
+            self._fetchUntilIndex(index)
+
+        return self._items[index]
+
+    def __setitem__(self, index: int | slice, value: Any) -> None:
+        self._items[index] = value
+
+    def __delitem__(self, index: int | slice) -> None:
+        del self._items[index]
+
+    def __len__(self) -> int:
+        return self._totalItems if self._totalItems is not None else len(self._items)
+
+    def insert(self, index: int, value: Any) -> None:
+        self._items.insert(index, value)
+
+    def __iter__(self) -> Iterator[Any]:
+        index = 0
+        while True:
+            if index < len(self._items):
+                yield self._items[index]
+                index += 1
+                continue
+
+            if not self._fetchNextPage():
+                break
+
+    def __repr__(self) -> str:
+        return f"LazyCollection(loadedItems={len(self._items)}, totalItems={self._totalItems!r})"
+
+    def _fetchAllPages(self) -> None:
+        while self._fetchNextPage():
+            pass