gramps-api-client

A minimal, dependency-free Python client for Gramps Web API. Standard library only (urllib, json, base64) — no requests, no gramps package needed.

Install

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:

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:

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():

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 for the full credential-tradeoff writeup and conflict-handling semantics.

Origin

This client began life inside the 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

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.