qilisdk 0.1.8__cp312-cp312-manylinux_2_28_x86_64.whl

qilisdk/_logging.py

@@ -0,0 +1,135 @@
+# Copyright 2025 Qilimanjaro Quantum Tech
+#
+# 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.
+
+"""config.py"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from loguru import logger
+from pydantic import BaseModel
+from pydantic_settings import BaseSettings
+from ruamel.yaml import YAML
+
+from qilisdk.settings import get_settings
+
+if TYPE_CHECKING:
+    from types import FrameType
+
+
+class SinkConfig(BaseModel):
+    """
+    Configuration for a single Loguru sink.
+    """
+
+    sink: str | Path
+    level: str = "INFO"
+    format: str | None = None
+    filter: str | dict[str, str] | None = None
+    colorize: bool = False
+    enqueue: bool = False
+    rotation: str | None = None
+    serialize: bool = False
+
+
+class InterceptLibraryConfig(BaseModel):
+    """
+    Configuration for intercepting a stdlib logging library.
+    """
+
+    name: str
+    level: str = "ERROR"
+
+
+class LoggingSettings(BaseSettings):
+    """
+    Pydantic settings for Loguru configuration loaded from YAML or JSON.
+    """
+
+    sinks: list[SinkConfig] = []
+    intercept_libraries: list[InterceptLibraryConfig] = []
+
+    @classmethod
+    def load(cls, path: str | Path) -> LoggingSettings:
+        path = Path(path)
+        yaml = YAML(typ="safe")
+        data = yaml.load(path)
+        return cls(**data)
+
+
+class InterceptHandler(logging.Handler):
+    """
+    Redirect stdlib 'logging' records to Loguru, optionally filtering by name_prefix.
+    """
+
+    def emit(self, record: logging.LogRecord) -> None:  # noqa: PLR6301
+        try:
+            level = logger.level(record.levelname).name
+        except ValueError:
+            level = record.levelno
+
+        frame: FrameType | None = logging.currentframe()
+        depth = 2
+        while frame and frame.f_code.co_filename == logging.__file__:
+            frame = frame.f_back
+            depth += 1
+
+        logger.opt(depth=depth, exception=record.exc_info).log(level, record.getMessage())
+
+
+def configure_logging() -> None:
+    """
+    Load settings (path overridden by environment variable) and configure Loguru + stdlib logging intercept.
+    """
+    # Determine config path
+    config_path = Path(get_settings().logging_config_path).expanduser()
+    if not config_path.is_absolute():
+        config_path = (Path.cwd() / config_path).resolve()
+
+    settings = LoggingSettings.load(config_path)
+
+    # 1) Remove all pre-configured Loguru handlers
+    logger.remove()
+
+    # 2) Add configured sinks
+    for sink_conf in settings.sinks:
+        params = sink_conf.model_dump()
+        sink_target = params.pop("sink")
+
+        # Resolve stderr/stdout
+        if isinstance(sink_target, str) and sink_target.lower() == "stderr":
+            sink_target = sys.stderr
+        elif isinstance(sink_target, str) and sink_target.lower() == "stdout":
+            sink_target = sys.stdout
+
+        clean_params = {k: v for k, v in params.items() if v is not None}
+
+        logger.add(sink_target, **clean_params)
+
+    # 3) Quiet down noisy libraries before intercepting
+    for intercept_library in settings.intercept_libraries:
+        logging.getLogger(intercept_library.name).setLevel(intercept_library.level)
+
+    # 4) Intercept stdlib -> Loguru
+    handler = InterceptHandler()
+    logging.root.handlers = [handler]
+    logging.root.setLevel(logging.NOTSET)
+
+    for logger_name in list(logging.root.manager.loggerDict.keys()):
+        logging.getLogger(logger_name).handlers = []
+        logging.getLogger(logger_name).propagate = True

qilisdk/_optionals.py

@@ -0,0 +1,137 @@
+# Copyright 2025 Qilimanjaro Quantum Tech
+#
+# 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.
+
+import importlib
+import importlib.metadata
+from dataclasses import dataclass
+from typing import Any, Callable, NoReturn
+
+
+class OptionalDependencyError(ImportError):
+    """Raised when an optional dependency is missing, with a custom message."""
+
+
+@dataclass(frozen=True)
+class Symbol:
+    path: str
+    name: str
+
+
+@dataclass(frozen=True)
+class OptionalFeature:
+    """Holds metadata about an optional feature.
+
+    Attributes:
+        name (str):
+            The name of the extras group in pyproject.toml
+        dependencies (list[str]):
+            The dependencies that must be installed
+        symbols (list[str]):
+            Which symbols (classes, functions, etc.) to re-export
+    """
+
+    name: str
+    dependencies: list[str]
+    symbols: list[Symbol]
+
+
+@dataclass
+class ImportedFeature:
+    """Holds the result of an optional import.
+
+    Attributes:
+        name (str):
+            A label for the feature (e.g. 'qibo-backend').
+        symbols (dict[str, Union[Any, Callable]]):
+            A mapping from symbol name to the real or stubbed object.
+            If the required dependency is missing, the symbol is a stub
+            that raises an error when called.
+    """
+
+    name: str
+    symbols: dict[str, Any | Callable]
+
+
+class _OptionalDependencyStub:
+    """Callable proxy that raises OptionalDependencyError for missing extras.
+
+    It also intercepts attribute access so expressions like ``SpeQtrum.login()``
+    raise an informative OptionalDependencyError rather than AttributeError.
+    """
+
+    def __init__(self, *, symbol_name: str, feature_name: str, import_error: Exception | None = None) -> None:
+        self._symbol_name = symbol_name
+        self._feature_name = feature_name
+        self._import_error = import_error
+        self.__name__ = symbol_name
+        self.__qualname__ = symbol_name
+
+    def _raise(self) -> NoReturn:
+        message = f"Using {self._symbol_name} requires installing the '{self._feature_name}' optional feature: `pip install qilisdk[{self._feature_name}]`\n"
+        if self._import_error is None:
+            raise OptionalDependencyError(message)
+        detail = f"{type(self._import_error).__name__}: {self._import_error}"
+        raise OptionalDependencyError(message + f"Import failed with: {detail}\n")
+
+    def __call__(self, *_: Any, **__: Any) -> NoReturn:
+        self._raise()
+
+    def __getattr__(self, name: str) -> "_OptionalDependencyStub":
+        if name.startswith("__") and name.endswith("__"):
+            raise AttributeError(name)
+        return _OptionalDependencyStub(
+            symbol_name=f"{self._symbol_name}.{name}",
+            feature_name=self._feature_name,
+            import_error=self._import_error,
+        )
+
+    def __repr__(self) -> str:
+        return f"<missing optional dependency: {self._symbol_name} (extra '{self._feature_name}')>"
+
+
+def import_optional_dependencies(feature: OptionalFeature) -> ImportedFeature:
+    """Tries to import a submodule at `feature.import_path` along with the required
+    distributions. If successful, returns a dict mapping each symbol to the
+    actual imported symbol. Otherwise returns stubs that raise an error on usage.
+
+    Args:
+        feature (OptionalFeature): An OptionalFeature instance describing the optional group
+
+    Returns:
+        Dict[str, Union[Any, Callable]]: A dict { symbol_name: symbol_or_stub }
+    """
+    missing: list[str] = []
+    for dist in feature.dependencies:
+        try:
+            importlib.metadata.version(dist)
+        except importlib.metadata.PackageNotFoundError:
+            missing.append(dist)
+
+    def make_stub(symbol_name: str, *, import_error: Exception | None = None) -> _OptionalDependencyStub:
+        return _OptionalDependencyStub(symbol_name=symbol_name, feature_name=feature.name, import_error=import_error)
+
+    if missing:
+        # Build stubs that raise a helpful error
+        stubs: dict[str, Any] = {symbol.name: make_stub(symbol.name) for symbol in feature.symbols}
+        return ImportedFeature(name=feature.name, symbols=stubs)
+
+    # All dependencies are present => import the real module
+    symbols = {}
+    for symbol in feature.symbols:
+        try:
+            module = importlib.import_module(symbol.path)
+            symbols[symbol.name] = getattr(module, symbol.name)
+        except Exception as exc:  # noqa: BLE001
+            symbols[symbol.name] = make_stub(symbol.name, import_error=exc)
+    return ImportedFeature(name=feature.name, symbols=symbols)

qilisdk/analog/__init__.py

@@ -0,0 +1,18 @@
+# Copyright 2025 Qilimanjaro Quantum Tech
+#
+# 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.
+
+from .hamiltonian import Hamiltonian, I, PauliI, PauliX, PauliY, PauliZ, X, Y, Z
+from .schedule import Schedule
+
+__all__ = ["Hamiltonian", "I", "PauliI", "PauliX", "PauliY", "PauliZ", "Schedule", "X", "Y", "Z"]

qilisdk/analog/exceptions.py

@@ -0,0 +1,17 @@
+# Copyright 2025 Qilimanjaro Quantum Tech
+#
+# 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.
+
+
+class InvalidHamiltonianOperation(Exception):
+    """Raised when an operation cannot be applied to the current Hamiltonian."""