marqetive-lib 0.1.0__py3-none-any.whl

marqetive/core/client.py

@@ -0,0 +1,108 @@
+"""API client implementation for MarqetiveLib."""
+
+from typing import Any
+
+import httpx
+from pydantic import BaseModel
+
+
+class APIResponse(BaseModel):
+    """Response model for API calls."""
+
+    status_code: int
+    data: dict[str, Any]
+    headers: dict[str, str]
+
+
+class APIClient:
+    """A simple HTTP API client with type hints.
+
+    This client provides a clean interface for making HTTP requests
+    with automatic response parsing and error handling.
+
+    Args:
+        base_url: The base URL for API requests
+        timeout: Request timeout in seconds (default: 30)
+        headers: Optional default headers for all requests
+
+    Example:
+        >>> client = APIClient(base_url="https://api.example.com")
+        >>> response = await client.get("/users/1")
+        >>> print(response.data)
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        timeout: float = 30.0,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        """Initialize the API client."""
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.default_headers = headers or {}
+        self._client: httpx.AsyncClient | None = None
+
+    async def __aenter__(self) -> "APIClient":
+        """Async context manager entry."""
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=self.timeout,
+            headers=self.default_headers,
+        )
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Async context manager exit."""
+        if self._client:
+            await self._client.aclose()
+
+    async def get(self, path: str, params: dict[str, Any] | None = None) -> APIResponse:
+        """Make a GET request.
+
+        Args:
+            path: The endpoint path
+            params: Optional query parameters
+
+        Returns:
+            APIResponse object containing status, data, and headers
+
+        Raises:
+            httpx.HTTPError: If the request fails
+        """
+        if not self._client:
+            raise RuntimeError("Client not initialized. Use async context manager.")
+
+        response: httpx.Response = await self._client.get(path, params=params)
+        response.raise_for_status()
+
+        return APIResponse(
+            status_code=response.status_code,
+            data=response.json() if response.content else {},
+            headers=dict(response.headers),
+        )
+
+    async def post(self, path: str, data: dict[str, Any] | None = None) -> APIResponse:
+        """Make a POST request.
+
+        Args:
+            path: The endpoint path
+            data: Optional request body data
+
+        Returns:
+            APIResponse object containing status, data, and headers
+
+        Raises:
+            httpx.HTTPError: If the request fails
+        """
+        if not self._client:
+            raise RuntimeError("Client not initialized. Use async context manager.")
+
+        response = await self._client.post(path, json=data)
+        response.raise_for_status()
+
+        return APIResponse(
+            status_code=response.status_code,
+            data=response.json() if response.content else {},
+            headers=dict(response.headers),
+        )

marqetive/core/progress.py

