micantis 1.2.3__tar.gz → 1.2.5__tar.gz

{micantis-1.2.3 → micantis-1.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: micantis
-Version: 1.2.3
+Version: 1.2.5
 Summary: Package to simplify Micantis API usage
 Author-email: Mykela DeLuca <mykela.deluca@micantis.io>
 License-Expression: MIT
@@ -548,6 +548,55 @@ assert result.success, result.errors
 
 > **Rename rules:** CellTest names must be unique and may only contain letters, digits, and `_ - . ( ) space`. CellData names must be unique; renaming a CellData also auto-updates the owning CellTest's DataSourceKey.
 
+## Write Data Metadata
+Assign or update metadata on a **data set** (CellData record), the same way as cells, using either:
+- the built-in field `"name"` (renames the data set) or `"dataSourceKey"`
+- the human-readable field name of a user-defined property (e.g., "Active Cycle Test?")
+- or the internal propertyDefinitionId (UUID)
+
+User-defined property names are resolved against the data-set metadata definitions, which you can list with `api.list_data_metadata_definitions()`.
+
+**Per-entity atomic:** all changes targeting a single data set commit or rollback together; other data sets are unaffected. Returns a `BatchUpdateResult` with `.success` and `.errors`, identical to `write_cell_metadata`.
+
+#### 📘 Examples
+
+```python
+# Example 1: Set a user-defined property on specific data sets
+changes = [
+    {"id": "your-cell-data-guid-here", "field": "Active Cycle Test?", "value": True},
+]
+
+result = api.write_data_metadata(changes=changes)
+if not result:
+    for e in result.errors:
+        print(f"{e['itemId']}: {e['error']}")
+```
+
+```python
+# Example 2: Rename a data set and update its dataSourceKey
+changes = [
+    {"id": "your-cell-data-guid-here", "field": "name", "value": "Formation_Run_42"},
+    {"id": "your-cell-data-guid-here", "field": "dataSourceKey", "value": "Formation"},
+]
+
+result = api.write_data_metadata(changes=changes)
+assert result.success, result.errors
+```
+
+```python
+# Example 3: Update using propertyDefinitionId (advanced)
+changes = [
+    {
+        "id": "your-cell-data-guid-here",
+        "propertyDefinitionId": "your-property-definition-guid",
+        "value": "true"
+    }
+]
+
+result = api.write_data_metadata(changes=changes)
+assert result.success, result.errors
+```
+
 ## Stitch Data
 Combine multiple data sets into a single stitched data set. This is useful for creating continuous test data from multiple separate test runs.
 
@@ -964,14 +1013,16 @@ for group in dupes:
 Attach an output file (PNG, CSV, XLSX, etc.) to a running or completed Python script execution. Called from within a Python script running in the Micantis environment.
 
 #### Parameters
-- `execution_id`: **str (required)**
-  The execution ID (GUID) of the running or completed execution
+- `execution_id`: **str (optional inside cloud executions)**
+  The execution ID (GUID) of the running or completed execution. Defaults to the `WORKBOOK_EXECUTION_ID` environment variable, which cloud executions always set; required when running elsewhere. A non-GUID first positional argument is treated as `file_path`
 - `file_path`: **str (required)**
   Local path to the file to upload. Maximum size: 50 MB
 - `title`: **str (required)**
   Human-readable title for the artifact
 - `filename`: **str (optional)**
   Override the filename stored on the server. If not provided, derived from the title and file extension
+- `mime`: **str (optional)**
+  Content type stored for the artifact (e.g. `image/png`). If not provided, guessed from the file extension, falling back to `application/octet-stream`
 
 #### Returns
 - Dictionary with `'name'`, `'title'`, `'contentType'`, and `'sizeBytes'`
@@ -979,22 +1030,19 @@ Attach an output file (PNG, CSV, XLSX, etc.) to a running or completed Python sc
 #### 📘 Examples
 
 ```python
-# Upload a plot generated during a Python execution
-result = api.upload_execution_artifact(
-    execution_id="your-execution-guid",
-    file_path="voltage_plot.png",
-    title="Voltage vs Time"
-)
+# Inside a cloud execution — execution_id is resolved from the environment
+result = api.upload_execution_artifact("voltage_plot.png", title="Voltage vs Time")
 print(f"Uploaded: {result['name']} ({result['sizeBytes']:,} bytes)")
 ```
 
 ```python
-# Upload a CSV results file with a custom filename
+# Explicit execution ID with a custom filename and content type
 result = api.upload_execution_artifact(
     execution_id="your-execution-guid",
     file_path="results.csv",
     title="Cycle Summary Results",
-    filename="cycle_summary_2025.csv"
+    filename="cycle_summary_2025.csv",
+    mime="text/csv"
 )
 ```
 

{micantis-1.2.3 → micantis-1.2.5}/README.md

@@ -528,6 +528,55 @@ assert result.success, result.errors
 
 > **Rename rules:** CellTest names must be unique and may only contain letters, digits, and `_ - . ( ) space`. CellData names must be unique; renaming a CellData also auto-updates the owning CellTest's DataSourceKey.
 
+## Write Data Metadata
+Assign or update metadata on a **data set** (CellData record), the same way as cells, using either:
+- the built-in field `"name"` (renames the data set) or `"dataSourceKey"`
+- the human-readable field name of a user-defined property (e.g., "Active Cycle Test?")
+- or the internal propertyDefinitionId (UUID)
+
+User-defined property names are resolved against the data-set metadata definitions, which you can list with `api.list_data_metadata_definitions()`.
+
+**Per-entity atomic:** all changes targeting a single data set commit or rollback together; other data sets are unaffected. Returns a `BatchUpdateResult` with `.success` and `.errors`, identical to `write_cell_metadata`.
+
+#### 📘 Examples
+
+```python
+# Example 1: Set a user-defined property on specific data sets
+changes = [
+    {"id": "your-cell-data-guid-here", "field": "Active Cycle Test?", "value": True},
+]
+
+result = api.write_data_metadata(changes=changes)
+if not result:
+    for e in result.errors:
+        print(f"{e['itemId']}: {e['error']}")
+```
+
+```python
+# Example 2: Rename a data set and update its dataSourceKey
+changes = [
+    {"id": "your-cell-data-guid-here", "field": "name", "value": "Formation_Run_42"},
+    {"id": "your-cell-data-guid-here", "field": "dataSourceKey", "value": "Formation"},
+]
+
+result = api.write_data_metadata(changes=changes)
+assert result.success, result.errors
+```
+
+```python
+# Example 3: Update using propertyDefinitionId (advanced)
+changes = [
+    {
+        "id": "your-cell-data-guid-here",
+        "propertyDefinitionId": "your-property-definition-guid",
+        "value": "true"
+    }
+]
+
+result = api.write_data_metadata(changes=changes)
+assert result.success, result.errors
+```
+
 ## Stitch Data
 Combine multiple data sets into a single stitched data set. This is useful for creating continuous test data from multiple separate test runs.
 
@@ -944,14 +993,16 @@ for group in dupes:
 Attach an output file (PNG, CSV, XLSX, etc.) to a running or completed Python script execution. Called from within a Python script running in the Micantis environment.
 
 #### Parameters
-- `execution_id`: **str (required)**
-  The execution ID (GUID) of the running or completed execution
+- `execution_id`: **str (optional inside cloud executions)**
+  The execution ID (GUID) of the running or completed execution. Defaults to the `WORKBOOK_EXECUTION_ID` environment variable, which cloud executions always set; required when running elsewhere. A non-GUID first positional argument is treated as `file_path`
 - `file_path`: **str (required)**
   Local path to the file to upload. Maximum size: 50 MB
 - `title`: **str (required)**
   Human-readable title for the artifact
 - `filename`: **str (optional)**
   Override the filename stored on the server. If not provided, derived from the title and file extension
+- `mime`: **str (optional)**
+  Content type stored for the artifact (e.g. `image/png`). If not provided, guessed from the file extension, falling back to `application/octet-stream`
 
 #### Returns
 - Dictionary with `'name'`, `'title'`, `'contentType'`, and `'sizeBytes'`
@@ -959,22 +1010,19 @@ Attach an output file (PNG, CSV, XLSX, etc.) to a running or completed Python sc
 #### 📘 Examples
 
 ```python
-# Upload a plot generated during a Python execution
-result = api.upload_execution_artifact(
-    execution_id="your-execution-guid",
-    file_path="voltage_plot.png",
-    title="Voltage vs Time"
-)
+# Inside a cloud execution — execution_id is resolved from the environment
+result = api.upload_execution_artifact("voltage_plot.png", title="Voltage vs Time")
 print(f"Uploaded: {result['name']} ({result['sizeBytes']:,} bytes)")
 ```
 
 ```python
-# Upload a CSV results file with a custom filename
+# Explicit execution ID with a custom filename and content type
 result = api.upload_execution_artifact(
     execution_id="your-execution-guid",
     file_path="results.csv",
     title="Cycle Summary Results",
-    filename="cycle_summary_2025.csv"
+    filename="cycle_summary_2025.csv",
+    mime="text/csv"
 )
 ```
 

{micantis-1.2.3 → micantis-1.2.5}/micantis/api_wrapper.py

@@ -2,11 +2,15 @@ import requests
 import pandas as pd
 import io
 import json
+import mimetypes
 import os
 import re
 import time
+import tempfile
+import uuid
 from datetime import datetime, timedelta, timezone
 from typing import Optional
+from urllib.parse import quote
 from msal import PublicClientApplication
 from azure.identity import (
     ManagedIdentityCredential,
@@ -43,6 +47,26 @@ def _apply_field_overrides(action, voltage, current, charge_capacity,
             action[key] = val
 
 
+def _is_guid(value) -> bool:
+    """True if value parses as a GUID — the format of execution IDs."""
+    try:
+        uuid.UUID(str(value))
+        return True
+    except ValueError:
+        return False
+
+
+# Content types that must not depend on the host OS mime registry
+# (Windows maps .csv to application/vnd.ms-excel, stored as an opaque artifact).
+_MIME_OVERRIDES = {
+    ".csv": "text/csv",
+    ".json": "application/json",
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".svg": "image/svg+xml",
+}
+
+
 class BatchUpdateResult:
     """
     Result of a batch metadata update call (`write_cell_metadata` / `write_data_metadata`).
@@ -884,6 +908,59 @@ class MicantisAPI:
         except requests.exceptions.RequestException as e:
             raise self._format_request_error(e)
 
+    def list_data_metadata_definitions(self, return_format='df', timeout: int = 30):
+        """
+        Returns a list of cell data metadata types.
+
+        Parameters
+        ----------
+        return_format : str, optional
+            Return format: 'df' for DataFrame (default), anything else for raw list.
+        timeout : int, optional
+            Request timeout in seconds. Default: 30.
+        """
+        try:
+            return self._retry_on_auth_failure(
+                self._list_data_metadata_definitions, return_format, timeout
+            )
+        except Exception as e:
+            print(f"⚠️ list_data_metadata_definitions failed: {e}")
+            return None
+
+    def _list_data_metadata_definitions(self, return_format: str, timeout: int):
+        """
+        Internal helper for list_data_metadata_definitions. Does not handle retries or printing.
+
+        Raises
+        ------
+        RuntimeError
+            If the request fails or authentication is missing.
+        """
+        if not self.headers:
+            raise RuntimeError("Authentication required. Call authenticate() first.")
+
+        self._refresh_token_if_needed()
+
+        try:
+            # Make the GET request
+            response = self.session.get(
+                f"{self.service_url}/publicapi/v1/metadata/list/data",
+                headers=self.headers,
+                timeout=timeout,
+            )
+            response.raise_for_status()
+
+            item = response.json()
+            if return_format == 'df':
+                df = pd.DataFrame(item)
+                return df
+
+            else:
+                return item
+
+        except requests.exceptions.RequestException as e:
+            raise self._format_request_error(e)
+
     def get_cell_metadata(self, cell_ids: list, metadata: list = None, return_images: bool = False, timeout: int = 30):
         """
         Fetch metadata for specific cells, using either metadata names or IDs.
@@ -1144,9 +1221,14 @@ class MicantisAPI:
         """
         Wrapper for POST /data/updatemetadata endpoint.
 
-        Updates built-in metadata fields on cell data records. Supported built-in
-        fields are "name" and "dataSourceKey". User-defined metadata properties on
-        cell data are not yet supported via the public API.
+        Each change targets either a built-in field (supported: "name",
+        "dataSourceKey") or a user-defined metadata property. For user-defined
+        properties, pass either a human-readable 'field' name (resolved via
+        metadata definitions) or a 'propertyDefinitionId' UUID.
+
+        Built-in field names take precedence over user-defined names; if you have a
+        user-defined property literally named "name" or "dataSourceKey", use
+        propertyDefinitionId to disambiguate.
 
         Renaming a data set ("name" field) enforces name-uniqueness; the change is
         rejected if another data set already has the target name. The owning
@@ -1166,7 +1248,10 @@ class MicantisAPI:
         changes : list of dict
             A list of metadata change dictionaries. Each dictionary must contain:
             - "id": str (cell data GUID)
-            - "field": "name" or "dataSourceKey"
+            - One of:
+                - "field": "name" or "dataSourceKey" (built-in fields)
+                - "field": "<metadata name>" (user-defined, e.g. "Active Cycle Test?")
+                - "propertyDefinitionId": "<UUID>" (user-defined)
             - "value": any (will be cast to str)
 
         timeout : int, optional
@@ -1184,8 +1269,9 @@ class MicantisAPI:
         Examples
         --------
         >>> result = api.write_data_metadata([
-        ...     {"id": cell_data_id, "field": "name",          "value": "Formation_Run_42"},
-        ...     {"id": cell_data_id, "field": "dataSourceKey", "value": "Formation"},
+        ...     {"id": cell_data_id, "field": "name",               "value": "Formation_Run_42"},
+        ...     {"id": cell_data_id, "field": "dataSourceKey",      "value": "Formation"},
+        ...     {"id": cell_data_id, "field": "Active Cycle Test?", "value": True},
         ... ])
         >>> if not result:
         ...     for e in result.errors:
@@ -1203,20 +1289,35 @@ class MicantisAPI:
 
         self._refresh_token_if_needed()
 
+        # Only look up user-property definitions if at least one change uses a 'field' that
+        # isn't a built-in (lookup is a separate round-trip and unnecessary otherwise).
+        needs_lookup = any(
+            "field" in change and change["field"] not in self._BUILTIN_DATA_METADATA_FIELDS
+            for change in changes
+        )
+        if needs_lookup:
+            metadata_df = self._list_data_metadata_definitions('df', timeout)
+            name_to_id = dict(zip(metadata_df['name'], metadata_df['id']))
+        else:
+            name_to_id = {}
+
         formatted_changes = []
         for change in changes:
-            field = change.get("field")
-            if field not in self._BUILTIN_DATA_METADATA_FIELDS:
-                supported = ", ".join(f'"{f}"' for f in sorted(self._BUILTIN_DATA_METADATA_FIELDS))
-                raise RuntimeError(
-                    f"write_data_metadata only supports built-in fields ({supported}). "
-                    f"Got field={field!r}."
-                )
-            formatted_changes.append({
-                "id": change["id"],
-                "field": field,
-                "value": str(change["value"]),
-            })
+            item = {"id": change["id"], "value": str(change["value"])}
+
+            if "field" in change and change["field"] in self._BUILTIN_DATA_METADATA_FIELDS:
+                item["field"] = change["field"]
+            elif "propertyDefinitionId" in change:
+                item["propertyDefinitionId"] = change["propertyDefinitionId"]
+            elif "field" in change:
+                field_name = change["field"]
+                if field_name not in name_to_id:
+                    raise RuntimeError(f"Field name '{field_name}' not found in metadata definitions.")
+                item["propertyDefinitionId"] = name_to_id[field_name]
+            else:
+                raise RuntimeError("Each change must include either 'field' or 'propertyDefinitionId'.")
+
+            formatted_changes.append(item)
 
         payload = {"changes": formatted_changes}
 
@@ -2213,6 +2314,111 @@ class MicantisAPI:
                                cycle, step_kind, step_index)
         return action
 
+    @staticmethod
+    def rename_column(source_column_index, new_name, name=None):
+        """Build a rename-column action for clean_data (MetadataEdit mode).
+
+        Rename a column's display Name — what graphs, tables, and reports look up
+        by YAxisName. Targets the ORIGINAL source column index; action order does
+        not shift index meaning.
+
+        Parameters
+        ----------
+        source_column_index : int
+            0-based index into the ORIGINAL source column list.
+        new_name : str
+            New display name. Preserve exact spacing / punctuation expected by
+            downstream lookups (e.g. "Temp  1 (C)" with two spaces).
+        name : str, optional
+            Descriptive name for this action.
+        """
+        action = {"$type": "rename",
+                  "sourceColumnIndex": int(source_column_index),
+                  "newName": new_name}
+        if name is not None:
+            action["name"] = name
+        return action
+
+    @staticmethod
+    def change_column_kind(source_column_index, new_kind, name=None):
+        """Build a change-column-kind action for clean_data (MetadataEdit mode).
+
+        Change a column's YAxisKind (cycle-tester aux) or ImportItemKind (logger)
+        — controls which kind-based lookups match the column. Targets the ORIGINAL
+        source column index.
+
+        Parameters
+        ----------
+        source_column_index : int
+            0-based index into the ORIGINAL source column list.
+        new_kind : str
+            Exact enum value name (e.g. 'Voltage', 'AuxTemperature').
+        name : str, optional
+            Descriptive name for this action.
+        """
+        action = {"$type": "kind",
+                  "sourceColumnIndex": int(source_column_index),
+                  "newKind": new_kind}
+        if name is not None:
+            action["name"] = name
+        return action
+
+    @staticmethod
+    def reorder_columns(source_column_indices, name=None):
+        """Build a reorder-columns action for clean_data (MetadataEdit mode).
+
+        Declarative final column layout: source columns appear in the cleaned
+        output in the order listed; any source index not listed is dropped.
+        Combines drop + reorder in one action. At most one per definition.
+
+        Parameters
+        ----------
+        source_column_indices : list[int]
+            Ordered list of 0-based source column indices to keep. Omit an index
+            to drop that column. Example: [0, 1, 3, 4, 5] drops source column 2.
+        name : str, optional
+            Descriptive name for this action.
+        """
+        action = {"$type": "reorderColumns",
+                  "sourceColumnIndices": [int(i) for i in source_column_indices]}
+        if name is not None:
+            action["name"] = name
+        return action
+
+    @staticmethod
+    def edit_logger_step(line=None, lines=None, columns=None, name=None):
+        """Build an edit-logger-timestep action for clean_data (logger-data analog of modify_step/bulk_modify).
+
+        Edit column values by 0-based column index on rows matched by ``line`` and/or
+        ``lines`` (union). Use on DataLoggerData sources only; for cycle-tester data
+        use modify_step / bulk_modify.
+
+        Parameters
+        ----------
+        line : int, optional
+            Single line number to edit.
+        lines : list of (int, int) tuples, optional
+            Line number ranges to edit, e.g. [(100, 200)]. End may be None for open-ended.
+        columns : dict of {int: float}
+            Column edits as {column_index: value}. Column index is 0-based and
+            must refer to a valid column in the source ImportDefinition.
+        name : str, optional
+            Descriptive name for this action.
+        """
+        if line is None and not lines:
+            raise ValueError("edit_logger_step requires either line or lines.")
+        if not columns:
+            raise ValueError("edit_logger_step requires columns.")
+        action = {"$type": "editLogger"}
+        if name is not None:
+            action["name"] = name
+        if line is not None:
+            action["lineNumber"] = line
+        if lines:
+            action["lineNumberRanges"] = _ranges(lines)
+        action["columns"] = [{"columnIndex": int(k), "value": float(v)} for k, v in columns.items()]
+        return action
+
     def clean_data(self,
                    source_ids: list,
                    mode: str = 'CycleAutoFixup',
@@ -2231,14 +2437,19 @@ class MicantisAPI:
         source_ids : list of str
             List of cell data IDs (GUIDs) to clean.
         mode : str, optional
-            Cleaning mode. One of 'CycleAutoFixup', 'FilterCycles', 'Parametric'.
-            Default: 'CycleAutoFixup'. Auto-set to 'Parametric' when actions is provided.
+            Cleaning mode. One of 'CycleAutoFixup', 'FilterCycles', 'Parametric', 'MetadataEdit'.
+            Default: 'CycleAutoFixup'. When ``actions`` is provided and mode is still the default,
+            it auto-sets to 'Parametric'. For 'MetadataEdit', pass mode explicitly.
         filter_cycles_definition : dict, optional
             Required when mode is 'FilterCycles'. Definition for filtering cycles.
         actions : list, optional
-            List of action dicts built with api.remove_steps(),
-            api.modify_step(), and/or api.bulk_modify().
-            Auto-sets mode to 'Parametric'. Example::
+            For Parametric mode: list of dicts from api.remove_steps(), api.modify_step(),
+            api.bulk_modify(), api.edit_logger_step().
+            For MetadataEdit mode: list of dicts from api.rename_column(),
+            api.change_column_kind(), api.reorder_columns().
+            Actions are applied in the order given.
+
+            Parametric example (cycle-tester)::
 
                 api.clean_data(
                     source_ids=[id],
@@ -2248,6 +2459,29 @@ class MicantisAPI:
                         api.bulk_modify(lines=[(100, 5000)], cycle=1),
                     ]
                 )
+
+            Parametric example (DataLoggerData)::
+
+                api.clean_data(
+                    source_ids=[logger_id],
+                    actions=[
+                        api.remove_steps(lines=[(1, 3)]),
+                        api.edit_logger_step(line=10, columns={0: 1.5}),
+                    ]
+                )
+
+            MetadataEdit example (rename + drop — works on both CT and logger)::
+
+                api.clean_data(
+                    source_ids=[id],
+                    mode='MetadataEdit',
+                    actions=[
+                        api.rename_column(source_column_index=3, new_name='Temp  1 (C)'),
+                        api.rename_column(source_column_index=4, new_name='Temp  2 (C)'),
+                        api.rename_column(source_column_index=5, new_name='Temp  3 (C)'),
+                        api.reorder_columns([0, 1, 3, 4, 5]),  # drops source column 2
+                    ]
+                )
         allow_async : bool, optional
             If True, runs asynchronously and returns job ID. Default: False.
         timeout : int, optional
@@ -2260,7 +2494,8 @@ class MicantisAPI:
             If allow_async is True: {'job_id': str}
             Returns None if an error occurs.
         """
-        if actions is not None:
+        # Auto-set mode only if the caller left the default; preserves explicit 'MetadataEdit' etc.
+        if actions is not None and mode == 'CycleAutoFixup':
             mode = 'Parametric'
 
         try:
@@ -2291,8 +2526,10 @@ class MicantisAPI:
 
         if mode == 'Parametric' and not actions:
             raise ValueError("actions is required when mode is 'Parametric'.")
+        if mode == 'MetadataEdit' and not actions:
+            raise ValueError("actions is required when mode is 'MetadataEdit'.")
 
-        _mode_map = {'CycleAutoFixup': 1, 'Parametric': 2, 'FilterCycles': 4}
+        _mode_map = {'CycleAutoFixup': 1, 'Parametric': 2, 'FilterCycles': 4, 'MetadataEdit': 5}
         if mode not in _mode_map:
             raise ValueError(f"mode must be one of {list(_mode_map)}, got '{mode}'")
 
@@ -2304,7 +2541,10 @@ class MicantisAPI:
         if filter_cycles_definition is not None:
             payload["filterCyclesDefinition"] = filter_cycles_definition
         if actions is not None:
-            payload["parametricDefinition"] = {"actions": actions}
+            if mode == 'MetadataEdit':
+                payload["metadataEditDefinition"] = {"actions": actions}
+            else:
+                payload["parametricDefinition"] = {"actions": actions}
 
         url = f"{self.service_url}/publicapi/v1/data/clean"
         if allow_async:
@@ -2578,21 +2818,34 @@ class MicantisAPI:
             raise self._format_request_error(e)
 
     def upload_execution_artifact(self,
-                                  execution_id: str,
-                                  file_path: str,
-                                  title: str,
+                                  execution_id: str = None,
+                                  file_path: str = None,
+                                  title: str = None,
                                   filename: str = None,
-                                  timeout: int = 120) -> dict:
+                                  timeout: int = 120,
+                                  mime: str = None) -> dict:
         """
         Upload an artifact (output file) produced by a running Python execution.
 
+        Inside a cloud execution, execution_id can be omitted — it is resolved
+        from the WORKBOOK_EXECUTION_ID environment variable, which the runner
+        always sets. The natural call shape there is::
+
+            api.upload_execution_artifact('/tmp/plot.png', title='My Plot')
+
+        A first positional argument that is not a GUID is treated as file_path
+        (when file_path is not also given), so the line above works even though
+        the first parameter is execution_id.
+
         Automatically reauthenticates if the session is expired or missing.
         Prints an error message and returns None if the request ultimately fails.
 
         Parameters
         ----------
-        execution_id : str
+        execution_id : str, optional
             The execution ID (GUID) of the running or completed Python execution.
+            Defaults to the WORKBOOK_EXECUTION_ID environment variable (always
+            set inside cloud executions). Required when running outside one.
         file_path : str
             Local path to the file to upload (PNG, CSV, XLSX, JSON, PDF, etc.).
             Maximum file size: 50 MB.
@@ -2603,6 +2856,10 @@ class MicantisAPI:
             from the title and file extension.
         timeout : int, optional
             Request timeout in seconds. Default: 120.
+        mime : str, optional
+            Content type stored for the artifact (e.g. 'image/png'). If not
+            provided, guessed from the file_path extension, falling back to
+            'application/octet-stream'.
 
         Returns
         -------
@@ -2618,6 +2875,7 @@ class MicantisAPI:
                 title,
                 filename,
                 timeout,
+                mime,
             )
         except Exception as e:
             print(f"⚠️ upload_execution_artifact failed: {e}")
@@ -2628,28 +2886,61 @@ class MicantisAPI:
                                    file_path: str,
                                    title: str,
                                    filename: str,
-                                   timeout: int) -> dict:
+                                   timeout: int,
+                                   mime: str) -> dict:
         """
         Internal helper for upload_execution_artifact. Does not handle retries or printing.
 
         Raises
         ------
         RuntimeError
-            If the request fails or authentication is missing.
+            If arguments are missing or invalid, the request fails, or
+            authentication is missing.
         """
         if not self.headers:
             raise RuntimeError("Authentication required. Call authenticate() first.")
 
         self._refresh_token_if_needed()
 
+        # Forgive the natural call shape api.upload_execution_artifact('/tmp/plot.png', title=...):
+        # a non-GUID first argument is the file path, and the execution ID comes from the environment.
+        if execution_id is not None and not _is_guid(execution_id):
+            if file_path is None:
+                file_path = execution_id
+                execution_id = None
+            else:
+                raise RuntimeError(
+                    f"execution_id '{execution_id}' is not an execution GUID. Inside a cloud "
+                    "execution you can omit execution_id entirely — it is read from the "
+                    "WORKBOOK_EXECUTION_ID environment variable automatically."
+                )
+
+        if execution_id is None:
+            execution_id = os.environ.get("WORKBOOK_EXECUTION_ID")
+            if not execution_id:
+                raise RuntimeError(
+                    "No execution_id provided and WORKBOOK_EXECUTION_ID is not set. Inside a "
+                    "cloud execution the variable is set automatically; outside one, pass "
+                    "execution_id explicitly."
+                )
+
+        if not file_path:
+            raise RuntimeError("file_path is required.")
+        if not title:
+            raise RuntimeError("title is required.")
+
         url = f"{self.service_url}/publicapi/v1/python/executions/{execution_id}/artifacts"
 
+        ext = os.path.splitext(file_path)[1].lower()
+        content_type = (mime or _MIME_OVERRIDES.get(ext)
+                        or mimetypes.guess_type(file_path)[0] or "application/octet-stream")
+
         try:
             with open(file_path, 'rb') as f:
                 form_data = {'title': (None, title)}
                 if filename is not None:
                     form_data['filename'] = (None, filename)
-                form_data['file'] = (os.path.basename(file_path), f)
+                form_data['file'] = (os.path.basename(file_path), f, content_type)
 
                 # Exclude Content-Type so requests sets the multipart boundary correctly
                 headers = {k: v for k, v in self.headers.items() if k.lower() != 'content-type'}
@@ -2666,6 +2957,114 @@ class MicantisAPI:
         except requests.exceptions.RequestException as e:
             raise self._format_request_error(e)
 
+    def list_attachments(self, timeout: int = 30) -> list:
+        """
+        List the files attached to the Moose conversation that launched this script.
+
+        Only works inside a Moose-triggered cloud execution (uses WORKBOOK_EXECUTION_ID).
+        Automatically reauthenticates if the session is expired or missing. Prints an error
+        and returns None on failure.
+
+        Returns
+        -------
+        list of dict or None
+            One entry per attachment: {"name", "contentType", "sizeBytes"}.
+        """
+        try:
+            return self._retry_on_auth_failure(self._list_attachments, timeout)
+        except Exception as e:
+            print(f"⚠️ list_attachments failed: {e}")
+            return None
+
+    def _list_attachments(self, timeout: int) -> list:
+        if not self.headers:
+            raise RuntimeError("Authentication required. Call authenticate() first.")
+        self._refresh_token_if_needed()
+
+        execution_id = os.environ.get("WORKBOOK_EXECUTION_ID")
+        if not execution_id:
+            raise RuntimeError(
+                "list_attachments is only available inside a cloud execution (WORKBOOK_EXECUTION_ID is not set)."
+            )
+
+        try:
+            r = self.session.get(
+                f"{self.service_url}/publicapi/v1/python/executions/{execution_id}/attachments",
+                headers=self.headers,
+                timeout=timeout,
+            )
+            r.raise_for_status()
+            return r.json()
+        except requests.exceptions.RequestException as e:
+            raise self._format_request_error(e)
+
+    def download_attachment(self, name: str, output_path: str = None,
+                            return_type: str = "bytes", timeout: int = 120):
+        """
+        Download a file attached to the Moose conversation that launched this script, by name,
+        WITHOUT inlining its bytes into your script source. Use this for any conversation
+        attachment too large to paste in — inlining data into the script is bounded by the
+        per-turn output budget (a few KB), but this streams the file into the container.
+
+        Only works inside a Moose-triggered cloud execution (uses WORKBOOK_EXECUTION_ID). Call
+        list_attachments() first to get exact names. Automatically reauthenticates if the
+        session is expired or missing. Prints an error and returns None on failure.
+
+        Parameters
+        ----------
+        name : str
+            Exact attachment filename (from list_attachments()).
+        output_path : str, optional
+            Where to save the file when return_type='path'. Defaults to a temp file.
+        return_type : str, optional
+            'bytes' (default) returns the raw bytes; 'path' writes the file to disk and returns
+            the path (best for large files); 'text' returns a UTF-8-decoded str.
+        timeout : int, optional
+            Request timeout in seconds. Default: 120.
+
+        Returns
+        -------
+        bytes | str | None
+            The attachment content per return_type, or None on failure.
+        """
+        try:
+            return self._retry_on_auth_failure(
+                self._download_attachment, name, output_path, return_type, timeout)
+        except Exception as e:
+            print(f"⚠️ download_attachment failed: {e}")
+            return None
+
+    def _download_attachment(self, name: str, output_path: str, return_type: str, timeout: int):
+        if not self.headers:
+            raise RuntimeError("Authentication required. Call authenticate() first.")
+        self._refresh_token_if_needed()
+
+        execution_id = os.environ.get("WORKBOOK_EXECUTION_ID")
+        if not execution_id:
+            raise RuntimeError(
+                "download_attachment is only available inside a cloud execution (WORKBOOK_EXECUTION_ID is not set)."
+            )
+
+        url = (f"{self.service_url}/publicapi/v1/python/executions/{execution_id}"
+               f"/attachments/{quote(name)}")
+
+        try:
+            with self.session.get(url, headers=self.headers, timeout=timeout, stream=True) as r:
+                r.raise_for_status()
+                if return_type == "path":
+                    path = output_path or os.path.join(tempfile.gettempdir(), os.path.basename(name))
+                    with open(path, "wb") as f:
+                        for chunk in r.iter_content(chunk_size=1024 * 1024):
+                            if chunk:
+                                f.write(chunk)
+                    return path
+                content = r.content
+                if return_type == "text":
+                    return content.decode("utf-8", errors="replace")
+                return content
+        except requests.exceptions.RequestException as e:
+            raise self._format_request_error(e)
+
     # ─────────────────────────────────────────
     # Job management (async operation polling)
     # ─────────────────────────────────────────

{micantis-1.2.3 → micantis-1.2.5}/micantis.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: micantis
-Version: 1.2.3
+Version: 1.2.5
 Summary: Package to simplify Micantis API usage
 Author-email: Mykela DeLuca <mykela.deluca@micantis.io>
 License-Expression: MIT
@@ -548,6 +548,55 @@ assert result.success, result.errors
 
 > **Rename rules:** CellTest names must be unique and may only contain letters, digits, and `_ - . ( ) space`. CellData names must be unique; renaming a CellData also auto-updates the owning CellTest's DataSourceKey.
 
+## Write Data Metadata
+Assign or update metadata on a **data set** (CellData record), the same way as cells, using either:
+- the built-in field `"name"` (renames the data set) or `"dataSourceKey"`
+- the human-readable field name of a user-defined property (e.g., "Active Cycle Test?")
+- or the internal propertyDefinitionId (UUID)
+
+User-defined property names are resolved against the data-set metadata definitions, which you can list with `api.list_data_metadata_definitions()`.
+
+**Per-entity atomic:** all changes targeting a single data set commit or rollback together; other data sets are unaffected. Returns a `BatchUpdateResult` with `.success` and `.errors`, identical to `write_cell_metadata`.
+
+#### 📘 Examples
+
+```python
+# Example 1: Set a user-defined property on specific data sets
+changes = [
+    {"id": "your-cell-data-guid-here", "field": "Active Cycle Test?", "value": True},
+]
+
+result = api.write_data_metadata(changes=changes)
+if not result:
+    for e in result.errors:
+        print(f"{e['itemId']}: {e['error']}")
+```
+
+```python
+# Example 2: Rename a data set and update its dataSourceKey
+changes = [
+    {"id": "your-cell-data-guid-here", "field": "name", "value": "Formation_Run_42"},
+    {"id": "your-cell-data-guid-here", "field": "dataSourceKey", "value": "Formation"},
+]
+
+result = api.write_data_metadata(changes=changes)
+assert result.success, result.errors
+```
+
+```python
+# Example 3: Update using propertyDefinitionId (advanced)
+changes = [
+    {
+        "id": "your-cell-data-guid-here",
+        "propertyDefinitionId": "your-property-definition-guid",
+        "value": "true"
+    }
+]
+
+result = api.write_data_metadata(changes=changes)
+assert result.success, result.errors
+```
+
 ## Stitch Data
 Combine multiple data sets into a single stitched data set. This is useful for creating continuous test data from multiple separate test runs.
 
@@ -964,14 +1013,16 @@ for group in dupes:
 Attach an output file (PNG, CSV, XLSX, etc.) to a running or completed Python script execution. Called from within a Python script running in the Micantis environment.
 
 #### Parameters
-- `execution_id`: **str (required)**
-  The execution ID (GUID) of the running or completed execution
+- `execution_id`: **str (optional inside cloud executions)**
+  The execution ID (GUID) of the running or completed execution. Defaults to the `WORKBOOK_EXECUTION_ID` environment variable, which cloud executions always set; required when running elsewhere. A non-GUID first positional argument is treated as `file_path`
 - `file_path`: **str (required)**
   Local path to the file to upload. Maximum size: 50 MB
 - `title`: **str (required)**
   Human-readable title for the artifact
 - `filename`: **str (optional)**
   Override the filename stored on the server. If not provided, derived from the title and file extension
+- `mime`: **str (optional)**
+  Content type stored for the artifact (e.g. `image/png`). If not provided, guessed from the file extension, falling back to `application/octet-stream`
 
 #### Returns
 - Dictionary with `'name'`, `'title'`, `'contentType'`, and `'sizeBytes'`
@@ -979,22 +1030,19 @@ Attach an output file (PNG, CSV, XLSX, etc.) to a running or completed Python sc
 #### 📘 Examples
 
 ```python
-# Upload a plot generated during a Python execution
-result = api.upload_execution_artifact(
-    execution_id="your-execution-guid",
-    file_path="voltage_plot.png",
-    title="Voltage vs Time"
-)
+# Inside a cloud execution — execution_id is resolved from the environment
+result = api.upload_execution_artifact("voltage_plot.png", title="Voltage vs Time")
 print(f"Uploaded: {result['name']} ({result['sizeBytes']:,} bytes)")
 ```
 
 ```python
-# Upload a CSV results file with a custom filename
+# Explicit execution ID with a custom filename and content type
 result = api.upload_execution_artifact(
     execution_id="your-execution-guid",
     file_path="results.csv",
     title="Cycle Summary Results",
-    filename="cycle_summary_2025.csv"
+    filename="cycle_summary_2025.csv",
+    mime="text/csv"
 )
 ```
 

{micantis-1.2.3 → micantis-1.2.5}/micantis.egg-info/SOURCES.txt

@@ -9,4 +9,5 @@ micantis.egg-info/SOURCES.txt
 micantis.egg-info/dependency_links.txt
 micantis.egg-info/requires.txt
 micantis.egg-info/top_level.txt
-tests/test_batch_update_result.py
+tests/test_batch_update_result.py
+tests/test_upload_execution_artifact.py

{micantis-1.2.3 → micantis-1.2.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "micantis"
-version = "1.2.3"
+version = "1.2.5"
 description = "Package to simplify Micantis API usage"
 authors = [
     { name = "Mykela DeLuca", email = "mykela.deluca@micantis.io" }

{micantis-1.2.3 → micantis-1.2.5}/tests/test_batch_update_result.py

@@ -6,12 +6,14 @@ Mocks the HTTP layer so it can run anywhere without a live server. Exercises:
 - 207 Multi-Status → BatchUpdateResult(success=False, errors=[...])
 - 400 Bad Request → BatchUpdateResult(success=False, errors=[...])
 - Truthiness (`if result:` works)
-- Rejection of unknown fields (client-side validation)
+- User-property name resolution and propertyDefinitionId pass-through
 
 Run:  pytest
 """
 from unittest.mock import MagicMock
 
+import pandas as pd
+
 from micantis.api_wrapper import MicantisAPI, BatchUpdateResult
 
 
@@ -115,18 +117,55 @@ def test_write_data_207_returns_partial():
     print("PASS: data/updatemetadata 207 → partial")
 
 
-def test_write_data_rejects_unknown_field():
+def test_write_data_unknown_property_name_raises():
+    # A non-built-in field is treated as a user-property name and resolved against the
+    # CellData metadata definitions; a name with no matching definition raises.
     api = _make_api()
+    api._list_data_metadata_definitions = lambda return_format, timeout: pd.DataFrame(
+        {"name": ["Active Cycle Test?"], "id": ["def-1"]}
+    )
     try:
         api._write_data_metadata(
-            [{"id": "x", "field": "Technician", "value": "foo"}], timeout=5,
+            [{"id": "x", "field": "Nonexistent Property", "value": "foo"}], timeout=5,
         )
     except RuntimeError as e:
-        assert "Technician" in str(e)
-        assert "name" in str(e) and "dataSourceKey" in str(e)
-        print("PASS: data/updatemetadata rejects unknown field client-side")
+        assert "Nonexistent Property" in str(e)
+        assert "not found in metadata definitions" in str(e)
+        print("PASS: data/updatemetadata raises on unknown user-property name")
         return
-    raise AssertionError("expected RuntimeError on unknown field")
+    raise AssertionError("expected RuntimeError on unknown property name")
+
+
+def test_write_data_resolves_property_name():
+    # A user-property name is resolved to its definition ID and sent as propertyDefinitionId.
+    api = _make_api()
+    api._list_data_metadata_definitions = lambda return_format, timeout: pd.DataFrame(
+        {"name": ["Active Cycle Test?"], "id": ["def-1"]}
+    )
+    api.session.post.return_value = _mock_response(204)
+    result = api._write_data_metadata(
+        [{"id": "x", "field": "Active Cycle Test?", "value": True}], timeout=5,
+    )
+    assert result.success is True
+    sent = api.session.post.call_args.kwargs["json"]["changes"][0]
+    assert sent == {"id": "x", "value": "True", "propertyDefinitionId": "def-1"}
+    print("PASS: data/updatemetadata resolves user-property name → propertyDefinitionId")
+
+
+def test_write_data_accepts_property_definition_id():
+    # A propertyDefinitionId is forwarded directly, with no definitions lookup.
+    api = _make_api()
+    api._list_data_metadata_definitions = MagicMock(
+        side_effect=AssertionError("should not look up definitions when an id is supplied")
+    )
+    api.session.post.return_value = _mock_response(204)
+    result = api._write_data_metadata(
+        [{"id": "x", "propertyDefinitionId": "def-9", "value": "true"}], timeout=5,
+    )
+    assert result.success is True
+    sent = api.session.post.call_args.kwargs["json"]["changes"][0]
+    assert sent == {"id": "x", "value": "true", "propertyDefinitionId": "def-9"}
+    print("PASS: data/updatemetadata forwards propertyDefinitionId directly")
 
 
 def test_name_is_accepted_as_builtin():

micantis-1.2.5/tests/test_upload_execution_artifact.py

@@ -0,0 +1,110 @@
+"""
+Unit tests for upload_execution_artifact argument resolution and multipart content type.
+
+Mocks the HTTP layer so it can run anywhere without a live server. Exercises the
+four supported call shapes:
+- Path-only positional + title + mime → execution_id resolved from WORKBOOK_EXECUTION_ID
+- Classic positional (guid, path, title) → unchanged, content type guessed from extension
+- Full keyword form → unchanged
+- No execution_id anywhere and no env var → clear printed error, returns None
+
+Run:  pytest
+"""
+from .test_batch_update_result import _make_api, _mock_response
+
+EXEC_ID = "11111111-2222-3333-4444-555555555555"
+OTHER_EXEC_ID = "99999999-8888-7777-6666-555555555555"
+
+RESULT_BODY = {
+    "name": "plot.png",
+    "title": "My Plot",
+    "contentType": "image/png",
+    "sizeBytes": 9,
+}
+
+
+def test_path_first_positional_resolves_execution_id_from_env(monkeypatch, tmp_path):
+    # The natural cloud call shape: file path first, no execution_id anywhere.
+    api = _make_api()
+    api.session.post.return_value = _mock_response(200, RESULT_BODY)
+    monkeypatch.setenv("WORKBOOK_EXECUTION_ID", EXEC_ID)
+
+    png = tmp_path / "plot.png"
+    png.write_bytes(b"\x89PNG fake")
+
+    result = api.upload_execution_artifact(str(png), title="My Plot", mime="image/png")
+
+    assert result == RESULT_BODY
+    url = api.session.post.call_args.args[0]
+    assert url == f"https://fake.test/publicapi/v1/python/executions/{EXEC_ID}/artifacts"
+    name, fobj, content_type = api.session.post.call_args.kwargs["files"]["file"]
+    assert name == "plot.png"
+    assert content_type == "image/png"
+    print("PASS: path-first positional resolves WORKBOOK_EXECUTION_ID and sends mime")
+
+
+def test_classic_positional_shape_unchanged(monkeypatch, tmp_path):
+    # (execution_id, file_path, title) keeps working; explicit GUID wins over the env var,
+    # and the part content type is guessed from the file extension when mime is omitted.
+    api = _make_api()
+    api.session.post.return_value = _mock_response(200, RESULT_BODY)
+    monkeypatch.setenv("WORKBOOK_EXECUTION_ID", OTHER_EXEC_ID)
+
+    png = tmp_path / "voltage_profile.png"
+    png.write_bytes(b"\x89PNG fake")
+
+    result = api.upload_execution_artifact(EXEC_ID, str(png), "Voltage Profile")
+
+    assert result == RESULT_BODY
+    url = api.session.post.call_args.args[0]
+    assert url == f"https://fake.test/publicapi/v1/python/executions/{EXEC_ID}/artifacts"
+    name, fobj, content_type = api.session.post.call_args.kwargs["files"]["file"]
+    assert name == "voltage_profile.png"
+    assert content_type == "image/png"
+    print("PASS: classic positional (guid, path, title) unchanged; mime guessed from extension")
+
+
+def test_keyword_shape_unchanged(monkeypatch, tmp_path):
+    api = _make_api()
+    api.session.post.return_value = _mock_response(200, RESULT_BODY)
+    monkeypatch.delenv("WORKBOOK_EXECUTION_ID", raising=False)
+
+    csv = tmp_path / "results.csv"
+    csv.write_text("a,b\n1,2\n")
+
+    result = api.upload_execution_artifact(
+        execution_id=EXEC_ID,
+        file_path=str(csv),
+        title="Analysis Results",
+        filename="cycle_summary.csv",
+    )
+
+    assert result == RESULT_BODY
+    url = api.session.post.call_args.args[0]
+    assert url == f"https://fake.test/publicapi/v1/python/executions/{EXEC_ID}/artifacts"
+    files = api.session.post.call_args.kwargs["files"]
+    assert files["filename"] == (None, "cycle_summary.csv")
+    name, fobj, content_type = files["file"]
+    assert name == "results.csv"
+    # Pinned by _MIME_OVERRIDES, independent of the host OS mime registry.
+    assert content_type == "text/csv"
+    print("PASS: full keyword form unchanged; filename part still sent")
+
+
+def test_missing_execution_id_and_env_var_reports_clear_error(monkeypatch, tmp_path, capsys):
+    # Outside a cloud execution with no explicit execution_id: P-03 convention —
+    # print the real error (naming the env var) and return None, no HTTP call.
+    api = _make_api()
+    monkeypatch.delenv("WORKBOOK_EXECUTION_ID", raising=False)
+
+    csv = tmp_path / "out.csv"
+    csv.write_text("a,b\n")
+
+    result = api.upload_execution_artifact(file_path=str(csv), title="Out")
+
+    assert result is None
+    out = capsys.readouterr().out
+    assert "upload_execution_artifact failed" in out
+    assert "WORKBOOK_EXECUTION_ID" in out
+    api.session.post.assert_not_called()
+    print("PASS: missing execution_id + env var → clear error naming WORKBOOK_EXECUTION_ID")