luna-quantum 1.1.0__cp312-cp312-win_amd64.whl

luna_quantum/_utility.py

@@ -0,0 +1,148 @@
+"""Utility module for internals."""
+
+import sys
+
+if sys.version_info < (3, 13):
+    from warnings import warn
+
+    class DeprecationWarning(Warning): ...  # noqa: A001
+
+    class deprecated:  # noqa: N801
+        """Indicate that a class, function or overload is deprecated.
+
+        When this decorator is applied to an object, the type checker
+        will generate a diagnostic on usage of the deprecated object.
+
+        Usage:
+
+            @deprecated("Use B instead")
+            class A:
+                pass
+
+            @deprecated("Use g instead")
+            def f():
+                pass
+
+            @overload
+            @deprecated("int support is deprecated")
+            def g(x: int) -> int: ...
+            @overload
+            def g(x: str) -> int: ...
+
+        The warning specified by *category* will be emitted at runtime
+        on use of deprecated objects. For functions, that happens on calls;
+        for classes, on instantiation and on creation of subclasses.
+        If the *category* is ``None``, no warning is emitted at runtime.
+        The *stacklevel* determines where the
+        warning is emitted. If it is ``1`` (the default), the warning
+        is emitted at the direct caller of the deprecated object; if it
+        is higher, it is emitted further up the stack.
+        Static type checker behavior is not affected by the *category*
+        and *stacklevel* arguments.
+
+        The deprecation message passed to the decorator is saved in the
+        ``__deprecated__`` attribute on the decorated object.
+        If applied to an overload, the decorator
+        must be after the ``@overload`` decorator for the attribute to
+        exist on the overload as returned by ``get_overloads()``.
+
+        See PEP 702 for details.
+
+        """
+
+        def __init__(
+            self,
+            message: str,
+            /,
+            *,
+            category: type[Warning] | None = DeprecationWarning,  # noqa: PYI011,RUF100
+            stacklevel: int = 1,
+        ) -> None:
+            if not isinstance(message, str):
+                raise TypeError(  # noqa: TRY003
+                    f"Expected an object of type str for 'message', not {type(message).__name__!r}"  # noqa: E501
+                )
+            self.message = message
+            self.category = category
+            self.stacklevel = stacklevel
+
+        def __call__(self, arg, /):  # noqa: C901,ANN001,ANN204
+            # Make sure the inner functions created below don't
+            # retain a reference to self.
+            msg = self.message
+            category = self.category
+            stacklevel = self.stacklevel
+            if category is None:
+                arg.__deprecated__ = msg
+                return arg
+            elif isinstance(arg, type):  # noqa: RET505
+                import functools  # noqa: PLC0415
+                from types import MethodType  # noqa: PLC0415
+
+                original_new = arg.__new__
+
+                @functools.wraps(original_new)
+                def __new__(cls, /, *args, **kwargs):  # noqa: N807,ANN001,ANN202,ANN003,ANN002
+                    if cls is arg:
+                        warn(msg, category=category, stacklevel=stacklevel + 1)
+                    if original_new is not object.__new__:
+                        return original_new(cls, *args, **kwargs)
+                    # Mirrors a similar check in object.__new__.
+                    elif cls.__init__ is object.__init__ and (args or kwargs):  # noqa: RET505
+                        raise TypeError(f"{cls.__name__}() takes no arguments")  # noqa: TRY003
+                    else:
+                        return original_new(cls)
+
+                arg.__new__ = staticmethod(__new__)
+
+                original_init_subclass = arg.__init_subclass__
+                # We need slightly different behavior if __init_subclass__
+                # is a bound method (likely if it was implemented in Python)
+                if isinstance(original_init_subclass, MethodType):
+                    original_init_subclass = original_init_subclass.__func__
+
+                    @functools.wraps(original_init_subclass)
+                    def __init_subclass__(*args, **kwargs):  # noqa: ANN002,ANN202,ANN003,N807
+                        warn(msg, category=category, stacklevel=stacklevel + 1)
+                        return original_init_subclass(*args, **kwargs)
+
+                    arg.__init_subclass__ = classmethod(__init_subclass__)
+                # Or otherwise, which likely means it's a builtin such as
+                # object's implementation of __init_subclass__.
+                else:
+
+                    @functools.wraps(original_init_subclass)
+                    def __init_subclass__(*args, **kwargs):  # noqa: ANN202,ANN002,ANN003,N807
+                        warn(msg, category=category, stacklevel=stacklevel + 1)
+                        return original_init_subclass(*args, **kwargs)
+
+                    arg.__init_subclass__ = __init_subclass__
+
+                arg.__deprecated__ = __new__.__deprecated__ = msg
+                __init_subclass__.__deprecated__ = msg
+                return arg
+            elif callable(arg):
+                import functools  # noqa: PLC0415
+                import inspect  # noqa: PLC0415
+
+                @functools.wraps(arg)
+                def wrapper(*args, **kwargs):  # noqa: ANN002,ANN003,ANN202
+                    warn(msg, category=category, stacklevel=stacklevel + 1)
+                    return arg(*args, **kwargs)
+
+                if inspect.iscoroutinefunction(arg):
+                    wrapper = inspect.markcoroutinefunction(wrapper)
+
+                arg.__deprecated__ = wrapper.__deprecated__ = msg
+                return wrapper
+            else:
+                raise TypeError(  # noqa: TRY003
+                    "@deprecated decorator with non-None category must be applied to "
+                    f"a class or callable, not {arg!r}"
+                )
+
+else:
+    from warnings import deprecated
+
+
+__all__ = ["deprecated"]

