ubq 0.1.0__py3-none-any.whl

ubq/models/__init__.py

@@ -0,0 +1,26 @@
+"""Generic Ubuntu data models."""
+
+from ubq.models.bug import BugRecord, BugTaskRecord
+from ubq.models.common import (
+    AuthContext,
+    AuthScope,
+    CommentRecord,
+    ProviderCredentials,
+    UserRecord,
+)
+from ubq.models.merge_request import MergeRequestRecord
+from ubq.models.package import PackageRecord
+from ubq.models.version import VersionRecord
+
+__all__ = [
+    "AuthScope",
+    "ProviderCredentials",
+    "AuthContext",
+    "CommentRecord",
+    "UserRecord",
+    "BugRecord",
+    "BugTaskRecord",
+    "VersionRecord",
+    "PackageRecord",
+    "MergeRequestRecord",
+]

ubq/models/bug.py

@@ -0,0 +1,49 @@
+"""Bug model records."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from ubq.models.common import CommentRecord, UserRecord
+
+
+@dataclass(frozen=True, slots=True)
+class BugTaskRecord:
+    """Subtask record for a bug."""
+
+    title: str
+    target: str | None = None
+    importance: str | None = None
+    status: str | None = None
+    date_assigned: datetime | None = None
+    date_closed: datetime | None = None
+    date_created: datetime | None = None
+    date_left_closed: datetime | None = None
+    date_left_new: datetime | None = None
+    date_incomplete: datetime | None = None
+    date_confirmed: datetime | None = None
+    date_triaged: datetime | None = None
+    date_in_progress: datetime | None = None
+    date_fix_committed: datetime | None = None
+    date_fix_released: datetime | None = None
+    milestone: str | None = None
+    owner: UserRecord | None = None
+    assignee: UserRecord | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class BugRecord:
+    """General bug information record."""
+
+    provider_name: str
+    id: str
+    title: str
+    description: str | None = None
+    tags: list[str] = field(default_factory=list)
+    comments: list[CommentRecord] = field(default_factory=list)
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    last_message_at: datetime | None = None
+    last_patch_at: datetime | None = None
+    owner: UserRecord | None = None
+    assignee: UserRecord | None = None
+    bug_tasks: list[BugTaskRecord] = field(default_factory=list)

ubq/models/common.py

@@ -0,0 +1,48 @@
+"""Shared model records."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+
+
+class AuthScope(Enum):
+    """Login permission scope Enum."""
+
+    READ_ONLY = "read-only"
+    READ_WRITE = "read-write"
+
+
+@dataclass(frozen=True, slots=True)
+class UserRecord:
+    """Generic user information."""
+
+    username: str | None = None
+    display_name: str | None = None
+    profile_url: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class CommentRecord:
+    """Comment data for a record."""
+
+    author: UserRecord | None = None
+    content: str = ""
+    created_at: datetime | None = None
+    edited_at: datetime | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderCredentials:
+    """Credentials used to authenticate with a provider."""
+
+    username: str | None = None
+    token: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class AuthContext:
+    """Authentication context used when creating a provider session."""
+
+    provider_name: str
+    scope: AuthScope
+    credentials: ProviderCredentials | None = None

ubq/models/merge_request.py

@@ -0,0 +1,27 @@
+"""Merge request model records."""
+
+from dataclasses import dataclass
+from datetime import datetime
+
+from ubq.models.common import UserRecord
+from ubq.models.package import PackageRecord
+
+
+@dataclass(frozen=True, slots=True)
+class MergeRequestRecord:
+    """Merge request or pull request metadata."""
+
+    provider_name: str
+    id: str
+    title: str
+    description: str
+    status: str | None = None
+    source_branch: str | None = None
+    target_branch: str | None = None
+    web_url: str | None = None
+    author: UserRecord | None = None
+    assignee: UserRecord | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    merged_at: datetime | None = None
+    package: PackageRecord | None = None

ubq/models/package.py

