marqetive-lib 0.1.0__py3-none-any.whl

marqetive/__init__.py

@@ -0,0 +1,113 @@
+"""MarqetiveLib: Modern Python utilities for web APIs and social media platforms.
+
+A comprehensive library providing utilities for working with web APIs,
+HTTP requests, data processing, and social media platform integrations.
+
+Usage:
+    Basic API client:
+        >>> from marqetive_lib import APIClient
+        >>> async with APIClient(base_url="https://api.example.com") as client:
+        ...     response = await client.get("/endpoint")
+
+    Platform managers (high-level):
+        >>> from marqetive_lib import initialize_platform_registry, get_manager_for_platform
+        >>> from marqetive_lib.platforms.models import AuthCredentials, PostCreateRequest
+        >>>
+        >>> initialize_platform_registry()
+        >>> manager = get_manager_for_platform("twitter")
+        >>> credentials = AuthCredentials(platform="twitter", access_token="...")
+        >>> request = PostCreateRequest(content="Hello!")
+        >>> post = await manager.execute_post(credentials, request)
+
+    Platform clients (low-level):
+        >>> from marqetive_lib.platforms.twitter import TwitterClient
+        >>> credentials = AuthCredentials(platform="twitter", access_token="...")
+        >>> async with TwitterClient(credentials) as client:
+        ...     post = await client.create_post(request)
+"""
+
+# Core API client
+# Account management
+from marqetive.core.account_factory import BaseAccountFactory
+
+# Registry and managers
+from marqetive.core.base_manager import BasePostManager
+from marqetive.core.client import APIClient
+
+# Progress tracking
+from marqetive.core.progress import (
+    ProgressCallback,
+    ProgressEvent,
+    ProgressStatus,
+    ProgressTracker,
+)
+from marqetive.core.registry import (
+    PlatformRegistry,
+    get_available_platforms,
+    get_manager_for_platform,
+    get_registry,
+    register_platform,
+)
+
+# Models
+from marqetive.platforms.models import (
+    AccountStatus,
+    AuthCredentials,
+    Comment,
+    CommentStatus,
+    MediaAttachment,
+    MediaType,
+    Post,
+    PostCreateRequest,
+    PostStatus,
+    PostUpdateRequest,
+)
+from marqetive.registry_init import (
+    initialize_platform_registry,
+    is_registry_initialized,
+)
+
+# Utilities
+from marqetive.utils.helpers import format_response
+
+# Retry utilities
+from marqetive.utils.retry import STANDARD_BACKOFF, BackoffConfig, retry_async
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Core
+    "APIClient",
+    "format_response",
+    # Registry
+    "PlatformRegistry",
+    "initialize_platform_registry",
+    "is_registry_initialized",
+    "get_registry",
+    "register_platform",
+    "get_manager_for_platform",
+    "get_available_platforms",
+    # Managers and factories
+    "BasePostManager",
+    "BaseAccountFactory",
+    # Progress tracking
+    "ProgressEvent",
+    "ProgressStatus",
+    "ProgressTracker",
+    "ProgressCallback",
+    # Retry
+    "BackoffConfig",
+    "STANDARD_BACKOFF",
+    "retry_async",
+    # Models
+    "AuthCredentials",
+    "AccountStatus",
+    "Post",
+    "PostStatus",
+    "PostCreateRequest",
+    "PostUpdateRequest",
+    "Comment",
+    "CommentStatus",
+    "MediaAttachment",
+    "MediaType",
+]

marqetive/core/__init__.py

@@ -0,0 +1,5 @@
+"""Core functionality for MarqetiveLib."""
+
+from marqetive.core.client import APIClient
+
+__all__ = ["APIClient"]

marqetive/core/account_factory.py