luna_quantum/_utility.pyi

@@ -0,0 +1,20 @@
+import sys
+
+if sys.version_info < (3, 13):  # noqa: PYI066
+    class DeprecationWarning(Warning): ...  # noqa: A001
+
+    class deprecated:  # noqa: N801
+        def __init__(
+            self,
+            message: str,
+            /,
+            *,
+            category: type[Warning] | None = ...,
+            stacklevel: int = 1,
+        ) -> None: ...
+        def __call__(self, arg, /): ...  # noqa: ANN001,ANN204
+
+else:
+    from warnings import deprecated
+
+__all__ = ["deprecated"]

luna_quantum/algorithms/__init__.py

@@ -0,0 +1 @@
+from luna_quantum.solve.parameters.algorithms import *  # noqa: F403

luna_quantum/aqm_overwrites/__init__.py

@@ -0,0 +1,3 @@
+from .model import Model
+
+__all__ = ["Model"]

luna_quantum/aqm_overwrites/model.py

@@ -0,0 +1,184 @@
+from luna_quantum._core import Model, Solution
+from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+from luna_quantum.factories.luna_solve_client_factory import LunaSolveClientFactory
+from luna_quantum.factories.usecase_factory import UseCaseFactory
+from luna_quantum.solve.domain.model_metadata import ModelMetadata
+from luna_quantum.solve.domain.solve_job import SolveJob
+from luna_quantum.util.class_patcher import (
+    patch_instance,
+    patch_property,
+    patch_static,
+)
+
+
+@patch_property(Model)
+def metadata(self: Model) -> ModelMetadata | None:
+    """
+    Return metadata for the current Model instance.
+
+    If metadata is cached and corresponds to the current hash, returns the cached
+    metadata. Otherwise, retrieves metadata via a client and updates the cache.
+
+    Parameters
+    ----------
+    self
+        Instance of Model.
+
+    Returns
+    -------
+    Optional[ModelMetadata]
+        Metadata for the current Model instance, or None if an error occurs or
+        metadata cannot be retrieved.
+    """
+    _hash = self.__hash__()
+    if (
+        "metadata" in self._metadata  # type: ignore[attr-defined]
+        and "hash" in self._metadata  # type: ignore[attr-defined]
+        and self._metadata["hash"] == _hash  # type: ignore[attr-defined]
+    ):
+        return self._metadata["metadata"]  # type: ignore  # noqa: PGH003 # Patched Model
+    client = LunaSolveClientFactory.get_client(
+        None
+    )  # TODO(Llewellyn): is there a way to let the user overwrite # noqa: FIX002
+    #  set the client here
+    try:
+        _metadata = UseCaseFactory.model_load_metadata_by_hash(client=client).__call__(
+            model_hash=_hash
+        )
+    except Exception:
+        _metadata = None
+    self._metadata["metadata"] = _metadata  # type: ignore  # noqa: PGH003 # Patched Model
+    self._metadata["hash"] = _hash  # type: ignore  # noqa: PGH003 # Patched Model
+
+    return _metadata
+
+
+@patch_static(Model)
+def load_luna(model_id: str, client: ILunaSolve | str | None = None) -> Model:
+    """
+    Load an AQ model using a specific model ID.
+
+    This function retrieves an AQ model from a client obj. The client can either be
+    provided directly or created dynamically if not specified.
+
+    Parameters
+    ----------
+    model_id : str
+        The identifier of the model that needs to be loaded.
+    client : Optional[Union[ILunaSolve, str]]
+        The client to use for loading the model. If not provided, a client
+        will be created automatically.
+
+    Returns
+    -------
+    Model
+        The AQ model that was successfully loaded.
+    """
+    client = LunaSolveClientFactory.get_client(client=client)
+    return UseCaseFactory.model_load_by_id(client=client).__call__(model_id=model_id)
+
+
+@patch_instance(Model)
+def save_luna(self: Model, client: ILunaSolve | str | None = None) -> None:
+    """
+    Save the model and update its metadata and hash.
+
+    This function saves the current state of the model using the provided client or
+    default client obtained from `ClientFactory`. It also updates the local `metadata`
+    attributes of the model after saving.
+
+    Parameters
+    ----------
+    self : Model
+        The instance of the Model class.
+    client : Optional[Union[ILunaSolve, str]], default=None
+        The client to facilitate saving the model. Can be an instance of `ILunaSolve`,
+        a string representing the client, or left as None to use the default client.
+
+    Returns
+    -------
+    None
+        This function does not return any values.
+
+    """
+    client = LunaSolveClientFactory.get_client(client=client)
+    self._metadata["metadata"] = UseCaseFactory.model_save(client=client).__call__(self)  # type: ignore  # noqa: PGH003 # Patched Model
+    self._metadata["hash"] = self.__hash__()  # type: ignore[attr-defined]
+
+
+@patch_instance(Model)
+def delete_luna(self: Model, client: ILunaSolve | str | None = None) -> None:
+    """
+    Delete the Luna instance of the Model.
+
+    Ensure the Model instance is removed properly using the provided client or the
+    default client.
+
+    Parameters
+    ----------
+    self : Model
+        The instance of the model to be deleted.
+    client : Optional[Union[ILunaSolve, str]], optional
+        The client used to connect to the service. If not provided, the default
+        client is used.
+
+    Returns
+    -------
+    None
+    """
+    client = LunaSolveClientFactory.get_client(client=client)
+    UseCaseFactory.model_delete(client=client).__call__(self)
+
+
+@patch_instance(Model)
+def load_solutions(
+    self: Model, client: ILunaSolve | str | None = None
+) -> list[Solution]:
+    """
+    Load solutions for an Model.
+
+    Fetch and return the list of all solutions for the patched Model
+    using the provided client or the default client.
+
+    Parameters
+    ----------
+    self : Model
+        The Model for which solutions are to be loaded.
+    client : Optional[Union[ILunaSolve, str]], optional
+        The client used to interact and retrieve model solutions. If not provided,
+        a default client will be created using the `ClientFactory`.
+
+    Returns
+    -------
+    List[IAqSolution]
+        A list of IAqSolution instances containing the solutions.
+
+    """
+    client = LunaSolveClientFactory.get_client(client=client)
+    return UseCaseFactory.model_get_solution(client=client).__call__(self)
+
+
+@patch_instance(Model)
+def load_solve_jobs(
+    self: Model, client: ILunaSolve | str | None = None
+) -> list[SolveJob]:
+    """
+    Load and return a list of SolveJob objects for the Model instance.
+
+    Parameters
+    ----------
+    self : Model
+        The instance of the Model for which solve jobs need to be loaded.
+    client : Optional[Union[ILunaSolve, str]], optional
+        The client object or client type for fetching solve jobs, by default None.
+
+    Returns
+    -------
+    List[SolveJob]
+        A list of SolveJob objects related to the Model instance.
+    """
+    client = LunaSolveClientFactory.get_client(client=client)
+    return UseCaseFactory.model_get_solve_job(client=client).__call__(self)
+
+
+__all__ = ["Model"]

