iqm-station-control-client 11.3.1__tar.gz → 12.0.0__tar.gz

{iqm_station_control_client-11.3.1 → iqm_station_control_client-12.0.0}/CHANGELOG.rst

@@ -1,11 +1,37 @@
-=========
-Changelog
-=========
-
-Version 11.3.1 (2025-10-27)
+Version 12.0.0 (2025-11-19)
 ===========================
 
-- Bump version for 4.3.1 release. No functional changes.
+Breaking changes
+----------------
+
+- :class:`.IqmServerClient` has been removed from station-control-client package.
+  Use new REST-based implementation of :class:`.IQMServerClient` in iqm-client package.
+
+Features
+--------
+
+- Add new circuit and job related models to station control interface,
+  used in IQM client when serializing/deserializing data in IQMServer communication
+- Deprecate ``observation_ids`` in ``ObservationSetWithObservations``, use ``observations`` instead.
+  This is to unify the data with IQMServer.
+- :class:`StationControlClient` now accepts the ``token`` and ``tokens_file`` parameters,
+  and can use the :envvar:`IQM_TOKEN` and :envvar:`IQM_TOKENS_FILE` environment variables
+  to get the authentication token.
+- In case major versions differ, log warning instead of raising an error in the python package
+  version compatibility check when connecting to station-control server with
+  :class:`iqm.station_control.client.station_control.StationControlClient`.
+- :class:`StationControlClient` now accepts the ``token`` and ``tokens_file`` parameters,
+  and can use the :envvar:`IQM_TOKEN` and :envvar:`IQM_TOKENS_FILE` environment variables
+  to get the authentication token.
+- In case major versions differ, log warning instead of raising an error in the python package
+  version compatibility check when connecting to station-control server with
+  :class:`iqm.station_control.client.station_control.StationControlClient`.
+
+Bug fixes
+---------
+
+- Restrict RunDefinition fields to fix issues with serializing None and roundtrip resulting in empty dictionary.
+- Fix python package compatibility version check when connecting to station-control server.
 
 Version 11.3.0 (2025-10-23)
 ===========================
@@ -382,7 +408,7 @@ Version 3.12.0 (2025-04-07)
 Features
 --------
 
-- Fix package version in published docs footers, :issue:`SW-1392`. 
+- Fix package version in published docs footers, :issue:`SW-1392`.
 
 Version 3.11.0 (2025-04-03)
 ===========================
@@ -827,7 +853,7 @@ Version 1.2 (2024-07-05)
 
 Features
 --------
-- Bump exa-common to 25.3 
+- Bump exa-common to 25.3
 
 
 Version 1.1 (2024-07-04)

iqm_station_control_client-12.0.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include version.txt
+include LICENSE.txt
+prune tests/*
+exclude .gitlab-ci.yml

{iqm_station_control_client-11.3.1/src/iqm_station_control_client.egg-info → iqm_station_control_client-12.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: iqm-station-control-client
-Version: 11.3.1
+Version: 12.0.0
 Summary: Python client for communicating with Station Control Service
 Author-email: IQM Finland Oy <info@meetiqm.com>
 License:                                  Apache License
@@ -204,7 +204,7 @@ License:                                  Apache License
            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.
-Project-URL: Documentation, https://iqm-finland.github.io/docs/iqm-station-control-client/
+Project-URL: Documentation, https://docs.meetiqm.com/iqm-station-control-client/
 Project-URL: Homepage, https://pypi.org/project/iqm-station-control-client/
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -213,7 +213,6 @@ Classifier: Intended Audience :: Science/Research
 Requires-Python: >=3.11
 Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
-Requires-Dist: iqm-exa-common<28,>=27
 Requires-Dist: iqm-data-definitions<3.0,>=2.18
 Requires-Dist: opentelemetry-exporter-otlp<2.0,>=1.25.0
 Requires-Dist: protobuf<5.0,>=4.25.3
@@ -225,6 +224,7 @@ Requires-Dist: requests==2.32.3
 Requires-Dist: types-requests
 Requires-Dist: tqdm>=4.59.0
 Requires-Dist: types-tqdm
+Requires-Dist: iqm-exa-common
 
 Station control client library
 ==============================

iqm_station_control_client-12.0.0/docs/changelog.rst

@@ -0,0 +1,8 @@
+.. _changelog:
+
+=========
+CHANGELOG
+=========
+
+.. include:: ../CHANGELOG.rst
+   :literal:

{iqm_station_control_client-11.3.1 → iqm_station_control_client-12.0.0}/pyproject.toml

@@ -1,4 +1,3 @@
-# This file is managed by monotool.py, do not edit by hand
 [build-system]
 build-backend = "setuptools.build_meta"
 requires = [ "setuptools", "setuptools_scm[toml]",]
@@ -18,7 +17,7 @@ email = "info@meetiqm.com"
 file = "LICENSE.txt"
 
 [project.urls]
-Documentation = "https://iqm-finland.github.io/docs/iqm-station-control-client/"
+Documentation = "https://docs.meetiqm.com/iqm-station-control-client/"
 Homepage = "https://pypi.org/project/iqm-station-control-client/"
 
 [tool.mypy]
@@ -58,7 +57,7 @@ nb_diff_ignore = [ "/metadata/language_info", "/metadata/widgets", "/cells/*/exe
 
 [tool.ruff.lint]
 ignore = [ "D203", "D213",]
