qlam-core 0.1.0__py3-none-any.whl

qlam_core/__init__.py

@@ -0,0 +1,52 @@
+"""qlam-core: Core library for QuEra Quantum Computing Services.
+
+This package provides the foundational components for interacting with
+QuEra's quantum computing services:
+
+- **config**: Configuration management
+- **auth**: Authentication providers and OAuth flows
+- **clients**: HTTP client with authentication integration
+- **common**: Shared utilities including AppContext
+- **paths**: Path management abstraction
+- **errors**: Error hierarchy and exit codes
+- **sdk**: Base classes for API clients
+- **plugins**: API clients for QuEra services (tasks, results, etc.)
+
+Example usage:
+
+    from qlam_core.common import AppContext
+    from qlam_core.plugins.tasks import TasksClient
+
+    ctx = AppContext(context_name="production")
+    with TasksClient(ctx) as client:
+        tasks = client.list()
+"""
+
+from qlam_core.errors.errors import (
+    APIError,
+    AuthConfigurationError,
+    AuthenticationError,
+    ConfigurationError,
+    FileSystemError,
+    NetworkError,
+    QlamCoreError,
+    ValidationError,
+)
+from qlam_core.errors.exit_codes import ExitCode
+from qlam_core.paths.paths import PathsProvider, QshPaths
+
+__all__ = [
+    # Errors
+    "QlamCoreError",
+    "AuthenticationError",
+    "AuthConfigurationError",
+    "ConfigurationError",
+    "APIError",
+    "ValidationError",
+    "NetworkError",
+    "FileSystemError",
+    "ExitCode",
+    # Paths
+    "PathsProvider",
+    "QshPaths",
+]

qlam_core/auth/__init__.py

@@ -0,0 +1,40 @@
+"""Authentication for qlam-core.
+
+This module provides authentication infrastructure:
+- BaseAuthProvider: Abstract base class for auth providers
+- AuthClient: Programmatic authentication API
+- AuthRegistry: Provider discovery and registration
+- OAuth flows, credentials cache, and provider implementations
+"""
+
+__all__ = [
+    "AuthClient",
+    "AuthRegistry",
+    "BaseAuthProvider",
+    "LoginLogoutMixin",
+    "auth_registry",
+]
+
+
+def __getattr__(name: str):
+    """Lazy imports to avoid circular dependencies."""
+    if name in ("BaseAuthProvider", "LoginLogoutMixin"):
+        from qlam_core.auth.base import BaseAuthProvider, LoginLogoutMixin
+
+        if name == "BaseAuthProvider":
+            return BaseAuthProvider
+        return LoginLogoutMixin
+
+    if name == "AuthClient":
+        from qlam_core.auth.client import AuthClient
+
+        return AuthClient
+
+    if name in ("AuthRegistry", "auth_registry"):
+        from qlam_core.auth.registry import AuthRegistry, auth_registry
+
+        if name == "AuthRegistry":
+            return AuthRegistry
+        return auth_registry
+
+    raise AttributeError(f"module 'qlam_core.auth' has no attribute '{name}'")

qlam_core/auth/base.py

