cellpycore 0.1.3__tar.gz → 0.1.4__tar.gz

cellpycore-0.1.4/.issueflows/02-partly-solved-issues/issue91_original.md

@@ -0,0 +1,27 @@
+# Issue #91: Release v0.1.4: docs (#90) and cellpy re-pin
+
+Source: https://github.com/cellpy/cellpy-core/issues/91
+
+## Original issue text
+
+## Context
+
+`v0.1.3` (2026-07-04) already ships the merge/update API from #86/#87. One commit on `main` since that tag:
+
+- #90 — Zensical docs migration, Read the Docs config, example notebooks
+
+`cellpy` still pins `cellpycore==0.1.2` in `[project.dependencies]` — needs re-pin after this release.
+
+## Tasks
+
+- [ ] Confirm `main` is green (ruff + pytest)
+- [ ] Update changelog / release notes for 0.1.4 (docs + any misc since 0.1.3)
+- [ ] Bump version (`uv version --bump patch` → 0.1.4) and commit
+- [ ] Cut GitHub release (`release patch` or equivalent) from up-to-date `main`
+- [ ] Verify `release.yml` passes and `cellpycore 0.1.4` appears on PyPI
+- [ ] cellpy: bump `cellpycore` pin in `pyproject.toml`, refresh `uv.lock`, run seam tests (`tests/test_slim.py`)
+
+## References
+
+- `.issueflows/04-designs-and-guides/release-procedure.md`
+- Issue #44 (release pipeline — done)

cellpycore-0.1.4/.issueflows/02-partly-solved-issues/issue91_plan.md

