cellpy 2.0.0a2__tar.gz → 2.0.0a4__tar.gz

cellpy-2.0.0a4/.issueflows/03-solved-issues/issue537_original.md

@@ -0,0 +1,28 @@
+# Issue #537: v2 pre-flip: replace hardcoded journal-page column literals with HeadersJournal
+
+Source: https://github.com/jepegit/cellpy/issues/537
+
+## Original issue text
+
+## Context
+
+Phase-3 flip prerequisite (native-headers plan Phase 0, item 2; hardcoded-column-headers-report §8 priority 1). Audited 2026-07-17 with `.issueflows/00-tools/scan_hardcoded_headers.py`; remaining `HeadersJournal`-family findings:
+
+| File | Findings (all families) |
+|---|---|
+| `cellpy/utils/batch_tools/batch_plotters.py` | 32 |
+| `cellpy/utils/helpers.py` | 34 (journal subset only in this issue) |
+| `cellpy/utils/collectors.py` | 16 (journal subset) |
+| `cellpy/utils/batch_tools/batch_journals.py` | 1 |
+| `cellpy/utils/batch.py` | 0 — already clean, keep it that way |
+
+## Work
+
+Mechanical 1:1: each literal flagged as `HeadersJournal` by the scan tool becomes an attribute access on the already-imported `hdr_journal` / `get_headers_journal()`. No behavior change. Leave non-journal findings in the same files for the sibling issue (steps/raw/summary literals).
+
+## Acceptance
+
+- [ ] Scan tool reports **zero `HeadersJournal` findings** for the files above
+- [ ] Full suite green (behavior unchanged — this is a pure rename-to-lookup)
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)

cellpy-2.0.0a4/.issueflows/03-solved-issues/issue537_plan.md

@@ -0,0 +1,38 @@
+# Issue #537 plan — journal-page column literals → HeadersJournal
+
+## Goal
+
+Remove the hard-coded journal column-name string literals flagged by
+`.issueflows/00-tools/scan_hardcoded_headers.py` as `HeadersJournal`, so a
+later header rename touches the header class only (native-headers Phase-0
+prerequisite).
+
+## Scope (verified with the scan tool, 2026-07-17)
+
+Only **6 findings, on 3 lines** — all are string-keyed subscripts into the
+already-imported `hdr_journal` object (the §6 "semi-sanctioned" pattern):
+
+- `cellpy/utils/batch_tools/batch_plotters.py:53` — `hdr_journal["mass"]`,
+  `["loading"]`, `["label"]`
+- `cellpy/utils/batch_tools/batch_plotters.py:76` — `hdr_journal["group"]`,
+  `["sub_group"]`
+- `cellpy/utils/helpers.py:278` — `hdr_journal["loading"]`
+
+Non-journal (raw/steps/summary) literals in the same files are **out of
+scope** — they belong to #538.
+
+## Approach
+
+Mechanical `hdr_journal["<name>"]` → `hdr_journal.<name>`. Verified all five
+attribute values equal their subscript values (`HeadersJournal` is a dataclass
+exposing both), so behavior is byte-identical.
+
+## Files to touch
+
+- `cellpy/utils/batch_tools/batch_plotters.py`
+- `cellpy/utils/helpers.py`
+
+## Test strategy
+
+Behavior-preserving rename-to-lookup; the full suite is the oracle. Confirm
+the scan tool reports **zero `HeadersJournal` findings** for both files after.

cellpy-2.0.0a4/.issueflows/03-solved-issues/issue537_status.md

@@ -0,0 +1,27 @@
+# Issue #537 status — journal-page column literals → HeadersJournal
+
+- [x] Done
+
+## Outcome
+
+All 6 `HeadersJournal` scan findings removed (3 lines):
+
+- `cellpy/utils/batch_tools/batch_plotters.py` — `hdr_journal["mass"|"loading"|"label"]`
+  and `["group"|"sub_group"]` → attribute access.
+- `cellpy/utils/helpers.py` — `hdr_journal["loading"]` → `hdr_journal.loading`.
+
+Scan tool now reports **0 `HeadersJournal` findings** for both files.
+
+## Verification
+
+- Attribute values confirmed equal to subscript values (byte-identical behavior).
+- `tests/test_batch.py` + `tests/test_helpers.py`: 58 passed post-edit.
+- Full suite baseline green (668 passed; the single Windows-only HDF5
+  `driver lock request failed` setup error on `test_has_no_full_duplicates` is
+  a pre-existing test-isolation flake — passes in isolation, not on the Linux
+  CI gate).
+- ruff: no new findings vs master.
+
+## Out of scope (other issues)
+
+- Raw/steps/summary literals in the same files → #538.

