marqetive-lib 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

marqetive/core/base_manager.py

@@ -1,303 +0,0 @@
-"""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 src.marqetive.core.account_factory import BaseAccountFactory
-from src.marqetive.core.progress import ProgressCallback, ProgressTracker
-from src.marqetive.platforms.exceptions import PlatformError
-from src.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

marqetive/core/progress.py

@@ -1,291 +0,0 @@
-"""Progress tracking system for long-running operations.
-
-This module provides models and utilities for tracking progress of operations
-like media uploads, post creation, and other long-running tasks.
-"""
-
-from collections.abc import Callable
-from datetime import datetime
-from enum import Enum
-from typing import Any
-
-from pydantic import BaseModel, Field
-
-
-class ProgressStatus(str, Enum):
-    """Status of a progress event."""
-
-    STARTED = "started"
-    IN_PROGRESS = "in_progress"
-    COMPLETED = "completed"
-    FAILED = "failed"
-    CANCELLED = "cancelled"
-
-
-class ProgressEvent(BaseModel):
-    """Represents a progress event for an operation.
-
-    Attributes:
-        operation: Name of the operation (e.g., "upload_media", "create_post").
-        progress: Current progress value (e.g., bytes uploaded).
-        total: Total expected value (e.g., total bytes).
-        status: Current status of the operation.
-        message: Optional human-readable message.
-        metadata: Additional operation-specific data.
-        timestamp: When this event occurred.
-
-    Example:
-        >>> event = ProgressEvent(
-        ...     operation="upload_media",
-        ...     progress=500,
-        ...     total=1000,
-        ...     status=ProgressStatus.IN_PROGRESS,
-        ...     message="Uploading image..."
-        ... )
-        >>> print(f"Progress: {event.percentage}%")
-        Progress: 50.0%
-    """
-
-    operation: str
-    progress: int | float
-    total: int | float | None = None
-    status: ProgressStatus
-    message: str | None = None
-    metadata: dict[str, Any] = Field(default_factory=dict)
-    timestamp: datetime = Field(default_factory=datetime.now)
-
-    @property
-    def percentage(self) -> float:
-        """Calculate progress as a percentage.
-
-        Returns:
-            Progress percentage (0-100), or 0 if total is None.
-        """
-        if self.total is None or self.total == 0:
-            return 0.0
-        return (self.progress / self.total) * 100
-
-    def is_complete(self) -> bool:
-        """Check if operation is complete.
-
-        Returns:
-            True if status is COMPLETED, False otherwise.
-        """
-        return self.status == ProgressStatus.COMPLETED
-
-    def is_failed(self) -> bool:
-        """Check if operation failed.
-
-        Returns:
-            True if status is FAILED, False otherwise.
-        """
-        return self.status == ProgressStatus.FAILED
-
-
-# Type alias for progress callback functions
-ProgressCallback = Callable[[ProgressEvent], None]
-
-
-class ProgressTracker:
-    """Tracks and emits progress events for operations.
-
-    Manages multiple progress callbacks and provides utilities for
-    emitting progress events with consistent formatting.
-
-    Example:
-        >>> tracker = ProgressTracker()
-        >>> tracker.add_callback(lambda e: print(f"{e.operation}: {e.percentage}%"))
-        >>>
-        >>> tracker.emit_start("upload_media")
-        >>> tracker.emit_progress("upload_media", 500, 1000, "Uploading...")
-        >>> tracker.emit_complete("upload_media", "Upload complete")
-    """
-
-    def __init__(self) -> None:
-        """Initialize progress tracker."""
-        self._callbacks: list[ProgressCallback] = []
-
-    def add_callback(self, callback: ProgressCallback) -> None:
-        """Add a progress callback.
-
-        Args:
-            callback: Function to call when progress events occur.
-
-        Example:
-            >>> def my_callback(event: ProgressEvent) -> None:
-            ...     print(f"{event.operation}: {event.percentage}%")
-            >>>
-            >>> tracker.add_callback(my_callback)
-        """
-        self._callbacks.append(callback)
-
-    def remove_callback(self, callback: ProgressCallback) -> None:
-        """Remove a progress callback.
-
-        Args:
-            callback: Callback to remove.
-        """
-        if callback in self._callbacks:
-            self._callbacks.remove(callback)
-
-    def clear_callbacks(self) -> None:
-        """Remove all callbacks."""
-        self._callbacks.clear()
-
-    def emit(self, event: ProgressEvent) -> None:
-        """Emit a progress event to all callbacks.
-
-        Args:
-            event: Progress event to emit.
-        """
-        import contextlib
-
-        for callback in self._callbacks:
-            with contextlib.suppress(Exception):
-                # Silently ignore callback errors to prevent disrupting operations
-                callback(event)
-
-    def emit_start(
-        self,
-        operation: str,
-        total: int | float | None = None,
-        message: str | None = None,
-        **metadata: Any,
-    ) -> None:
-        """Emit an operation start event.
-
-        Args:
-            operation: Name of the operation.
-            total: Total expected value (optional).
-            message: Optional message.
-            **metadata: Additional metadata.
-
-        Example:
-            >>> tracker.emit_start("upload_media", total=1024000,
-            ...                    message="Starting upload...")
-        """
-        event = ProgressEvent(
-            operation=operation,
-            progress=0,
-            total=total,
-            status=ProgressStatus.STARTED,
-            message=message or f"Starting {operation}",
-            metadata=metadata,
-        )
-        self.emit(event)
-
-    def emit_progress(
-        self,
-        operation: str,
-        progress: int | float,
-        total: int | float | None = None,
-        message: str | None = None,
-        **metadata: Any,
-    ) -> None:
-        """Emit a progress update event.
-
-        Args:
-            operation: Name of the operation.
-            progress: Current progress value.
-            total: Total expected value (optional).
-            message: Optional message.
-            **metadata: Additional metadata.
-
-        Example:
-            >>> tracker.emit_progress("upload_media", 512000, 1024000,
-            ...                       message="Uploading...")
-        """
-        event = ProgressEvent(
-            operation=operation,
-            progress=progress,
-            total=total,
-            status=ProgressStatus.IN_PROGRESS,
-            message=message,
-            metadata=metadata,
-        )
-        self.emit(event)
-
-    def emit_complete(
-        self,
-        operation: str,
-        message: str | None = None,
-        **metadata: Any,
-    ) -> None:
-        """Emit an operation complete event.
-
-        Args:
-            operation: Name of the operation.
-            message: Optional message.
-            **metadata: Additional metadata.
-
-        Example:
-            >>> tracker.emit_complete("upload_media",
-            ...                       message="Upload successful!")
-        """
-        event = ProgressEvent(
-            operation=operation,
-            progress=100,
-            total=100,
-            status=ProgressStatus.COMPLETED,
-            message=message or f"{operation} completed",
-            metadata=metadata,
-        )
-        self.emit(event)
-
-    def emit_failed(
-        self,
-        operation: str,
-        error: str | Exception,
-        **metadata: Any,
-    ) -> None:
-        """Emit an operation failed event.
-
-        Args:
-            operation: Name of the operation.
-            error: Error message or exception.
-            **metadata: Additional metadata.
-
-        Example:
-            >>> try:
-            ...     # Some operation
-            ...     pass
-            ... except Exception as e:
-            ...     tracker.emit_failed("upload_media", e)
-        """
-        message = str(error) if isinstance(error, Exception) else error
-        event = ProgressEvent(
-            operation=operation,
-            progress=0,
-            total=100,
-            status=ProgressStatus.FAILED,
-            message=message,
-            metadata=metadata,
-        )
-        self.emit(event)
-
-    def emit_cancelled(
-        self,
-        operation: str,
-        message: str | None = None,
-        **metadata: Any,
-    ) -> None:
-        """Emit an operation cancelled event.
-
-        Args:
-            operation: Name of the operation.
-            message: Optional message.
-            **metadata: Additional metadata.
-
-        Example:
-            >>> tracker.emit_cancelled("upload_media",
-            ...                        message="Upload cancelled by user")
-        """
-        event = ProgressEvent(
-            operation=operation,
-            progress=0,
-            total=100,
-            status=ProgressStatus.CANCELLED,
-            message=message or f"{operation} cancelled",
-            metadata=metadata,
-        )
-        self.emit(event)