ionworks-api 0.1.0__tar.gz → 0.1.2__tar.gz

{ionworks_api-0.1.0 → ionworks_api-0.1.2}/.gitignore

@@ -2,9 +2,15 @@
 .pytest_cache
 .venv
 .env*
+!.env.example
 .ruff_cache
 .vscode
 __pycache__
 .DS_Store
 .idea
 .local
+uv.lock
+
+# Docs
+docs/_build/
+docs/.jupyter_cache/

ionworks_api-0.1.2/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ionworks Technologies Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{ionworks_api-0.1.0 → ionworks_api-0.1.2}/PKG-INFO

@@ -1,7 +1,8 @@
 Metadata-Version: 2.4
 Name: ionworks-api
-Version: 0.1.0
+Version: 0.1.2
 Summary: Python client for interacting with the Ionworks API
+License-File: LICENSE.md
 Requires-Python: >=3.10
 Requires-Dist: black
 Requires-Dist: iwutil
@@ -17,6 +18,10 @@ Requires-Dist: supabase
 Requires-Dist: types-requests>=2.31.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo; extra == 'docs'
+Requires-Dist: myst-nb>=1.0.0; extra == 'docs'
+Requires-Dist: sphinx>=7.0.0; extra == 'docs'
 Description-Content-Type: text/markdown
 
 # Ionworks API Client
@@ -34,7 +39,13 @@ A Python client for interacting with the Ionworks API.
 pip install -e .
 ```
 
-3. Get your API key from the [Ionworks account settings](https://app.ionworks.com/dashboard/account) and set it as the `IONWORKS_API_KEY` environment variable (or in a `.env` file).
+3. Copy the example environment file and fill in your credentials:
+
+```bash
+cp .env.example .env
+```
+
+Get your API key from the [Ionworks account settings](https://app.ionworks.com/dashboard/account) and your project ID from your project settings page. See [Environment Setup](#environment-setup) for details.
 
 ## Usage
 
@@ -185,7 +196,6 @@ Available element types:
 - `validation`: Validate model against data
 
 ```python
-import time
 from ionworks import Ionworks
 
 client = Ionworks()
@@ -236,22 +246,15 @@ pipeline_config = {
     },
 }
 
-# Submit pipeline
+# Submit pipeline and wait for completion
 pipeline = client.pipeline.create(pipeline_config)
 print(f"Pipeline submitted: {pipeline.id}")
 
-# Poll for completion
-while True:
-    pipeline = client.pipeline.get(pipeline.id)
-    print(f"Status: {pipeline.status}")
-    if pipeline.status == "completed":
-        result = client.pipeline.result(pipeline.id)
-        print("Fitted parameters:", result.element_results["fit data"])
-        break
-    elif pipeline.status == "failed":
-        print("Pipeline failed:", pipeline.error)
-        break
-    time.sleep(2)
+pipeline = client.pipeline.wait_for_completion(pipeline.id, timeout=600)
+
+if pipeline.status == "completed":
+    result = client.pipeline.result(pipeline.id)
+    print("Fitted parameters:", result.element_results["fit data"])
 ```
 
 ### Running simulations
@@ -307,6 +310,22 @@ simulation_data = client.simulation.get_result(result.simulation_id)
 time_series = simulation_data.get("time_series", {})
 ```
 
+## Environment Setup
+
+The client uses environment variables for configuration. Copy the example file and fill in your values:
+
+```bash
+cp .env.example .env
+```
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `IONWORKS_API_KEY` | Yes | — | API key from [account settings](https://app.ionworks.com/dashboard/account) |
+| `IONWORKS_API_URL` | No | `https://api.ionworks.com` | API base URL |
+| `PROJECT_ID` | For pipelines | — | Project ID from your project settings page |
+
+The client loads `.env` automatically via `python-dotenv`.
+
 ## Error Handling
 
 The client will raise exceptions in the following cases:

{ionworks_api-0.1.0 → ionworks_api-0.1.2}/README.md

@@ -13,7 +13,13 @@ A Python client for interacting with the Ionworks API.
 pip install -e .
 ```
 
-3. Get your API key from the [Ionworks account settings](https://app.ionworks.com/dashboard/account) and set it as the `IONWORKS_API_KEY` environment variable (or in a `.env` file).
+3. Copy the example environment file and fill in your credentials:
+
+```bash
+cp .env.example .env
+```
+
+Get your API key from the [Ionworks account settings](https://app.ionworks.com/dashboard/account) and your project ID from your project settings page. See [Environment Setup](#environment-setup) for details.
 
 ## Usage
 
@@ -164,7 +170,6 @@ Available element types:
 - `validation`: Validate model against data
 
 ```python
-import time
 from ionworks import Ionworks
 
 client = Ionworks()
@@ -215,22 +220,15 @@ pipeline_config = {
     },
 }
 
