pcss-qapi 0.1.0__py3-none-any.whl

pcss_qapi/__init__.py

@@ -0,0 +1,5 @@
+"""Python client for pccs quantum api"""
+
+from pcss_qapi.auth import AuthorizationService
+
+__all__ = ["AuthorizationService"]

pcss_qapi/auth/__init__.py

@@ -0,0 +1,4 @@
+"""Authorization workflows for pcss_qapi"""
+from .auth_service import AuthorizationService
+
+__all__ = ['AuthorizationService']

pcss_qapi/auth/auth_service.py

@@ -0,0 +1,132 @@
+"""Authorization service for pcss_qapi"""
+import json
+import os
+
+import hashlib
+
+from pcss_qapi.auth.oauth_flow import OAuthManager
+from pcss_qapi.utils.fs_manager import FSManager, API_KEY_FILE_NAME
+
+from pcss_qapi.base.connection_base import ApiConnection
+from pcss_qapi.auth.connections import PcssQapiConnection
+
+OAUTH_MANAGERS: dict[str, OAuthManager] = {}
+
+
+def get_manager_for_connection(connection: ApiConnection) -> OAuthManager:
+    """Get oauth manager for given connection type, create new if not existing"""
+    connection_manager = OAUTH_MANAGERS.get(str(hash(connection)), None)
+    if connection_manager is None:
+        connection_manager = OAuthManager(
+            connection.oauth_client_id,
+            connection.oauth_issuer,
+            connection.oauth_min_ttl_seconds
+        )
+        OAUTH_MANAGERS[str(hash(connection))] = connection_manager
+    return connection_manager
+
+
+def get_hash(issuer: str, client_id: str) -> str:
+    """get hash for connection"""
+    return hashlib.sha256(f'{issuer}{client_id}'.encode('utf-8')).hexdigest()
+
+
+class AuthorizationService:
+    """
+    Authentication and login handler for pcss_qapi service
+    """
+
+    @staticmethod
+    def _get_functional_tokens(oauth_manager: OAuthManager) -> tuple[str | None, str | None]:
+        """Get access and refresh tokens, refresh if necessary."""
+        storage_path = FSManager.get_storage_path()
+        filepath = os.path.join(storage_path, API_KEY_FILE_NAME)
+
+        if not os.path.exists(filepath):
+            return None, None
+
+        key_hash = get_hash(oauth_manager.issuer, oauth_manager.client_id)
+
+        access_token, refresh_token = None, None
+        with open(filepath, 'r', encoding='UTF-8') as f:
+            key_infos = json.loads(f.read())
+            key_info = key_infos.get(key_hash, None)
+            if key_info is None:
+                return None, None
+
+            access_token, refresh_token = key_info.get('access_token', None), key_info.get('refresh_token', None)
+            if access_token is None or refresh_token is None:
+                return None, None
+
+            if not oauth_manager.is_token_valid(access_token):
+                access_token, refresh_token = oauth_manager.get_refreshed_tokens(refresh_token)
+
+        if access_token is not None and refresh_token is not None:
+            FSManager.update_credentials(
+                key_hash,
+                {
+                    'refresh_token': refresh_token,
+                    'access_token': access_token
+                })  # Save refreshed tokens
+
+        return access_token, refresh_token
+
+    @staticmethod
+    def login(
+        connection: ApiConnection = PcssQapiConnection,
+    ):
+        """
+        Cache api key string for later use.
+
+        Args:
+        """
+        storage_location = FSManager.get_storage_path()
+
+        storage_path = FSManager.get_fixed_path(storage_location)
+        os.makedirs(storage_path, exist_ok=True)
+
+        connection_manager = get_manager_for_connection(connection)
+        key_hash = get_hash(connection_manager.issuer, connection_manager.client_id)
+
+        access_token, refresh_token = AuthorizationService._get_functional_tokens(connection_manager)
+        if access_token is not None and refresh_token is not None:
+            print("ℹ️ Using cached tokens. If you want to change the account use AuthorizationService.logout() first.")
+            return
+
+        access_token, refresh_token = connection_manager.get_device_flow_tokens()
+        if access_token is None or refresh_token is None:
+            raise ValueError("Authorization error, did not receive tokens.")
+
+        FSManager.update_credentials(
+            key_hash,
+            {
+                'refresh_token': refresh_token,
+                'access_token': access_token
+            })
+
+    @staticmethod
+    def logout(
+        connection: ApiConnection | None = None
+    ):
+        """Remove credentials for active account"""
+
+        filepath = os.path.join(FSManager.get_storage_path(), API_KEY_FILE_NAME)
+        if connection is None:
+            if os.path.exists(filepath):
+                os.remove(filepath)
+            return
+
+        FSManager.remove_credentials(
+            get_hash(connection.oauth_issuer, connection.oauth_client_id)
+        )
+
+    @staticmethod
+    def get_api_key(connection: ApiConnection) -> str:
+        """Get api key string if available. Automatically logs out if unable to refresh key."""
+
+        connection_manager = get_manager_for_connection(connection)
+        access_token, _ = AuthorizationService._get_functional_tokens(connection_manager)
+        if access_token is None:
+            AuthorizationService.logout()
+            raise ValueError("Use AuthorizationService.login()")
+        return access_token

