Parameters and configuration¶

Parallel pydantic-settings configuration stack (issues #452, #453).

Production code should use cellpy.config directly. Legacy cellpy.parameters.prms forwards here via a deprecated shim.

model_dump_for_file() -> dict[str, Any]

LoadOptions(user_config_file: Path | None = None, project_config_file: Path | None = None, env_file: Path | None = None, cwd: Path | None = None, skip_files: bool = False, skip_env: bool = False, legacy_yaml_file: Path | None = None)

override(**sections: Any) -> Iterator[CellpyConfig]

reload(overrides: dict[str, Any] | None = None, *, options: LoadOptions | None = None) -> CellpyConfig

reset_session() -> None

Pydantic models mirroring legacy prms sections (issue #452).

model_dump_for_file() -> dict[str, Any]

get_password() -> str | None

default_inventory_config(root: Path) -> CellpyConfig

inventory_paths_config(root: Path) -> PathsConfig

The one place that resolves cellpy credentials (config plan Step 6, #565).

Before this module four call sites — internals/otherpath.py, internals/connections.py, readers/filefinder.py and readers/instruments/arbin_sql_config.py — each knew the CELLPY_* environment variable names and each read them with a bare os.getenv. That is the scatter the config plan set out to remove: four places to update when a variable is renamed, and four different answers when one of them is stale.

Resolution order, per credential:

1. the session config (cellpy.config.secrets) — this is where the config loader has already deposited the environment and .env layers, and where an explicit runtime assignment lands;
2. the live environment — consulted only if the session value is unset, so that a variable exported after cellpy was imported still works (a normal notebook pattern) without letting the environment silently override a value the user set deliberately at runtime.

Credentials are never read from a config file: the loader refuses a [secrets] section outright (config plan decision 5).

get_host() -> str | None

get_key_filename() -> str | None

get_password() -> str | None

get_user() -> str | None

resolve_credentials() -> SecretsConfig

The public column-name API for a cell (native-headers Phase 4, issue #558).

CellpyCell.schema answers one question: what is this column called on the frames this cell is carrying? It is the sanctioned replacement for the legacy headers_normal / headers_step_table / headers_summary attributes, which are now a deprecation shim (legacy_header_shim, D6).

>>> c = cellpy.get(...)                                    # doctest: +SKIP
>>> c.data.raw[c.schema.raw.potential]                     # doctest: +SKIP
>>> c.data.summary[c.schema.summary.charge_capacity]       # doctest: +SKIP

Frame names follow the frames, not cellpy-core. cellpycore.config.Schema spells its three frames raw / step / cycle; the frames a user holds are c.data.raw / c.data.steps / c.data.summary. This wrapper closes that gap — c.schema.summary sits next to c.data.summary — so there is exactly one public spelling per frame. Internals that want the cellpy-core object keep using c.core.schema.

You always spell the column the native way; the value tracks the runtime. c.schema.raw.potential is how you ask for the potential column on any cell. On the native runtime (the cellpy 2 default) it returns "potential". On the legacy runtime (native_schema=False, the retiring v8/bridge compatibility path) the frames still carry legacy column names, so the same attribute returns "voltage" — the name that actually indexes that frame. That uniformity is what lets cellpy's own internals, which must run on both runtimes, be written once against the native vocabulary.

The contract in one line: whatever c.schema.<frame>.<column> returns is a valid key into c.data.<frame>.

CellSchema(core_schema: 'config.Schema', native: bool = True)

raw

steps

summary

Unit presentation helpers (unit plan Phase 4, issue #564).

Plots and reports need to say what a number is measured in. Before this module every caller composed that string by hand::

f"Capacity ({c.cellpy_units.charge}/{c.cellpy_units.specific_gravimetric})"

which is where gravimetric/areal/absolute mix-ups live: the mode is encoded in the choice of attribute, so picking the wrong one is a silent mislabel rather than an error. These two helpers make the mode an argument instead:

>>> units_label("charge", mode="gravimetric")          # doctest: +SKIP
'mAh/g'
>>> with_cellpy_unit("Capacity", "charge", "areal")    # doctest: +SKIP
'Capacity (mAh/cm**2)'

units defaults to the session's cellpy units. Pass a cell's own units explicitly — units_label("charge", "gravimetric", units=c.cellpy_units) — whenever the label describes that cell's frames rather than session policy. Values cross the seam, never config objects (architecture plan §4).

units_label(physical_property: str, mode: Optional[str] = None, *, units: Optional['CellpyUnits'] = None) -> str

with_cellpy_unit(name: str, physical_property: str, mode: Optional[str] = None, *, units: Optional['CellpyUnits'] = None) -> str