@@ -0,0 +1,166 @@
+# Issue #91 plan — Release v0.1.4 + retroactive HISTORY backfill
+
+## Goal
+
+Correct `HISTORY.md` so shipped work is attributed to the right versions (everything
+currently under `[Unreleased]` → **`[0.1.3]`**, dated 2026-07-04), add **`[0.1.4]`**
+with **only** the Zensical / Read the Docs documentation work (#90), then cut the
+`v0.1.4` release and re-pin `cellpy` off the stale `cellpycore==0.1.2` pin.
+
+## Constraints
+
+- **Version attribution (user):** Only the Zensical documentation migration belongs in
+  `0.1.4`. No code/API bullets in the 0.1.4 section.
+- **No PyPI re-release of 0.1.3** — backfill is changelog-only; `v0.1.3` on PyPI is
+  already correct for code content.
+- **Single source of truth:** Root [`HISTORY.md`](../../HISTORY.md) is included into the
+  docs site via [`docs/changelog.md`](../../docs/changelog.md) (`--8<--` snippet); edit
+  `HISTORY.md` only.
+- **Release ritual:** Follow
+  [`.issueflows/04-designs-and-guides/release-procedure.md`](../04-designs-and-guides/release-procedure.md)
+  — bump committed on branch, tag from clean `main` after merge (or user runs `release`
+  alias post-merge).
+- **cellpy boundary:** Re-pin lives in `jepegit/cellpy` (separate branch/PR); keep
+  editable `[tool.uv.sources]` path override unchanged per migration guide.
+
+### Prior art
+
+- [`release-procedure.md`](../04-designs-and-guides/release-procedure.md) — bump, `release`
+  alias, `release.yml`, cellpy re-pin checklist.
+- [`zensical-docs.md`](../04-designs-and-guides/zensical-docs.md) — what #90 landed
+  (structure, RTD build, notebook → markdown pipeline).
+- [`iflow-history-update`](../../.cursor/skills/iflow-history-update/SKILL.md) — Keep a
+  Changelog promote pattern (`[Unreleased]` → `[x.y.z] - date` + fresh empty
+  `[Unreleased]`).
+- Issue #56 close — prior patch release that promoted `[Unreleased]` to `[0.1.2]` at
+  `/iflow-close` time.
+- **Toolbox:** none (`00-tools/` index empty).
+- **Grep:** no release/changelog helper scripts; `.aliases` `release()` reads version from
+  `pyproject.toml` and calls `gh release create`.
+
+## Approach
+
+### 1. Retroactive `[0.1.3]` section (changelog debt)
+
+Move the **entire** current `[Unreleased]` bullet list into a new section:
+
+```markdown
+## [0.1.3] - 2026-07-04
+```
+
+(Use the actual `v0.1.3` tag date — 2026-07-04.)
+
+**Add missing bullets** that shipped between `v0.1.2` and `v0.1.3` but were never
+written to `HISTORY.md`:
+
+| Change | Ref | Notes |
+|--------|-----|-------|
+| Merge/update e2e coverage | #89 | Golden-style tests for `merge_data` / `update_data` pipeline |
+| README doc links use absolute GitHub URLs (PyPI-safe) | #62 / #63 | Small docs fix in the same release window |
+
+**Do not add** #88 (Cursor Cloud `AGENTS.md` blurb) — agent/dev doc, not a user-facing
+release note unless you explicitly want it.
+
+**Optional tidy while editing:** align issue refs where HISTORY already mentions work
+(e.g. pre-commit is #84 issue / #85 PR — keep `#84` or note both; merge is #86 issue /
+#87 PR — current `#86` is fine).
+
+Leave a fresh empty:
+
+```markdown
+## [Unreleased]
+
+```
+
+above `[0.1.4]` (added in step 2).
+
+### 2. `[0.1.4]` section (this release)
+
+Under `[Unreleased]`, add **one** consolidated bullet for #90 (paraphrase from
+[`zensical-docs.md`](../04-designs-and-guides/zensical-docs.md)):
+
+- Migrate documentation to **Zensical** with **Read the Docs** hosting
+  (`.readthedocs.yaml`, `zensical.toml`, `docs` group in `pyproject.toml`).
+- Restructure docs tree (`getting-started`, `user-guide/`, `specifications/`,
+  `examples/`, `development/`); `changelog.md` and `development/roadmap.md` snippet-include
+  root `HISTORY.md` / `ROADMAP.md`.
+- Add executable example notebooks (committed markdown + plot outputs under
+  `docs/examples/`). (#90)
+
+Then **promote** for release (during `/iflow-close` with bump):
+
+```markdown
+## [0.1.4] - <release-date>
+```
+
+(empty `[Unreleased]` above it again).
+
+### 3. Version bump + release (cellpy-core)
+
+On branch `91-release-v0-1-4`:
+
+1. Preflight: `uv run ruff check`, `uv run pytest` (matches `release.yml`).
+2. Commit HISTORY backfill + `[0.1.4]` unreleased bullet (can be one commit or two —
+   prefer **one PR** with clear commit message).
+3. `/iflow-close bump patch` → `0.1.4`, promote `[Unreleased]` → `[0.1.4]`, open PR.
+4. After merge to `main`: user runs `release` (or `release patch` if version not yet
+   committed — follow alias guards) → verify `release.yml` green → confirm
+   `cellpycore 0.1.4` on PyPI.
+
+Current state: `pyproject.toml` is `0.1.3`; `v0.1.3` tag exists; one commit since tag
+(`b5f088a` #90 docs only) — aligns with 0.1.4 scope.
+
+### 4. cellpy re-pin (follow-up in sibling repo)
+
+On a `cellpy` branch (e.g. `core91-pin-cellpycore-0-1-4`):
+
+- `[project.dependencies]`: `cellpycore==0.1.2` → `cellpycore==0.1.4` (or `>=0.1.4` if
+  you prefer minimum pin — match #400 style: exact `==` before cellpy release).
+- `uv lock` / `uv sync` in `cellpy`.
+- `uv run pytest tests/test_slim.py` (and optionally parity tests).
+- Open PR on `jepegit/cellpy`; reference cellpy-core #91.
+
+Can land same day as core release but is a **separate PR** (different repo).
+
+## Files to touch
+
+| Path | Change |
+|------|--------|
+| [`HISTORY.md`](../../HISTORY.md) | Promote `[Unreleased]` → `[0.1.3]`; add missing #89/#63 bullets; add #90 under unreleased then promote to `[0.1.4]` at close |
+| [`pyproject.toml`](../../pyproject.toml) | `0.1.3` → `0.1.4` at `/iflow-close bump patch` |
+| [`uv.lock`](../../uv.lock) | Refresh if bump touches lock (usually unchanged for patch) |
+| `.issueflows/01-current-issues/issue91_status.md` | Progress + done checkbox at close |
+| `cellpy/pyproject.toml` + `cellpy/uv.lock` | Re-pin (separate repo, separate PR) |
+
+**No code changes** under `src/cellpycore/` for this issue.
+
+## Test strategy
+
+**cellpy-core (before PR):**
+
+```bash
+uv run ruff check src/ tests/
+uv run ruff format --check
+uv run pytest
+```
+
+Release CI repeats the same. No new tests — changelog/release only.
+
+**cellpy (re-pin PR):**
+
+```bash
+cd ../cellpy && uv lock && uv run pytest tests/test_slim.py
+```
+
+## Open questions
+
+1. **cellpy pin style:** exact `cellpycore==0.1.4` vs `>=0.1.4`? Recommend `==0.1.4`
+   to mirror #400 until the next cellpy release.
+2. **Include #88 in 0.1.3 HISTORY?** Plan default: **no** (skip).
+3. **Split PRs?** Recommend single cellpy-core PR (HISTORY backfill + 0.1.4 notes +
+   bump); cellpy re-pin as sibling PR after PyPI publish.
+
+---
+
+**Ready for `/iflow-start` after you Accept.** Revise/Abort if you want different pin
+style or to include #88.

cellpycore-0.1.4/.issueflows/02-partly-solved-issues/issue91_status.md

@@ -0,0 +1,16 @@
+# Issue #91 status
+
+- [ ] Done
+
+## What's done
+
+- Plan confirmed: `cellpycore==0.1.4` pin style; skip #88 in HISTORY.
+- Retroactive `[0.1.3]` section in `HISTORY.md` (moved unreleased bullets + #89, #63).
+- `[0.1.4]` promoted in `HISTORY.md`; `pyproject.toml` bumped to 0.1.4.
+- Preflight green: ruff + 150 pytest passed.
+- PR opened for cellpy-core changelog + version bump.
+
+## Remaining work
+
+- Merge PR, run `release` alias on `main`, verify PyPI `cellpycore 0.1.4`.
+- cellpy: separate PR — `cellpycore==0.1.4`, `uv lock`, `tests/test_slim.py`.

cellpycore-0.1.4/.issueflows/04-designs-and-guides/zensical-docs.md

@@ -0,0 +1,39 @@
+# Documentation stack: Zensical on Read the Docs
+
+**Context.** The repo's loose markdown docs were restructured into a proper
+site. `development.md` once said "we intend to implement sphinx"; that
+intention is superseded by this decision.
+
+**Decision.** Docs are built with [Zensical](https://zensical.org) (the
+Material-for-MkDocs successor) and hosted on Read the Docs.
+
+- Config: `zensical.toml` at the repo root (nav, theme, markdown extensions).
+- Hosting: `.readthedocs.yaml` uses `build.jobs` (`pip install zensical` →
+  `zensical build --clean` → copy `site/` to `$READTHEDOCS_OUTPUT/html/`).
+  The RTD build needs **only** zensical — no project deps.
+- Local preview: `uv run --group docs zensical serve`.
+- Structure: `docs/{index,getting-started,changelog}.md`, `user-guide/`,
+  `examples/`, `specifications/` (was `data_format_specifications/`),
+  `development/`. `changelog.md` and `development/roadmap.md` are thin
+  `--8<--` snippet includes of root `HISTORY.md` / `ROADMAP.md` (single
+  source of truth stays at the root; `pymdownx.snippets` has
+  `base_path = ["."]`).
+
+**Notebooks.** Zensical does not render `.ipynb` (it copies them verbatim).
+Example notebooks under `docs/examples/` are therefore executed and converted
+to committed markdown pages (plus `*_files/` plot PNGs) with nbconvert:
+
+```bash
+uv run --group docs jupyter nbconvert --to notebook --execute --inplace docs/examples/*.ipynb
+uv run --group docs jupyter nbconvert --to markdown docs/examples/*.ipynb
+```
+
+Re-run and commit the outputs whenever a notebook changes. The `.ipynb` files
+stay in the nav-adjacent docs tree as downloadable sources. Ruff lints and
+formats notebooks too (`ruff format docs/examples/*.ipynb`).
+
+**Alternatives considered.** Sphinx (heavier, reST-leaning, docs were already
+markdown); MkDocs + mkdocs-jupyter (Zensical does not support MkDocs plugins,
+and the team wanted Zensical); converting notebooks at RTD build time (adds
+jupyter+project deps to the RTD build for little gain — committed rendered
+pages keep the RTD build trivially `pip install zensical`).

cellpycore-0.1.4/.readthedocs.yaml

@@ -0,0 +1,17 @@
+# Read the Docs configuration for the Zensical-built documentation.
+# Reference: https://docs.readthedocs.com/platform/stable/intro/zensical.html
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  jobs:
+    install:
+      - pip install zensical
+    build:
+      html:
+        - zensical build --clean
+    post_build:
+      - mkdir -p $READTHEDOCS_OUTPUT/html/
+      - cp --recursive site/* $READTHEDOCS_OUTPUT/html/

{cellpycore-0.1.3 → cellpycore-0.1.4}/HISTORY.md

@@ -4,12 +4,26 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.1.4] - 2026-07-04
+
+- Migrate documentation to Zensical with Read the Docs hosting
+  (`.readthedocs.yaml`, `zensical.toml`, optional `docs` dependency group).
+  Restructure the docs tree (`getting-started`, `user-guide/`, `specifications/`,
+  `examples/`, `development/`); `changelog.md` and `development/roadmap.md`
+  snippet-include root `HISTORY.md` and `ROADMAP.md`. Add executable example
+  notebooks with committed markdown and plot outputs under `docs/examples/`. (#90)
+- Backfill `HISTORY.md` for the 0.1.3 release and bump to 0.1.4. (#91)
+
+## [0.1.3] - 2026-07-04
+
 - Add in-repo pre-commit hooks (`ruff check --fix`, `ruff format`) via
   `.pre-commit-config.yaml` and document one-time `uv run pre-commit install`
   setup. (#84)
 - Add `merge_data` and `update_data` for combining processed `Data` objects and
   incrementally appending new raw rows (with `CellpyCellCore` wrappers and tests).
   (#86)
+- Add merge/update end-to-end test coverage for the public merge and incremental
+  update pipeline. (#89)
 - Move `CellpyError` / `NoDataFound` from `legacy/` to top-level
   `cellpycore.exceptions` (legacy re-export kept); expand the `CellpyCellCore`
   class docstring; add `ROADMAP.md` for planned features and open design
@@ -44,6 +58,8 @@ All notable changes to this project will be documented in this file.
   API, and an opt-in pytest-benchmark suite (`uv run pytest -m benchmark`).
 - Update the README developer section to uv's project workflow: `uv sync` after
   cloning, `uv add` for new dependencies, `uv run pytest` for tests (#64).
+- Use absolute GitHub URLs for README documentation links so they resolve on PyPI.
+  (#62)
 
 ## [0.1.2] - 2026-07-02
 

{cellpycore-0.1.3 → cellpycore-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cellpycore
-Version: 0.1.3
+Version: 0.1.4
 Summary: Core engine for cellpy: fast, thread-safe step and cycle summarization of battery-cycling raw data
 License-Expression: MIT
 License-File: LICENSE
@@ -49,11 +49,20 @@ Source: <https://github.com/cellpy/cellpy-core>
 
 ## Documentation
 
-- [Using cellpy-core standalone (slim-consumer guide)](https://github.com/cellpy/cellpy-core/blob/main/docs/standalone-use.md) —
+Full documentation (built with [Zensical](https://zensical.org), hosted on
+Read the Docs): <https://cellpy-core.readthedocs.io/>
+
+Key pages:
+
+- [Using cellpy-core standalone (slim-consumer guide)](https://github.com/cellpy/cellpy-core/blob/main/docs/user-guide/standalone-use.md) —
   get step tables and per-cycle summaries from a native-schema polars frame
   without full cellpy.
-- [Harmonized raw format specification](https://github.com/cellpy/cellpy-core/blob/main/docs/data_format_specifications/harmonized_raw.md)
-- [The Data object](https://github.com/cellpy/cellpy-core/blob/main/docs/data-object-definition.md)
+- [Harmonized raw format specification](https://github.com/cellpy/cellpy-core/blob/main/docs/specifications/harmonized-raw.md)
+- [The Data object](https://github.com/cellpy/cellpy-core/blob/main/docs/user-guide/data-object.md)
+- [Example notebooks](https://github.com/cellpy/cellpy-core/tree/main/docs/examples)
+
+Build the docs locally with `uv run --group docs zensical serve` (config in
+`zensical.toml`; notebook-regeneration instructions in `docs/examples/index.md`).
 
 ## Developing
 

{cellpycore-0.1.3 → cellpycore-0.1.4}/README.md

@@ -29,11 +29,20 @@ Source: <https://github.com/cellpy/cellpy-core>
 
 ## Documentation
 
-- [Using cellpy-core standalone (slim-consumer guide)](https://github.com/cellpy/cellpy-core/blob/main/docs/standalone-use.md) —
+Full documentation (built with [Zensical](https://zensical.org), hosted on
+Read the Docs): <https://cellpy-core.readthedocs.io/>
+
+Key pages:
+
+- [Using cellpy-core standalone (slim-consumer guide)](https://github.com/cellpy/cellpy-core/blob/main/docs/user-guide/standalone-use.md) —
   get step tables and per-cycle summaries from a native-schema polars frame
   without full cellpy.
-- [Harmonized raw format specification](https://github.com/cellpy/cellpy-core/blob/main/docs/data_format_specifications/harmonized_raw.md)
-- [The Data object](https://github.com/cellpy/cellpy-core/blob/main/docs/data-object-definition.md)
+- [Harmonized raw format specification](https://github.com/cellpy/cellpy-core/blob/main/docs/specifications/harmonized-raw.md)
+- [The Data object](https://github.com/cellpy/cellpy-core/blob/main/docs/user-guide/data-object.md)
+- [Example notebooks](https://github.com/cellpy/cellpy-core/tree/main/docs/examples)
+
+Build the docs locally with `uv run --group docs zensical serve` (config in
+`zensical.toml`; notebook-regeneration instructions in `docs/examples/index.md`).
 
 ## Developing
 

{cellpycore-0.1.3 → cellpycore-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cellpycore"
-version = "0.1.3"
+version = "0.1.4"
 license = "MIT"
 license-files = ["LICEN[CS]E*"]
 description = "Core engine for cellpy: fast, thread-safe step and cycle summarization of battery-cycling raw data"
@@ -69,6 +69,12 @@ dev = [
     "pytest-cov>=7.1.0",
     "pre-commit>=4.6.0",
 ]
+docs = [
+    "ipykernel>=7.3.0",
+    "matplotlib>=3.10.6",
+    "nbconvert>=7.17.1",
+    "zensical>=0.0.46",
+]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{cellpycore-0.1.3 → cellpycore-0.1.4}/src/cellpycore/config.py

@@ -82,7 +82,7 @@ class ResetGranularity(StrEnum):
 
     Describes where a cycler's cumulative capacity / energy counter resets to
     zero. The harmonized raw format mandates ``CYCLE`` (see
-    ``docs/data_format_specifications/harmonized_raw.md`` §Capacity convention);
+    ``docs/specifications/harmonized-raw.md`` §Capacity convention);
     :func:`cellpycore.summarizers.normalize_capacity_granularity` uses this enum
     to normalize ``STEP`` / ``TEST`` cumulative raw from other cyclers to the
     mandated ``CYCLE`` convention before aggregation.
@@ -177,7 +177,7 @@ class StepMode(StrEnum):
     Note:
         Absence / "no specific mode" is represented by a null value in the
         table, not by the literal string ``"None"``. The spec table in
-        ``docs/data_format_specifications/harmonized_raw.md`` lists ``"None"``
+        ``docs/specifications/harmonized-raw.md`` lists ``"None"``
         as a sample value; that is documentation shorthand for "missing" and is
         intentionally not a member here.
 
@@ -197,7 +197,7 @@ class CycleType(StrEnum):
 
     A *reference* vocabulary (plain strings stored in the table, unknown values
     allowed, extend by adding members). Values keep the capitalization used in
-    the spec table in ``docs/data_format_specifications/harmonized_raw.md``.
+    the spec table in ``docs/specifications/harmonized-raw.md``.
 
     Not used by the engine yet.
 
@@ -566,11 +566,11 @@ class RawCols(Cols):
 
     Each attribute maps a logical quantity to the column name used in the
     harmonized raw format that cellpy-core consumes. The authoritative spec is
-    ``docs/data_format_specifications/harmonized_raw.md``; the column order here
+    ``docs/specifications/harmonized-raw.md``; the column order here
     mirrors that spec table.
     """
 
-    # Follows docs/data_format_specifications/harmonized_raw.md (authoritative,
+    # Follows docs/specifications/harmonized-raw.md (authoritative,
     # 2025-09-17). Column order mirrors the spec table.
     datapoint_num: str = "datapoint_num"
     source_datapoint_num: str = "source_datapoint_num"
@@ -594,7 +594,7 @@ class RawCols(Cols):
     potential: str = "potential"
     current: str = "current"
     # Capacity / energy are cumulative per cycle, per direction (reset each cycle).
-    # See docs/data_format_specifications/harmonized_raw.md ("Capacity convention").
+    # See docs/specifications/harmonized-raw.md ("Capacity convention").
     cumulative_charge_capacity: str = "cumulative_charge_capacity"
     cumulative_discharge_capacity: str = "cumulative_discharge_capacity"
     cumulative_charge_energy: str = "cumulative_charge_energy"

{cellpycore-0.1.3 → cellpycore-0.1.4}/src/cellpycore/metadata/__init__.py

@@ -3,7 +3,7 @@
 This sub-package provides the *shape and tools* for test-/cell-level metadata,
 without requiring that metadata be populated on the core ``Data`` object. See
 ``.issueflows/04-designs-and-guides/metadata-scaffolding.md`` for the design and
-``docs/data_format_specifications/harmonized_raw.md`` for the authoritative field
+``docs/specifications/harmonized-raw.md`` for the authoritative field
 list.
 
 Two levels of metadata:

{cellpycore-0.1.3 → cellpycore-0.1.4}/src/cellpycore/metadata/models.py

@@ -18,7 +18,7 @@ There are two levels of metadata (see issue #30 and
   many tests via a ``TestMetaCollection`` keyed by ``test_id``.
 
 The authoritative field list lives in
-``docs/data_format_specifications/harmonized_raw.md`` ("Test metadata (TestMeta)");
+``docs/specifications/harmonized-raw.md`` ("Test metadata (TestMeta)");
 the dataclasses here mirror it. Field names are also mined from legacy cellpy's
 ``cellpy.parameters.internal_settings.CellpyMetaCommon`` /
 ``CellpyMetaIndividualTest`` so the two libraries stay aligned.
@@ -118,7 +118,7 @@ class TestMeta:
     """Test-dependent metadata, one record per test run (keyed by ``test_id``).
 
     Mirrors the "Test metadata (TestMeta)" table in
-    ``docs/data_format_specifications/harmonized_raw.md`` and the test-dependent
+    ``docs/specifications/harmonized-raw.md`` and the test-dependent
     fields of legacy ``CellpyMetaIndividualTest``. ``cell`` optionally links the
     cell-dependent metadata so the two-level split is captured without forcing a
     separate table.

{cellpycore-0.1.3 → cellpycore-0.1.4}/src/cellpycore/summarizers.py

@@ -128,7 +128,7 @@ def normalize_capacity_granularity(
     """Normalize cumulative raw capacity / energy columns to cycle-cumulative.
 
     The engine mandates **cycle-cumulative** raw capacity / energy (reset at each
-    cycle boundary; see ``docs/data_format_specifications/harmonized_raw.md``).
+    cycle boundary; see ``docs/specifications/harmonized-raw.md``).
     Cyclers that instead deliver **step-cumulative** (reset per step) or
     **test-cumulative** (never reset) raw can be normalized here before
     aggregation. The transform is granularity-agnostic: for each present column,