luna-quantum 1.1.0__cp312-cp312-win_amd64.whl

luna_quantum/util/active_waiting.py

@@ -0,0 +1,79 @@
+import logging
+from collections.abc import Callable
+from time import sleep
+from typing import ClassVar
+
+from luna_quantum.util.log_utils import Logging
+
+
+class ActiveWaiting:
+    """
+    Provides active waiting functionality using a customizable loop.
+
+    The `ActiveWaiting` class offers a static method to perform a loop with
+    a sleep interval that increases iteratively, allowing the user to
+    regularly check a condition and optionally perform an additional action.
+    """
+
+    _logger: ClassVar[logging.Logger] = Logging.get_logger(__name__)
+
+    @staticmethod
+    def run(
+        loop_check: Callable[[], bool],
+        loop_call: Callable[[], None] | None = None,
+        sleep_time_max: float = 60.0,
+        sleep_time_increment: float = 5.0,
+        sleep_time_initial: float = 5.0,
+    ) -> None:
+        """
+        Execute a loop that checks a condition and optionally performs an action.
+
+        This function executes a loop that repeatedly checks a condition using a
+        callback function. If provided, it will also execute another callback after
+        each sleep period. The sleep time increases incrementally up to a maximum
+        value, starting from an initial sleep time.
+
+        Parameters
+        ----------
+        loop_check : Callable[[], bool]
+            A callable function that returns a boolean. The loop will continue as
+            long as this callable returns True.
+        loop_call : Optional[Callable[[], None]]
+            An optional callable function to be executed after each sleep period.
+            Defaults to None.
+        sleep_time_max : float
+            The maximum sleep time between condition checks. Defaults to 60.0 seconds.
+        sleep_time_increment : float
+            The amount of time to increment the sleep period after each iteration.
+            Defaults to 5.0 seconds.
+        sleep_time_initial : float
+            The initial sleep time before the first condition check. Defaults to
+            5.0 seconds. If invalid (< 0.0), it will be adjusted to the default.
+
+        Raises
+        ------
+        ValueError
+            If `sleep_time_initial`, `sleep_time_increment`, or `sleep_time_max` are
+            non-positive values where a positive value is required.
+        """
+        cur_sleep_time: float
+
+        if sleep_time_initial > 0.0:
+            cur_sleep_time = sleep_time_initial
+        else:
+            cur_sleep_time = 5.0
+            ActiveWaiting._logger.warning(
+                f"Invalid sleep_time_initial: {sleep_time_initial},"
+                f" setting it to default value {cur_sleep_time}"
+            )
+
+        while loop_check():
+            ActiveWaiting._logger.info(
+                f"Sleeping for {cur_sleep_time} seconds. "
+                f"Waiting and checking a function in a loop."
+            )
+            sleep(cur_sleep_time)
+            cur_sleep_time += sleep_time_increment
+            cur_sleep_time = min(cur_sleep_time, sleep_time_max)
+            if loop_call:
+                loop_call()

luna_quantum/util/class_patcher.py