@@ -0,0 +1,212 @@
+"""Base account factory for managing platform credentials and client creation.
+
+This module provides an abstract base class for platform-specific account
+factories that handle credential management, token refresh, and client creation.
+"""
+
+import logging
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import Any
+
+from marqetive.platforms.exceptions import PlatformAuthError
+from marqetive.platforms.models import AccountStatus, AuthCredentials
+
+logger = logging.getLogger(__name__)
+
+
+class BaseAccountFactory(ABC):
+    """Abstract base class for platform account factories.
+
+    Account factories manage the lifecycle of platform credentials including:
+    - Token expiry checking and automatic refresh
+    - Account status management
+    - Platform-specific client creation
+
+    Subclasses must implement:
+    - refresh_token(): Platform-specific token refresh logic
+    - create_client(): Create platform-specific API client
+    - validate_credentials(): Check if credentials are valid
+
+    Example:
+        >>> class TwitterAccountFactory(BaseAccountFactory):
+        ...     async def refresh_token(self, credentials):
+        ...         # Implement Twitter OAuth token refresh
+        ...         pass
+        ...
+        ...     async def create_client(self, credentials):
+        ...         return TwitterClient(credentials=credentials)
+        ...
+        ...     async def validate_credentials(self, credentials):
+        ...         # Check if credentials work
+        ...         pass
+    """
+
+    def __init__(
+        self,
+        on_status_update: Callable[[str, AccountStatus], None] | None = None,
+    ) -> None:
+        """Initialize the account factory.
+
+        Args:
+            on_status_update: Optional callback when account status changes.
+                            Called with (user_id, new_status).
+        """
+        self.on_status_update = on_status_update
+
+    @property
+    @abstractmethod
+    def platform_name(self) -> str:
+        """Get the name of the platform this factory manages.
+
+        Returns:
+            Platform name (e.g., "twitter", "linkedin").
+        """
+        pass
+
+    @abstractmethod
+    async def refresh_token(self, credentials: AuthCredentials) -> AuthCredentials:
+        """Refresh the OAuth access token.
+
+        Args:
+            credentials: Current credentials with expired token.
+
+        Returns:
+            Updated credentials with new token.
+
+        Raises:
+            PlatformAuthError: If token refresh fails.
+        """
+        pass
+
+    @abstractmethod
+    async def create_client(self, credentials: AuthCredentials) -> Any:
+        """Create a platform-specific API client.
+
+        Args:
+            credentials: Valid credentials for the platform.
+
+        Returns:
+            Platform-specific API client instance.
+
+        Raises:
+            PlatformAuthError: If credentials are invalid.
+        """
+        pass
+
+    @abstractmethod
+    async def validate_credentials(self, credentials: AuthCredentials) -> bool:
+        """Validate that credentials are working.
+
+        Args:
+            credentials: Credentials to validate.
+
+        Returns:
+            True if credentials are valid, False otherwise.
+        """
+        pass
+
+    async def get_credentials(
+        self,
+        credentials: AuthCredentials,
+        auto_refresh: bool = True,
+    ) -> AuthCredentials:
+        """Get credentials, refreshing if necessary.
+
+        This method checks if credentials are expired and automatically
+        refreshes them if auto_refresh is True.
+
+        Args:
+            credentials: Current credentials.
+            auto_refresh: Whether to automatically refresh expired tokens.
+
+        Returns:
+            Valid credentials (refreshed if necessary).
+
+        Raises:
+            PlatformAuthError: If refresh fails or credentials are invalid.
+        """
+        # Check if token needs refresh
+        if credentials.needs_refresh():
+            if not auto_refresh:
+                logger.warning(
+                    f"Credentials for {credentials.platform} are expired "
+                    "but auto_refresh is disabled"
+                )
+                return credentials
+
+            logger.info(
+                f"Token expired for {credentials.platform}, attempting refresh..."
+            )
+            try:
+                refreshed_creds = await self.refresh_token(credentials)
+                refreshed_creds.mark_valid()
+
+                # Notify status update
+                if self.on_status_update and refreshed_creds.user_id:
+                    self.on_status_update(refreshed_creds.user_id, AccountStatus.VALID)
+
+                logger.info(f"Successfully refreshed token for {credentials.platform}")
+                return refreshed_creds
+
+            except PlatformAuthError as e:
+                # Determine if this is an OAuth error requiring reconnection
+                if "oauth" in str(e).lower() or "authorization" in str(e).lower():
+                    credentials.mark_reconnection_required()
+                    if self.on_status_update and credentials.user_id:
+                        self.on_status_update(
+                            credentials.user_id, AccountStatus.RECONNECTION_REQUIRED
+                        )
+                    logger.error(
+                        f"OAuth error refreshing token for {credentials.platform}: {e}"
+                    )
+                else:
+                    credentials.mark_error()
+                    if self.on_status_update and credentials.user_id:
+                        self.on_status_update(credentials.user_id, AccountStatus.ERROR)
+                    logger.error(
+                        f"Error refreshing token for {credentials.platform}: {e}"
+                    )
+                raise
+
+        return credentials
+
+    async def create_authenticated_client(
+        self,
+        credentials: AuthCredentials,
+        auto_refresh: bool = True,
+    ) -> Any:
+        """Create an authenticated client, refreshing credentials if needed.
+
+        This is the main method to use for getting a ready-to-use client.
+
+        Args:
+            credentials: Platform credentials.
+            auto_refresh: Whether to automatically refresh expired tokens.
+
+        Returns:
+            Authenticated platform client.
+
+        Raises:
+            PlatformAuthError: If authentication fails.
+        """
+        # Get valid credentials (refresh if needed)
+        valid_creds = await self.get_credentials(credentials, auto_refresh=auto_refresh)
+
+        # Create client
+        client = await self.create_client(valid_creds)
+
+        return client
+
+    def _update_status(self, user_id: str | None, status: AccountStatus) -> None:
+        """Internal method to update account status.
+
+        Args:
+            user_id: User ID for the account.
+            status: New status.
+        """
+        if self.on_status_update and user_id:
+            try:
+                self.on_status_update(user_id, status)
+            except Exception as e:
+                logger.error(f"Error calling status update callback: {e}")