@@ -0,0 +1,191 @@
+"""Authentication provider framework base classes and mixins
+
+Implement custom auth providers by subclassing `BaseAuthProvider` and, where
+appropriate, implementing the `HTTPHeadersMixin` to supply HTTP headers and
+`LoginLogoutMixin` for interactive flows. Optional `TokenMixin` defines a
+canonical way to expose tokens.
+
+Creating a custom provider (example)::
+
+    from typing import Dict, Any
+    from qlam_core.auth.base import BaseAuthProvider, HTTPHeadersMixin, LoginLogoutMixin
+
+
+    class MyTokenProvider(BaseAuthProvider, HTTPHeadersMixin, LoginLogoutMixin):
+        name = "mytoken"  # used by registry
+
+        def __init__(self, context_name: str, token: str | None = None) -> None:
+            self._context_name = context_name
+            self._token = token
+
+        def is_authenticated(self) -> bool:
+            return bool(self._token)
+
+        def get_auth_context(self) -> JsonDict:
+            return {"context": self._context_name, "has_token": self.is_authenticated()}
+
+        def get_headers(self) -> Dict[str, str]:
+            return {"Authorization": f"Bearer {self._token}"} if self._token else {}
+
+        def login(self) -> None:
+            # Implement a real flow; for example, prompt the user or exchange credentials
+            self._token = "...obtained..."
+
+Registering the provider:
+
+- Either rely on dynamic discovery in ``qlam_core.auth.registry`` if placed under
+  ``qlam_core.auth.providers``, or call ``auth_registry.register_factory("mytoken", factory)``.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Protocol, runtime_checkable
+from qlam_core.auth.credentials.models import CredentialBase
+
+from qlam_core.common.typing import JsonDict
+
+
+class BaseAuthProvider(ABC):
+    """Abstract base class implementing core AuthProvider interface.
+
+    Provides only the required methods - other capabilities are mixed in via protocols.
+    """
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """Human-readable description of this authentication provider.
+
+        :return: Description suitable for help text and user interfaces.
+        """
+        ...
+
+    @abstractmethod
+    def is_authenticated(self) -> bool:
+        """Check if the provider has valid authentication.
+
+        :return: True if authenticated, False otherwise.
+        """
+        ...
+
+    @abstractmethod
+    def get_auth_context(self) -> JsonDict:
+        """Get authentication context for use by clients.
+
+        :return: Dictionary describing authentication state and metadata.
+        """
+        ...
+
+    @abstractmethod
+    def get_credential(self) -> CredentialBase | None:
+        """Return a credential payload as a Pydantic model.
+
+        Providers may return a credential with a non-authenticated status
+        (e.g. ``status="Not authenticated"``) to convey metadata such as
+        refresh capability.  Return ``None`` only when the provider has no
+        credential data at all.
+        """
+        ...
+
+    @classmethod
+    def build_from_settings(
+        cls, *, context_name: str, provider_name: str | None, provider_config: Any
+    ) -> "BaseAuthProvider":
+        """Create provider instance from settings configuration.
+
+        :param context_name: Context name for the provider.
+        :param provider_name: Optional provider name for identification.
+        :param provider_config: Provider configuration object from settings.
+        :return: Configured provider instance.
+        :raises NotImplementedError: If provider doesn't implement this method.
+        """
+        raise NotImplementedError(f"Provider {cls.__name__} must implement build_from_settings")
+
+    @classmethod
+    def extra_info_from_config(cls, provider_config: Any) -> JsonDict:
+        """Extract extra display information from provider configuration.
+
+        :param provider_config: Provider configuration object from settings.
+        :return: Dictionary of extra information for display purposes.
+        """
+        return {}
+
+
+@runtime_checkable
+class HTTPHeadersMixin(Protocol):
+    """Protocol for auth providers that can generate HTTP headers.
+
+    This protocol defines the interface for providers that can generate
+    authentication headers for HTTP requests. Implementation is left to
+    the concrete provider classes.
+    """
+
+    def get_headers(self) -> Dict[str, str]:
+        """Get authentication headers for HTTP requests.
+
+        :return: Dictionary of HTTP headers for authentication
+        """
+        ...
+
+
+class LoginLogoutMixin:
+    """Mixin providing default login/logout implementations."""
+
+    def login(self) -> None:
+        """Default login implementation (no-op).
+
+        Override to implement provider-specific login logic.
+        """
+        pass
+
+    def logout(self) -> None:
+        """Default logout implementation (no-op).
+
+        Override to implement provider-specific logout logic.
+        """
+        pass
+
+
+@runtime_checkable
+class TokenMixin(Protocol):
+    """Protocol for token-based authentication providers.
+
+    This protocol defines the interface for providers that work with
+    access tokens. Implementation of token management is left to
+    concrete provider classes.
+    """
+
+    def token(self) -> str:
+        """Return an access token to be injected into requests.
+
+        :return: Access token string.
+        """
+        ...
+
+
+class RefreshCredentialsMixin(ABC):
+    """Mixin for auth providers that can refresh cached credentials.
+
+    Providers that support refresh should inherit this mixin and implement the
+    required methods. This gives us a clear, explicit contract (no attribute
+    introspection needed) and works well with dynamic provider loading.
+    """
+
+    @abstractmethod
+    def refresh_credentials(self, *, force: bool = False) -> bool:
+        """Refresh credentials for this provider, updating the cache if needed."""
+
+    @abstractmethod
+    def can_refresh_credentials(self) -> bool:
+        """Return True if cached credentials can be refreshed non-interactively right now."""
+
+
+def supports_refresh_credentials(provider: object) -> bool:
+    """Return True if ``provider`` supports non-interactive credential refresh.
+
+    .. note::
+        This is intentionally a contract-based check: refresh-capable providers must
+        inherit :class:`~qlam_core.auth.base.RefreshCredentialsMixin`.
+    """
+    return isinstance(provider, RefreshCredentialsMixin)