iqm-station-control-client 4.1.0__tar.gz → 5.0.0__tar.gz

{iqm_station_control_client-4.1.0 → iqm_station_control_client-5.0.0}/CHANGELOG.rst

@@ -2,6 +2,23 @@
 Changelog
 =========
 
+Version 5.0.0 (2025-05-28)
+==========================
+
+Breaking changes
+----------------
+
+- :attr:`.JobData.job_error` now has separate fields for user error message and full error log, instead of only
+  containing the full error log. :issue:`SW-1179`
+
+Version 4.2.0 (2025-05-23)
+==========================
+
+Bug fixes
+---------
+
+- Use explicit UTF-8 encoding for JSON data in HTTP requests.
+
 Version 4.1.0 (2025-05-21)
 ==========================
 

{iqm_station_control_client-4.1.0/src/iqm_station_control_client.egg-info → iqm_station_control_client-5.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: iqm-station-control-client
-Version: 4.1.0
+Version: 5.0.0
 Summary: Python client for communicating with Station Control Service
 Author-email: IQM Finland Oy <info@meetiqm.com>
 License:                                  Apache License

{iqm_station_control_client-4.1.0 → iqm_station_control_client-5.0.0}/src/iqm/station_control/client/iqm_server/iqm_server_client.py

@@ -55,7 +55,7 @@ from iqm.station_control.interface.models import (
     SweepDefinition,
     SweepResults,
 )
-from iqm.station_control.interface.models.jobs import JobData, JobResult
+from iqm.station_control.interface.models.jobs import JobData, JobError, JobResult
 from iqm.station_control.interface.models.sweep import SweepBase
 
 logger = logging.getLogger(__name__)
@@ -169,7 +169,9 @@ class IqmServerClient(StationControlClient, metaclass=IqmServerClientMeta):
                     parallel_sweep_progress=[],
                     interrupted=False,
                 ),
-                job_error=job.error if job.HasField("error") else "",
+                job_error=JobError(full_error_log=job.error, user_error_message=job.error)
+                if job.HasField("error")
+                else None,
                 position=job.queue_position if job.HasField("queue_position") else None,
             )
 

{iqm_station_control_client-4.1.0 → iqm_station_control_client-5.0.0}/src/iqm/station_control/client/station_control.py

@@ -28,6 +28,7 @@ import uuid
 from iqm.models.channel_properties import ChannelProperties
 from opentelemetry import propagate, trace
 from packaging.version import Version, parse
+from pydantic import BaseModel
 import requests
 
 from exa.common.data.setting_node import SettingNode
@@ -159,7 +160,7 @@ class StationControlClient:
         self._qcm_data_client = QCMDataClient(qcm_url) if qcm_url else None
 
     @property
-    def version(self):
+    def version(self) -> str:
         """Return the version of the station control API this client is using."""
         return "v1"
 
@@ -220,8 +221,8 @@ class StationControlClient:
     def get_or_create_software_version_set(self, software_version_set: SoftwareVersionSet) -> int:
         """Get software version set ID from the database, or create if it doesn't exist."""
         # FIXME: We don't have information if the object was created or fetched. Thus, server always responds 200 (OK).
-        data = json.dumps(software_version_set)
-        response = self._send_request(requests.post, "software-version-sets", data=data)
+        json_str = json.dumps(software_version_set)
+        response = self._send_request(requests.post, "software-version-sets", json_str=json_str)
         return int(response.content)
 
     def get_settings(self) -> SettingNode:
@@ -230,7 +231,7 @@ class StationControlClient:
 
     @cache
     def _get_cached_settings(self) -> SettingNode:
-        response = self._send_request(requests.get, "settings", headers={"Content-Type": "application/octet-stream"})
+        response = self._send_request(requests.get, "settings")
         return deserialize_setting_node(response.content)
 
     @cache
