feat: BatBase MetadataSource adapter for cellpy (#2)

[jepegit]

Closes #2 — Epic M / M2 (stage 4 of jepegit/cellpy#783). Depends on #1 (merged) and jepegit/cellpy#1106 (merged). Non-yolo: mapping decisions against an unsettled API, so this is the review point and is not auto-merged.

What

• cellpy_connectors/batbase_source.py
  • BatBaseMetadataSource (name = "batbase", fetch(MetaQuery) -> tuple[MetaRecord, ...]) over BatBaseClient; no credentials or token logic here. Client built lazily on first use so the registry can instantiate it without credentials present.
  • Query kinds: cell_name (default — journal label, else name, else device_name, matched client-side over a per-instance cached listing, 300 s), tag (project ⇒ server-side cellpy_tag__name+cellpy_tag__project; numeric key = tag id; unscoped name resolved via test-cellpy-tag across visible projects), external_id (one row; 404 ⇒ ()), test_name. Unknown kinds ⇒ ().
  • journal_row_to_meta(row) — pure, cellpy-free field/unit/vocabulary map: mass, total_mass→tot_mass, area→active_electrode_area, loading→active_electrode_loading, nominal_capacity_value+unit→nom_cap in mAh/g | mAh/cm² | mAh + nom_cap_specifics, cell_type hc/fc/3e/sym → half_cell/…, test_mode → cycle_mode (anode / cathode / full), label→cell_name, comments, test_schedule. Never emits None; never fills provenance (instrument stays in raw).
  • ConnectorAuthError → MetadataSourceAuthError (cellpy never swallows it); other ConnectorError → MetadataSourceError (cellpy's fetch_meta degrades to an empty layer).
• pyproject.toml: [project.entry-points."cellpy.metadata_sources"] batbase = ….
• cellpy remains not a runtime dependency (lazy imports inside fetch).

BatBase API gap

/api/test-cellpy-journal/ serializes model fields only; the journal-table annotations (mass, total_mass, area, loading, nom_cap, cell_type) and name filters are not on the API. Filed as ife-bat/batbase#473. The mapping already reads those keys, so records carry label / nominal capacity / test mode / schedule / comments today and gain mass etc. when #473 ships — no adapter change needed.

Tests

• tests/test_batbase_source.py: 29 tests — mapping/units/vocabulary (cellpy-free), lazy client, cache, and cellpy-dependent Protocol / entry-point / check_metadata_source conformance / error translation / end-to-end CellpyCell.fetch_meta("batbase") applying mass (skip without cellpy #784).
• uv run pytest with sibling cellpy installed: 78 passed.
• Live smoke through the real entry point against the local dev server (empty DB): ms.names() == ('batbase',), all query kinds return () cleanly, 404 path clean.

Docs

README "As a cellpy metadata source", this-project.md, .issueflows/04-designs-and-guides/batbase-metadata-source.md, test registry.

Made with Cursor