@@ -0,0 +1,164 @@
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, Literal, TypeVar
+
+from luna_quantum.exceptions.patch_class_field_exists_error import (
+    PatchClassFieldExistsError,
+)
+
+T = TypeVar("T")  # To represent the return type of the decorated function
+
+
+def add_to_class(
+    class_: type[Any],
+    method_type: Literal["normal", "static", "class", "property"] = "normal",
+) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """
+    Add a function as a method into a specified class.
+
+    The decorator facilitates adding a function to a class as a method. The
+    method can be of type 'normal' (instance method), 'static', 'class', or
+    'property'. The function metadata is preserved during this process.
+
+    Parameters
+    ----------
+    class_ : Type
+        The class to which the function will be added.
+
+    method_type : {"normal", "static", "class", "property"}, optional
+        The type of method to integrate into the class. Defaults to "normal".
+        - "normal": Adds the function as an instance-level method.
+        - "static": Adds the function as a static method.
+        - "class": Adds the function as a class-level method.
+        - "property": Adds the function as a property.
+
+    Returns
+    -------
+    Callable
+        A callable decorator that, when applied to a function, integrates it
+        as the specified method type into the class.
+
+    """
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        # Preserve function metadata
+        @wraps(func)
+        def wrapped_func(*args: Any, **kwargs: Any) -> T:
+            return func(*args, **kwargs)
+
+        # Add the function to the class based on the method type
+        if method_type == "static":
+            setattr(class_, func.__name__, staticmethod(func))  # Add as static method
+        elif method_type == "class":
+            setattr(class_, func.__name__, classmethod(func))  # Add as class method
+        elif method_type == "property":
+            setattr(class_, func.__name__, property(func))  # Add as property
+        else:  # Default is normal (instance-level method)
+            setattr(class_, func.__name__, func)
+
+        return wrapped_func
+
+    return decorator
+
+
+def patch_instance(class_: type[Any]) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """
+    Patch a class with a "normal" method.
+
+    This function acts as a decorator that adds a new method to the given class.
+    The newly added method behaves as a standard instance method, meaning it
+    has access to the instance (`self`) when called.
+
+    Parameters
+    ----------
+        class_: The class to which the method will be added.
+
+    Returns
+    -------
+        A decorator function that takes the method to be added as its argument.
+    """
+    return add_to_class(class_, "normal")
+
+
+def patch_static(class_: type[Any]) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """
+    Patch a class with a "static" method.
+
+    This function acts as a decorator that adds a new static method to the given class.
+    The newly added static method does not require an instance of the class to be
+    called.
+
+    Parameters
+    ----------
+        class_: The class to which the static method will be added.
+
+    Returns
+    -------
+        A decorator function that takes the static method to be added as its argument.
+    """
+    return add_to_class(class_, "static")
+
+
+def patch_class(class_: type[Any]) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """
+    Patch a class with a "class" method.
+
+    This function acts as a decorator that adds a new class method to the given class.
+    The newly added method will have access to the class itself (`cls`) when called.
+
+    Parameters
+    ----------
+        class_: The class to which the class method will be added.
+
+    Returns
+    -------
+        A decorator function that takes the class method to be added as its argument.
+    """
+    return add_to_class(class_, "class")
+
+
+def patch_property(class_: type[Any]) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """
+    Patch a class with a "property" method.
+
+    This function acts as a decorator that adds a new property to the given class.
+    The decorator converts the given method into a readable property.
+
+    Parameters
+    ----------
+        class_: The class to which the property will be added.
+
+    Returns
+    -------
+        A decorator function that takes the method to be added as a property.
+    """
+    return add_to_class(class_, "property")
+
+
+def patch_field_to_class(
+    class_: type[Any],
+    field_name: str,
+    default_value: Any = None,  # noqa: ANN401 we dont know the type in the decorator
+) -> None:
+    """
+    Add a new field to a class.
+
+    This function allows adding a field with a default value to the given class.
+    If the field already exists in the class, a `PatchClassFieldExistsError` is raised.
+
+    Parameters
+    ----------
+        class_: The class to which the field will be added.
+        field_name: The name of the field to be added.
+        default_value: The default value to assign to the field (optional).
+
+    Raises
+    ------
+        PatchClassFieldExistsError
+            If the class already has a field with the given name.
+    """
+    if hasattr(class_, field_name):
+        raise PatchClassFieldExistsError(
+            class_name=class_.__name__, field_name=field_name
+        )
+    setattr(class_, field_name, default_value)

luna_quantum/util/debug_info.py