-# Submit pipeline
+# Submit pipeline and wait for completion
 pipeline = client.pipeline.create(pipeline_config)
 print(f"Pipeline submitted: {pipeline.id}")
 
-# Poll for completion
-while True:
-    pipeline = client.pipeline.get(pipeline.id)
-    print(f"Status: {pipeline.status}")
-    if pipeline.status == "completed":
-        result = client.pipeline.result(pipeline.id)
-        print("Fitted parameters:", result.element_results["fit data"])
-        break
-    elif pipeline.status == "failed":
-        print("Pipeline failed:", pipeline.error)
-        break
-    time.sleep(2)
+pipeline = client.pipeline.wait_for_completion(pipeline.id, timeout=600)
+
+if pipeline.status == "completed":
+    result = client.pipeline.result(pipeline.id)
+    print("Fitted parameters:", result.element_results["fit data"])
 ```
 
 ### Running simulations
@@ -286,6 +284,22 @@ simulation_data = client.simulation.get_result(result.simulation_id)
 time_series = simulation_data.get("time_series", {})
 ```
 
+## Environment Setup
+
+The client uses environment variables for configuration. Copy the example file and fill in your values:
+
+```bash
+cp .env.example .env
+```
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `IONWORKS_API_KEY` | Yes | — | API key from [account settings](https://app.ionworks.com/dashboard/account) |
+| `IONWORKS_API_URL` | No | `https://api.ionworks.com` | API base URL |
+| `PROJECT_ID` | For pipelines | — | Project ID from your project settings page |
+
+The client loads `.env` automatically via `python-dotenv`.
+
 ## Error Handling
 
 The client will raise exceptions in the following cases:

ionworks_api-0.1.2/ionworks/__init__.py

@@ -0,0 +1,28 @@
+"""
+Ionworks API Client.
+
+A Python client for interacting with the Ionworks platform for battery cell
+testing, simulation, and modeling.
+
+Example:
+-------
+>>> from ionworks import Ionworks
+>>> client = Ionworks()
+>>> specs = client.cell_spec.list()
+"""
+
+from .client import Ionworks
+from .errors import IonworksError
+from .validators import (
+    MeasurementValidationError,
+    get_dataframe_backend,
+    set_dataframe_backend,
+)
+
+__all__ = [
+    "Ionworks",
+    "IonworksError",
+    "MeasurementValidationError",
+    "get_dataframe_backend",
+    "set_dataframe_backend",
+]

{ionworks_api-0.1.0 → ionworks_api-0.1.2}/ionworks/cell_instance.py

@@ -1,3 +1,11 @@
+"""
+Cell instance client for managing individual cell records.
+
+This module provides the :class:`CellInstanceClient` for creating, reading,
+updating, and deleting cell instances, which represent individual physical
+battery cells linked to a cell specification.
+"""
+
 from typing import Any
 
 from pydantic import ValidationError
@@ -12,13 +20,20 @@ from .models import (
 
 
 class CellInstanceClient:
-    def __init__(self, client: Any):
+    """Client for managing cell instances."""
+
+    def __init__(self, client: Any) -> None:
+        """Initialize the CellInstanceClient.
+
+        Parameters
+        ----------
+        client : Any
+            The HTTP client instance used for API calls.
+        """
         self.client = client
 
     def get(self, cell_instance_id: str) -> CellInstance:
-        """
-        Get a specific cell instance by ID.
-        """
+        """Get a specific cell instance by ID."""
         endpoint = f"/cell_instances/{cell_instance_id}"
         try:
             response_data = self.client.get(endpoint)
@@ -30,9 +45,7 @@ class CellInstanceClient:
             raise RuntimeError(f"API call to {endpoint} failed: {e}") from e
 
     def get_by_slug(self, cell_instance_slug: str) -> CellInstance:
-        """
-        Get a specific cell instance by slug.
-        """
+        """Get a specific cell instance by slug."""
         endpoint = f"/cell_instances/slug/{cell_instance_slug}"
         try:
             response_data = self.client.get(endpoint)
@@ -43,9 +56,7 @@ class CellInstanceClient:
             raise RuntimeError(f"API call to {endpoint} failed: {e}") from e
 
     def list(self, cell_spec_id: str) -> list[CellInstance]:
-        """
-        List all cell instances for a cell specification by specification ID.
-        """
+        """List all cell instances for a cell specification by specification ID."""
         endpoint = f"/cell_specifications/{cell_spec_id}/cell_instances"
         try:
             response_data = self.client.get(endpoint)
@@ -74,14 +85,13 @@ class CellInstanceClient:
     #     return [CellMeasurementDetailBase(**item) for item in response_data]
 
     def update(self, cell_instance_id: str, data: dict[str, Any]) -> CellInstance:
-        """
-        Update an existing cell instance.
+        """Update an existing cell instance.
 
         Parameters
         ----------
         cell_instance_id : str
             The ID of the cell instance to update.
-        data : dict
+        data : dict[str, Any]
             Dictionary containing the fields to update.
 
         Returns
@@ -94,30 +104,36 @@ class CellInstanceClient:
         return CellInstance(**response_data)
 
     def delete(self, cell_instance_id: str) -> None:
-        """
-        Delete a cell instance by ID.
-        """
+        """Delete a cell instance by ID."""
         endpoint = f"/cell_instances/{cell_instance_id}"
         self.client.delete(endpoint)
 
     # Renamed and moved method from Data class
     def detail(self, cell_instance_id: str) -> CellInstanceDetail:
-        """
-        Loads the full details for a cell instance from a single API endpoint,
-        including its spec, instance data, steps DataFrame, and time series DataFrame.
-        Uses the /detail endpoint.
+        """Load the full details for a cell instance.
 
-        Args:
-            organization: The organization slug.
-            cell_instance_id: The cell instance ID.
+        Loads the full details for a cell instance from a single API endpoint,
+        including its spec, instance data, steps DataFrame, and time series
+        DataFrame. Uses the /detail endpoint.
 
-        Returns:
-            A FullCellInstance object containing validated data.
+        Parameters
+        ----------
+        cell_instance_id : str
+            The cell instance ID.
 
-        Raises:
-            RuntimeError: If the API call fails.
-            ValueError: If the API response format is unexpected or parsing fails.
-            ValidationError: If the response data doesn't match expected models.
+        Returns
+        -------
+        CellInstanceDetail
+            Object containing validated cell instance data.
+
+        Raises
+        ------
+        RuntimeError
+            If the API call fails.
+        ValueError
+            If the API response format is unexpected or parsing fails.
+        ValidationError
+            If the response data doesn't match expected models.
         """
         endpoint = f"/cell_instances/{cell_instance_id}/detail"
         try:
@@ -127,9 +143,9 @@ class CellInstanceClient:
         except ValidationError as e:
             # Pydantic validation error during parsing
             raise ValueError(f"Response validation failed for {endpoint}: {e}") from e
-        except ValueError as e:
+        except ValueError:
             # Re-raise our explicit format validation errors
-            raise e
+            raise
         except Exception as e:
             # Catch client errors or any other unexpected issues
             raise RuntimeError(
@@ -137,19 +153,13 @@ class CellInstanceClient:
             ) from e
 
     def create(self, cell_spec_id: str, data: dict[str, Any]) -> CellInstance:
-        """
-        Create a new cell instance under a cell specification by
-        specification ID.
-        """
+        """Create a new cell instance under a cell specification by specification ID."""
         endpoint = f"/cell_specifications/{cell_spec_id}/cell_instances"
         response_data = self.client.post(endpoint, data)
         return CellInstance(**response_data)
 
     def create_or_get(self, cell_spec_id: str, data: dict[str, Any]) -> CellInstance:
-        """
-        Create a new cell instance if it doesn't exist, otherwise get the
-        existing one.
-        """
+        """Create a new cell instance if it doesn't exist, otherwise get it."""
         try:
             return self.create(cell_spec_id, data)
         except IonworksError as e:
@@ -157,11 +167,11 @@ class CellInstanceClient:
                 existing_id = e.data.get("existing_cell_instance_id")
                 if existing_id:
                     return self.get(existing_id)
-            raise e
+            raise
 
     def list_with_measurements(self, cell_spec_id: str) -> CellSpecificationInstances:
-        """
-        List all instances and measurements for a cell specification.
+        """List all instances and measurements for a cell specification.
+
         Returns normalized data: separate lists for specification, instances, and
         measurements.
         """
@@ -179,8 +189,8 @@ class CellInstanceClient:
     def list_with_measurements_and_steps(
         self, cell_spec_id: str
     ) -> CellSpecificationInstancesWithSteps:
-        """
-        List all instances, measurements, and steps for a cell specification.
+        """List all instances, measurements, and steps for a cell specification.
+
         Returns normalized data: separate lists for specification, instances,
         measurements, and steps.
         """
@@ -195,7 +205,3 @@ class CellInstanceClient:
             raise ValueError(f"Response validation failed for {endpoint}: {e}") from e
         except Exception as e:
             raise RuntimeError(f"API call to {endpoint} failed: {e}") from e
-
-
-class CellMeasurementClient:
-    pass