-select = [ "E4", "E7", "E9", "E5", "F", "Q", "PL", "I", "D", "UP007", "UP006", "UP035", "ANN001", "ANN201", "ANN202",]
+select = [ "E4", "E7", "E9", "E5", "F", "Q", "PL", "I", "D", "UP007", "UP006", "UP035", "ANN001", "ANN201", "ANN202", "NPY201",]
 unfixable = [ "F401",]
 
 [tool.ruff.lint.isort]
@@ -69,10 +68,10 @@ known-third-party = [ "exa", "iqm",]
 relative-imports-order = "closest-to-furthest"
 
 [tool.ruff.lint.per-file-ignores]
-"**/__init__.py" = [ "F401", "PLR0402",]
+"**/__init__.py" = [ "D104", "F401", "PLR0402",]
 "**/docs/*" = [ "E402", "D100",]
 "**/setup.py" = [ "D100", "D103", "I001", "ANN201",]
-"**/src/*" = [ "PLR2004", "D400", "D415", "D205", "D401", "D417", "D100", "D101", "D107", "D102", "D105", "D103", "D404", "D104",]
+"**/src/*" = [ "PLR2004", "D400", "D415", "D205", "D401", "D417", "D100", "D107", "D105", "D102", "D404",]
 "**/tests/*" = [ "F632", "PLR2004", "PLR0402", "PLC0414", "D", "ANN001", "ANN201", "ANN202",]
 
 [tool.ruff.lint.pylint]

{iqm_station_control_client-11.3.1 → iqm_station_control_client-12.0.0}/requirements/base.txt

@@ -1,4 +1,3 @@
-iqm-exa-common>=27,<28
 iqm-data-definitions >= 2.18, < 3.0
 opentelemetry-exporter-otlp >= 1.25.0, < 2.0
 protobuf >= 4.25.3, < 5.0
@@ -9,4 +8,5 @@ PyYAML >= 6.0, < 7.0
 requests == 2.32.3
 types-requests
 tqdm >= 4.59.0
-types-tqdm
+types-tqdm
+iqm-exa-common

iqm_station_control_client-12.0.0/src/iqm/station_control/client/authentication.py