@@ -0,0 +1,52 @@
+import platform
+import sys
+from logging import Logger
+
+from rich import box
+from rich.table import Table
+
+from luna_quantum._core import __aq_model_version__, __luna_quantum_version__
+from luna_quantum.util.log_utils import Logging
+
+_logger: Logger = Logging.get_logger(__name__)
+_pkg_list: list[str] = ["numpy", "pydantic"]
+
+
+def debug_info() -> None:
+    """Print debug information."""
+    python_version = (
+        f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+    )
+    os_info = f"{platform.system()} {platform.release()}"
+
+    # Get additional system information
+    architecture = platform.machine()
+    python_implementation = platform.python_implementation()
+
+    table = Table(
+        title="Luna Debug Information",
+        title_justify="left",
+        caption="System and environment details for troubleshooting",
+        box=box.MARKDOWN,
+    )
+    table.add_column("Property", style="cyan", no_wrap=True)
+    table.add_column("Version", style="green", no_wrap=True)
+
+    # Add rows to the table
+    table.add_row("Luna Quantum", f"{__luna_quantum_version__}")
+    table.add_row("AqModel", f"{__aq_model_version__}")
+    table.add_row("Python", f"{python_version}")
+    table.add_row("Python Implementation", f"{python_implementation}")
+    table.add_row("Operating System", f"{os_info}")
+    table.add_row("Architecture", f"{architecture}")
+
+    for package in _pkg_list:
+        try:
+            module = __import__(package)
+            version = getattr(module, "__version__", "pkg found, version unknown")
+            table.add_row(package, version)
+        except ImportError:
+            table.add_row(package, "pkg not found")
+
+    # Print the table to console
+    Logging.get_console().print(table)

luna_quantum/util/log_utils.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+import logging
+from contextlib import contextmanager
+from functools import wraps
+from typing import TYPE_CHECKING, ParamSpec, TypeVar
+
+from rich.console import Console
+from rich.logging import RichHandler
+from rich.progress import Progress, SpinnerColumn, TaskID, TextColumn
+from rich.theme import Theme
+
+from luna_quantum.config import config
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+class Logging:
+    """Utilities for configuring and accessing Luna SDK loggers.
+
+    This class provides static methods to:
+    - Set and retrieve the global logging level for SDK components
+    - Create and configure loggers with Rich formatting
+    - Manage consistent logging behavior across the SDK
+    """
+
+    @staticmethod
+    def is_process_bar_shown() -> bool:
+        """
+        Return whether to use a process bar for progress bars.
+
+        Returns
+        -------
+        bool
+            Returns whether to use a process bar for progress bars.
+        """
+        return (
+            not config.LUNA_LOG_DISABLE_SPINNER
+            and Logging.get_level() != logging.NOTSET
+        )
+
+    @staticmethod
+    def set_level(log_level: int) -> None:
+        """Set the logging level for all SDK loggers.
+
+        Parameters
+        ----------
+        log_level : int
+            Logging level to set (e.g., logging.DEBUG, logging.INFO)
+        """
+        config.LUNA_LOG_DEFAULT_LEVEL = logging.getLevelName(log_level)
+
+        for logger_name in logging.root.manager.loggerDict:
+            if logger_name.startswith("luna_quantum"):  # Only modify SDK loggers
+                logging.getLogger(logger_name).setLevel(log_level)
+
+    @staticmethod
+    def get_level() -> int:
+        """Return the current logging level for the SDK.
+
+        Returns
+        -------
+        int
+            Current logging level as defined in the logging module
+            (e.g., logging.DEBUG, logging.INFO, etc.)
+        """
+        return logging._nameToLevel.get(config.LUNA_LOG_DEFAULT_LEVEL, logging.INFO)  # noqa: SLF001 #No other way to map these log levels.
+
+    @staticmethod
+    def get_console() -> Console:
+        """Return a Rich console instance for use in logging."""
+        custom_theme = Theme(
+            {
+                "logging.level.debug": "bright_blue",
+                "logging.level.info": "bright_green",
+                "logging.level.warning": "bold bright_yellow",
+                "logging.level.error": "bold bright_red",
+                "logging.level.critical": "bold bright_magenta",
+            }
+        )
+        return Console(theme=custom_theme)
+
+    @staticmethod
+    def get_logger(name: str) -> logging.Logger:
+        """Get a logger with the specified name and set up a RichHandler for it.
+
+        Parameters
+        ----------
+        name : str
+            Name of the logger to retrieve or create
+
+        Returns
+        -------
+        logging.Logger
+            Configured logger instance with appropriate handlers
+        """
+        logger = logging.getLogger(name)
+        logger.setLevel(Logging.get_level())
+        logger.propagate = False
+
+        if logger.hasHandlers():
+            return logger
+
+        handler = RichHandler(
+            console=Logging.get_console(),
+            rich_tracebacks=True,
+            show_time=True,
+            show_level=True,
+            show_path=False,
+            log_time_format="%Y-%m-%d %H:%M:%S",  # ISO 8601 format
+        )
+
+        logger.addHandler(handler)
+        return logger
+
+
+@contextmanager
+def progress_bar(
+    total: int | None, desc: str = "", unit: str = "steps"
+) -> Generator[tuple[Progress, TaskID]]:
+    """Create a progress bar using Rich as a context manager.
+
+    Parameters
+    ----------
+    total: int | None
+        Total number of steps in the progress bar
+    desc: str
+        Description text to display next to the progress bar
+    unit: str
+        Unit label for the progress steps, by default "steps"
+
+    Yields
+    ------
+    tuple[Progress, TaskID]
+        A tuple containing the Progress object and task ID for updating
+    """
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        console=Console(
+            theme=Theme(
+                {
+                    "bar.back": "blue",
+                    "bar.pulse": "bright_blue",
+                }
+            )
+        ),
+        transient=True,
+        disable=not Logging.is_process_bar_shown(),
+    ) as progress:
+        task = progress.add_task(f"[blue]{desc}", total=total, unit=unit)
+        yield progress, task  # Yield both progress and task for updates
+
+
+def progress(
+    total: int | None,
+    desc: str = "",
+    unit: str = "steps",
+) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """
+    Decorate a func with a progress-bar.
+
+    Parameters
+    ----------
+    total: int | None
+        Total number of steps in the progress bar
+    desc: str
+        Description text to display next to the progress bar
+    unit: str
+        Unit label for the progress steps, by default "steps"
+
+    """
+
+    def decorated_func(func: Callable[P, T]) -> Callable[P, T]:
+        @wraps(func)
+        def decorator(*args: P.args, **kwargs: P.kwargs) -> T:
+            with progress_bar(total=total, desc=desc, unit=unit):
+                return func(*args, **kwargs)
+
+        return decorator
+
+    return decorated_func

