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
Threads - Publish text and media posts via Threads Graph API

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

pip install marqetive

Or with Poetry:

poetry add marqetive

Quick Start

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

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"]
    ))

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

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

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

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

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

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

# 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

# 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

# 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 file for details.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

marqetive_lib-0.12.7.tar.gz (231.4 kB view details)

Uploaded Jul 21, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

marqetive_lib-0.12.7-py3-none-any.whl (282.9 kB view details)

Uploaded Jul 21, 2026 Python 3

File details

Details for the file marqetive_lib-0.12.7.tar.gz.

File metadata

Download URL: marqetive_lib-0.12.7.tar.gz
Upload date: Jul 21, 2026
Size: 231.4 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: poetry/2.4.1 CPython/3.14.6 Darwin/24.6.0

File hashes

Hashes for marqetive_lib-0.12.7.tar.gz
Algorithm	Hash digest
SHA256	`d613e7fcf894515bad3deb912943cea79d20d8a0b72c9d9af9fb4cc5275e9f93`
MD5	`6c861a2b2aa1e675e80e682b8303c556`
BLAKE2b-256	`762835a3f6724aacad89c0c5269e31fd02e513159fc5f1d3c7021cfd74cbabe6`

See more details on using hashes here.

File details

Details for the file marqetive_lib-0.12.7-py3-none-any.whl.

File metadata

Download URL: marqetive_lib-0.12.7-py3-none-any.whl
Upload date: Jul 21, 2026
Size: 282.9 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: poetry/2.4.1 CPython/3.14.6 Darwin/24.6.0

File hashes

Hashes for marqetive_lib-0.12.7-py3-none-any.whl
Algorithm	Hash digest
SHA256	`b7fc526da079748cf88a25238683d86ab5a01ee6a71c9b9a652bb608594b1a12`
MD5	`5bbd567fb289610bc56221cb0c80ea7a`
BLAKE2b-256	`ff3e1e1d9bf647422028485b3a613b0540826a7cc28734f6cd819891cd3f2d60`