@@ -0,0 +1,239 @@
+# Copyright 2024 IQM client developers
+#
+# 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.
+"""This module contains user authentication related classes and functions required by IQMClient."""
+
+from abc import ABC, abstractmethod
+from base64 import b64decode
+from collections.abc import Callable
+import json
+import os
+import time
+from typing import Any, TypeAlias
+
+from iqm.iqm_server_client.errors import ClientAuthenticationError, ClientConfigurationError
+
+REFRESH_MARGIN_SECONDS = 60
+
+
+AuthHeaderCallback: TypeAlias = Callable[[], str]
+"""Function that returns an authorization header containing a bearer token."""
+
+
+class TokenManager:
+    """TokenManager manages the access token required for user authentication.
+
+    Args:
+        token: Long-lived IQM token in plain text format.
+        tokens_file: Path to a tokens file used for authentication.
+        auth_header_callback: Callback function that returns an Authorization header containing a bearer token.
+        use_env_vars: Iff True, the first two parameters can also be read from the environment variables
+            :envvar:`IQM_TOKEN` and :envvar:`IQM_TOKENS_FILE`, respectively.
+            Environment variables can not be mixed with initialisation arguments.
+
+    At most one auth parameter should be given.
+
+    """
+
+    @staticmethod
+    def time_left_seconds(token: Any) -> int:
+        """Check how much time is left until the token expires.
+
+        Returns:
+            Time left on token in seconds.
+
+        """
+        if not token or not isinstance(token, str):
+            return 0
+        parts = token.split(".", 2)
+        if len(parts) != 3:
+            return 0
+        # Add padding to adjust body length to a multiple of 4 chars as required by base64 decoding
+        try:
+            body = parts[1] + ("=" * (-len(parts[1]) % 4))
+            exp_time = int(json.loads(b64decode(body)).get("exp", "0"))
+            return max(0, exp_time - int(time.time()))
+        except (UnicodeDecodeError, json.decoder.JSONDecodeError, ValueError, TypeError):
+            return 0
+
+    def __init__(
+        self,
+        token: str | None = None,
+        tokens_file: str | None = None,
+        auth_header_callback: AuthHeaderCallback | None = None,
+        *,
+        use_env_vars: bool = True,
+    ):
+        def _format_names(variable_names: list[str]) -> str:
+            """Format a list of variable names"""
+            return ", ".join(f'"{name}"' for name in variable_names)
+
+        auth_parameters: dict[str, str] = {}
+
+        init_parameters = {"token": token, "tokens_file": tokens_file}
+        init_params_given = [key for key, value in init_parameters.items() if value]
+        if auth_header_callback:
+            init_params_given.append("auth_header_callback")
+
+        if use_env_vars:
+            env_variables = {"token": "IQM_TOKEN", "tokens_file": "IQM_TOKENS_FILE"}
+            env_vars_given = [name for name in env_variables.values() if os.environ.get(name)]
+        else:
+            env_variables = {}
+            env_vars_given = []
+
+        if init_params_given and env_vars_given:
+            raise ClientConfigurationError(
+                "Authentication parameters given both as initialisation args and as environment variables: "
+                + f"initialisation args {_format_names(init_params_given)}, "
+                + f"environment variables {_format_names(env_vars_given)}."
+                + " Parameter sources must not be mixed."
+            )
+        auth_params_given = init_params_given + env_vars_given
+        if len(auth_params_given) > 1:
+            raise ClientConfigurationError(
+                f"No more than one authentication parameter may be given, received {auth_params_given}"
+            )
+
+        self._token_provider: TokenProviderInterface | None = None
+        self._auth_header_callback: AuthHeaderCallback | None = None
+        self._access_token: str | None = None
+
+        if auth_header_callback:
+            self._auth_header_callback = auth_header_callback
+            return
+
+        if env_vars_given:
+            auth_parameters = {key: value for key, name in env_variables.items() if (value := os.environ.get(name))}
+        else:
+            auth_parameters = {key: value for key, value in init_parameters.items() if value}
+
+        if not auth_parameters:
+            return  # no authentication
+        if set(auth_parameters) == {"token"}:
+            # This is not necessarily a JWT token
+            self._token_provider = ExternalToken(auth_parameters["token"])
+        elif set(auth_parameters) == {"tokens_file"}:
+            self._token_provider = TokensFileReader(auth_parameters["tokens_file"])
+        else:
+            raise ClientConfigurationError("Not possible.")
+
+    def get_auth_header_callback(self) -> AuthHeaderCallback | None:
+        """Return a callback providing an Authorization header, or None if we cannot provide it."""
+        return self._get_bearer_token if self._token_provider else self._auth_header_callback
+
+    def _get_bearer_token(self, retries: int = 1) -> str:
+        """Return a valid bearer token.
+
+        Raises:
+            ClientAuthenticationError: getting the token failed
+            RuntimeError: There is no token provider (authentication disabled)
+
+        """
+        if self._token_provider is None:
+            raise RuntimeError("There is no token provider.")
+
+        # Use the existing access token if it is still valid
+        if TokenManager.time_left_seconds(self._access_token) > REFRESH_MARGIN_SECONDS:
+            return f"Bearer {self._access_token}"
+
+        # Otherwise, get a new access token from token provider
+        try:
+            self._access_token = self._token_provider.get_token()
+            return f"Bearer {self._access_token}"
+        except ClientAuthenticationError:
+            if retries < 1:
+                raise
+
+        # Try again
+        return self._get_bearer_token(retries - 1)
+
+    def close(self) -> bool:
+        """Close the configured token provider.
+
+        Returns:
+            True if closing was successful
+
+        Raises:
+            ClientAuthenticationError: closing failed
+
+        """
+        if self._token_provider is None:
+            return False
+
+        self._token_provider.close()
+        self._token_provider = None
+        return True
+
+
+class TokenProviderInterface(ABC):
+    """Interface to token provider"""
+
+    @abstractmethod
+    def get_token(self) -> str:
+        """Return a valid access token.
+
+        Raises:
+            ClientAuthenticationError: acquiring the token failed
+
+        """
+
+    @abstractmethod
+    def close(self) -> None:
+        """Close the authentication session.
+
+        Raises:
+            ClientAuthenticationError: closing the session failed
+
+        """
+
+
+class ExternalToken(TokenProviderInterface):
+    """Holds an external token"""
+
+    def __init__(self, token: str):
+        self._token: str | None = token
+
+    def get_token(self) -> str:
+        if self._token is None:
+            raise ClientAuthenticationError("No external token available")
+        return self._token
+
+    def close(self) -> None:
+        self._token = None
+        raise ClientAuthenticationError("Can not close externally managed auth session")
+
+
+class TokensFileReader(TokenProviderInterface):
+    """Reads token from a file"""
+
+    def __init__(self, tokens_file: str):
+        self._path: str | None = tokens_file
+
+    def get_token(self) -> str:
+        try:
+            if self._path is None:
+                raise ClientAuthenticationError("No tokens file available")
+            with open(self._path, encoding="utf-8") as file:
+                raw_data = file.read()
+            json_data = json.loads(raw_data)
+            token = json_data.get("access_token")
+            if TokenManager.time_left_seconds(token) <= 0:
+                raise ClientAuthenticationError("Access token in file has expired or is not valid")
+        except (FileNotFoundError, IsADirectoryError, json.decoder.JSONDecodeError) as e:
+            raise ClientAuthenticationError(rf"Failed to read access token from file '{self._path}': {e}") from e
+        return token
+
+    def close(self) -> None:
+        self._path = None
+        raise ClientAuthenticationError("Can not close externally managed auth session")