luna_quantum/util/pretty_base.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel
+
+
+class PrettyBase(BaseModel):
+    """Helper class to implement pretty print."""
+
+    def _pretty_print(self, data: dict, indent: int = 0) -> str:  # type: ignore[type-arg]
+        """Return nested dictionaries in a readable YAML-inspired format as a string.
+
+        This format enhances human readability by using a YAML-like structured style.
+
+        Parameters
+        ----------
+        data: dict
+        indent: int
+        """
+        output = ""
+        for key, value in data.items():
+            output += "    " * indent + str(key) + ":"
+            if isinstance(value, dict):
+                if value == {}:
+                    output += " {}\n"
+                else:
+                    output += "\n"
+                    output += self._pretty_print(value, indent + 1)
+            elif isinstance(value, datetime):
+                output += f" {value.strftime('%Y-%m-%d %H:%M:%S (%Z)')}\n"
+            else:
+                output += f" {value}\n"
+        return output
+
+    def __str__(self) -> str:
+        """Override the default object string representation."""
+        data = self.model_dump()
+
+        return self._pretty_print(data)
+
+    @property
+    def head(self) -> str:
+        """Print a truncated version of the pretty print console representation."""
+        limit = 20
+
+        def truncate(data: dict, limit: int) -> tuple[dict, bool]:  # type: ignore[type-arg]
+            if data is None:
+                return None, False
+
+            if isinstance(data, dict):
+                d = {
+                    k: truncate(v, limit)[0]
+                    for i, (k, v) in enumerate(data.items())
+                    if i < limit
+                }
+                return d, len(data) > limit
+            if isinstance(data, list):
+                d = data[:limit]
+                return d, len(data) > limit
+            return data, False
+
+        data = self.model_dump()
+
+        data_truncated, _ = truncate(data, limit)
+
+        return self._pretty_print(data_truncated)