@@ -0,0 +1,11 @@
+"""Package model records."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class PackageRecord:
+    """Package metadata in a provider."""
+
+    provider_name: str
+    name: str

ubq/models/version.py

@@ -0,0 +1,18 @@
+"""Version model records."""
+
+from dataclasses import dataclass
+from datetime import datetime
+
+from ubq.models.package import PackageRecord
+
+
+@dataclass(frozen=True, slots=True)
+class VersionRecord:
+    """Version information for a package in a provider."""
+
+    provider_name: str
+    version_string: str
+    package: PackageRecord | None = None
+    pocket: str | None = None
+    created_at: datetime | None = None
+    released_at: datetime | None = None

ubq/providers/__init__.py

@@ -0,0 +1,21 @@
+"""Provider interfaces and implementations."""
+
+from ubq.providers.bug import BugProvider
+from ubq.providers.launchpad.bug import LaunchpadBugProvider
+from ubq.providers.launchpad.package import LaunchpadPackageProvider
+from ubq.providers.merge_request import MergeRequestProvider
+from ubq.providers.package import PackageProvider
+from ubq.providers.provider import Provider
+from ubq.providers.session import ProviderSession
+from ubq.providers.version import VersionProvider
+
+__all__ = [
+    "Provider",
+    "ProviderSession",
+    "BugProvider",
+    "PackageProvider",
+    "VersionProvider",
+    "MergeRequestProvider",
+    "LaunchpadBugProvider",
+    "LaunchpadPackageProvider",
+]

ubq/providers/bug.py

@@ -0,0 +1,17 @@
+"""Common interface for bug data providers."""
+
+from typing import Protocol, runtime_checkable
+
+from ubq.models import BugRecord
+from ubq.providers.provider import Provider
+
+
+@runtime_checkable
+class BugProvider(Provider, Protocol):
+    """Contract that all bug providers must implement."""
+
+    def get_bug_metadata(self, bug_id: str) -> BugRecord:
+        """Fetch a single bug without additional requests for comments or tasks."""
+
+    def get_bug(self, bug_id: str) -> BugRecord:
+        """Fetch a single bug by provider-specific identifier."""

ubq/providers/launchpad/__init__.py

@@ -0,0 +1,11 @@
+"""Launchpad data provider implementations."""
+
+from ubq.providers.launchpad.bug import LaunchpadBugProvider
+from ubq.providers.launchpad.package import LaunchpadPackageProvider
+from ubq.providers.launchpad.provider import LaunchpadProvider
+
+__all__ = [
+    "LaunchpadProvider",
+    "LaunchpadBugProvider",
+    "LaunchpadPackageProvider",
+]

ubq/providers/launchpad/bug.py

@@ -0,0 +1,136 @@
+"""Launchpad bug data provider."""
+
+from typing import Any
+
+from lazr.restfulclient.errors import NotFound
+
+from ubq.models import BugRecord, BugTaskRecord, CommentRecord, UserRecord
+from ubq.providers.bug import BugProvider
+from ubq.providers.launchpad.provider import LaunchpadProvider
+
+BASE_BUG_URL = "https://api.launchpad.net/devel/ubuntu/+bug/"
+BASE_USER_URL = "https://launchpad.net/~"
+
+
+class LaunchpadBugProvider(LaunchpadProvider, BugProvider):
+    """Provider implementation for Launchpad bugs."""
+
+    def _fetch_lp_bug_by_id(self, bug_id: str) -> Any:
+        """Load a Launchpad URL and attempt to convert it to arbitrary bug data."""
+        if self._launchpad is None:
+            raise RuntimeError("Launchpad not yet authenticated. Run 'authenticate()' first.")
+
+        try:
+            lp_object = self._launchpad.load(BASE_BUG_URL + bug_id)
+        except NotFound:
+            return None
+
+        # Launchpad will sometimes return default bug_task for a bug, if so it needs to be
+        # converted to a bug explicitly. Otherwise assume it's already a bug.
+        try:
+            lp_bug = lp_object.bug
+        except AttributeError:
+            lp_bug = lp_object
+
+        return lp_bug
+
+    def get_bug_task_by_url(self, task_url: str):
+        """Fetch a Launchpad bug task by URL."""
+        if self._launchpad is None:
+            raise RuntimeError("Launchpad not yet authenticated. Run 'authenticate()' first.")
+
+        try:
+            lp_task = self._launchpad.load(task_url)
+        except NotFound:
+            return None
+
+        assignee = None
+        if hasattr(lp_task, "assignee"):
+            assignee = UserRecord(
+                username=lp_task.assignee.name,
+                display_name=lp_task.assignee.display_name,
+                profile_url=f"{BASE_USER_URL}{lp_task.assignee.name}",
+            )
+
+        return BugTaskRecord(
+            title=lp_task.title,
+            target=lp_task.target,
+            importance=lp_task.importance,
+            status=lp_task.status,
+            date_assigned=lp_task.date_assigned,
+            date_closed=lp_task.date_closed,
+            date_created=lp_task.date_created,
+            date_left_closed=lp_task.date_left_closed,
+            date_left_new=lp_task.date_left_new,
+            date_incomplete=lp_task.date_incomplete,
+            date_confirmed=lp_task.date_confirmed,
+            date_triaged=lp_task.date_triaged,
+            date_in_progress=lp_task.date_in_progress,
+            date_fix_committed=lp_task.date_fix_committed,
+            date_fix_released=lp_task.date_fix_released,
+            milestone=lp_task.milestone.name if lp_task.milestone else None,
+            assignee=assignee,
+        )
+
+    def get_bug_metadata(self, bug_id: str) -> BugRecord:
+        """Fetch a Launchpad bug without comments or tasks."""
+        lp_bug = self._fetch_lp_bug_by_id(bug_id)
+        if lp_bug is None:
+            return None
+
+        return BugRecord(
+            provider_name=self.provider_name,
+            id=str(lp_bug.id),
+            title=lp_bug.title,
+            description=lp_bug.description,
+            created_at=lp_bug.date_created,
+            updated_at=lp_bug.date_last_updated,
+            last_message_at=lp_bug.date_last_message,
+            last_patch_at=lp_bug.latest_patch_uploaded,
+            tags=lp_bug.tags,
+        )
+
+    def get_bug(self, bug_id: str) -> BugRecord:
+        """Fetch a Launchpad bug by identifier."""
+        lp_bug = self._fetch_lp_bug_by_id(bug_id)
+        if lp_bug is None:
+            return None
+
+        tasks = []
+        if hasattr(lp_bug, "bug_tasks"):
+            tasks = [self.get_bug_task_by_url(str(task)) for task in lp_bug.bug_tasks]
+
+        comments = []
+        if hasattr(lp_bug, "messages"):
+            for msg in lp_bug.messages:
+                if msg.visible:
+                    author = None
+                    if hasattr(msg, "owner") and msg.owner is not None:
+                        author = UserRecord(
+                            username=msg.owner.name,
+                            display_name=msg.owner.display_name,
+                            profile_url=f"{BASE_USER_URL}{msg.owner.name}",
+                        )
+
+                    comments.append(
+                        CommentRecord(
+                            author=author,
+                            content=msg.content,
+                            created_at=msg.date_created,
+                            edited_at=msg.date_last_edited,
+                        )
+                    )
+
+        return BugRecord(
+            provider_name=self.provider_name,
+            id=str(lp_bug.id),
+            title=lp_bug.title,
+            description=lp_bug.description,
+            created_at=lp_bug.date_created,
+            updated_at=lp_bug.date_last_updated,
+            last_message_at=lp_bug.date_last_message,
+            last_patch_at=lp_bug.latest_patch_uploaded,
+            tags=lp_bug.tags,
+            bug_tasks=tasks,
+            comments=comments,
+        )

ubq/providers/launchpad/package.py

@@ -0,0 +1,12 @@
+"""Launchpad package data provider."""
+
+from ubq.models import PackageRecord
+from ubq.providers.launchpad.provider import LaunchpadProvider
+from ubq.providers.package import PackageProvider
+
+
+class LaunchpadPackageProvider(LaunchpadProvider, PackageProvider):
+    """Provider implementation for Launchpad packages."""
+
+    def get_package(self, package_name: str) -> PackageRecord:
+        """Fetch a Launchpad package by name."""

ubq/providers/launchpad/provider.py

@@ -0,0 +1,47 @@
+"""Shared Launchpad provider base classes."""
+
+from launchpadlib.credentials import Credentials
+from launchpadlib.launchpad import Launchpad
+
+from ubq.models import AuthContext, AuthScope
+from ubq.providers.session import ProviderSession
+
+
+class LaunchpadProvider:
+    """Common Launchpad provider behavior shared by capability adapters."""
+
+    provider_name = "launchpad"
+
+    def __init__(self):
+        self._launchpad = None
+
+    def authenticate(self, auth_context: AuthContext) -> ProviderSession:
+        """Authenticate with Launchpad and return a reusable session."""
+        if auth_context.credentials is not None and auth_context.credentials.token is not None:
+            credentials = Credentials.from_string(auth_context.credentials.token)
+
+            self._launchpad = Launchpad(
+                credentials,
+                None,
+                None,
+                service_root="production",
+                version="devel",
+            )
+
+        else:
+            access_levels = ["READ_PUBLIC"]
+
+            if auth_context.scope == AuthScope.READ_WRITE:
+                access_levels = ["WRITE_PRIVATE"]
+
+            self._launchpad = Launchpad.login_with(
+                application_name="ubq",
+                service_root="production",
+                allow_access_levels=access_levels,
+                version="devel",
+            )
+
+        return ProviderSession(
+            provider_name=self.provider_name,
+            scope=auth_context.scope,
+        ).with_provider(self)

ubq/providers/merge_request.py

@@ -0,0 +1,14 @@
+"""Common interface for merge request data providers."""
+
+from typing import Protocol, runtime_checkable
+
+from ubq.models import MergeRequestRecord
+from ubq.providers.provider import Provider
+
+
+@runtime_checkable
+class MergeRequestProvider(Provider, Protocol):
+    """Contract that all merge request providers must implement."""
+
+    def get_merge_request(self, merge_request_id: str) -> MergeRequestRecord:
+        """Fetch a merge request by provider-specific identifier."""

ubq/providers/package.py

@@ -0,0 +1,14 @@
+"""Common interface for package data providers."""
+
+from typing import Protocol, runtime_checkable
+
+from ubq.models import PackageRecord
+from ubq.providers.provider import Provider
+
+
+@runtime_checkable
+class PackageProvider(Provider, Protocol):
+    """Contract that all package providers must implement."""
+
+    def get_package(self, package_name: str) -> PackageRecord:
+        """Fetch a single package by provider-specific name."""

ubq/providers/provider.py

@@ -0,0 +1,16 @@
+"""Common interface for all data providers."""
+
+from typing import Protocol, runtime_checkable
+
+from ubq.models import AuthContext
+from ubq.providers.session import ProviderSession
+
+
+@runtime_checkable
+class Provider(Protocol):
+    """Base ubq provider class."""
+
+    provider_name: str
+
+    def authenticate(self, auth_context: AuthContext) -> "ProviderSession":
+        """Authenticate against provider and return a reusable session."""

ubq/providers/session.py

@@ -0,0 +1,58 @@
+"""Common interface for authenticated provider sessions."""
+
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING
+
+from ubq.models import AuthScope
+
+if TYPE_CHECKING:
+    from ubq.providers import BugProvider, MergeRequestProvider, PackageProvider, VersionProvider
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderSession:
+    """Authenticated provider session scoped by read-only or rw permissions."""
+
+    provider_name: str
+    scope: AuthScope
+    bug_provider: "BugProvider | None" = None
+    version_provider: "VersionProvider | None" = None
+    package_provider: "PackageProvider | None" = None
+    merge_request_provider: "MergeRequestProvider | None" = None
+
+    def with_provider(self, provider: object) -> "ProviderSession":
+        """Return a new session with any supported capabilities attached."""
+
+        from ubq.providers import (
+            BugProvider,
+            MergeRequestProvider,
+            PackageProvider,
+            VersionProvider,
+        )
+
+        session = self
+        if isinstance(provider, BugProvider):
+            session = replace(session, bug_provider=provider)
+        if isinstance(provider, VersionProvider):
+            session = replace(session, version_provider=provider)
+        if isinstance(provider, PackageProvider):
+            session = replace(session, package_provider=provider)
+        if isinstance(provider, MergeRequestProvider):
+            session = replace(session, merge_request_provider=provider)
+        return session
+
+    def get_bug_provider(self) -> "BugProvider | None":
+        """Return bug capability for this session if available."""
+        return self.bug_provider
+
+    def get_version_provider(self) -> "VersionProvider | None":
+        """Return version capability for this session if available."""
+        return self.version_provider
+
+    def get_package_provider(self) -> "PackageProvider | None":
+        """Return package capability for this session if available."""
+        return self.package_provider
+
+    def get_merge_request_provider(self) -> "MergeRequestProvider | None":
+        """Return merge request capability for this session if available."""
+        return self.merge_request_provider

ubq/providers/version.py

@@ -0,0 +1,14 @@
+"""Common interface for version data providers."""
+
+from typing import Protocol, runtime_checkable
+
+from ubq.models import VersionRecord
+from ubq.providers.provider import Provider
+
+
+@runtime_checkable
+class VersionProvider(Provider, Protocol):
+    """Contract that all version providers must implement."""
+
+    def get_version(self, package_name: str, pocket: str) -> VersionRecord:
+        """Fetch the version of a package by name and release pocket."""

ubq/services/__init__.py

@@ -0,0 +1,9 @@
+"""Service entry points for querying data providers."""
+
+from ubq.services.query import QueryService
+from ubq.services.registry import ProviderRegistry
+
+__all__ = [
+    "QueryService",
+    "ProviderRegistry",
+]

ubq/services/query.py

@@ -0,0 +1,83 @@
+"""Query service for Ubuntu data."""
+
+from ubq.models import (
+    AuthScope,
+    BugRecord,
+    MergeRequestRecord,
+    PackageRecord,
+    ProviderCredentials,
+    VersionRecord,
+)
+from ubq.services.registry import ProviderRegistry
+
+
+class QueryService:
+    """Query service for data from provider sessions."""
+
+    def __init__(self, registry: ProviderRegistry | None = None):
+        self._registry = registry or ProviderRegistry()
+
+    def login(
+        self,
+        provider_name: str,
+        scope: AuthScope = AuthScope.READ_ONLY,
+        credentials: ProviderCredentials | None = None,
+        force: bool = False,
+    ) -> None:
+        """Create or refresh a scoped provider session."""
+        self._registry.login(
+            provider_name=provider_name,
+            scope=scope,
+            credentials=credentials,
+            force=force,
+        )
+
+    def get_bug(
+        self,
+        bug_id: str,
+        provider_name: str,
+        scope: AuthScope = AuthScope.READ_ONLY,
+        metadata_only: bool = False,
+    ) -> BugRecord:
+        """Fetch a bug from a provider using an active scoped session."""
+        provider = self._registry.get_bug_provider(provider_name, scope=scope)
+
+        if metadata_only:
+            return provider.get_bug_metadata(bug_id)
+
+        return provider.get_bug(bug_id)
+
+    def get_version(
+        self,
+        package_name: str,
+        pocket: str,
+        provider_name: str,
+        scope: AuthScope = AuthScope.READ_ONLY,
+    ) -> VersionRecord:
+        """Fetch package version metadata using an active scoped session."""
+        provider = self._registry.get_version_provider(provider_name, scope=scope)
+        return provider.get_version(package_name, pocket)
+
+    def get_package(
+        self,
+        package_name: str,
+        provider_name: str,
+        scope: AuthScope = AuthScope.READ_ONLY,
+    ) -> PackageRecord:
+        """Fetch a package from a provider using an active scoped session."""
+        provider = self._registry.get_package_provider(provider_name, scope=scope)
+        return provider.get_package(package_name)
+
+    def get_merge_request(
+        self,
+        merge_request_id: str,
+        provider_name: str,
+        scope: AuthScope = AuthScope.READ_ONLY,
+    ) -> MergeRequestRecord:
+        """Fetch a merge request using an active scoped session."""
+        provider = self._registry.get_merge_request_provider(provider_name, scope=scope)
+        return provider.get_merge_request(merge_request_id)
+
+    def available_providers(self) -> tuple[str, ...]:
+        """Return all provider names queryable by this service."""
+        return self._registry.available_provider_names()