{iqm_station_control_client-11.3.1 → iqm_station_control_client-12.0.0}/src/iqm/station_control/client/list_models.py

@@ -32,6 +32,7 @@ from iqm.station_control.interface.models import (
     RunLite,
     SequenceMetadataData,
     StaticQuantumArchitecture,
+    TimelineEntry,
 )
 from iqm.station_control.interface.pydantic_base import PydanticBase
 
@@ -70,41 +71,45 @@ class ListModel(RootModel):
     )
 
 
-class DutList(ListModel):
+class DutList(ListModel):  # noqa: D101
     root: list[DutData]
 
 
-class DutFieldDataList(ListModel):
+class DutFieldDataList(ListModel):  # noqa: D101
     root: list[DutFieldData]
 
 
-class ObservationDataList(ListModel):
+class ObservationDataList(ListModel):  # noqa: D101
     root: list[ObservationData]
 
 
-class ObservationDefinitionList(ListModel):
+class ObservationDefinitionList(ListModel):  # noqa: D101
     root: list[ObservationDefinition]
 
 
-class ObservationLiteList(ListModel):
+class ObservationLiteList(ListModel):  # noqa: D101
     root: list[ObservationLite]
 
 
-class ObservationUpdateList(ListModel):
+class ObservationUpdateList(ListModel):  # noqa: D101
     root: list[ObservationUpdate]
 
 
