marqetive-lib 0.1.5__tar.gz → 0.1.7__tar.gz

marqetive_lib-0.1.7/PKG-INFO

@@ -0,0 +1,289 @@
+Metadata-Version: 2.4
+Name: marqetive-lib
+Version: 0.1.7
+Summary: Modern Python utilities for web APIs
+Keywords: api,utilities,web,http,marqetive
+Requires-Python: >=3.12
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Provides-Extra: dev
+Provides-Extra: docs
+Requires-Dist: aiofiles (>=24.0.0)
+Requires-Dist: httpx (>=0.28.1)
+Requires-Dist: mkdocs (>=1.5.0) ; extra == "docs"
+Requires-Dist: mkdocs-material (>=9.5.0) ; extra == "docs"
+Requires-Dist: mkdocstrings[python] (>=0.30.1) ; extra == "docs"
+Requires-Dist: pydantic (>=2.0.0)
+Requires-Dist: pyright (>=1.1.0) ; extra == "dev"
+Requires-Dist: pytest (>=9.0.0) ; extra == "dev"
+Requires-Dist: pytest-asyncio (>=1.3.0) ; extra == "dev"
+Requires-Dist: pytest-cov (>=7.0.0) ; extra == "dev"
+Requires-Dist: ruff (>=0.14.4) ; extra == "dev"
+Requires-Dist: tweepy (>=4.16.0,<5.0.0)
+Project-URL: Documentation, https://marqetive-lib.readthedocs.io
+Project-URL: Homepage, https://github.com/yourusername/marqetive-lib
+Project-URL: Issues, https://github.com/yourusername/marqetive-lib/issues
+Project-URL: Repository, https://github.com/yourusername/marqetive-lib
+Description-Content-Type: text/markdown
+
+# MarqetiveLib
+
+Modern Python library for social media platform integrations - Simple, type-safe, and async-ready.
+
+## Supported Platforms
+
+- **Twitter/X** - Post tweets, upload media, manage threads
+- **LinkedIn** - Share updates, upload images and videos
+- **Instagram** - Create posts with media via Graph API
+- **TikTok** - Upload and publish videos
+
+## Features
+
+- **Unified API**: Single interface for all social media platforms
+- **Async-First**: Built for modern async Python applications
+- **Type-Safe**: Full type hints and Pyright compliance
+- **Auto Token Refresh**: Factory handles OAuth token lifecycle automatically
+- **Media Upload**: Progress tracking for large file uploads
+- **Retry Logic**: Exponential backoff with jitter for transient failures
+- **Well Tested**: Comprehensive test coverage
+
+## Installation
+
+```bash
+pip install marqetive
+```
+
+Or with Poetry:
+
+```bash
+poetry add marqetive
+```
+
+## Quick Start
+
+```python
+import asyncio
+from marqetive import get_client, AuthCredentials, PostCreateRequest
+
+async def main():
+    # Create credentials for your platform
+    credentials = AuthCredentials(
+        platform="twitter",
+        access_token="your_access_token",
+        refresh_token="your_refresh_token"
+    )
+
+    # Get authenticated client (auto-refreshes token if expired)
+    client = await get_client(credentials)
+
+    # Use client as async context manager
+    async with client:
+        request = PostCreateRequest(content="Hello from MarqetiveLib!")
+        post = await client.create_post(request)
+        print(f"Posted! ID: {post.platform_id}")
+
+asyncio.run(main())
+```
+
+## Platform Examples
+
+### Twitter
+
+```python
+from marqetive import get_client, AuthCredentials, PostCreateRequest
+
+credentials = AuthCredentials(
+    platform="twitter",
+    access_token="your_access_token",
+    refresh_token="your_refresh_token"  # Optional, for token refresh
+)
+
+client = await get_client(credentials)
+async with client:
+    # Text post
+    post = await client.create_post(PostCreateRequest(content="Hello Twitter!"))
+
+    # Post with media
+    post = await client.create_post(PostCreateRequest(
+        content="Check out this image!",
+        media_paths=["/path/to/image.jpg"]
+    ))
+```
+
+### LinkedIn
+
+```python
+from marqetive import get_client, AuthCredentials, PostCreateRequest
+
+credentials = AuthCredentials(
+    platform="linkedin",
+    access_token="your_access_token",
+    user_id="urn:li:person:your_person_id"  # Required for LinkedIn
+)
+
+client = await get_client(credentials)
+async with client:
+    post = await client.create_post(PostCreateRequest(
+        content="Excited to share this update!"
+    ))
+```
+
+### Instagram
+
+```python
+from marqetive import get_client, AuthCredentials, PostCreateRequest
+
+credentials = AuthCredentials(
+    platform="instagram",
+    access_token="your_access_token",
+    user_id="your_instagram_business_account_id"  # Required
+)
+
+client = await get_client(credentials)
+async with client:
+    # Instagram requires media for posts
+    post = await client.create_post(PostCreateRequest(
+        content="Beautiful day! #photography",
+        media_paths=["/path/to/photo.jpg"]
+    ))
+```
+
+### TikTok
+
+```python
+from marqetive import get_client, AuthCredentials, PostCreateRequest
+
+credentials = AuthCredentials(
+    platform="tiktok",
+    access_token="your_access_token",
+    additional_data={"open_id": "your_open_id"}  # Required for TikTok
+)
+
+client = await get_client(credentials)
+async with client:
+    post = await client.create_post(PostCreateRequest(
+        content="Check out this video!",
+        media_paths=["/path/to/video.mp4"]
+    ))
+```
+
+## Using Custom OAuth Credentials
+
+```python
+from marqetive import PlatformFactory, AuthCredentials, PostCreateRequest
+
+# Create factory with your OAuth app credentials
+factory = PlatformFactory(
+    twitter_client_id="your_client_id",
+    twitter_client_secret="your_client_secret",
+    linkedin_client_id="your_linkedin_client_id",
+    linkedin_client_secret="your_linkedin_client_secret"
+)
+
+credentials = AuthCredentials(
+    platform="twitter",
+    access_token="user_access_token",
+    refresh_token="user_refresh_token"
+)
+
+# Get client with automatic token refresh
+client = await factory.get_client(credentials)
+async with client:
+    post = await client.create_post(PostCreateRequest(content="Hello!"))
+```
+
+## Progress Tracking for Media Uploads
+
+```python
+def progress_callback(operation: str, progress: int, total: int, message: str | None):
+    percent = (progress / total) * 100 if total > 0 else 0
+    print(f"{operation}: {percent:.1f}% - {message or ''}")
+
+client = await get_client(credentials, progress_callback=progress_callback)
+async with client:
+    post = await client.create_post(PostCreateRequest(
+        content="Uploading video...",
+        media_paths=["/path/to/large_video.mp4"]
+    ))
+```
+
+## Error Handling
+
+```python
+from marqetive import get_client, AuthCredentials, PostCreateRequest
+from marqetive.core.exceptions import (
+    PlatformError,
+    PlatformAuthError,
+    RateLimitError,
+    MediaUploadError
+)
+
+try:
+    client = await get_client(credentials)
+    async with client:
+        post = await client.create_post(request)
+except PlatformAuthError as e:
+    print(f"Authentication failed: {e}")
+    # Token may need refresh or reconnection
+except RateLimitError as e:
+    print(f"Rate limited. Retry after: {e.retry_after} seconds")
+except MediaUploadError as e:
+    print(f"Media upload failed: {e}")
+except PlatformError as e:
+    print(f"Platform error: {e}")
+```
+
+## Development
+
+### Setup Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/marqetive-lib.git
+cd marqetive-lib
+
+# Install Poetry if you haven't already
+curl -sSL https://install.python-poetry.org | python3 -
+
+# Install dependencies
+poetry install --with dev,docs
+
+# Activate virtual environment
+poetry shell
+```
+
+### Running Tests
+
+```bash
+# Run tests
+poetry run pytest
+
+# Run tests with coverage
+poetry run pytest --cov=src/marqetive --cov-report=term-missing
+
+# Run platform-specific tests
+poetry run pytest tests/platforms/test_twitter.py
+```
+
+### Code Quality
+
+```bash
+# Lint code with Ruff
+poetry run ruff check .
+
+# Format code with Ruff
+poetry run ruff format .
+
+# Type check with Pyright
+poetry run pyright src/
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+