pcss_qapi/auth/connections.py

@@ -0,0 +1,15 @@
+"""Connection definitions"""
+
+from pcss_qapi.base.connection_base import ApiConnection
+
+PcssQapiConnection = ApiConnection(
+    oauth_client_id='jupyter.quantum.psnc.pl-notebooks',
+    oauth_issuer='https://sso.classroom.pionier.net.pl/auth/realms/Classroom',
+    oauth_min_ttl_seconds=60,
+    api_health_url='https://api.quantum.psnc.pl/api/health/test-connection',
+    task_endpoints_url='https://api.quantum.psnc.pl/api/client/tasks',
+    machine_endpoints_url='https://api.quantum.psnc.pl/api/client/machines',
+)
+
+
+__all__ = ['PcssQapiConnection']

pcss_qapi/auth/oauth_flow.py

@@ -0,0 +1,203 @@
+"""OAuth authorization management"""
+import time
+import base64
+import json
+from typing import Any
+import requests
+
+
+def _print_nothing(width):
+    print("".join(' ' for _ in range(width)), end='\r')
+
+
+def _print_formatted_time(time_seconds):
+    spinner = "⣾⣽⣻⢿⡿⣟⣯⣷"
+
+    minutes_left = time_seconds // 60
+    seconds_left = time_seconds % 60
+
+    minutes_string = f'{minutes_left} minutes'
+    seconds_string = f'{seconds_left} seconds'
+
+    s = f"""{spinner[time_seconds % len(spinner)]} Waiting... {" ".join([minutes_string if minutes_left else "",
+                                                                         seconds_string])} remaining to complete authorization."""
+    print(s, end='\r')
+    return len(s)
+
+
+def _show_error(error_type: str | None, last_printed_line_len: int):
+    if error_type == "authorization_pending":
+        pass
+    else:
+        error_message = {
+            'slow_down': '⏳ Server requested slower polling. Increasing interval.',
+            'access_denied': '❌ Access was denied by user.',
+            None: '❌ Failed to parse polling error response.'
+        }.get(error_type, '❌ Failed to parse polling error response.')
+
+        _print_nothing(last_printed_line_len)
+        print(error_message)
+
+
+def _decode_jwt_payload(token):
+    try:
+        parts = token.split(".")
+        if len(parts) != 3:
+            return None
+        padded = parts[1] + "=" * (-len(parts[1]) % 4)
+        decoded_bytes = base64.urlsafe_b64decode(padded)
+        return json.loads(decoded_bytes)
+    except Exception:  # pylint:disable = broad-exception-caught
+        return None
+
+
+class OAuthManager:
+    """Token handler"""
+
+    def __init__(self, client_id, issuer, min_ttl) -> None:
+        self.client_id = client_id
+        self.issuer = issuer
+        self.min_ttl = min_ttl
+
+        self.token_endpoint: str | None = None
+        self.device_endpoint: str | None = None
+
+        self._try_get_urls()
+
+    def _try_get_urls(self) -> bool:
+        success = False
+        try:
+            discovery_url = f"{self.issuer}/.well-known/openid-configuration"
+            discovery = requests.get(discovery_url, timeout=5).json()
+            self.token_endpoint = discovery["token_endpoint"]
+            self.device_endpoint = discovery["device_authorization_endpoint"]
+            success = True
+        except requests.exceptions.ConnectionError:
+            pass
+        return success
+
+    def is_token_valid(self, token):
+        """Check if token will be valid for more than self.min_ttl seconds."""
+        payload = _decode_jwt_payload(token)
+        if not payload or "exp" not in payload:
+            return False
+        exp = payload["exp"]
+        return (exp - int(time.time())) >= self.min_ttl
+
+    def get_refreshed_tokens(self, refresh_token) -> tuple[str | None, str | None]:
+        """Get new access and refresh tokens fr"""
+        if (self.token_endpoint is None or self.device_endpoint is None) and not self._try_get_urls():
+            raise RuntimeError("Authentication server inaccessible")
+
+        resp = requests.post(
+            self.token_endpoint,
+            data={
+                "grant_type": "refresh_token",
+                "client_id": self.client_id,
+                "refresh_token": refresh_token
+            },
+            timeout=20)
+        if resp.ok:
+            data = resp.json()
+            return data.get("access_token"), data.get("refresh_token")
+
+        # print(f"⚠️ Refresh grant failed (HTTP {resp.status_code}): {resp.text}")
+        return None, None
+
+    def _get_device_flow_data(self) -> dict[str, Any]:
+        response = requests.post(
+            self.device_endpoint,
+            data={
+                "client_id": self.client_id
+            },
+            timeout=20)
+        if not response.ok:
+            try:
+                error_data = response.json()
+                error = error_data.get("error", "unknown_error")
+                description = error_data.get("error_description", "No description.")
+            except Exception:  # pylint:disable = broad-exception-caught
+                error = "unknown_error"
+                description = response.text
+            raise RuntimeError(f"Device Authorization Error: {error} — {description}")  # pylint:disable = broad-exception-raised
+
+        if 'application/json' not in response.headers.get('content-type', ''):
+            raise ValueError("Invalid device flow response.")
+
+        data = response.json()
+        required_fields = ["verification_uri_complete", "device_code", "expires_in"]
+        if not all(field in data for field in required_fields):
+            raise ValueError("Missing expected fields in device flow response.")  # pylint:disable = broad-exception-raised
+
+        return data
+
+    def _poll_auth_server(self, device_code) -> tuple[str | None, str | None, str | None]:
+        poll = requests.post(
+            self.token_endpoint,
+            data={
+                "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                "device_code": device_code,
+                "client_id": self.client_id
+            },
+            timeout=20)
+        if poll.status_code == 200:
+            t = poll.json()
+            return t.get("access_token"), t.get("refresh_token"), None
+        if poll.status_code == 400:
+            err = None
+            try:
+                err = poll.json().get("error")
+            except requests.JSONDecodeError:
+                pass
+            return None, None, err
+        return None, None, None
+
+    def get_device_flow_tokens(self) -> tuple[str | None, str | None]:  # pylint:disable = too-many-statements,too-many-locals
+        """Get new access and refresh tokens from device flow."""
+        if (self.token_endpoint is None or self.device_endpoint is None) and not self._try_get_urls():
+            raise RuntimeError("Authentication server inaccessible")
+
+        data = self._get_device_flow_data()
+
+        print("\n🔐 Authorize Access")
+        print("----------------------------------------")
+        print("You are about to be redirected to an authorization server.")
+        print("There, you will be asked to grant access permissions.")
+        print("This allows the system to act on your behalf using delegated access.")
+        print("Please confirm only if you trust this application.")
+        print(f"➡️  Click to authorize: {data['verification_uri_complete']}")
+        print()
+
+        device_code = data["device_code"]
+        interval = data.get("interval", 5)
+        expires_in = data["expires_in"]
+
+        sleep_time = 1
+        interval_count = 0
+
+        last_printed_line_len = 0
+        while expires_in > 0:
+            if interval_count < 0:
+                interval_count = interval
+
+                access_token, refresh_token, error_type = self._poll_auth_server(device_code)
+
+                if access_token is not None and refresh_token is not None:
+                    _print_nothing(last_printed_line_len)
+                    print("✅ Access granted.")
+                    return access_token, refresh_token
+
+                _show_error(error_type, last_printed_line_len)
+
+                if error_type == 'slow_down':
+                    interval += 1
+                elif error_type != 'authorization_pending':
+                    return None, None
+
+            expires_in -= sleep_time
+            interval_count -= sleep_time
+            last_printed_line_len = _print_formatted_time(expires_in)
+            time.sleep(sleep_time)
+
+        print("\n❌ Timeout: Authorization not completed in time.")
+        return None, None

