Metadata-Version: 2.4
Name: dwzclient
Version: 0.1.4
Summary: Async client for the DSB DWZ liste REST API (minimal)
Author-email: Uli Baumann <dwz@uli-baumann.de>
License: MIT
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.8
Dynamic: license-file

[![PyPI Version](https://img.shields.io/pypi/v/dwzclient?style=flat-square)](https://pypi.org/project/dwzclient/)

# dwzclient

Minimal async client for the DSB DWZListe REST API. Focused on a small, well-typed surface to fetch player data and map it to dataclasses (`Person`, `Membership`).

Key features
- Async `DWZClient.get_person(nuliga_id)` — fetch a single person by nuLiga id.
- Async `DWZClient.search_persons(...)` — search for persons using the DWZListe REST search endpoint (supports firstname, lastname, nuLigaPersonId, vkz, paging and arbitrary query filters).

Quick install
------------

Install from PyPI:

```bash
pip install dwzclient
```

Development install (recommended)

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
pip install -r requirements-dev.txt  # optional: pytest, flake8
```

Quickstart
----------

Fetch a person by nuLiga id:

```py
import aiohttp
from dwzclient import DWZClient

async def main():
    async with aiohttp.ClientSession() as session:
        client = DWZClient(session)
        person = await client.get_person("NU4168433")
        print(person)

```

Search for persons (example)
----------------------------

`search_persons` sends query parameters to the DWZListe REST endpoint and expects the official paging wrapper with results under the `data` key. It returns a list of `Person` dataclasses.

Usage example:

```py
import aiohttp
from dwzclient import DWZClient

async def main():
    async with aiohttp.ClientSession() as session:
        client = DWZClient(session)
        results = await client.search_persons(firstname="Max", lastname="Mustermann")
        for p in results:
            print(f"{p.firstname} {p.lastname} ({p.nuLigaPersonId}) - rating={p.rating}")

```

Parameters (summary)
- `firstname`, `lastname`, `nuLigaPersonId`, `vkz` (optional filters)
- `page`, `size` (paging)
- `**filters` — forwarded as additional query parameters to the API

Notes
- The client strictly follows the DWZListe REST API format: the search response must contain a paging wrapper with `data` (list of person objects).
- `memberships` in the API are mapped to the `Membership` dataclass; missing fields are handled gracefully.

Running tests
-------------

Run the local test-suite (no install required):

```bash
PYTHONPATH=. pytest -qv
```

Alternatively, after editable install:

```bash
pytest -qv
```

Linting
-------

```bash
PYTHONPATH=. flake8 dwzclient tests
```

Changelog & release
-------------------

Version is now `0.1.4` (search API docs + vkz/search improvements). If you want, I can add a `CHANGELOG.md` entry and create a git tag.

Contributing
------------
See `CONTRIBUTING.md` for development, testing and release guidance.

License
-------
MIT
