Add GrampsWebApiDb: use a Gramps Web API server as a live database backend

[dsblank]

Summary

GrampsWebApiDb is a DATABASE-type addon that lets Gramps (desktop or
scripted) open a gramps-web-api server (e.g. a gramps-connect or Gramps
Web instance) as a regular family tree — read and write, no
export/import step, no separate sync tool to run by hand.

It's not fast (every write is a network round trip), but it means the
same tree hosted online is simultaneously usable from Gramps desktop and
from the web app, live.

How it works

Rather than implementing DbReadBase/DbWriteBase from scratch (~175
methods), WebApiDB subclasses the stock SQLite DBAPI backend.
DbGeneric already implements every get_*/iter_*/commit_*/
remove_* method generically on top of a small SQL connection, so this
addon only needs to supply two things:

• A local SQLite mirror for fast reads, kept in sync via
  GET /transactions/history/?after=<high-water-mark> — the same
  per-object transaction log the server's own undo system uses. The
  high-water-mark is persisted in the mirror's own metadata table
  (_get_metadata/_set_metadata), so reopening an existing tree is
  incremental, not a full re-download.
• Write-through, hooked at transaction_commit() (the single point
  DbTxn.__exit__ calls after any completed local transaction) rather
  than each individual commit_person/commit_family/etc. Local edits
  push to POST /transactions/ automatically.

webapi_client.py is a small, self-contained HTTP client (stdlib
urllib only, no extra dependency) — trimmed from and crediting the
WebApiHandler class in the GrampsWebSync addon (same repo). It's now
a hand-synced vendored copy of a standalone gramps-api-client
package (not yet published; same code, class renamed Client) — the
addon keeps its own copy since Gramps addons can't declare a pip
dependency. That standalone package also ships a
gramps-api-client generate-key CLI as an alternative to the
mint_api_key() script-based flow described below.

Credentials

A single environment variable, GRAMPS_WEB_API_KEY, shaped
"<REFRESH_TOKEN>*<BASE64URL(URL)>". This is deliberately not a login
dialog: requires_login() returns False, and the same env var also
works as a bare SDK credential (WebApiHandler.from_env()) for scripts
that talk to the server directly, without Gramps involved at all — one
credential, two consumers.

The TOKEN half is a non-expiring JWT refresh token
(gramps-web-api's JWT_REFRESH_TOKEN_EXPIRES is False by default),
obtained once via WebApiHandler.mint_api_key(url, username, password)
(or the gramps-api-client generate-key CLI mentioned above). This
is a known, deliberate stopgap, not a real personal-access-token:
gramps-web-api has scoped, revocable token infrastructure already
(AccessToken, hashed, per-scope) but it's currently hardcoded to a
single scope (anniversaries_ics) and not wired into general request
auth. Until that's generalized server-side, this key is exactly as
powerful as the account it was minted from, and — unlike a real
personal-access-token — isn't individually revocable (a password change
doesn't invalidate it). This tradeoff and the reasoning are documented
in webapi_client.py's module docstring.

Usage

1. Mint a GRAMPS_WEB_API_KEY -- it bakes in the host, and logs in as a
   particular user/database on that server. Via the CLI, for example:

$ gramps-api-client generate-key --url "http://localhost:5003/api" --user "gramps"
Password:...
<the key>

2. export GRAMPS_WEB_API_KEY="<the key>"
3. Add the addon in Gramps
4. Start Gramps; in Preferences, change the database backend to "Gramps
   Web API Database".

5. Create a new family tree. The type just reflects what the GRAMPS_WEB_API_KEY points to at that time.

Gramps opens the tree already populated with the server's data (the
initial sync), and from there it behaves like any other family tree:
edit, delete, undo, and redo all work, with every change pushed back to
the server live.

Status

• ✅ Read sync (_sync_from_server), incremental, verified against a
  live server
• ✅ Write-through (transaction_commit hook), verified add/update/delete
  round-trip against a live server, confirmed via an independent fresh
  mirror that pushes actually reach the server
• ✅ Verified live in Gramps desktop itself (not just scripts): backend
  selectable in the New Family Tree dialog, syncs and edits correctly
• ✅ Push conflict detection — pushes no longer go out with force=1;
  the server's optimistic-concurrency check (comparing each item's
  pre-edit snapshot against its current data) now actually runs, and a
  rejection raises WebApiPushConflict, which transaction_commit()
  catches to resync the local mirror from the server instead of
  silently overwriting. Real conflict resolution (merge, prompt the
  user) is still out of scope — the losing local edit is simply lost
  from the server's perspective.
• ✅ Undo/redo integration — undo()/redo() are overridden to push to
  the server too, not just the local mirror: undo sends the original
  transaction's payload to POST /transactions/?undo=1 (the server
  reverses it itself), redo just re-pushes it forward, same as an
  ordinary commit. Both go through the same conflict-detection/resync
  path as a plain commit. Verified end-to-end against a live server
  (add a person, undo, confirm via a fresh mirror sync that the server
  no longer has it, redo, confirm it's back). Gramps' own undo history
  is in-memory/per-session, not persisted, so this only matters within
  a single running session.
• ❌ No media file sync

Registered status=UNSTABLE to reflect the remaining gaps. Targets
gramps_target_version="6.0".

Testing

• Automated: python3 -m unittest GrampsWebApiDb.tests.test_webapi_client GrampsWebApiDb.tests.test_grampswebapidb -v — 67 tests, covering
  webapi_client.py's auth/retry/rate-limit/conflict logic and
  grampswebapidb.py's sync/apply-change/transaction-commit/undo-redo
  logic, with urlopen and the SQLite base class mocked (no live server
  needed).
• Manual, end-to-end against a real gramps-web-api server: read sync,
  write-through, incremental re-sync, push-conflict detection + resync,
  undo/redo (round-tripped through independent fresh mirrors to confirm
  the server's state, not just the local one), and live use from Gramps
  desktop (New Family Tree dialog, backend selectable, syncs and edits
  correctly). Also verified make_database("grampswebapidb") loads the
  addon through Gramps's real plugin manager, not just via direct
  import.