marqetive-lib 0.1.11__tar.gz

marqetive_lib-0.1.11/PKG-INFO

@@ -0,0 +1,289 @@
+Metadata-Version: 2.4
+Name: marqetive-lib
+Version: 0.1.11
+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.11/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.11/pyproject.toml

@@ -0,0 +1,176 @@
+[build-system]
+requires = ["poetry-core>=2.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[project]
+name = "marqetive-lib"
+version = "0.1.11"
+description = "Modern Python utilities for web APIs"
+readme = "README.md"
+requires-python = ">=3.12"
+keywords = ["api", "utilities", "web", "http", "marqetive"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.0.0",
+    "tweepy (>=4.16.0,<5.0.0)",
+    "aiofiles>=24.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0.0",
+    "pytest-cov>=7.0.0",
+    "pytest-asyncio>=1.3.0",
+    "ruff>=0.14.4",
+    "pyright>=1.1.0",
+]
+docs = [
+    "mkdocs>=1.5.0",
+    "mkdocs-material>=9.5.0",
+    "mkdocstrings[python]>=0.30.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/yourusername/marqetive-lib"
+Documentation = "https://marqetive-lib.readthedocs.io"
+Repository = "https://github.com/yourusername/marqetive-lib"
+Issues = "https://github.com/yourusername/marqetive-lib/issues"
+
+[tool.poetry]
+packages = [{ include = "marqetive", from = "src" }]
+
+# Poetry-specific dependency management
+[tool.poetry.dependencies]
+python = "^3.12"
+httpx = "^0.28.1"
+pydantic = "^2.0.0"
+tweepy = "^4.16.0"
+aiofiles = "^24.0.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^9.0.0"
+pytest-cov = "^7.0.0"
+pytest-asyncio = "^1.3.0"
+ruff = "^0.14.4"
+pyright = "^1.1.0"
+ipython = "^9.7.0"
+
+[tool.poetry.group.docs.dependencies]
+mkdocs = "^1.5.0"
+mkdocs-material = "^9.5.0"
+mkdocstrings = { extras = ["python"], version = "^0.30.1" }
+
+# Ruff configuration
+[tool.ruff]
+# Target Python 3.12+
+target-version = "py312"
+
+# Line length to match Black's default
+line-length = 88
+
+# Directories to exclude
+exclude = [".git", ".venv", "__pycache__", "build", "dist", "*.egg-info"]
+
+[tool.ruff.lint]
+# Enable rule sets
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+    "ARG", # flake8-unused-arguments
+    "SIM", # flake8-simplify
+]
+
+# Rules to ignore
+ignore = [
+    "E501", # line too long (handled by formatter)
+    "B008", # do not perform function calls in argument defaults
+]
+
+# Allow autofix for all enabled rules
+fixable = ["ALL"]
+unfixable = []
+
+# Allow unused variables when underscore-prefixed
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.format]
+# Use double quotes for strings
+quote-style = "double"
+
+# Indent with spaces
+indent-style = "space"
+
+# Respect magic trailing commas
+skip-magic-trailing-comma = false
+
+# Auto-detect line endings
+line-ending = "auto"
+
+[tool.ruff.lint.isort]
+known-first-party = ["marqetive"]
+
+# Pyright configuration
+[tool.pyright]
+# Paths to include in analysis
+include = ["src"]
+
+# Paths to exclude
+exclude = ["**/__pycache__", "**/node_modules", ".venv", "build", "dist"]
+
+# Python version
+pythonVersion = "3.12"
+pythonPlatform = "All"
+
+# Type checking mode: "off", "basic", "standard", "strict"
+typeCheckingMode = "standard"
+
+# Reporting options (incremental strictness)
+reportMissingImports = true
+reportMissingTypeStubs = false
+reportUnusedImport = "warning"
+reportUnusedClass = "warning"
+reportUnusedFunction = "warning"
+reportUnusedVariable = "warning"
+reportDuplicateImport = "warning"
+reportOptionalSubscript = "error"
+reportOptionalMemberAccess = "error"
+reportOptionalCall = "error"
+reportOptionalIterable = "error"
+reportOptionalContextManager = "error"
+reportOptionalOperand = "error"
+
+# Stricter checks (enable gradually)
+reportUnknownParameterType = "none"
+reportUnknownArgumentType = "none"
+reportUnknownLambdaType = "none"
+reportUnknownVariableType = "none"
+reportUnknownMemberType = "none"
+
+# Use stub packages when available
+stubPath = "typings"
+
+# Pytest configuration
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+    "--cov=marqetive",
+    "--cov-report=term-missing",
+]
+testpaths = ["tests"]
+pythonpath = ["src"]