@@ -286,8 +287,7 @@ class StationControlClient:
 
         """
         data = serialize_sweep_job_request(sweep_definition, queue_name="sweeps")
-        headers = {"Content-Type": "application/octet-stream"}
-        return self._send_request(requests.post, "sweeps", data=data, headers=headers).json()
+        return self._send_request(requests.post, "sweeps", octets=data).json()
 
     def get_sweep(self, sweep_id: uuid.UUID) -> SweepData:
         """Get N-dimensional sweep data from the database."""
@@ -320,8 +320,7 @@ class StationControlClient:
         """Execute an N-dimensional sweep of selected variables and save run, sweep and results."""
         data = serialize_run_job_request(run_definition, queue_name="sweeps")
 
-        headers = {"Content-Type": "application/octet-stream"}
-        response = self._send_request(requests.post, "runs", data=data, headers=headers)
+        response = self._send_request(requests.post, "runs", octets=data)
         if wait_job_completion:
             return self._wait_job_completion(response.json()["job_id"], update_progress_callback)
         return False
@@ -378,8 +377,8 @@ class StationControlClient:
             Created observations, each including also the database created fields like ID and timestamps.
 
         """
-        data = ObservationDefinitionList(observation_definitions).model_dump_json()
-        response = self._send_request(requests.post, "observations", data=data)
+        json_str = self._serialize_model(ObservationDefinitionList(observation_definitions))
+        response = self._send_request(requests.post, "observations", json_str=json_str)
         return self._create_list_with_meta(response, ObservationDataList)
 
     def get_observations(
@@ -477,8 +476,8 @@ class StationControlClient:
             Updated observations, each including also the database created fields like ID and timestamps.
 
         """
-        data = ObservationUpdateList(observation_updates).model_dump_json()
-        response = self._send_request(requests.patch, "observations", data=data)
+        json_str = self._serialize_model(ObservationUpdateList(observation_updates))
+        response = self._send_request(requests.patch, "observations", json_str=json_str)
         return ObservationDataList.model_validate(response.json())
 
     def query_observation_sets(self, **kwargs) -> ListWithMeta[ObservationSetData]:
@@ -519,8 +518,8 @@ class StationControlClient:
             ExaError: If creation failed.
 
         """
-        data = observation_set_definition.model_dump_json()
-        response = self._send_request(requests.post, "observation-sets", data=data)
+        json_str = self._serialize_model(observation_set_definition)
+        response = self._send_request(requests.post, "observation-sets", json_str=json_str)
         return ObservationSetData.model_validate(response.json())
 
     def get_observation_set(self, observation_set_id: uuid.UUID) -> ObservationSetData:
@@ -552,8 +551,8 @@ class StationControlClient:
             ExaError: If updating failed.
 
         """
-        data = observation_set_update.model_dump_json()
-        response = self._send_request(requests.patch, "observation-sets", data=data)
+        json_str = self._serialize_model(observation_set_update)
+        response = self._send_request(requests.patch, "observation-sets", json_str=json_str)
         return ObservationSetData.model_validate(response.json())
 
     def finalize_observation_set(self, observation_set_id: uuid.UUID) -> None:
@@ -652,8 +651,8 @@ class StationControlClient:
         self, sequence_metadata_definition: SequenceMetadataDefinition
     ) -> SequenceMetadataData:
         """Create sequence metadata in the database."""
-        data = sequence_metadata_definition.model_dump_json()
-        response = self._send_request(requests.post, "sequence-metadatas", data=data)
+        json_str = self._serialize_model(sequence_metadata_definition)
+        response = self._send_request(requests.post, "sequence-metadatas", json_str=json_str)
         return SequenceMetadataData.model_validate(response.json())
 
     def save_sequence_result(self, sequence_result_definition: SequenceResultDefinition) -> SequenceResultData:
@@ -663,10 +662,10 @@ class StationControlClient:
         Timestamps are assigned by the database. "modified_timestamp" is not set on initial creation,
         but it's updated on each subsequent call.
         """
-        data = sequence_result_definition.model_dump_json()
         # FIXME: We don't have information if the object was created or updated. Thus, server always responds 200 (OK).
+        json_str = self._serialize_model(sequence_result_definition)
         response = self._send_request(
-            requests.put, f"sequence-results/{sequence_result_definition.sequence_id}", data=data
+            requests.put, f"sequence-results/{sequence_result_definition.sequence_id}", json_str=json_str
         )
         return SequenceResultData.model_validate(response.json())
 
@@ -678,7 +677,7 @@ class StationControlClient:
     def get_job(self, job_id: uuid.UUID) -> JobData:
         """Get job data."""
         response = self._send_request(requests.get, f"jobs/{job_id}")
-        return response.json()
+        return JobData.model_validate(response.json())
 
     def _wait_job_completion(self, job_id: str, update_progress_callback: Callable[[Statuses], None] | None) -> bool:
         logger.info("Waiting for job ID: %s", job_id)
@@ -700,11 +699,11 @@ class StationControlClient:
         max_seen_position = 0
         while True:
             job = self._poll_job(job_id)
-            if job["job_status"] >= JobStatus.EXECUTION_START:
+            if job.job_status >= JobStatus.EXECUTION_START:
                 if max_seen_position:
                     update_progress_callback([("Progress in queue", max_seen_position, max_seen_position)])
-                return job["job_status"]
-            position = job["position"]
+                return job.job_status
+            position = job.position
 
             if position == 0:
                 sleep(1)
@@ -721,26 +720,70 @@ class StationControlClient:
         # Keep polling job status until it finishes, and update progress with `update_progress_callback`.
         while True:
             job = self._poll_job(job_id)
-            update_progress_callback(job["job_result"].get("parallel_sweep_progress", []))
-            if JobStatus(job["job_status"]) in JobStatus.terminal_statuses():
+            update_progress_callback(job.job_result.parallel_sweep_progress)
+            if job.job_status in JobStatus.terminal_statuses():
                 return
             sleep(1)
 
     def _poll_job(self, job_id: str) -> JobData:
-        job = self._send_request(requests.get, f"jobs/{job_id}").json()
-        if job["job_status"] == JobStatus.FAILED:
-            raise InternalServerError(f"Job: {job.get('job_id')}\n{job.get('job_error')}")
+        response = self._send_request(requests.get, f"jobs/{job_id}")
+        job = JobData.model_validate(response.json())
+        if job.job_status == JobStatus.FAILED:
+            raise InternalServerError(f"Job: {job.job_id}\n{job.job_error}")
         return job
 
+    @staticmethod
+    def _serialize_model(model: BaseModel) -> str:
+        """Serialize a Pydantic model into a JSON string.
+
+        All Pydantic models should be serialized using this method, to keep the client behavior uniform.
+
+        TODO add a corresponding deserialization method.
+
+        Args:
+            model: Pydantic model to JSON-serialize.
+
+        Returns:
+            Corresponding JSON string, may contain arbitrary Unicode characters.
+
+        """
+        # Strings in model can contain non-latin-1 characters. Unlike json.dumps which encodes non-latin-1 chars
+        # using the \uXXXX syntax, BaseModel.model_dump_json() keeps them in the produced JSON str.
+        return model.model_dump_json()
+
     def _send_request(
-        self, http_method: Callable[..., requests.Response], url_path: str, **kwargs
+        self,
+        http_method: Callable[..., requests.Response],
+        url_path: str,
+        *,
+        json_str: str | None = None,
+        octets: bytes | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
     ) -> requests.Response:
-        # Send the request and return the response.
+        """Send a HTTP request.
+
+        Parameters ``json_str``, ``octets`` and ``params`` are mutually exclusive.
+        The first non-None argument (in this order) will be used to construct the body of the request.
+
+        Args:
+            http_method: HTTP method to use for the request, any of requests.[post|get|put|head|delete|patch|options].
+            url_path: URL for the request.
+            json_str: JSON string to store in the body, may contain arbitrary Unicode characters.
+            octets: Pre-serialized binary data to store in the body.
+            params: HTTP query to store in the body.
+            headers: Additional HTTP headers for the request. Some may be overridden.
+
+        Returns:
+            Response to the request.
+
+        Raises:
+            StationControlError: Request was not successful.
+
+        """
         # Will raise an error if respectively an error response code is returned.
-        # http_method should be any of requests.[post|get|put|head|delete|patch|options]
-        params = kwargs.get("params", {})
-        headers = kwargs.get("headers", {})
-        data = kwargs.get("data", None)
+        headers = headers or {}
+
         if self._enable_opentelemetry:
             parent_span_context = trace.set_span_in_context(trace.get_current_span())
             propagate.inject(carrier=headers, context=parent_span_context)
@@ -749,9 +792,23 @@ class StationControlClient:
             headers["Authorization"] = self._get_token_callback()
 
         # Build request options explicitly
-        http_request_options = {"params": params, "data": data, "headers": headers}
-        # Remove None and {} values
-        http_request_options = {key: value for key, value in http_request_options.items() if value not in [None, {}]}
+        http_request_options: dict[str, Any] = {}
+        if json_str is not None:
+            # Must be able to handle JSON strings with arbitrary unicode characters, so we use an explicit
+            # encoding into bytes, and set the headers so the recipient can decode the request body correctly.
+            http_request_options["data"] = json_str.encode("utf-8")
+            headers["Content-Type"] = "application/json; charset=UTF-8"
+        elif octets is not None:
+            http_request_options["data"] = octets
+            headers["Content-Type"] = "application/octet-stream"
+        elif params is not None:
+            http_request_options["params"] = params
+        # otherwise no body-related parameter will be passed to requests
+
+        if headers:
+            # do not pass empty headers dict
+            http_request_options["headers"] = headers
+
         url = f"{self.root_url}/{url_path}"
         # TODO SW-1387: Use v1 API
         # url = f"{self.root_url}/{self.version}/{url_path}"
@@ -803,7 +860,7 @@ class StationControlClient:
         return parse(version("iqm-station-control-client"))
 
     @staticmethod
-    def _clean_query_parameters(model: Any, **kwargs) -> dict:
+    def _clean_query_parameters(model: Any, **kwargs) -> dict[str, Any]:
         if issubclass(model, PydanticBase) and "invalid" in model.model_fields.keys() and "invalid" not in kwargs:
             # Get only valid items by default, "invalid=None" would return also invalid ones.
             # This default has to be set on the client side, server side uses default "None".

{iqm_station_control_client-4.1.0 → iqm_station_control_client-5.0.0}/src/iqm/station_control/interface/models/jobs.py

@@ -38,13 +38,20 @@ class JobResult(PydanticBase):
     interrupted: bool
 
 
+class JobError(PydanticBase):
+    """Error log for a job."""
+
+    full_error_log: str
+    user_error_message: str
+
+
 class JobData(PydanticBase):
     """Job response data model"""
 
     job_id: UUID
     job_status: JobStatus
     job_result: JobResult
-    job_error: str | None
+    job_error: JobError | None
     position: int | None
 
 

{iqm_station_control_client-4.1.0 → iqm_station_control_client-5.0.0/src/iqm_station_control_client.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: iqm-station-control-client
-Version: 4.1.0
+Version: 5.0.0
 Summary: Python client for communicating with Station Control Service
 Author-email: IQM Finland Oy <info@meetiqm.com>
 License:                                  Apache License

iqm_station_control_client-5.0.0/version.txt

@@ -0,0 +1 @@
+5.0.0

iqm_station_control_client-4.1.0/version.txt

@@ -1 +0,0 @@
-4.1.0