luna_quantum/backends/__init__.py

@@ -0,0 +1 @@
+from luna_quantum.solve.parameters.backends import *  # noqa: F403

luna_quantum/client/controllers/__init__.py

@@ -0,0 +1,4 @@
+from luna_quantum.client.controllers.luna_q import LunaQ
+from luna_quantum.client.controllers.luna_solve import LunaSolve
+
+__all__ = ["LunaQ", "LunaSolve"]

luna_quantum/client/controllers/luna_http_client.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from importlib.metadata import version
+from typing import Any
+
+import httpx
+from httpx import Client, Response
+
+from luna_quantum.client.error.timeout_error import LunaTimeoutError
+from luna_quantum.client.error.utils.http_error_utils import HttpErrorUtils
+
+
+class LunaHTTPClient(Client):
+    """
+    Luna HTTP client.
+
+    Mainly used to set custom headers.
+    """
+
+    _version: str = version("luna-quantum")
+
+    _user_agent: str = f"LunaSDK/{_version}"
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+
+        self.headers["User-Agent"] = self._user_agent
+
+    def request(self, *args: Any, **kwargs: Any) -> Response:
+        """Send request to Luna platform."""
+        try:
+            response: Response = super().request(*args, **kwargs)
+        except httpx.TimeoutException:
+            # Handle all possible in httpx timeout exceptions
+            raise LunaTimeoutError from None
+        HttpErrorUtils.check_for_error(response)
+        return response