pcss_qapi/base/connection_base.py

@@ -0,0 +1,20 @@
+"""Connection base"""
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ApiConnection:
+    """Base class for defining a new api connection"""
+
+    oauth_client_id: str
+    oauth_issuer: str
+    oauth_min_ttl_seconds: int
+    api_health_url: str
+    task_endpoints_url: str
+    machine_endpoints_url: str
+
+    def __str__(self) -> str:
+        return f"<{self.task_endpoints_url.replace('https://', '').replace('http://', '').split('/', maxsplit=1)[0]}>"
+
+    def __repr__(self) -> str:
+        return str(self)

pcss_qapi/base/job_base.py

@@ -0,0 +1,52 @@
+"""Job ABCs"""
+import os
+import json
+from typing import Any
+from abc import ABC, abstractmethod
+from pcss_qapi.utils import FSManager
+
+
+class BaseRemoteJob(ABC):
+    """Blueprint for an api remote job (non qiskit)"""
+
+    def __init__(self, job_type: str) -> None:
+        super().__init__()
+        self.uid = None
+        self.type = job_type  # Provider type
+
+    @abstractmethod
+    def _is_remote_available(self) -> bool:
+        """Check if remote api is up"""
+    @abstractmethod
+    def _submit(self):
+        """Submit job to remote"""
+
+    @abstractmethod
+    def _get_job_metadata(self) -> dict:
+        """Additional metadata to save"""
+
+    def _save_job(self):
+        save_path = FSManager.get_task_directory(self.type)
+        os.makedirs(save_path, exist_ok=True)
+        with open(os.path.join(save_path, f'{self.uid}.json'), 'w+', encoding='UTF-8') as f:
+            f.write(json.dumps(self._get_job_metadata()))
+
+    def submit(self) -> None:
+        """Submit job to remote"""
+        if not self._is_remote_available():
+            raise ValueError('Remote server is unreachable')
+        self._submit()
+        self._save_job()
+
+    @property
+    @abstractmethod
+    def status(self) -> Any:
+        """Task status"""
+
+    @abstractmethod
+    def results(self) -> Any:
+        """Get task results"""
+
+    @abstractmethod
+    def cancel(self) -> bool:
+        """Attempt to cancel task if it is queued, return True if successful"""