marqetive_lib-0.1.7/README.md

@@ -0,0 +1,255 @@
+# MarqetiveLib
+
+Modern Python library for social media platform integrations - Simple, type-safe, and async-ready.
+
+## Supported Platforms
+
+- **Twitter/X** - Post tweets, upload media, manage threads
+- **LinkedIn** - Share updates, upload images and videos
+- **Instagram** - Create posts with media via Graph API
+- **TikTok** - Upload and publish videos
+
+## Features
+
+- **Unified API**: Single interface for all social media platforms
+- **Async-First**: Built for modern async Python applications
+- **Type-Safe**: Full type hints and Pyright compliance
+- **Auto Token Refresh**: Factory handles OAuth token lifecycle automatically
+- **Media Upload**: Progress tracking for large file uploads
+- **Retry Logic**: Exponential backoff with jitter for transient failures
+- **Well Tested**: Comprehensive test coverage
+
+## Installation
+
+```bash
+pip install marqetive
+```
+
+Or with Poetry:
+
+```bash
+poetry add marqetive
+```
+
+## Quick Start
+
+```python
+import asyncio
+from marqetive import get_client, AuthCredentials, PostCreateRequest
+
+async def main():
+    # Create credentials for your platform
+    credentials = AuthCredentials(
+        platform="twitter",
+        access_token="your_access_token",
+        refresh_token="your_refresh_token"
+    )
+
+    # Get authenticated client (auto-refreshes token if expired)
+    client = await get_client(credentials)
+
+    # Use client as async context manager
+    async with client:
+        request = PostCreateRequest(content="Hello from MarqetiveLib!")
+        post = await client.create_post(request)
+        print(f"Posted! ID: {post.platform_id}")
+
+asyncio.run(main())
+```
+
+## Platform Examples
+
+### Twitter
+
+```python
+from marqetive import get_client, AuthCredentials, PostCreateRequest
+
+credentials = AuthCredentials(
+    platform="twitter",
+    access_token="your_access_token",
+    refresh_token="your_refresh_token"  # Optional, for token refresh
+)
+
+client = await get_client(credentials)
+async with client:
+    # Text post
+    post = await client.create_post(PostCreateRequest(content="Hello Twitter!"))
+
+    # Post with media
+    post = await client.create_post(PostCreateRequest(
+        content="Check out this image!",
+        media_paths=["/path/to/image.jpg"]
+    ))
+```
+
+### LinkedIn
+
+```python
+from marqetive import get_client, AuthCredentials, PostCreateRequest
+
+credentials = AuthCredentials(
+    platform="linkedin",
+    access_token="your_access_token",
+    user_id="urn:li:person:your_person_id"  # Required for LinkedIn
+)
+
+client = await get_client(credentials)
+async with client:
+    post = await client.create_post(PostCreateRequest(
+        content="Excited to share this update!"
+    ))
+```
+
+### Instagram
+
+```python
+from marqetive import get_client, AuthCredentials, PostCreateRequest
+
+credentials = AuthCredentials(
+    platform="instagram",
+    access_token="your_access_token",
+    user_id="your_instagram_business_account_id"  # Required
+)
+
+client = await get_client(credentials)
+async with client:
+    # Instagram requires media for posts
+    post = await client.create_post(PostCreateRequest(
+        content="Beautiful day! #photography",
+        media_paths=["/path/to/photo.jpg"]
+    ))
+```
+
+### TikTok
+
+```python
+from marqetive import get_client, AuthCredentials, PostCreateRequest
+
+credentials = AuthCredentials(
+    platform="tiktok",
+    access_token="your_access_token",
+    additional_data={"open_id": "your_open_id"}  # Required for TikTok
+)
+
+client = await get_client(credentials)
+async with client:
+    post = await client.create_post(PostCreateRequest(
+        content="Check out this video!",
+        media_paths=["/path/to/video.mp4"]
+    ))
+```
+
+## Using Custom OAuth Credentials
+
+```python
+from marqetive import PlatformFactory, AuthCredentials, PostCreateRequest
+
+# Create factory with your OAuth app credentials
+factory = PlatformFactory(
+    twitter_client_id="your_client_id",
+    twitter_client_secret="your_client_secret",
+    linkedin_client_id="your_linkedin_client_id",
+    linkedin_client_secret="your_linkedin_client_secret"
+)
+
+credentials = AuthCredentials(
+    platform="twitter",
+    access_token="user_access_token",
+    refresh_token="user_refresh_token"
+)
+
+# Get client with automatic token refresh
+client = await factory.get_client(credentials)
+async with client:
+    post = await client.create_post(PostCreateRequest(content="Hello!"))
+```
+
+## Progress Tracking for Media Uploads
+
+```python
+def progress_callback(operation: str, progress: int, total: int, message: str | None):
+    percent = (progress / total) * 100 if total > 0 else 0
+    print(f"{operation}: {percent:.1f}% - {message or ''}")
+
+client = await get_client(credentials, progress_callback=progress_callback)
+async with client:
+    post = await client.create_post(PostCreateRequest(
+        content="Uploading video...",
+        media_paths=["/path/to/large_video.mp4"]
+    ))
+```
+
+## Error Handling
+
+```python
+from marqetive import get_client, AuthCredentials, PostCreateRequest
+from marqetive.core.exceptions import (
+    PlatformError,
+    PlatformAuthError,
+    RateLimitError,
+    MediaUploadError
+)
+
+try:
+    client = await get_client(credentials)
+    async with client:
+        post = await client.create_post(request)
+except PlatformAuthError as e:
+    print(f"Authentication failed: {e}")
+    # Token may need refresh or reconnection
+except RateLimitError as e:
+    print(f"Rate limited. Retry after: {e.retry_after} seconds")
+except MediaUploadError as e:
+    print(f"Media upload failed: {e}")
+except PlatformError as e:
+    print(f"Platform error: {e}")
+```
+
+## Development
+
+### Setup Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/marqetive-lib.git
+cd marqetive-lib
+
+# Install Poetry if you haven't already
+curl -sSL https://install.python-poetry.org | python3 -
+
+# Install dependencies
+poetry install --with dev,docs
+
+# Activate virtual environment
+poetry shell
+```
+
+### Running Tests
+
+```bash
+# Run tests
+poetry run pytest
+
+# Run tests with coverage
+poetry run pytest --cov=src/marqetive --cov-report=term-missing
+
+# Run platform-specific tests
+poetry run pytest tests/platforms/test_twitter.py
+```
+
+### Code Quality
+
+```bash
+# Lint code with Ruff
+poetry run ruff check .
+
+# Format code with Ruff
+poetry run ruff format .
+
+# Type check with Pyright
+poetry run pyright src/
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