marqetive/core/base_manager.py

@@ -0,0 +1,303 @@
+"""Base manager for platform post operations.
+
+This module provides an abstract base class for managing post operations
+across different social media platforms with consistent patterns for
+progress tracking, error handling, and state management.
+"""
+
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from typing import Any
+
+from marqetive.core.account_factory import BaseAccountFactory
+from marqetive.core.progress import ProgressCallback, ProgressTracker
+from marqetive.platforms.exceptions import PlatformError
+from marqetive.platforms.models import AuthCredentials, Post, PostCreateRequest
+
+logger = logging.getLogger(__name__)
+
+
+class BasePostManager(ABC):
+    """Abstract base class for platform post managers.
+
+    Managers coordinate the posting process including:
+    - Creating authenticated clients via account factories
+    - Tracking operation progress
+    - Handling errors consistently
+    - Supporting cancellation
+
+    Subclasses must implement:
+    - _execute_post_impl(): Platform-specific posting logic
+    - platform_name: Property returning the platform name
+
+    Example:
+        >>> class TwitterPostManager(BasePostManager):
+        ...     @property
+        ...     def platform_name(self) -> str:
+        ...         return "twitter"
+        ...
+        ...     async def _execute_post_impl(self, client, request):
+        ...         return await client.create_post(request)
+    """
+
+    def __init__(
+        self,
+        account_factory: BaseAccountFactory | None = None,
+    ) -> None:
+        """Initialize the post manager.
+
+        Args:
+            account_factory: Account factory for creating clients.
+                            If None, subclass must provide default.
+        """
+        self._account_factory = account_factory
+        self._progress_tracker = ProgressTracker()
+        self._cancel_event = asyncio.Event()
+
+    @property
+    @abstractmethod
+    def platform_name(self) -> str:
+        """Get the name of the platform this manager handles.
+
+        Returns:
+            Platform name (e.g., "twitter", "linkedin").
+        """
+        pass
+
+    @property
+    def account_factory(self) -> BaseAccountFactory:
+        """Get the account factory.
+
+        Returns:
+            Account factory instance.
+
+        Raises:
+            RuntimeError: If account factory not set.
+        """
+        if self._account_factory is None:
+            raise RuntimeError(
+                f"{self.__class__.__name__} requires an account_factory. "
+                "Either pass it to __init__ or override this property."
+            )
+        return self._account_factory
+
+    def add_progress_callback(self, callback: ProgressCallback) -> None:
+        """Add a callback to receive progress updates.
+
+        Args:
+            callback: Function that receives ProgressEvent objects.
+
+        Example:
+            >>> def my_callback(event):
+            ...     print(f"{event.operation}: {event.percentage}%")
+            >>>
+            >>> manager.add_progress_callback(my_callback)
+        """
+        self._progress_tracker.add_callback(callback)
+
+    def remove_progress_callback(self, callback: ProgressCallback) -> None:
+        """Remove a progress callback.
+
+        Args:
+            callback: Callback to remove.
+        """
+        self._progress_tracker.remove_callback(callback)
+
+    def clear_progress_callbacks(self) -> None:
+        """Remove all progress callbacks."""
+        self._progress_tracker.clear_callbacks()
+
+    async def execute_post(
+        self,
+        credentials: AuthCredentials,
+        request: PostCreateRequest,
+    ) -> Post:
+        """Execute post creation with progress tracking and error handling.
+
+        This is the main entry point for creating posts. It handles:
+        - Client creation via account factory
+        - Progress tracking
+        - Cancellation support
+        - Consistent error handling
+
+        Args:
+            credentials: Platform credentials.
+            request: Post creation request.
+
+        Returns:
+            Created Post object.
+
+        Raises:
+            PlatformError: If post creation fails.
+            asyncio.CancelledError: If operation is cancelled.
+
+        Example:
+            >>> credentials = AuthCredentials(platform="twitter", ...)
+            >>> request = PostCreateRequest(content="Hello world!")
+            >>> post = await manager.execute_post(credentials, request)
+            >>> print(f"Posted: {post.post_id}")
+        """
+        # Reset cancel event
+        self._cancel_event.clear()
+
+        try:
+            # Emit start event
+            self._progress_tracker.emit_start(
+                "execute_post",
+                message=f"Starting post to {self.platform_name}",
+                platform=self.platform_name,
+            )
+
+            # Check for cancellation
+            if self._cancel_event.is_set():
+                self._progress_tracker.emit_cancelled("execute_post")
+                raise asyncio.CancelledError("Post execution was cancelled")
+
+            # Create authenticated client
+            logger.info(f"Creating {self.platform_name} client...")
+            client = await self.account_factory.create_authenticated_client(credentials)
+
+            # Check for cancellation
+            if self._cancel_event.is_set():
+                self._progress_tracker.emit_cancelled("execute_post")
+                raise asyncio.CancelledError("Post execution was cancelled")
+
+            # Execute platform-specific posting logic
+            logger.info(f"Creating post on {self.platform_name}...")
+            post = await self._execute_post_impl(client, request, credentials)
+
+            # Emit completion event
+            self._progress_tracker.emit_complete(
+                "execute_post",
+                message=f"Post created successfully on {self.platform_name}",
+                post_id=post.post_id,
+                platform=self.platform_name,
+            )
+
+            logger.info(
+                f"Successfully created post {post.post_id} on {self.platform_name}"
+            )
+            return post
+
+        except asyncio.CancelledError:
+            self._progress_tracker.emit_cancelled(
+                "execute_post",
+                message=f"Post creation cancelled on {self.platform_name}",
+            )
+            raise
+
+        except Exception as e:
+            error_msg = f"Failed to create post on {self.platform_name}: {str(e)}"
+            logger.error(error_msg)
+            self._progress_tracker.emit_failed("execute_post", e)
+
+            # Wrap in PlatformError if not already
+            if not isinstance(e, PlatformError):
+                raise PlatformError(error_msg, platform=self.platform_name) from e
+            raise
+
+    @abstractmethod
+    async def _execute_post_impl(
+        self,
+        client: Any,
+        request: PostCreateRequest,
+        credentials: AuthCredentials,
+    ) -> Post:
+        """Platform-specific post creation implementation.
+
+        Subclasses must implement this to handle the actual post creation
+        logic for their specific platform.
+
+        Args:
+            client: Platform-specific authenticated client.
+            request: Post creation request.
+            credentials: Platform credentials (for context).
+
+        Returns:
+            Created Post object.
+
+        Raises:
+            PlatformError: If post creation fails.
+        """
+        pass
+
+    def cancel_post(self) -> None:
+        """Cancel the current post operation.
+
+        Sets a cancellation flag that is checked at key points during
+        post execution. The operation may not stop immediately.
+
+        Example:
+            >>> task = asyncio.create_task(manager.execute_post(...))
+            >>> # Later...
+            >>> manager.cancel_post()
+            >>> try:
+            ...     await task
+            ... except asyncio.CancelledError:
+            ...     print("Operation was cancelled")
+        """
+        self._cancel_event.set()
+        logger.info(f"Cancellation requested for {self.platform_name} post")
+
+    def is_cancelled(self) -> bool:
+        """Check if cancellation has been requested.
+
+        Returns:
+            True if cancel_post() was called, False otherwise.
+        """
+        return self._cancel_event.is_set()
+
+    async def get_post_status(
+        self,
+        credentials: AuthCredentials,
+        post_id: str,
+    ) -> Post:
+        """Get the current status of a post.
+
+        Args:
+            credentials: Platform credentials.
+            post_id: Platform-specific post ID.
+
+        Returns:
+            Post object with current status.
+
+        Raises:
+            PlatformError: If fetching post fails.
+        """
+        try:
+            client = await self.account_factory.create_authenticated_client(credentials)
+            return await client.get_post(post_id)
+        except Exception as e:
+            error_msg = f"Failed to get post status from {self.platform_name}: {str(e)}"
+            logger.error(error_msg)
+            if not isinstance(e, PlatformError):
+                raise PlatformError(error_msg, platform=self.platform_name) from e
+            raise
+
+    async def delete_post(
+        self,
+        credentials: AuthCredentials,
+        post_id: str,
+    ) -> bool:
+        """Delete a post.
+
+        Args:
+            credentials: Platform credentials.
+            post_id: Platform-specific post ID.
+
+        Returns:
+            True if deletion was successful.
+
+        Raises:
+            PlatformError: If deletion fails.
+        """
+        try:
+            client = await self.account_factory.create_authenticated_client(credentials)
+            return await client.delete_post(post_id)
+        except Exception as e:
+            error_msg = f"Failed to delete post from {self.platform_name}: {str(e)}"
+            logger.error(error_msg)
+            if not isinstance(e, PlatformError):
+                raise PlatformError(error_msg, platform=self.platform_name) from e
+            raise