socialpost 0.1.0

Unified social media publishing library

SocialPost

A unified, provider-agnostic Python library for publishing content across multiple social media platforms. Built with enterprise-grade architecture: clean abstractions, dependency injection, comprehensive error handling, and extensive testability.

Features

• Multi-platform support - TikTok, Reddit, Instagram, Facebook, YouTube
• Async-first - All network I/O is async, with concurrent publishing support
• Strongly typed - Complete type hints, frozen dataclasses, Protocol-based interfaces
• Fail-safe by default - Railway-oriented programming with Result[T] types, no surprise exceptions
• Dependency injection - Pluggable HTTP clients, authenticators, and rate limiters
• Extensible - Protocol-based design makes adding new platforms straightforward

Installation

pip install socialpost

# With all platform dependencies
pip install socialpost[all]

# Specific platforms
pip install socialpost[reddit,tiktok]

Quick Start

import asyncio
from socialpost import SocialPost, Post, Media, MediaType, ContentFormat

async def main():
    async with SocialPost() as sp:
        # Configure your platform (see docs/auth_setup.md for credentials)
        # await sp.add_platform("reddit", reddit_auth, reddit_publisher)

        # Create a post
        post = Post(
            text="Check out this library!",
            tags=["python", "automation"],
            metadata={"subreddit": "programming"},
        )

        # Publish
        # result = await sp.publish("reddit", post)
        # if result.is_ok:
        #     print(f"Published! ID: {result.unwrap()}")
        # else:
        #     error = result.unwrap_err()
        #     print(f"Failed: {error.message}")

asyncio.run(main())

Multi-Platform Publishing

# Publish to all configured platforms
results = await sp.publish_to_all(post, platforms=["reddit", "tiktok"])

for platform, result in results.items():
    if result.is_ok:
        print(f"{platform}: {result.unwrap()}")
    else:
        print(f"{platform}: {result.unwrap_err().message}")

Documentation

• Architecture Overview
• Authentication Setup Guide
• Basic Usage Example
• Error Handling Example
• Full Architecture Spec

Supported Platforms

Platform	Text	Images	Video	Stories	Polls	Threads
Reddit	Yes	Yes	Yes	No	Yes	Yes
TikTok	No	No	Yes	No	No	No
Instagram	No	Yes	Yes	Yes	No	No
Facebook	Yes	Yes	Yes	Yes	No	No
YouTube	No	No	Yes	No	No	No

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=socialpost

# Type checking
mypy socialpost

# Format code
black socialpost
ruff check socialpost

Contributing

Contributions are welcome! See CONTEXT.md for architectural guidelines and code style.

License

MIT