@@ -0,0 +1,291 @@
+"""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)

marqetive/core/registry.py

@@ -0,0 +1,257 @@
+"""Platform registry for managing platform manager instances.
+
+This module provides a singleton registry pattern for registering and accessing
+platform managers across the application.
+"""
+
+import threading
+from typing import Any, TypeVar
+
+from marqetive.platforms.models import AuthCredentials
+
+# Type variable for manager classes
+ManagerType = TypeVar("ManagerType")
+
+
+class PlatformRegistry:
+    """Singleton registry for platform managers.
+
+    The registry maintains a mapping of platform names to their manager classes
+    and provides caching of manager instances to avoid unnecessary recreation.
+
+    Thread-safe implementation using threading.Lock.
+
+    Example:
+        >>> from marqetive_lib.platforms.twitter.manager import TwitterPostManager
+        >>> registry = PlatformRegistry()
+        >>> registry.register_platform("twitter", TwitterPostManager)
+        >>> manager = registry.get_manager("twitter", credentials=creds)
+    """
+
+    _instance: "PlatformRegistry | None" = None
+    _lock: threading.Lock = threading.Lock()
+
+    def __new__(cls) -> "PlatformRegistry":
+        """Ensure only one instance exists (singleton pattern)."""
+        if cls._instance is None:
+            with cls._lock:
+                # Double-check locking pattern
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+                    cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self) -> None:
+        """Initialize the registry."""
+        # Only initialize once
+        if self._initialized:
+            return
+
+        self._platforms: dict[str, type] = {}
+        self._manager_cache: dict[str, Any] = {}
+        self._cache_lock = threading.Lock()
+        self._initialized = True
+
+    def register_platform(self, platform_name: str, manager_class: type) -> None:
+        """Register a platform manager class.
+
+        Args:
+            platform_name: Name of the platform (e.g., "twitter", "linkedin").
+            manager_class: The manager class to register.
+
+        Raises:
+            ValueError: If platform is already registered.
+
+        Example:
+            >>> registry.register_platform("twitter", TwitterPostManager)
+        """
+        if platform_name in self._platforms:
+            raise ValueError(f"Platform '{platform_name}' is already registered")
+
+        self._platforms[platform_name] = manager_class
+
+    def unregister_platform(self, platform_name: str) -> None:
+        """Unregister a platform and clear its cached instances.
+
+        Args:
+            platform_name: Name of the platform to unregister.
+
+        Example:
+            >>> registry.unregister_platform("twitter")
+        """
+        with self._cache_lock:
+            self._platforms.pop(platform_name, None)
+            # Clear cached instances for this platform
+            keys_to_remove = [
+                k for k in self._manager_cache if k.startswith(f"{platform_name}:")
+            ]
+            for key in keys_to_remove:
+                self._manager_cache.pop(key)
+
+    def get_manager(
+        self,
+        platform_name: str,
+        use_cache: bool = True,
+        **kwargs: Any,
+    ) -> Any:
+        """Get or create a manager instance for the specified platform.
+
+        Args:
+            platform_name: Name of the platform (e.g., "twitter", "linkedin").
+            use_cache: Whether to use cached instance (default: True).
+            **kwargs: Arguments to pass to the manager constructor.
+
+        Returns:
+            Manager instance for the platform.
+
+        Raises:
+            ValueError: If platform is not registered.
+
+        Example:
+            >>> manager = registry.get_manager("twitter", credentials=creds)
+            >>> post = await manager.execute_post(...)
+        """
+        if platform_name not in self._platforms:
+            available = ", ".join(self.get_available_platforms())
+            raise ValueError(
+                f"Platform '{platform_name}' is not registered. "
+                f"Available platforms: {available}"
+            )
+
+        # Generate cache key from platform name and kwargs
+        cache_key = self._generate_cache_key(platform_name, **kwargs)
+
+        if use_cache:
+            with self._cache_lock:
+                if cache_key in self._manager_cache:
+                    return self._manager_cache[cache_key]
+
+        # Create new manager instance
+        manager_class = self._platforms[platform_name]
+        manager = manager_class(**kwargs)
+
+        if use_cache:
+            with self._cache_lock:
+                self._manager_cache[cache_key] = manager
+
+        return manager
+
+    def get_available_platforms(self) -> list[str]:
+        """Get list of all registered platform names.
+
+        Returns:
+            List of platform names.
+
+        Example:
+            >>> platforms = registry.get_available_platforms()
+            >>> print(platforms)
+            ['twitter', 'linkedin', 'instagram', 'tiktok']
+        """
+        return list(self._platforms.keys())
+
+    def clear_cache(self) -> None:
+        """Clear all cached manager instances.
+
+        Example:
+            >>> registry.clear_cache()
+        """
+        with self._cache_lock:
+            self._manager_cache.clear()
+
+    def _generate_cache_key(self, platform_name: str, **kwargs: Any) -> str:
+        """Generate a cache key for manager instance.
+
+        Args:
+            platform_name: Name of the platform.
+            **kwargs: Manager constructor arguments.
+
+        Returns:
+            Cache key string.
+        """
+        # For credentials, use account_id if available
+        if "credentials" in kwargs:
+            creds = kwargs["credentials"]
+            if isinstance(creds, AuthCredentials) and creds.user_id:
+                return f"{platform_name}:user_id:{creds.user_id}"
+
+        # Default to platform name only
+        return platform_name
+
+
+# Global registry instance
+_global_registry: PlatformRegistry | None = None
+_global_lock = threading.Lock()
+
+
+def get_registry() -> PlatformRegistry:
+    """Get the global platform registry instance.
+
+    Returns:
+        Global PlatformRegistry instance.
+
+    Example:
+        >>> registry = get_registry()
+        >>> manager = registry.get_manager("twitter", credentials=creds)
+    """
+    global _global_registry
+
+    if _global_registry is None:
+        with _global_lock:
+            if _global_registry is None:
+                _global_registry = PlatformRegistry()
+
+    return _global_registry
+
+
+def register_platform(platform_name: str, manager_class: type) -> None:
+    """Register a platform in the global registry.
+
+    Convenience function that uses the global registry.
+
+    Args:
+        platform_name: Name of the platform.
+        manager_class: The manager class to register.
+
+    Example:
+        >>> from marqetive_lib.platforms.twitter.manager import TwitterPostManager
+        >>> register_platform("twitter", TwitterPostManager)
+    """
+    registry = get_registry()
+    registry.register_platform(platform_name, manager_class)
+
+
+def get_manager_for_platform(platform_name: str, **kwargs: Any) -> Any:
+    """Get a manager instance for the specified platform.
+
+    Convenience function that uses the global registry.
+
+    Args:
+        platform_name: Name of the platform.
+        **kwargs: Arguments to pass to the manager constructor.
+
+    Returns:
+        Manager instance for the platform.
+
+    Example:
+        >>> manager = get_manager_for_platform("twitter", credentials=creds)
+        >>> post = await manager.execute_post(...)
+    """
+    registry = get_registry()
+    return registry.get_manager(platform_name, **kwargs)
+
+
+def get_available_platforms() -> list[str]:
+    """Get list of all registered platforms.
+
+    Convenience function that uses the global registry.
+
+    Returns:
+        List of platform names.
+
+    Example:
+        >>> platforms = get_available_platforms()
+        >>> print(platforms)
+        ['twitter', 'linkedin', 'instagram']
+    """
+    registry = get_registry()
+    return registry.get_available_platforms()

marqetive/platforms/__init__.py

@@ -0,0 +1,55 @@
+"""Social media platform integrations.
+
+This package provides a unified interface for interacting with various social
+media platforms including Instagram, Twitter/X, and LinkedIn.
+
+Platform clients are available via their respective subpackages:
+    - from marqetive_lib.platforms.twitter import TwitterClient
+    - from marqetive_lib.platforms.linkedin import LinkedInClient
+    - from marqetive_lib.platforms.instagram import InstagramClient
+"""
+
+from marqetive.platforms.base import SocialMediaPlatform
+from marqetive.platforms.exceptions import (
+    MediaUploadError,
+    PlatformAuthError,
+    PlatformError,
+    PostNotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+from marqetive.platforms.models import (
+    AuthCredentials,
+    Comment,
+    CommentStatus,
+    MediaAttachment,
+    MediaType,
+    PlatformResponse,
+    Post,
+    PostCreateRequest,
+    PostStatus,
+    PostUpdateRequest,
+)
+
+__all__ = [
+    # Base class
+    "SocialMediaPlatform",
+    # Models
+    "AuthCredentials",
+    "Comment",
+    "CommentStatus",
+    "MediaAttachment",
+    "MediaType",
+    "PlatformResponse",
+    "Post",
+    "PostCreateRequest",
+    "PostStatus",
+    "PostUpdateRequest",
+    # Exceptions
+    "MediaUploadError",
+    "PlatformAuthError",
+    "PlatformError",
+    "PostNotFoundError",
+    "RateLimitError",
+    "ValidationError",
+]