{marqetive_lib-0.1.5 → marqetive_lib-0.1.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "marqetive-lib"
-version = "0.1.5"
+version = "0.1.7"
 description = "Modern Python utilities for web APIs"
 readme = "README.md"
 requires-python = ">=3.12"

{marqetive_lib-0.1.5 → marqetive_lib-0.1.7}/src/marqetive/__init__.py

@@ -62,6 +62,8 @@ from marqetive.core.models import (
     PostCreateRequest,
     PostStatus,
     PostUpdateRequest,
+    ProgressEvent,
+    ProgressStatus,
 )
 
 # Factory
@@ -85,17 +87,21 @@ __all__ = [
     "BackoffConfig",
     "STANDARD_BACKOFF",
     "retry_async",
-    # Models
-    "AuthCredentials",
+    # Enums
     "AccountStatus",
-    "Post",
+    "CommentStatus",
+    "MediaType",
     "PostStatus",
-    "PostCreateRequest",
-    "PostUpdateRequest",
+    "ProgressStatus",
+    # Core Models
+    "AuthCredentials",
     "Comment",
-    "CommentStatus",
     "MediaAttachment",
-    "MediaType",
+    "Post",
+    "ProgressEvent",
+    # Base Request Models
+    "PostCreateRequest",
+    "PostUpdateRequest",
     # Exceptions
     "PlatformError",
     "PlatformAuthError",

{marqetive_lib-0.1.5 → marqetive_lib-0.1.7}/src/marqetive/core/__init__.py

@@ -31,17 +31,19 @@ __all__ = [
     # Base class
     "SocialMediaPlatform",
     "ProgressCallback",
-    # Models
+    # Enums
     "AccountStatus",
+    "CommentStatus",
+    "MediaType",
+    "PostStatus",
+    # Core Models
     "AuthCredentials",
     "Comment",
-    "CommentStatus",
     "MediaAttachment",
-    "MediaType",
     "PlatformResponse",
     "Post",
+    # Base Request Models
     "PostCreateRequest",
-    "PostStatus",
     "PostUpdateRequest",
     # Exceptions
     "InvalidFileTypeError",