qbraid-core 0.1.0.dev0__tar.gz → 0.1.0.dev1__tar.gz

{qbraid-core-0.1.0.dev0 → qbraid-core-0.1.0.dev1}/.gitignore

@@ -1,5 +1,6 @@
 # project files
 qbraid_core/_version.py
+docs/stubs/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

{qbraid-core-0.1.0.dev0 → qbraid-core-0.1.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: qbraid-core
-Version: 0.1.0.dev0
+Version: 0.1.0.dev1
 Summary: Python library with core abstractions for software development in the qBraid ecosystem.
 Author-email: qBraid Development Team <contact@qbraid.com>
 License: Proprietary
@@ -88,10 +88,11 @@ Other credential configuration methods can be found [here](https://docs.qbraid.c
 After configuring your qBraid credentials, verify your setup by running the following from a Python interpreter:
 
 ```python
->>> from qbraid_core.devices import get_devices
->>> device_data, _ = get_devices()
+>>> import qbraid_core
+>>> quantum_client = qbraid_core.client('quantum')
+>>> device_data = quantum_client.search_devices()
 >>> for item in device_data:
-...     print(item)
+...     print(item['qbraid_id'])
 ```
 
 ## Community

{qbraid-core-0.1.0.dev0 → qbraid-core-0.1.0.dev1}/README.md

@@ -50,10 +50,11 @@ Other credential configuration methods can be found [here](https://docs.qbraid.c
 After configuring your qBraid credentials, verify your setup by running the following from a Python interpreter:
 
 ```python
->>> from qbraid_core.devices import get_devices
->>> device_data, _ = get_devices()
+>>> import qbraid_core
+>>> quantum_client = qbraid_core.client('quantum')
+>>> device_data = quantum_client.search_devices()
 >>> for item in device_data:
-...     print(item)
+...     print(item['qbraid_id'])
 ```
 
 ## Community

qbraid-core-0.1.0.dev1/docs/api/qbraid_core.services.rst

@@ -0,0 +1,16 @@
+qbraid_core.services
+====================
+
+.. automodule:: qbraid_core.services
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+-----------
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   environments
+   quantum

{qbraid-core-0.1.0.dev0 → qbraid-core-0.1.0.dev1}/docs/index.rst

@@ -96,9 +96,7 @@ Documentation
    :hidden:
 
    api/qbraid_core
-   api/qbraid_core.devices
-   api/qbraid_core.environments
-   api/qbraid_core.jobs
+   api/qbraid_core.services
    api/qbraid_core.system
 
 

{qbraid-core-0.1.0.dev0 → qbraid-core-0.1.0.dev1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qbraid-core"
-version = "0.1.0.dev0"
+version = "0.1.0.dev1"
 authors = [
     {name = "qBraid Development Team", email = "contact@qbraid.com"},
 ]

qbraid-core-0.1.0.dev1/qbraid_core/__init__.py

@@ -0,0 +1,106 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+This top level module contains the main qBraid public functionality.
+
+.. currentmodule:: qbraid_core
+
+Classes
+----------
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   QbraidClient
+   QbraidSession
+   PostForcelistRetry
+
+
+Functions
+----------
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   client
+   register_client
+   discover_services
+   setup_default_session
+
+Exceptions
+------------
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   QbraidException
+   AuthError
+   ConfigError
+   RequestsApiError
+
+"""
+from .client import QbraidClient
+from .exceptions import (
+    AuthError,
+    ConfigError,
+    QbraidException,
+    RequestsApiError,
+    ResourceNotFoundError,
+    UserNotFoundError,
+)
+from .registry import discover_services, register_client
+from .retry import PostForcelistRetry
+from .session import QbraidSession
+
+# Hold the default session in a global variable, but don't initialize it yet.
+_DEFAULT_SESSION = None
+
+
+def setup_default_session(**kwargs):
+    """
+    Set up a default session, passing through any parameters to the session
+    constructor. There is no need to call this unless you wish to pass custom
+    parameters, because a default session will be created for you.
+    """
+    global _DEFAULT_SESSION  # pylint: disable=global-statement
+    _DEFAULT_SESSION = QbraidSession(**kwargs)
+
+
+def _get_default_session():
+    """
+    Get or create a default session. If the session does not exist, it is created
+    with the provided keyword arguments. If it already exists, the existing session
+    is returned, ignoring any provided arguments.
+
+    This function ensures that a session is created only once and reused, offering
+    a balance between laziness and reusability.
+
+    Args:
+        **kwargs: Keyword arguments to pass to the Session constructor if creating
+                  a new session.
+
+    Returns:
+        The default session instance.
+    """
+    if _DEFAULT_SESSION is None:
+        setup_default_session()
+
+    return _DEFAULT_SESSION
+
+
+def client(*args, **kwargs):
+    """
+    Create a client for a specified service using the default session. If specific
+    session parameters are needed, a new default session can be initialized before
+    calling this function.
+
+    Args:
+        service_name (str): The name of the service for which to create the client.
+        **kwargs: Keyword arguments for session customization, used only if creating
+                  a new default session.
+
+    Returns:
+        A service client instance.
+    """
+    return _get_default_session().client(*args, **kwargs)

{qbraid-core-0.1.0.dev0 → qbraid-core-0.1.0.dev1}/qbraid_core/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.1.dev1+gd5f4c29'
-__version_tuple__ = version_tuple = (0, 1, 'dev1', 'gd5f4c29')
+__version__ = version = '0.1.dev1+g2b36ca5'
+__version_tuple__ = version_tuple = (0, 1, 'dev1', 'g2b36ca5')

qbraid-core-0.1.0.dev1/qbraid_core/client.py

@@ -0,0 +1,110 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module defining abstract base clas for qBraid micro-service clients.
+
+"""
+import datetime
+import os
+import re
+from typing import Optional
+
+from .exceptions import AuthError, RequestsApiError, ResourceNotFoundError, UserNotFoundError
+from .session import QbraidSession
+
+
+class QbraidClient:
+    """Base class for qBraid micro-service clients."""
+
+    def __init__(self, session: Optional[QbraidSession] = None):
+        self.session = session or QbraidSession()
+
+    @property
+    def session(self) -> QbraidSession:
+        """The QbraidSession used to make requests."""
+        return self._session
+
+    @session.setter
+    def session(self, value: Optional[QbraidSession]) -> None:
+        """Set the QbraidSession.
+
+        Raises:
+            AuthError: If the provided session is not valid.
+        """
+        qbraid_session = value or QbraidSession()
+        try:
+            _ = qbraid_session.get_user()
+        except UserNotFoundError as err:
+            raise AuthError("Access denied due to missing or invalid credentials") from err
+        self._session = qbraid_session
+
+    @staticmethod
+    def _is_valid_object_id(candidate_id: str) -> bool:
+        """
+        Check if the provided string is a valid MongoDB ObjectId format.
+
+        Args:
+            candidate_id (str): The string to check.
+
+        Returns:
+            bool: True if the string is a valid ObjectId format, False otherwise.
+        """
+        try:
+            return bool(re.match(r"^[0-9a-fA-F]{24}$", candidate_id))
+        except (TypeError, SyntaxError):
+            return False
+
+    @staticmethod
+    def _convert_email_symbols(email: str) -> Optional[str]:
+        """Convert email to compatible string format"""
+        return (
+            email.replace("-", "-2d")
+            .replace(".", "-2e")
+            .replace("@", "-40")
+            .replace("_", "-5f")
+            .replace("+", "-2b")
+        )
+
+    def _running_in_lab(self) -> bool:
+        """Check if running in the qBraid Lab environment."""
+        # API interaction to confirm environment
+        try:
+            utc_datetime = datetime.datetime.now(datetime.UTC)
+        except AttributeError:  # deprecated but use as fallback if datetime.UTC is not available
+            utc_datetime = datetime.datetime.utcnow()
+
+        try:
+            formatted_time = utc_datetime.strftime("%Y%m%d%H%M%S")
+            directory = os.path.join(os.path.expanduser("~"), ".qbraid", "certs")
+            filepath = os.path.join(directory, formatted_time)
+            os.makedirs(directory, exist_ok=True)
+
+            # Create an empty file
+            with open(filepath, "w", encoding="utf-8"):
+                pass  # The file is created and closed immediately
+
+            response = self.session.get(f"/lab/is-mounted/{formatted_time}")
+            is_mounted = bool(response.json().get("isMounted", False))
+        except (RequestsApiError, KeyError):
+            is_mounted = False
+
+        try:
+            os.remove(filepath)
+        except (FileNotFoundError, IOError):
+            pass
+        return is_mounted
+
+    def user_credits_value(self) -> float:
+        """
+        Get the current user's qBraid credits value.
+
+        Returns:
+            float: The current user's qBraid credits value.
+        """
+        try:
+            res = self.session.get("/billing/credits/get-user-credits").json()
+            credits_value = res["qbraidCredits"]
+            return float(credits_value)
+        except (RequestsApiError, KeyError, ValueError) as err:
+            raise ResourceNotFoundError("Credits value not found") from err

{qbraid-core-0.1.0.dev0 → qbraid-core-0.1.0.dev1}/qbraid_core/exceptions.py

@@ -34,3 +34,11 @@ class ConfigError(QbraidException):
 
 class RequestsApiError(QbraidException):
     """Exception re-raising a RequestException."""
+
+
+class ResourceNotFoundError(QbraidException):
+    """Exception re-raising a RequestException."""
+
+
+class UserNotFoundError(ResourceNotFoundError):
+    """Exception raised when a user is not found."""

qbraid-core-0.1.0.dev1/qbraid_core/registry.py

@@ -0,0 +1,77 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module for registering qBraid service clients.
+
+"""
+import importlib
+import inspect
+import os
+import pkgutil
+from typing import Callable, Dict, Iterator, Optional, Type
+
+client_registry: Dict[str, Type] = {}
+
+
+def register_client(service_name: Optional[str] = None) -> Callable:
+    """
+    Decorator to register a client class under a given service name.
+
+    If the service name is not explicitly provided, the decorator attempts to infer the service name
+    based on the directory name of the module where the decorated class is defined. This is useful
+    for automating the registration of service clients based on their directory structure.
+
+    Args:
+        service_name (Optional[str]): The name of the service to register the client under. If None,
+                                      the name is inferred from the module's directory name.
+
+    Returns:
+        Callable: A decorator that registers the decorated class in the global `client_registry`
+                  under the determined service name.
+
+    Raises:
+        ValueError: If the service name could not be determined automatically.
+
+    Example:
+        @register_client()
+        class Service1Client:
+        # Implementation of the client
+    """
+
+    def decorator(cls: Type) -> Type:
+        nonlocal service_name
+        if service_name is None:
+            # Inspect the stack to find the module of the caller
+            frame = inspect.stack()[1]
+            module = inspect.getmodule(frame[0])
+            if module is not None and hasattr(module, "__file__"):
+                # Extract the service name from the module's file path
+                service_dir = os.path.basename(os.path.dirname(module.__file__))
+                service_name = service_dir
+            else:
+                raise ValueError("Could not determine the service name automatically.")
+
+        # Register the class with the determined service name
+        client_registry[service_name] = cls
+
+        return cls
+
+    return decorator
+
+
+def discover_services(directory: str) -> Iterator[str]:
+    """
+    Discover and import service client modules to trigger registration.
+
+    Args:
+        directory (str): Directory path to search for service modules.
+
+    Returns:
+        Iterator over the names of the discovered services.
+    """
+    for _, name, ispkg in pkgutil.iter_modules([directory]):
+        if ispkg:
+            package = f"qbraid_core.services.{name}"
+            yield name
+            importlib.import_module(package)

qbraid-core-0.1.0.dev1/qbraid_core/retry.py

@@ -0,0 +1,83 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module containing custom ``urllib3.Retry`` class
+
+"""
+
+import logging
+
+from urllib3.util.retry import Retry
+
+STATUS_FORCELIST = (
+    500,  # General server error
+    502,  # Bad Gateway
+    503,  # Service Unavailable
+    504,  # Gateway Timeout
+    520,  # Cloudflare general error
+    522,  # Cloudflare connection timeout
+    524,  # Cloudflare Timeout
+)
+
+logger = logging.getLogger(__name__)
+
+
+class PostForcelistRetry(Retry):
+    """Custom :py:class:`urllib3.Retry` class that performs retry on ``POST`` errors in the
+    force list. Retrying of ``POST`` requests are allowed *only* when the status code returned
+    is on the :py:const:`~qbraid_core.retry.STATUS_FORCELIST`. While ``POST`` requests are
+    recommended not to be retried due to not being idempotent, retrying on specific 5xx errors
+    through the qBraid API is safe.
+    """
+
+    def increment(  # type: ignore[no-untyped-def]
+        self,
+        method=None,
+        url=None,
+        response=None,
+        error=None,
+        _pool=None,
+        _stacktrace=None,
+    ):
+        """Overwrites parent class increment method for logging."""
+        if logger.getEffectiveLevel() is logging.DEBUG:
+            # coverage: ignore
+            status = data = headers = None
+            if response:
+                status = response.status
+                data = response.data
+                headers = response.headers
+            logger.debug(
+                "Retrying method=%s, url=%s, status=%s, error=%s, data=%s, headers=%s",
+                method,
+                url,
+                status,
+                error,
+                data,
+                headers,
+            )
+        return super().increment(
+            method=method,
+            url=url,
+            response=response,
+            error=error,
+            _pool=_pool,
+            _stacktrace=_stacktrace,
+        )
+
+    def is_retry(self, method: str, status_code: int, has_retry_after: bool = False) -> bool:
+        """Indicate whether the request should be retried.
+
+        Args:
+            method: Request method.
+            status_code: Status code.
+            has_retry_after: Whether retry has been done before.
+
+        Returns:
+            ``True`` if the request should be retried, ``False`` otherwise.
+        """
+        if method.upper() == "POST" and status_code in self.status_forcelist:
+            return True
+
+        return super().is_retry(method, status_code, has_retry_after)

{qbraid-core-0.1.0.dev0/qbraid_core → qbraid-core-0.1.0.dev1/qbraid_core/services}/environments/__init__.py

@@ -2,9 +2,17 @@
 # All rights reserved.
 
 """
-Module for interfacing with qBraid environments.
+Module providing utilities for interfacing with qBraid environments
 
-.. currentmodule:: qbraid_core.environments
+.. currentmodule:: qbraid_core.services.environments
+
+Classes
+----------
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   EnvironmentManagerClient
 
 Functions
 ----------
@@ -12,10 +20,10 @@ Functions
 .. autosummary::
    :toctree: ../stubs/
 
-   create_venv
+   create_local_venv
    install_status_codes
    update_install_status
-   get_qbraid_envs_paths
+   get_default_envs_paths
    get_env_path
    get_tmp_dir_names
    get_next_tmpn
@@ -29,15 +37,17 @@ Exceptions
 .. autosummary::
    :toctree: ../stubs/
 
-   QbraidEnvironmentError
+   EnvironmentServiceRequestError
+   EnvironmentServiceRuntimeError
 
 """
-from .create import create_venv
-from .exceptions import QbraidEnvironmentError
+from .client import EnvironmentManagerClient
+from .create import create_local_venv
+from .exceptions import EnvironmentServiceRequestError, EnvironmentServiceRuntimeError
 from .paths import (
+    get_default_envs_paths,
     get_env_path,
     get_next_tmpn,
-    get_qbraid_envs_paths,
     get_tmp_dir_names,
     which_python,
 )

qbraid-core-0.1.0.dev1/qbraid_core/services/environments/client.py

@@ -0,0 +1,105 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module providing client for interacting with qBraid quantum services.
+
+"""
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from qbraid_core.client import QbraidClient
+from qbraid_core.exceptions import RequestsApiError
+from qbraid_core.registry import register_client
+
+from .exceptions import EnvironmentServiceRequestError
+from .paths import get_default_envs_paths
+from .validate import is_valid_env_name, is_valid_slug
+
+
+@register_client()
+class EnvironmentManagerClient(QbraidClient):
+    """Client for interacting with qBraid environment services."""
+
+    # envs_paths = Optional[Union[Path, str]] = None
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.envs_paths = get_default_envs_paths()
+
+    @property
+    def envs_paths(self) -> List[Path]:
+        """Returns a dictionary of environment paths.
+
+        Returns:
+            A dictionary containing the environment paths.
+        """
+        return self._envs_paths
+
+    @envs_paths.setter
+    def envs_paths(self, value: List[Path]):
+        """Sets the qBraid environments paths."""
+        self._envs_paths = value
+
+    def create_environment(self, name: str, description: Optional[str] = None) -> Dict[str, Any]:
+        """Creates a new environment with the given name and description.
+
+        Args:
+            name: The name of the environment to create.
+            description: Optional description of the environment.
+
+        Returns:
+            A dictionary containing the environment data.
+
+        Raises:
+            ValueError: If the environment name is invalid or the description is too long.
+            EnvironmentServiceRequestError: If the create environment request fails.
+        """
+        if not is_valid_env_name(name):
+            raise ValueError(f"Invalid environment name: {name}")
+
+        if description and len(description) > 300:
+            raise ValueError("Description is too long. Maximum length is 300 characters.")
+
+        req_body = {
+            "name": name,
+            "description": description or "",
+            "tags": "",  # comma separated list of tags
+            "code": "",  # newline separated list of packages
+            "visibility": "private",
+            "kernelName": "",
+            "prompt": "",
+            "origin": "CLI",  # TODO: change to "CORE"
+        }
+
+        try:
+            env_data = self.session.post("/environments/create", json=req_body).json()
+        except RequestsApiError as err:
+            raise EnvironmentServiceRequestError("Create environment request failed") from err
+
+        if env_data is None or len(env_data) == 0 or env_data.get("slug") is None:
+            raise EnvironmentServiceRequestError(
+                "Create environment request responsed with invalid environment data"
+            )
+
+        return env_data
+
+    def delete_environment(self, slug: str) -> None:
+        """Deletes the environment with the given slug.
+
+        Args:
+            slug: The slug of the environment to delete.
+
+        Returns:
+            None
+
+        Raises:
+            ValueError: If the environment slug is invalid.
+            EnvironmentServiceRequestError: If the delete environment request fails.
+        """
+        if not is_valid_slug(slug):
+            raise ValueError(f"Invalid environment slug: {slug}")
+
+        try:
+            self.session.delete(f"/environments/{slug}")
+        except RequestsApiError as err:
+            raise EnvironmentServiceRequestError("Delete environment request failed") from err

{qbraid-core-0.1.0.dev0/qbraid_core → qbraid-core-0.1.0.dev1/qbraid_core/services}/environments/create.py

@@ -21,7 +21,7 @@ logging.basicConfig(
 )
 
 
-def create_venv(slug_path: Union[str, Path], prompt: str) -> None:
+def create_local_venv(slug_path: Union[str, Path], prompt: str) -> None:
     """Create virtual environment and swap PS1 display name."""
     try:
         # Ensure slug_path is a Path object

qbraid-core-0.1.0.dev1/qbraid_core/services/environments/exceptions.py

@@ -0,0 +1,18 @@
+# Copyright (c) 2024, qBraid Development Team
+# All rights reserved.
+
+"""
+Module defining custom exceptions for the qBraid environments module.
+
+"""
+
+from qbraid_core.exceptions import QbraidException
+
+
+class EnvironmentServiceRequestError(QbraidException):
+    """Base class for errors raised by API requests made through qBraid environment
+    service clients."""
+
+
+class EnvironmentServiceRuntimeError(QbraidException):
+    """Base class for runtime errors raised by qBraid quantum service clients."""