{cellpy-2.0.0a2 → cellpy-2.0.0a4}/DEPRECATIONS.md

@@ -8,5 +8,4 @@ uv run python -m cellpy._deprecation
 
 | Name | Replacement | Introduced | Removal |
 | --- | --- | --- | --- |
-| `cellpy.utils.easyplot` | `cellpy.utils.plotutils and cellpy.utils.collectors` | 1.1 | 2.0 |
 | `make_new_cell` | `CellpyCell.vacant` | 2.0 | 2.1 |

{cellpy-2.0.0a2 → cellpy-2.0.0a4}/HISTORY.md

@@ -2,6 +2,39 @@
 
 ## [Unreleased]
 
+* **Breaking:** `CellpyCell.get_cap` now returns native `cellpycore` curve
+  columns (#540, native-headers flip Stage 1): `voltage` → `potential` and
+  `cycle` → `cycle_num` (`capacity` / `direction` unchanged). All in-repo
+  consumers — `plotutils.cycles_plot`, the batch collectors, `ica`, and the
+  CSV/Excel exporters — are updated; user code that indexes the `get_cap`
+  frame directly must rename. See `docs/getting_started/migration_v1_to_v2.md`.
+
+* Removed the deprecated `cellpy.utils.easyplot` module (#544). It was
+  deprecated since 1.1 with removal scheduled for 2.0; use
+  `cellpy.utils.plotutils` and `cellpy.utils.collectors` instead. The module,
+  its tests, its docs entry, and its `DEPRECATIONS.md` row are gone.
+
+* Step-type string literals use the `cellpycore` vocabulary (#543, native-
+  headers Phase-0 prerequisite): `CellpyCell.list_of_step_types` is now
+  `list(config.STEP_TYPES)` (was a hand-maintained duplicate of the 13
+  step-type names), and the step-table `type` comparisons in `utils/ocv_rlx.py`
+  / `utils/helpers.py` use `StepType.CHARGE.value` / `.DISCHARGE.value` instead
+  of bare `"charge"` / `"discharge"` literals. Behavior-identical.
+
+* Header column literals in `utils/helpers.py` and `filters/summary.py` use
+  header-object attributes (#538, native-headers Phase-0 prerequisite): the
+  base-name string-keyed `hdr_summary["charge_capacity"]`-style lookups become
+  attribute access, and `filter_summary`'s `rate_columns` default is resolved
+  from `HeadersSummary` (was a hard-coded `("charge_c_rate", "discharge_c_rate")`
+  tuple). Postfix/specific columns (`*_gravimetric`, `areal_*`) keep string-key
+  composition. Behavior-identical.
+
+* Journal-page column literals use `HeadersJournal` attributes (#537, native-
+  headers Phase-0 prerequisite): the string-keyed `hdr_journal["mass"]`-style
+  lookups in `batch_plotters.py` and `helpers.py` become attribute access
+  (`hdr_journal.mass`, …) so a journal-header rename touches the header class
+  only. Behavior-identical.
+
 * Remote paths via `universal_pathlib` (#375, #371): `OtherPath` is now a thin
   wrapper around `UPath` (fsspec/Paramiko) instead of Fabric. Supported schemes
   remain `ssh://` / `sftp://` / `scp://` (scp aliased to sftp). Remote

{cellpy-2.0.0a2 → cellpy-2.0.0a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cellpy
-Version: 2.0.0a2
+Version: 2.0.0a4
 Summary: Extract and manipulate data from battery data testers.
 Project-URL: Homepage, https://github.com/jepegit/cellpy
 Project-URL: Repository, https://github.com/jepegit/cellpy

{cellpy-2.0.0a2 → cellpy-2.0.0a4}/cellpy/_deprecation.py

@@ -94,12 +94,8 @@ def write_deprecations_md(path: str | Path) -> None:
 def _seed_known_deprecations() -> None:
     """Register deprecations that exist before any runtime call (for doc generation)."""
     _register("make_new_cell", "CellpyCell.vacant", removal="2.1")
-    _register(
-        "cellpy.utils.easyplot",
-        "cellpy.utils.plotutils and cellpy.utils.collectors",
-        removal="2.0",
-        introduced="1.1",
-    )
+    # cellpy.utils.easyplot was removed in 2.0 (#544); it is no longer a
+    # pending deprecation, so it is dropped from the registry / DEPRECATIONS.md.
 
 
 if __name__ == "__main__":

{cellpy-2.0.0a2 → cellpy-2.0.0a4}/cellpy/exporters/tabular.py

@@ -23,9 +23,15 @@ import warnings
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from cellpycore.config import CurveCols
+
 from cellpy.exceptions import NoDataFound
 from cellpy.readers import externals
 
+# get_cap emits native CurveCols names (#540): potential/cycle_num, not
+# voltage/cycle.
+_CCOLS = CurveCols()
+
 if TYPE_CHECKING:
     from cellpy.readers.cellreader import CellpyCell
 
@@ -74,8 +80,8 @@ def export_cycles(
             if df.empty:
                 logging.debug("NoneType from get_cap")
             else:
-                c = df["capacity"]
-                v = df["voltage"]
+                c = df[_CCOLS.capacity]
+                v = df[_CCOLS.potential]
 
                 _last = c.iat[-1]
                 _first = c.iat[0]

{cellpy-2.0.0a2 → cellpy-2.0.0a4}/cellpy/filters/summary.py

@@ -29,6 +29,8 @@ import logging
 from collections.abc import Mapping, Sequence
 from typing import Any, Callable, Optional, Union
 
+from cellpy.parameters.internal_settings import get_headers_summary
+
 import pandas as pd
 
 logger = logging.getLogger(__name__)
@@ -145,7 +147,7 @@ def filter_summary(
     df: pd.DataFrame,
     *,
     rate: RangeArg = None,
-    rate_columns: ColumnsArg = ("charge_c_rate", "discharge_c_rate"),
+    rate_columns: ColumnsArg = None,
     **extra_filters: Any,
 ) -> pd.DataFrame:
     """Filter rows of a cellpy summary DataFrame.
@@ -159,6 +161,8 @@ def filter_summary(
             mapping ``{"value": v, "delta": d}`` (keep rows with
             ``v - d < value <= v + d``).
         rate_columns: Which column(s) the ``rate`` filter applies to.
+            ``None`` (default) resolves to the summary C-rate columns
+            (``HeadersSummary.charge_c_rate`` / ``.discharge_c_rate``).
             A single string is coerced to a one-element tuple. With more
             than one column the predicate is AND-ed across columns - a
             row is kept only if *every* listed column lies in range.
@@ -176,6 +180,10 @@ def filter_summary(
             argument is malformed.
         TypeError: A range argument has an unsupported type.
     """
+    if rate_columns is None:
+        hdr_summary = get_headers_summary()
+        rate_columns = (hdr_summary.charge_c_rate, hdr_summary.discharge_c_rate)
+
     range_kwargs = {k: v for k, v in extra_filters.items() if not k.endswith("_columns")}
     column_kwargs = {k: v for k, v in extra_filters.items() if k.endswith("_columns")}
 

{cellpy-2.0.0a2 → cellpy-2.0.0a4}/cellpy/readers/capacity_curves.py

@@ -13,12 +13,20 @@ import logging
 import warnings
 from typing import TYPE_CHECKING
 
+from cellpycore.config import CurveCols
+
 import cellpy.config as config
 
 from . import externals as externals
 from cellpy.readers import data_structures as ds
 from cellpy.exceptions import NullData
 
+# Native curve-frame column names (cellpycore #118). get_cap and the
+# single-branch charge/discharge extractors emit these unconditionally on the
+# v2 line (#540): potential/cycle_num replace the legacy voltage/cycle;
+# capacity/direction are unchanged.
+_CCOLS = CurveCols()
+
 if TYPE_CHECKING:
     from cellpy.readers.cellreader import CellpyCell
 
@@ -241,7 +249,10 @@ def get_cap(
 
     if insert_nan:
         _nan = externals.pandas.DataFrame(
-            {"capacity": [externals.numpy.nan], "voltage": [externals.numpy.nan]}
+            {
+                _CCOLS.capacity: [externals.numpy.nan],
+                _CCOLS.potential: [externals.numpy.nan],
+            }
         )
 
     converter_kwargs = dict()
@@ -391,8 +402,8 @@ def get_cap(
                     logging.debug("no first charge step found")
 
             if return_dataframe:
-                x_col = "voltage"
-                y_col = "capacity"
+                x_col = _CCOLS.potential
+                y_col = _CCOLS.capacity
                 if interpolate_along_cap:
                     x_col, y_col = y_col, x_col
 
@@ -401,8 +412,8 @@ def get_cap(
                     if not _first_step_c.empty:
                         _first_df = externals.pandas.DataFrame(
                             {
-                                "voltage": _first_step_v,
-                                "capacity": _first_step_c,
+                                _CCOLS.potential: _first_step_v,
+                                _CCOLS.capacity: _first_step_c,
                             }
                         )
                         if interpolated:
@@ -417,7 +428,7 @@ def get_cap(
                         if insert_nan:
                             _first_df = externals.pandas.concat([_first_df, _nan])
                         if categorical_column:
-                            _first_df["direction"] = -1
+                            _first_df[_CCOLS.direction] = -1
                     else:
                         _first_df = externals.pandas.DataFrame()
 
@@ -425,8 +436,8 @@ def get_cap(
                     if not _last_step_c.empty:
                         _last_df = externals.pandas.DataFrame(
                             {
-                                "voltage": _last_step_v.values,
-                                "capacity": _last_step_c.values,
+                                _CCOLS.potential: _last_step_v.values,
+                                _CCOLS.capacity: _last_step_c.values,
                             }
                         )
                         if interpolated:
@@ -441,7 +452,7 @@ def get_cap(
                         if insert_nan:
                             _last_df = externals.pandas.concat([_last_df, _nan])
                         if categorical_column:
-                            _last_df["direction"] = 1
+                            _last_df[_CCOLS.direction] = 1
                     else:
                         _last_df = externals.pandas.DataFrame()
 
@@ -457,9 +468,7 @@ def get_cap(
                 else:
                     c = externals.pandas.concat([_first_df, _last_df], axis=0)
                     if label_cycle_number:
-                        c.insert(0, "cycle", current_cycle)
-                        # c["cycle"] = current_cycle
-                        # c = c[["cycle", "voltage", "capacity", "direction"]]
+                        c.insert(0, _CCOLS.cycle_num, current_cycle)
                     if cycle_df.empty:
                         cycle_df = c
                     else:
@@ -467,8 +476,8 @@ def get_cap(
                 if capacity_then_voltage:
                     cols = cycle_df.columns.to_list()
                     new_cols = [
-                        cols.pop(cols.index("capacity")),
-                        cols.pop(cols.index("voltage")),
+                        cols.pop(cols.index(_CCOLS.capacity)),
+                        cols.pop(cols.index(_CCOLS.potential)),
                     ]
                     new_cols.extend(cols)
                     cycle_df = cycle_df[new_cols]

{cellpy-2.0.0a2 → cellpy-2.0.0a4}/cellpy/readers/cellreader.py

@@ -58,6 +58,7 @@ from cellpy.parameters.internal_settings import (
 # still expects. cellpy-core's __init__ is intentionally empty, so import submodules.
 from cellpycore import units as core_units
 from cellpycore.cell_core import OldCellpyCellCore
+from cellpycore.config import STEP_TYPES
 
 from cellpy.readers.cellpy_file import dtype as cellpy_file_dtype
 from cellpy.readers.cellpy_file import fids as cellpy_file_fids
@@ -297,21 +298,9 @@ class CellpyCell:
 
         self.capacity_modifiers = ["reset"]
 
-        self.list_of_step_types = [
-            "charge",
-            "discharge",
-            "cv_charge",
-            "cv_discharge",
-            "taper_charge",
-            "taper_discharge",
-            "charge_cv",
-            "discharge_cv",
-            "ocvrlx_up",
-            "ocvrlx_down",
-            "ir",
-            "rest",
-            "not_known",
-        ]
+        # single source of the step-type vocabulary (cellpycore #543);
+        # was a hand-maintained duplicate of config.STEP_TYPES.
+        self.list_of_step_types = list(STEP_TYPES)
         # - options
         self.force_step_table_creation = config.reader.force_step_table_creation
         self.force_all = config.reader.force_all

{cellpy-2.0.0a2 → cellpy-2.0.0a4}/cellpy/utils/batch_tools/batch_plotters.py

@@ -50,7 +50,7 @@ def create_legend(info, c, option="clean", use_index=False):
 
     logging.debug("    - creating legends")
     mass, loading, label = info.loc[
-        c, [hdr_journal["mass"], hdr_journal["loading"], hdr_journal["label"]]
+        c, [hdr_journal.mass, hdr_journal.loading, hdr_journal.label]
     ]
 
     if use_index or not label:
@@ -73,7 +73,7 @@ def create_legend(info, c, option="clean", use_index=False):
 
 def look_up_group(info, c):
     logging.debug("    - looking up groups")
-    g, sg = info.loc[c, [hdr_journal["group"], hdr_journal["sub_group"]]]
+    g, sg = info.loc[c, [hdr_journal.group, hdr_journal.sub_group]]
     return int(g), int(sg)
 
 

{cellpy-2.0.0a2 → cellpy-2.0.0a4}/cellpy/utils/collectors.py

@@ -19,7 +19,15 @@ import matplotlib.pyplot as plt
 import numpy as np
 
 import cellpy
+from cellpycore.config import CurveCols
+
 from cellpy.parameters.internal_settings import get_headers_journal
+
+# get_cap curve frames use native CurveCols names (#540): potential/cycle_num
+# replace the legacy voltage/cycle. The capacity-curve plotters below default
+# their x/y/z column selectors to these. (Summary and ICA collectors use their
+# own schemas and are left untouched.)
+_CCOLS = CurveCols()
 from cellpy.readers.data_structures import group_by_interpolate
 from cellpy.utils.batch import Batch
 from cellpy.utils.helpers import concat_summaries
@@ -1163,9 +1171,14 @@ class BatchSummaryCollector(BatchCollector):
         wide_cols = []
         value_cols = []
         sort_by = []
+        # summary collectors label the cycle column "cycle"; curve collectors
+        # carry the native CurveCols name "cycle_num" (#540).
         if "cycle" in cols:
             index = "cycle"
             cols.remove("cycle")
+        elif _CCOLS.cycle_num in cols:
+            index = _CCOLS.cycle_num
+            cols.remove(_CCOLS.cycle_num)
         else:
             print("Could not find index")
             return self.data
@@ -1965,9 +1978,9 @@ def spread_plot(curves, plotly_arguments=None, y_label_mapper=None, **kwargs):
 
 def sequence_plotter(
     collected_curves: pd.DataFrame,
-    x: str = "capacity",
-    y: str = "voltage",
-    z: str = "cycle",
+    x: str = _CCOLS.capacity,
+    y: str = _CCOLS.potential,
+    z: str = _CCOLS.cycle_num,
     g: str = "cell",
     standard_deviation: str = None,
     group: str = hdr_journal.group,
@@ -2359,10 +2372,10 @@ def sequence_plotter(
             seaborn_arguments["height"] = kwargs.pop("height", 3)
             seaborn_arguments["aspect"] = kwargs.pop("height", 1)
             sns.set_theme(style="darkgrid")
-            x = seaborn_arguments.get("x", "capacity")
-            y = seaborn_arguments.get("y", "voltage")
+            x = seaborn_arguments.get("x", _CCOLS.capacity)
+            y = seaborn_arguments.get("y", _CCOLS.potential)
             row = seaborn_arguments.get("row", hdr_journal.group)
-            hue = seaborn_arguments.get("hue", "cycle")
+            hue = seaborn_arguments.get("hue", _CCOLS.cycle_num)
             col = seaborn_arguments.get("col", hdr_journal.sub_group)
             height = seaborn_arguments.get("height", 3)
             aspect = seaborn_arguments.get("aspect", 1)
@@ -2520,9 +2533,9 @@ def sequence_plotter(
 def _cycles_plotter(
     collected_curves,
     cycles=None,
-    x="capacity",
-    y="voltage",
-    z="cycle",
+    x=_CCOLS.capacity,
+    y=_CCOLS.potential,
+    z=_CCOLS.cycle_num,
     g="cell",
     standard_deviation=None,
     default_title="Charge-Discharge Curves",
@@ -2579,7 +2592,7 @@ def _cycles_plotter(
         if cycles is not None:
             number_of_figs = len(cycles)
         else:
-            number_of_figs = len(collected_curves["cycle"].unique())
+            number_of_figs = len(collected_curves[_CCOLS.cycle_num].unique())
     elif method == "summary":
         number_of_figs = len(collected_curves["variable"].unique())
         sub_fig_min_height = 300
@@ -2889,9 +2902,9 @@ def cycles_plotter(
 
     return _cycles_plotter(
         collected_curves,
-        x="capacity",
-        y="voltage",
-        z="cycle",
+        x=_CCOLS.capacity,
+        y=_CCOLS.potential,
+        z=_CCOLS.cycle_num,
         g="cell",
         x_unit=x_unit,
         y_unit=y_unit,