-class ObservationSetDataList(ListModel):
+class ObservationSetDataList(ListModel):  # noqa: D101
     root: list[ObservationSetData]
 
 
-class SequenceMetadataDataList(ListModel):
+class RunLiteList(ListModel):  # noqa: D101
+    root: list[RunLite]
+
+
+class SequenceMetadataDataList(ListModel):  # noqa: D101
     root: list[SequenceMetadataData]
 
 
-class StaticQuantumArchitectureList(ListModel):
+class StaticQuantumArchitectureList(ListModel):  # noqa: D101
     root: list[StaticQuantumArchitecture]
 
 
-class RunLiteList(ListModel):
-    root: list[RunLite]
+class TimelineEntryList(ListModel):  # noqa: D101
+    root: list[TimelineEntry]

{iqm_station_control_client-11.3.1 → iqm_station_control_client-12.0.0}/src/iqm/station_control/client/qon.py

@@ -23,7 +23,7 @@ from typing import Annotated, Any, Final, TypeAlias
 from pydantic import Field
 from pydantic.dataclasses import dataclass
 
-from iqm.station_control.interface.models.observation import ObservationBase
+from iqm.station_control.interface.models import ObservationBase
 
 logger = logging.getLogger(__name__)
 

{iqm_station_control_client-11.3.1 → iqm_station_control_client-12.0.0}/src/iqm/station_control/client/serializers/run_serializers.py

@@ -40,8 +40,8 @@ def serialize_run_definition(run_definition: RunDefinition) -> RunDefinitionProt
         username=run_definition.username,
         experiment_name=run_definition.experiment_name,
         experiment_label=run_definition.experiment_label,
-        options=serialize_struct(run_definition.options),  # type: ignore[arg-type]
-        additional_run_properties=serialize_struct(run_definition.additional_run_properties),  # type: ignore[arg-type]
+        options=serialize_struct(run_definition.options),
+        additional_run_properties=serialize_struct(run_definition.additional_run_properties),
         software_version_set_id=run_definition.software_version_set_id,
         components=run_definition.components,
         default_data_parameters=run_definition.default_data_parameters,
@@ -50,8 +50,9 @@ def serialize_run_definition(run_definition: RunDefinition) -> RunDefinitionProt
     run_definition_proto.sweep_definition_payload.Pack(
         serialize_sweep_definition(run_definition.sweep_definition), type_url_prefix="iqm-data-definitions"
     )
-    for key, sweep in run_definition.hard_sweeps.items():  # type: ignore[union-attr]
+    for key, sweep in run_definition.hard_sweeps.items():
         run_definition_proto.hard_sweeps[key].CopyFrom(proto_serialization.nd_sweep.pack(sweep, minimal=False))
+
     return run_definition_proto
 
 
@@ -94,7 +95,7 @@ def serialize_run_data(run_data: RunData) -> dict:
         "options": run_data.options,
         "additional_run_properties": run_data.additional_run_properties,
         "software_version_set_id": run_data.software_version_set_id,
-        "hard_sweeps": {key: encode_nd_sweeps(value) for key, value in run_data.hard_sweeps.items()},  # type: ignore[union-attr]
+        "hard_sweeps": {key: encode_nd_sweeps(value) for key, value in run_data.hard_sweeps.items()},
         "components": run_data.components,
         "default_data_parameters": run_data.default_data_parameters,
         "default_sweep_parameters": run_data.default_sweep_parameters,

{iqm_station_control_client-11.3.1 → iqm_station_control_client-12.0.0}/src/iqm/station_control/client/serializers/struct_serializer.py

@@ -33,7 +33,7 @@ def deserialize_struct(proto: pb.Struct) -> dict:
     return {key: _deserialize_value(value) for key, value in proto.fields.items()}
 
 
-def _serialize_value(value: None | float | str | bool | dict | list | int) -> pb.Value:
+def _serialize_value(value: None | float | str | bool | dict | list) -> pb.Value:
     """Serialize a value into a Value protobuf representation."""
     if value is None:
         return pb.Value(null_value=True)