iqm-exa-common 26.2__tar.gz → 26.3__tar.gz

{iqm_exa_common-26.2 → iqm_exa_common-26.3}/CHANGELOG.rst

@@ -2,6 +2,15 @@
 Changelog
 =========
 
+Version 26.3 (2025-03-05)
+=========================
+
+Features
+--------
+
+- Add new error classes designed for client-server communication via station control client.
+- Remove general RequestError and use new specific error classes instead.
+
 Version 26.2 (2025-03-03)
 =========================
 

{iqm_exa_common-26.2/src/iqm_exa_common.egg-info → iqm_exa_common-26.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: iqm-exa-common
-Version: 26.2
+Version: 26.3
 Summary: Framework for control and measurement of superconducting qubits: common library
 Author-email: IQM Finland Oy <info@meetiqm.com>
 License:                                  Apache License

{iqm_exa_common-26.2 → iqm_exa_common-26.3}/src/exa/common/data/base_model.py

@@ -11,12 +11,9 @@ class BaseModel(pydantic.BaseModel):
     """
 
     model_config = ConfigDict(
-        # extra="forbid",  # Forbid any extra attributes
-        # TODO (Marko): Use "ignore" at least temporarily
-        #  Data sent by old server code might include extra attributes like "parent_name",
-        #  which fails with a new client using extra="ignore".
-        #  Before merging to master, consider if we want to be strict with extra="forbid",
-        #  or would it be better to use extra="ignore" (shouldn't be needed if we update the server code anyway).
+        # TODO: Consider setting extra="forbid", extra="ignore" is needed only if new clients use older servers
+        #  After station control API versioning, backwards compatibility works, i.e. old clients can use newer servers.
+        #  Reverse shouldn't be needed, since we don't promise any forwards compatibility.
         extra="ignore",  # Ignore any extra attributes
         validate_assignment=True,  # Validate the data when the model is changed
         validate_default=True,  # Validate default values during validation

{iqm_exa_common-26.2 → iqm_exa_common-26.3}/src/exa/common/data/parameter.py

@@ -70,7 +70,7 @@ import xarray as xr
 from exa.common.control.sweep.sweep_values import SweepValues
 from exa.common.data.base_model import BaseModel
 from exa.common.data.value import ObservationValue
-from exa.common.errors.exa_error import InvalidParameterValueError
+from exa.common.errors.server_errors import ValidationError
 
 CastType = str | list["CastType"] | None
 
@@ -225,9 +225,7 @@ class Parameter(BaseModel):
         )
         if self.element_indices is not None:
             if self.collection_type is not CollectionType.SCALAR:
-                raise InvalidParameterValueError(
-                    "Element-wise parameter must have CollectionType.SCALAR collection type."
-                )
+                raise ValidationError("Element-wise parameter must have 'CollectionType.SCALAR' collection type.")
 
             match self.element_indices:
                 case [_i, *_more_is] as idxs:
@@ -236,7 +234,7 @@ class Parameter(BaseModel):
                 case int(idx):
                     idxs = [idx]
                 case _:
-                    raise InvalidParameterValueError("element_indices must be one or more ints.")
+                    raise ValidationError("Parameter 'element_indices' must be one or more ints.")
             object.__setattr__(self, "element_indices", idxs)
 
             object.__setattr__(self, "_parent_name", self.name)
@@ -379,12 +377,12 @@ class Parameter(BaseModel):
             The element-wise parameter.
 
         Raises:
-            InvalidParameterValueError: If ``self`` is not collection-valued.
+            UnprocessableEntityError: If ``self`` is not collection-valued.
 
         """
         if self.collection_type is CollectionType.SCALAR:
-            raise InvalidParameterValueError(
-                "Cannot create an element-wise parameter from a parameter with CollectionType.SCALAR."
+            raise ValidationError(
+                "Cannot create an element-wise parameter from a parameter with 'CollectionType.SCALAR'."
             )
         return Parameter(
             name=self.name,
@@ -433,7 +431,7 @@ class Setting(BaseModel):
             # To avoid extra complexity, let Pydantic deal with the raw data and change the value in "after" validation.
             object.__setattr__(self, "value", self.parameter.collection_type.cast(self.value))
         if self.value is not None and not self.parameter.validate(self.value):
-            raise InvalidParameterValueError("Invalid value {} for parameter {}.".format(self.value, self.parameter))
+            raise ValidationError(f"Invalid value '{self.value}' for parameter '{self.parameter}'.")
         return self
 
     def update(self, value: ObservationValue) -> Setting:

{iqm_exa_common-26.2 → iqm_exa_common-26.3}/src/exa/common/data/value.py

@@ -43,7 +43,6 @@ Uncertainty = Annotated[
     WithJsonSchema(core_schema.any_schema()),
 ]
 
-# TODO (Marko): Consider if we want to rename these?
-#  We have "as" imports so seems like more descriptive name would be better.
+# TODO: Consider if we want to rename these permanently to avoid unnecessary "as" imports
 ObservationValue = Value
 ObservationUncertainty = Uncertainty

{iqm_exa_common-26.2 → iqm_exa_common-26.3}/src/exa/common/errors/exa_error.py

@@ -1,3 +1,6 @@
+import warnings
+
+
 class ExaError(Exception):
     """Base class for exa errors.
 
@@ -10,25 +13,21 @@ class ExaError(Exception):
         super().__init__(message, *args)
         self.message = message
 
+    def __str__(self):
+        return self.message
+
 
 class UnknownSettingError(ExaError, AttributeError):
     """This SettingNode does not have a given key."""
 
 
-class InvalidParameterValueError(ExaError, ValueError):
-    """The value set does not conform to the parameter restrictions."""
+class EmptyComponentListError(ExaError, ValueError):
+    """Error raised when an empty list is given as components for running an experiment."""
 
 
 class InvalidSweepOptionsTypeError(ExaError, TypeError):
     """The type of sweep options is invalid."""
 
     def __init__(self, options: str, *args):
+        warnings.warn("InvalidSweepOptionsTypeError is deprecated.", DeprecationWarning)
         super().__init__(f"Options have unsupported type of {options}", *args)
-
-
-class RequestError(ExaError):
-    """Error raised when something went wrong on the server after sending a request."""
-
-
-class EmptyComponentListError(ExaError, ValueError):
-    """Error raised when an empty list is given as components for running an experiment."""

iqm_exa_common-26.3/src/exa/common/errors/server_errors.py

@@ -0,0 +1,74 @@
+# Copyright 2024 IQM
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Errors used in the client-server communication."""
+
+from http import HTTPStatus
+
+from exa.common.errors.exa_error import ExaError
+
+
+class StationControlError(ExaError):
+    """Base class for station control errors used in client-server communication."""
+
+    # TODO: StationControlError shouldn't need to inherit ExaError
+    #  Some clients might still expect ExaErrors, thus inheriting here to avoid issues because of that.
+    #  Ideally, we would keep server errors (raised by station control) and any client side errors separately.
+
+
+class BadRequestError(StationControlError):
+    """Error raised when the request syntax is invalid or the method is unsupported in general."""
+
+
+class UnauthorizedError(StationControlError):
+    """Error raised when the user is not authorized."""
+
+
+class ForbiddenError(StationControlError):
+    """Error raised when the operation is forbidden for the user."""
+
+
+class NotFoundError(StationControlError):
+    """Error raised when nothing was found with the given parameters.
+
+    This should be used when it's expected that something is found, for example when trying to find with an exact ID.
+    """
+
+
+class ValidationError(StationControlError):
+    """Error raised when something is unprocessable in general, for example if the input value is not acceptable."""
+
+
+class InternalServerError(StationControlError):
+    """Error raised when an unexpected error happened on the server side.
+
+    This error should never be raised when something expected happens,
+    and whenever the client encounters this, it should be considered as a server bug.
+    """
+
+
+class ServiceUnavailableError(StationControlError):
+    """Error raised when the service is unavailable."""
+
+
+ERROR_TO_STATUS_CODE_MAPPING = {
+    BadRequestError: HTTPStatus.BAD_REQUEST,  # 400
+    UnauthorizedError: HTTPStatus.UNAUTHORIZED,  # 401
+    ForbiddenError: HTTPStatus.FORBIDDEN,  # 403
+    NotFoundError: HTTPStatus.NOT_FOUND,  # 404
+    ValidationError: HTTPStatus.UNPROCESSABLE_ENTITY,  # 422
+    InternalServerError: HTTPStatus.INTERNAL_SERVER_ERROR,  # 500
+    ServiceUnavailableError: HTTPStatus.SERVICE_UNAVAILABLE,  # 503
+}
+
+STATUS_CODE_TO_ERROR_MAPPING = {value: key for key, value in ERROR_TO_STATUS_CODE_MAPPING.items()}

{iqm_exa_common-26.2 → iqm_exa_common-26.3}/src/exa/common/qcm_data/qcm_data_client.py

@@ -24,7 +24,8 @@ from typing import Any
 from packaging.version import Version
 import requests
 
-from exa.common.errors.exa_error import ExaError, RequestError
+from exa.common.errors.exa_error import ExaError
+from exa.common.errors.server_errors import NotFoundError, ValidationError
 from exa.common.qcm_data.file_adapter import FileAdapter
 
 MIN_SUPPORTED_CONTENT_FORMAT_VERSION = Version("1.0")
@@ -70,10 +71,7 @@ class QCMDataClient:
 
     @root_url.setter
     def root_url(self, root_url: str) -> None:
-        """Sets the remote QCM Data service URL.
-
-        Cache for :func:`get_chad` has to be reset when the URL changes.
-        """
+        """Sets the remote QCM Data service URL."""
         if self._root_url != root_url:
             self._root_url = root_url
 
@@ -90,14 +88,14 @@ class QCMDataClient:
         url_tail = f"/cheddars/{chip_label}?target=in-house"
         try:
             response = self._send_request(self.session.get, f"{self.root_url}{url_tail}")
-        except RequestError as err:
+        except NotFoundError as err:
             if self._fallback_root_url:
                 response = self._send_request(self.session.get, f"{self._fallback_root_url}{url_tail}")
             else:
                 raise err
         data = response.json().get("data")
         if not data:
-            raise RequestError(f"Chip design record for {chip_label} does not contain data.")
+            raise ValidationError(f"Chip design record for {chip_label} does not contain data.")
         self._validate_chip_design_record(data, chip_label)
         return data
 
@@ -113,7 +111,7 @@ class QCMDataClient:
                 error_message = response_dict["detail"]
             except json.JSONDecodeError:
                 error_message = response.text
-            raise RequestError(f"{url} returned error code {response.status_code}: {error_message}")
+            raise NotFoundError(error_message)
         return response
 
     @staticmethod

{iqm_exa_common-26.2 → iqm_exa_common-26.3/src/iqm_exa_common.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: iqm-exa-common
-Version: 26.2
+Version: 26.3
 Summary: Framework for control and measurement of superconducting qubits: common library
 Author-email: IQM Finland Oy <info@meetiqm.com>
 License:                                  Apache License

{iqm_exa_common-26.2 → iqm_exa_common-26.3}/src/iqm_exa_common.egg-info/SOURCES.txt

@@ -52,6 +52,7 @@ src/exa/common/data/settingnode_v2.html.jinja2
 src/exa/common/data/value.py
 src/exa/common/errors/__init__.py
 src/exa/common/errors/exa_error.py
+src/exa/common/errors/server_errors.py
 src/exa/common/helpers/__init__.py
 src/exa/common/helpers/data_helper.py
 src/exa/common/helpers/json_helper.py

iqm_exa_common-26.3/version.txt

@@ -0,0 +1 @@
+26.3

iqm_exa_common-26.2/version.txt

@@ -1 +0,0 @@
-26.2