luna_quantum/util/pydantic_utils.py

@@ -0,0 +1,38 @@
+from typing import TypeVar
+
+from pydantic import BaseModel
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class PydanticUtils:
+    """A utility class for operations on Pydantic models."""
+
+    @staticmethod
+    def update_model(to_update: T, other_model: T) -> None:
+        """
+        Update the attributes of a given pydantic model.
+
+        This function works by iterating over the attributes
+        of the second model (provided as input) and assigns the corresponding values
+        to the attributes of the first model.
+
+        Parameters
+        ----------
+        to_update : T
+            The model instance whose attributes need to be updated. This instance
+            will have its attributes overridden with the corresponding values from
+            the other model instance.
+        other_model : T
+            The model instance providing the new values for the update. Its
+            attributes are used to overwrite the attributes of the `to_update`
+            instance.
+
+        Returns
+        -------
+        None
+            This function does not return a value. Instead, it updates the
+            `to_update` instance in place.
+        """
+        for key, value in other_model.model_dump().items():
+            setattr(to_update, key, value)

luna_quantum/utils.py

@@ -0,0 +1,3 @@
+"""Utility module containing convenience functions."""
+
+from ._core.utils import *  # type: ignore[reportMissingImports] # noqa: F403

luna_quantum/utils.pyi

@@ -0,0 +1,67 @@
+from collections.abc import Generator, Iterable
+from typing import overload
+
+from . import Expression, Variable
+
+@overload
+def quicksum(iterable: Generator[Expression], /) -> Expression: ...
+@overload
+def quicksum(iterable: Generator[Variable], /) -> Expression: ...
+@overload
+def quicksum(iterable: Generator[int], /) -> Expression: ...
+@overload
+def quicksum(iterable: Generator[float], /) -> Expression: ...
+@overload
+def quicksum(
+    iterable: Generator[Expression], /, start: Expression | None = None
+) -> Expression: ...
+@overload
+def quicksum(
+    iterable: Generator[Variable], /, start: Expression | None = None
+) -> Expression: ...
+@overload
+def quicksum(
+    iterable: Generator[int], /, start: Expression | None = None
+) -> Expression: ...
+@overload
+def quicksum(
+    iterable: Generator[float], /, start: Expression | None = None
+) -> Expression: ...
+@overload
+def quicksum(
+    iterable: Generator[Expression | Variable | float | int],
+    /,
+    start: Expression | None = None,
+) -> Expression: ...
+@overload
+def quicksum(iterable: Iterable[Expression], /) -> Expression: ...
+@overload
+def quicksum(iterable: Iterable[Variable], /) -> Expression: ...
+@overload
+def quicksum(iterable: Iterable[int], /) -> Expression: ...
+@overload
+def quicksum(iterable: Iterable[float], /) -> Expression: ...
+@overload
+def quicksum(
+    iterable: Iterable[Expression], /, start: Expression | None = None
+) -> Expression: ...
+@overload
+def quicksum(
+    iterable: Iterable[Variable], /, start: Expression | None = None
+) -> Expression: ...
+@overload
+def quicksum(
+    iterable: Iterable[int], /, start: Expression | None = None
+) -> Expression: ...
+@overload
+def quicksum(
+    iterable: Iterable[float], /, start: Expression | None = None
+) -> Expression: ...
+@overload
+def quicksum(
+    iterable: Iterable[Expression | Variable | float | int],
+    /,
+    start: Expression | None = None,
+) -> Expression: ...
+
+__all__ = ["quicksum"]