cellpy¶

The top-level entry points — what most scripts need.

get `module-attribute` ¶

get = cellreader.get

merge_cells `module-attribute` ¶

merge_cells = cellreader.merge_cells

print_instruments `module-attribute` ¶

print_instruments = readers.cellreader.print_instruments

Command-line API¶

Everything the cellpy command does is callable from Python, so scripts do not have to shell out and parse output.

cli_api ¶

Library-first API behind the cellpy command line (CLI plan Phase 0–1).

What a command does and how it is spelled were the same code, so anything the CLI could do was unreachable from a script: you either shelled out to cellpy run -j journal.json and parsed stdout, or you reimplemented it.

The logic lives here as ordinary typed functions, and cellpy.cli becomes argument parsing that calls them. Nothing about the command line changes — this is a move, not a redesign (#568 for convert/run; #651 for the rest).

Output. These functions are quiet by default, as a library should be. Each public entry takes an echo callable; the CLI passes typer.echo. Larger commands bind that echo with _using_echo so private helpers can call _say without threading the callable through every signature::

from cellpy import cli_api
cli_api.run_journal("my_experiment.json")            # quiet
cli_api.run_journal("my_experiment.json", echo=print)  # chatty
cli_api.setup_config(silent=True, echo=print)

config_path ¶

config_path(*, echo: Optional[Echo] = None)

Return the user config file path (also echoes it).

convert ¶

convert(source: PathLike, destination: Optional[PathLike] = None, *, to: Optional[str] = None, echo: Optional[Echo] = None) -> pathlib.Path

Upgrade a legacy cellpy-file to a current on-disk format.

Parameters:

source (PathLike) –

the old cellpy file.
destination (Optional[PathLike], default: None ) –

where to write. Defaults to <name>_<target> beside the source, with the suffix the target format uses (.cellpy for v9, .h5 for v8).
to (Optional[str], default: None ) –

"v9" (zip-of-parquet — what CellpyCell.save writes) or "v8" (legacy HDF5). When omitted the target is inferred from destination's suffix — .h5/.hdf5 means v8, anything else means v9 — which is the same rule CellpyCell.save applies. With no destination either, the target is v9.
echo (Optional[Echo], default: None ) –

progress reporter; quiet by default.

Returns:

Path –

The path written.

Raises:

ValueError –

if to is not a known target.

Changed in 2.0

This used to write v8 unconditionally, naming the output <name>_v8. It now produces v9 by default. Pass to="v8" (or a .h5 destination) for the old format.

create_project ¶

create_project(template=None, *, directory=None, project=None, experiment=None, local_user_template: bool = False, serve_: bool = False, run_: bool = False, lab: bool = False, jupyter_executable=None, list_: bool = False, echo: Optional[Echo] = None, **kwargs)

Library form of cellpy new.

dump_env_file ¶

dump_env_file(env_filename)

saves (writes) the env to file

echo_missing_modules ¶

echo_missing_modules()

prints out the missing modules

edit_file ¶

edit_file(name=None, *, default_editor=None, debug: bool = False, silent: bool = False, echo: Optional[Echo] = None) -> None

Library form of cellpy edit.

get_default_config_file_path ¶

get_default_config_file_path(init_filename=None)

gets the path to the default config-file

get_dst_file ¶

get_dst_file(user_dir, init_filename)

gets the destination path for the config-file

get_package_prm_dir ¶

get_package_prm_dir()

gets the folder where the cellpy package lives

list_journals ¶

list_journals(batchfiledir: Optional[PathLike] = None, *, echo: Optional[Echo] = None) -> list[pathlib.Path]

List the batch journals in batchfiledir.

Returns the paths as well as echoing them, so a script can use the result instead of scraping the output.

migrate_config ¶

migrate_config(src=None, dst=None, dry_run=False, force=False, *, echo=None)

One-time conversion of the legacy YAML .conf file to cellpy.toml.

The old file is left untouched (it keeps working through the v2.0 deprecation window); the generated TOML takes precedence once present.

open_db_editor ¶

open_db_editor(*, debug: bool = False, silent: bool = False, echo: Optional[Echo] = None) -> None

Open the cellpy database in the platform's spreadsheet application.

pull_resources ¶

pull_resources(*, tests: bool = False, examples: bool = False, clone: bool = False, directory=None, password=None, echo: Optional[Echo] = None) -> None

Library form of cellpy pull.

run_from_db ¶

run_from_db(name: str, *, debug: bool = False, silent: bool = False, raw: bool = False, cellpyfile: bool = False, minimal: bool = False, nom_cap: Optional[float] = None, batch_col: Optional[str] = None, project: Optional[str] = None, echo: Optional[Echo] = None) -> Any

Process a batch selected from the database.

run_journal ¶

run_journal(journal: PathLike, *, debug: bool = False, silent: bool = False, raw: bool = False, cellpyfile: bool = False, minimal: bool = False, nom_cap: Optional[float] = None, echo: Optional[Echo] = None) -> Any

Process one batch journal.

Parameters:

journal (PathLike) –

journal file. A bare name is looked up in the configured batchfiledir, as the CLI has always done.
debug (bool, default: False ) –

raise the log level to DEBUG.
silent (bool, default: False ) –

do not print the resulting batch object.
raw (bool, default: False ) –

force re-reading the raw files.
cellpyfile (bool, default: False ) –

force using the cellpy files.
minimal (bool, default: False ) –

skip the raw/cycles/ica exports.
nom_cap (Optional[float], default: None ) –

nominal capacity override.
echo (Optional[Echo], default: None ) –

progress reporter; quiet by default.

Returns:

Any –

The batch object, or None if the journal could not be found.

run_journals ¶

run_journals(folder: PathLike, *, debug: bool = False, silent: bool = False, raw: bool = False, cellpyfile: bool = False, minimal: bool = False, echo: Optional[Echo] = None) -> None

Process every journal in a folder.

run_project ¶

run_project(project: PathLike, *, echo: Optional[Echo] = None, **kwargs: Any) -> None

Execute every notebook in a project folder with papermill.

save_prm_file ¶

save_prm_file(prm_filename)

saves (writes) the prms to file

setup_config ¶

setup_config(*, interactive: bool = False, not_relative: bool = False, dry_run: bool = False, reset: bool = False, root_dir=None, folder_name=None, test_user=None, silent: bool = False, no_deps: bool = False, echo: Optional[Echo] = None)

Write / refresh the user cellpy configuration (library form of cellpy setup).

show_info ¶

show_info(*, version: bool = False, configloc: bool = False, params: bool = False, show_config: bool = False, check: bool = False, echo: Optional[Echo] = None) -> None

Library form of cellpy info.

start_jupyter ¶

start_jupyter(*, lab: bool = False, directory=None, executable=None, echo: Optional[Echo] = None) -> None

Library form of cellpy serve.