MarqetiveLib

The async Python client library behind Postey - the social media publishing platform. Simple, type-safe, and async-ready.

Supported Platforms

All nine platforms Postey publishes to:

X (Twitter) - 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
YouTube - Upload Shorts and videos
Threads - Publish text and media posts via Threads Graph API
Bluesky - Post via the AT Protocol
Facebook - Publish to Pages via Graph API
Pinterest - Create pins with media

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-lib

Or with Poetry:

poetry add marqetive-lib

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 git@github.com:quantplay-admin/MarqetiveLib.git
cd MarqetiveLib

# 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

The tests/usage money-path suites need a live Redis and fail without one — they are the only coverage of the debit Lua and the fair-use ceiling, so they must never skip:

docker run --rm -p 6379:6379 redis:7-alpine

Set REDIS_URL to point elsewhere (default redis://localhost:6379). The suite flushes DB index REDIS_TEST_DB (default 15) around every test.

# 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.

Metadata

Release files for marqetive-lib 0.24.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for marqetive-lib 0.24.1
File	Size	Uploaded
marqetive_lib-0.24.1.tar.gz	330.2 kB	Sep 12, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for marqetive-lib 0.24.1
File	Interpreter	ABI	Platform	Reset
marqetive_lib-0.24.1-py3-none-any.whl 397.0 kB Sep 12, 2026	Python 3	none	any	Details

Total release size: 727.2 kB

Release files / marqetive_lib-0.24.1.tar.gz

Download URL	marqetive_lib-0.24.1.tar.gz
Size	330.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`3c0a4be8fdafc24cff08f0700fe6ceb266fc74d5932a82a87026392ba2060ec1`
BLAKE2b-256 checksum How to use checksums	`7425f4585d9d904a6de550be2454276380574a369c7f55e93b76ae9281a4592a`
Upload date	Sep 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.4.1 CPython/3.14.7 Darwin/24.6.0`

Release files / marqetive_lib-0.24.1-py3-none-any.whl

Download URL	marqetive_lib-0.24.1-py3-none-any.whl
Size	397.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`a3f5fa6cffa51d15f176242d386209ff6f909df8778772868c80d3c575256617`
BLAKE2b-256 checksum How to use checksums	`fde1f087c8b990bd99355fff8bf1d9113079117b0437004f7357dba6cf636d8f`
Upload date	Sep 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.4.1 CPython/3.14.7 Darwin/24.6.0`