Metadata-Version: 2.4
Name: gramps-api-client
Version: 1.1.0
Summary: A minimal, dependency-free Python client for Gramps Web API
License-Expression: GPL-2.0-or-later
License-File: LICENSE
Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# gramps-api-client

A minimal, dependency-free Python client for [Gramps Web API](https://github.com/gramps-project/gramps-web-api). Standard library only (`urllib`, `json`, `base64`) — no `requests`, no `gramps` package needed.

## Install

```bash
pip install -e .
```

(Not yet published to PyPI.)

## Credentials

The client is built from a single `GRAMPS_WEB_API_KEY`-shaped string, `<REFRESH_TOKEN>*<BASE64URL(URL)>`. Mint one once via username/password, either from the CLI:

```bash
gramps-api-client generate-key --url https://your-server/api --username youruser
# prompts for the password (getpass, never a CLI flag), prints the key to stdout
```

or in Python:

```python
from gramps_api_client import Client

api_key = Client.mint_api_key("https://your-server/api", "username", "password")
# store api_key somewhere safe (env var, secrets manager, ...) -- it is a
# long-lived, non-revocable-except-by-password-change credential, treat it
# like a password.
```

From then on, either construct directly from that key, or set it as
`GRAMPS_WEB_API_KEY` in the environment and use `Client.from_env()`:

```python
import os
from gramps_api_client import Client

os.environ["GRAMPS_WEB_API_KEY"] = api_key
client = Client.from_env()

transactions, total = client.get_transaction_history(after=0)
```

See `Client`'s and `push_transaction()`'s docstrings in
[`src/gramps_api_client/client.py`](src/gramps_api_client/client.py)
for the full credential-tradeoff writeup and conflict-handling semantics.

## Origin

This client began life inside the
[GrampsWebSync](https://github.com/gramps-project/addons-source/tree/maintenance/gramps52/GrampsWebSync)
addon and the GrampsWebApiDb addon (both `gramps-project/addons-source`;
GrampsWebApiDb is not yet merged upstream), which each needed a
dependency-free HTTP client to talk to a Gramps Web API server. This
package is now the standalone, canonical home for that code —
`GrampsWebApiDb` vendors a synced copy of `client.py`, since Gramps addons
are self-contained tarballs with no mechanism to declare a pip dependency
on an external package.

## Development

```bash
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest -v
```

## License

GPL-2.0-or-later, matching the addon code this was extracted from. See
[`LICENSE`](LICENSE).