pcss_qapi/base/provider_base.py

@@ -0,0 +1,38 @@
+"""Provider ABCs"""
+from abc import ABC, abstractmethod
+from typing import Any
+
+from pcss_qapi.base.connection_base import ApiConnection
+from pcss_qapi.auth.connections import PcssQapiConnection
+
+
+class BaseProvider(ABC):
+    """Backend provider ABC"""
+
+    def __init__(
+        self,
+        connection: ApiConnection = PcssQapiConnection
+    ) -> None:
+        self.connection = connection
+
+    @abstractmethod
+    def get_backend(self, backend_name) -> Any:
+        """Get backend with the name of backend_name"""
+
+    @abstractmethod
+    def available_backends(self, simulators: bool = False) -> list[str]:
+        """
+        Return names of available backends for the authed user.
+
+        Returns:
+            list[str]: Backend names.
+        """
+
+    @abstractmethod
+    def least_busy(self) -> Any:
+        """
+        Return least busy backend from the pool of **real** backends.
+
+        Returns:
+            object: Least busy backend.
+        """

pcss_qapi/orca/__init__.py

@@ -0,0 +1,15 @@
+"""ORCA Computing providers, backends, etc."""
+import warnings
+
+from pcss_qapi.utils.exceptions import MissingOptionalDependencyError
+from .orca_task import OrcaTask
+
+__all__ = ['OrcaTask']
+
+# We want OrcaTask to be available even without ptseries
+try:
+    from .backend import OrcaBackend
+    from .provider import OrcaProvider
+    __all__ += ['OrcaProvider', 'OrcaBackend']
+except MissingOptionalDependencyError as e:
+    warnings.warn(e.msg)