Cell Specification#

Client for managing cell specifications.

For usage examples and guides, see Data API on docs.ionworks.com.

Cell specification client for managing cell type definitions.

This module provides the CellSpecificationClient for creating, reading, updating, and deleting cell specifications, which define the properties of battery cell types (manufacturer, chemistry, ratings, etc.).

class ionworks.cell_specification.CellSpecificationClient(client)[source]#

Bases: object

Client for managing cell specifications.

Provides methods to create, read, update, and delete cell specifications, which define the properties of battery cell types (manufacturer, chemistry, ratings, etc.).

Parameters:

client (Any)

__init__(client)[source]#

Initialize the CellSpecificationClient.

Parameters:

client (Any) – The HTTP client instance for making API requests.

Return type:

None

get(cell_spec_id)[source]#

Get a specific cell specification by ID.

Parameters:

cell_spec_id (str) – The ID of the cell specification to retrieve.

Returns:

The requested cell specification object.

Return type:

CellSpecification

list(include_components=False, limit=None, offset=None, *, name=None, name_exact=None, form_factor=None, created_by_email=None, created_after=None, created_before=None, updated_after=None, updated_before=None, order_by=None, order=None, project_id=None, material_id=None, anode_material_id=None, cathode_material_id=None, electrolyte_material_id=None, separator_material_id=None, case_material_id=None, exclude_cell_spec_id=None)[source]#

List cell specifications with optional pagination and filtering.

Always returns a PaginatedList which behaves like a regular list. Use limit and offset to control the page.

Parameters:

  • include_components (bool, optional) – If True, returns each specification with its nested component and material data. Defaults to False (metadata only).

  • limit (int | None, optional) – Maximum number of specs to return per page.

  • offset (int | None, optional) – Number of specs to skip for pagination.

  • name (str | None, optional) – Case-insensitive substring match on spec name.

  • name_exact (str | None, optional) – Exact match on spec name. Takes precedence over name.

  • form_factor (str | None, optional) – Exact match on form factor.

  • created_by_email (str | None, optional) – Case-insensitive substring match on the creator’s email.

  • created_after (str | None, optional) – ISO datetime; return specs created after this time.

  • created_before (str | None, optional) – ISO datetime; return specs created before this time.

  • updated_after (str | None, optional) – ISO datetime; return specs updated after this time.

  • updated_before (str | None, optional) – ISO datetime; return specs updated before this time.

  • order_by (str | None, optional) – Column to sort by ("name", "created_at", "updated_at").

  • order (str | None, optional) – Sort direction: "asc" or "desc".

  • project_id (str | None, optional) – Restrict results to this project. Required for an identity lookup — name_exact or a material reverse-lookup (see material_id) — where it falls back to IONWORKS_PROJECT_ID and raises if neither is set, because those resolve one specific spec and names and materials are only unique within a project. For a plain list, omitting it applies no project filter.

  • material_id (str | list[str] | None, optional) – Return specs referencing this material through any component. A single id matches specs using that material; a list matches specs using any of the given materials.

  • anode_material_id (str | None, optional) – Return specs whose anode uses this material.

  • cathode_material_id (str | None, optional) – Return specs whose cathode uses this material.

  • electrolyte_material_id (str | None, optional) – Return specs whose electrolyte uses this material.

  • separator_material_id (str | None, optional) – Return specs whose separator uses this material.

  • case_material_id (str | None, optional) – Return specs whose case uses this material.

  • exclude_cell_spec_id (str | None, optional) – Exclude the spec with this id from the results.

Returns:

A list of cell specification objects.

Return type:

PaginatedList[CellSpecification]

related_specs(cell_spec_id, *, slots=None, exclude_self=True, limit=100, offset=0, include_components=False)[source]#

Other cell specs sharing a component material with this spec.

Parameters:

  • cell_spec_id (str) – The spec whose slot materials define the search.

  • slots (list[str] | None, optional) – Slots to compare (subset of anode/cathode/electrolyte/separator/case). None → any slot: match other specs using any of this spec’s slot materials in any slot. A list → per-slot: match each named slot only against this spec’s material in that same slot (e.g. ["anode", "cathode"] finds specs whose anode matches this anode or whose cathode matches this cathode).

  • exclude_self (bool, optional) – Exclude cell_spec_id from results (applied server-side). Defaults True.

  • limit (int, optional) – Maximum number of specs to return per page. Defaults to 100.

  • offset (int, optional) – Number of specs to skip for pagination. Defaults to 0.

  • include_components (bool, optional) – If True, return each spec with its nested component and material data. Defaults to False (metadata only).

Returns:

Specs sharing a material, backend-paginated and self-excluded. Scoped to this spec’s project; for a System-library spec (no project) the search spans the whole org.

Return type:

PaginatedList[CellSpecification]

Raises:

ValueError – If slots contains an unknown slot name.

create(data)[source]#

Create a new cell specification.

Parameters:

data (dict[str, Any]) – Dictionary containing the cell specification data. If project_id is omitted, the client’s default project_id is used.

Returns:

The newly created cell specification object.

Return type:

CellSpecification

create_or_get(data)[source]#

Create a new cell specification or get an existing one.

Creates a new cell specification if it doesn’t exist, otherwise returns the existing one.

Parameters:

data (dict[str, Any]) – Dictionary containing the cell specification data.

Returns:

The cell specification object (newly created or existing).

Return type:

CellSpecification

update(cell_spec_id, data)[source]#

Update an existing cell specification.

Parameters:

  • cell_spec_id (str) – The ID of the cell specification to update.

  • data (dict[str, Any]) – Dictionary containing the fields to update. Supports nested component/material data for upsert.

Returns:

The updated cell specification object.

Return type:

CellSpecification

delete(cell_spec_id)[source]#

Delete a cell specification by ID.

Parameters:

cell_spec_id (str) – The ID of the cell specification to delete.

Return type:

None