luna_quantum/client/controllers/luna_platform_client.py

@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+import os
+from abc import abstractmethod
+from contextlib import suppress
+from enum import Enum
+from http import HTTPStatus
+from typing import TYPE_CHECKING, ClassVar
+
+import httpx
+from httpx import HTTPStatusError, Request, Response
+
+from luna_quantum.client.controllers.luna_http_client import LunaHTTPClient
+from luna_quantum.client.error.luna_api_key_invalid_error import LunaApiKeyInvalidError
+from luna_quantum.client.error.luna_api_key_missing_error import LunaApiKeyMissingError
+from luna_quantum.client.error.utils.http_error_utils import HttpErrorUtils
+from luna_quantum.client.interfaces.services.service_i import IService
+from luna_quantum.client.rest_client.users_rest_client import UsersRestClient
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+
+class LunaPrefixEnum(str, Enum):
+    """Enumeration of Luna services."""
+
+    LUNA_SOLVE = "luna-solve"
+    LUNA_Q = "luna-q"
+
+
+def check_httpx_exceptions(response: Response) -> None:
+    """
+    Check if response contains errors from the server.
+
+    This function examines the HTTP response and raises appropriate SDK exceptions
+    if error conditions are detected.
+
+    Parameters
+    ----------
+    response: Response
+        The HTTP response object to be examined for error conditions.
+    """
+    HttpErrorUtils.check_for_error(response)
+
+
+class APIKeyAuth(httpx.Auth):  # noqa: PLW1641
+    """API key authentication method for luna platform."""
+
+    def __init__(self, token: str) -> None:
+        self.token = token
+
+        self.dev_header_value = os.getenv("LUNA_DEV_EXTRA_HEADER_VALUE", None)
+        self.dev_header_name = os.getenv("LUNA_DEV_EXTRA_HEADER_NAME", None)
+
+    def auth_flow(self, request: Request) -> Generator[Request, Response]:
+        """
+        Authenticate a request to Luna platform.
+
+        Parameters
+        ----------
+        request: Request
+            Request that needs to be authenticated.
+        """
+        request.headers["Luna-API-Key"] = self.token
+
+        if self.dev_header_name and self.dev_header_value:
+            request.headers[self.dev_header_name] = self.dev_header_value
+        yield request
+
+    def __eq__(self, other: object) -> bool:
+        """
+        Check if the object is equal to the current instance.
+
+        Parameters
+        ----------
+        other: object
+            Object to compare with the current instance.
+
+        Returns
+        -------
+        bool:
+            True if the object is equal to the current instance, False otherwise.
+
+        """
+        if self is other:
+            return True
+        if not isinstance(other, APIKeyAuth):
+            return False
+        return (
+            self.token == other.token
+            and self.dev_header_name == other.dev_header_name
+            and self.dev_header_value == other.dev_header_value
+        )
+
+
+class LunaPlatformClient(IService):
+    """Luna platform REST client."""
+
+    _base_url: str
+
+    _httpx_client: httpx.Client
+    _api_key: ClassVar[str | None] = None
+    _timeout: float | None = None
+
+    @property
+    def client(self) -> httpx.Client:
+        """
+        Return httpx client.
+
+        Returns
+        -------
+        httpx.Client
+        """
+        return self._httpx_client
+
+    @classmethod
+    @abstractmethod
+    def get_api(cls) -> LunaPrefixEnum:
+        """Return the api of the client."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | None = 240.0,
+    ) -> None:
+        """
+        LunaPlatformClient is a main entrypoint of the SDK.
+
+        All the operations with entities should be processed using an instance of
+        LunaPlatformClient.
+
+        Parameters
+        ----------
+        api: LunaPrefixEnum
+            Current API with which luna client is working. Can be luna-solve or luna-q.
+        api_key: Optional[str]
+            Api key to be used to authorize. Default none.
+            If its none then the key set by the `authorize` method will be used.
+        base_url:
+            Base API URL.
+            If you want to use API not on your local PC then change it.
+            You can do that by setting the environment variable LUNA_BASE_URL.
+            Default value https://api.aqarios.com.
+        timeout:
+            Default timeout in seconds for the requests via the LunaQ client. `None`
+            means that the SDK uses no timeouts. Note that either way the Luna platform
+            itself will time out after 240 seconds.
+            Default: 240.0
+        """
+        self._base_url = self._get_base_url(base_url)
+        self._timeout = timeout
+
+        api_key = self._get_api_key(api_key)
+
+        self.dev_header_value = os.getenv("LUNA_DEV_EXTRA_HEADER_VALUE", None)
+        self.dev_header_name = os.getenv("LUNA_DEV_EXTRA_HEADER_NAME", None)
+
+        self._httpx_client = LunaHTTPClient(
+            auth=APIKeyAuth(api_key),
+            base_url=self._base_url,
+            follow_redirects=True,
+            timeout=self._timeout,
+            event_hooks={"response": [check_httpx_exceptions]},
+        )
+
+        self._authenticate()
+
+    def _get_api_key(self, api_key: str | None = None) -> str:
+        """
+        Retrieve the API key for authentication.
+
+        Get the API key from provided arguments, class-specific key, or environment
+        variables. Raises an error if no API key is available.
+
+        Parameters
+        ----------
+        api_key : str or None, optional
+            An API key string if provided.
+
+        Returns
+        -------
+        str
+            The API key to be used for authentication.
+
+        Raises
+        ------
+        LunaApiKeyMissingError
+            If no API key is available from any source.
+        """
+        if api_key:
+            auth_key = api_key
+        elif self.__class__._api_key:  # noqa: SLF001 Use here self.__class__ so that LunaSolve and LunaQ can have different api keys set
+            auth_key = self.__class__._api_key  # noqa: SLF001 Use here self.__class__ so that LunaSolve and LunaQ can have different api keys set
+        elif key := os.getenv("LUNA_API_KEY", None):
+            auth_key = key
+        else:
+            raise LunaApiKeyMissingError
+        return auth_key
+
+    def _get_base_url(self, base_url: str | None = None) -> str:
+        """
+        Get the base url.
+
+        Parameters
+        ----------
+        base_url: str
+            Base API URL.
+            If you want to use API not on your local PC then change it.
+            You can do that by setting the environment variable LUNA_BASE_URL.
+            Default value https://api.aqarios.com.
+
+        Returns
+        -------
+        str
+            Base url.
+
+        """
+        if base_url is None:
+            base_url = os.getenv("LUNA_BASE_URL", "https://api.aqarios.com")
+        if os.getenv("LUNA_DISABLE_SUFFIX", "false").lower() == "true":
+            return f"{base_url}/api/v1"
+        return f"{base_url}/{self.get_api().value}/api/v1"
+
+    def __del__(self) -> None:  # noqa: D105
+        if hasattr(self, "_httpx_client"):
+            with suppress(Exception):
+                self._httpx_client.close()
+
+    def _authenticate(self) -> None:
+        try:
+            UsersRestClient(service=self).get_me()
+        except HTTPStatusError as exception:
+            if exception.response.status_code == HTTPStatus.UNAUTHORIZED:
+                raise LunaApiKeyInvalidError from exception
+            raise
+
+    def is_same(
+        self,
+        api_key: str | None = None,
+    ) -> bool:
+        """
+        Whether the service is created with the current environment variables.
+
+        Returns
+        -------
+        bool:
+            True if the service is created with the current environment variables.
+            False otherwise.
+        """
+        api_key = self._get_api_key(api_key)
+
+        return (
+            self._get_base_url() == self._base_url
+            and APIKeyAuth(api_key) == self._httpx_client.auth
+        )