Metadata-Version: 2.4
Name: ediarum-sdk
Version: 0.2.1
Summary: Shared platform integration pieces for ediarum backend services.
Author: Malte Vogl
Author-email: Malte Vogl <malte.vogl@bbaw.de>
License-Expression: MIT
License-File: LICENSE
Requires-Dist: fastapi>=0.142.1
Requires-Dist: httpx2>=2.13.1
Requires-Dist: sqlmodel>=0.0.47
Requires-Dist: watchdog>=6.0.0
Requires-Python: >=3.13
Project-URL: Repository, https://www.ediarum.org/
Description-Content-Type: text/markdown

# ediarum.sdk

Shared Python package for ediarum backend services (`ediarum.register`,
`ediarum.id`, `ediarum.fileservice`). It provides platform authentication,
a debounced file watcher and a client for the platform's project registry.

Requires Python 3.13 or later.

## Modules

| Module | Contents |
|---|---|
| `ediarum_sdk.auth` | Caller identification for FastAPI apps: platform auth-verify client (`platform_user`, `PlatformCallerDep`, `ProjectCallerDep`, `PlatformAdminDep`) and hashed API keys (`ApiKey`, `make_api_key_dependency`). Both produce a `Caller`. |
| `ediarum_sdk.watch` | `Watcher`: debounced, per-project filesystem watcher that calls `on_due(project, paths)` once a project has been quiet for `quiet_seconds`. |
| `ediarum_sdk.projects` | `ProjectsClient`: thread-safe, caching client for the platform's project list (`ProjectInfo`). Serves the last cached list if the platform is unreachable. |

## Configuration

| Variable | Used by | Purpose |
|---|---|---|
| `AUTH_VERIFY_URL` | `auth.AuthConfig.from_env()` | Platform auth-verify endpoint |
| `AUTH_DEV_USER` | `auth.AuthConfig.from_env()` | Treat every request as this admin user. Development only; mutually exclusive with `AUTH_VERIFY_URL` |
| `PLATFORM_PROJECTS_URL` | `projects.ProjectsClient` | Platform project registry, `…/api/auth/service/projects` (can also be passed as `url=`) |
| `PLATFORM_SERVICE_TOKEN` | `projects.ProjectsClient` | Service token for the registry, sent as `Authorization: Bearer` (can also be passed as `token=`) |

## Usage

```python
from pathlib import Path
from ediarum_sdk.watch import Watcher

def handle_changes(project: str, paths: set[str]) -> None:
    ...

Watcher({"demo": Path("/data/xml/demo")}, on_due=handle_changes).run_forever()
```

```python
import httpx2 as httpx
from ediarum_sdk.projects import ProjectsClient

projects = ProjectsClient(httpx.Client())
info = projects.get("demo")
```

## Notes

- The watcher is a supplementary trigger. File-change events can be lost;
  services should also run a periodic content-hash scan.
- The registry answers with `slug`, `name`, `repo_url`, `branch` and
  `index_source_of_truth`. `ProjectInfo` maps them to `label` and
  `source_of_truth`; `sparse_path` is `""` (whole repository) unless a row
  sets it.

## Installation

```
uv add ediarum-sdk
```

For development against unreleased changes, use a path dependency in
`[tool.uv.sources]`.

## Development

```
uv sync
uv run pytest
```

## Release

Set `version` in `pyproject.toml`, commit, then tag and push:

```
git tag v0.2.0
git push --tags
```

GitLab CI runs the tests and publishes the tagged version to PyPI.

## License

MIT, see [LICENSE](LICENSE).
