bsky-bridge

A Python library for the BlueSky Social Network API.

Features

• Simple authentication with automatic session persistence
• Automatic token refresh and rate limit handling
• Post text with mentions, links, and hashtags (auto-detected)
• Post up to 4 images per post with alt text support
• Automatic image optimization (resize, compress, EXIF stripping)
• Language specification for multilingual posts
• Reply controls (threadgate) - restrict who can reply to your posts

Installation

pip install bsky-bridge

Quick Start

from bsky_bridge import BskySession, post_text

session = BskySession("your_handle.bsky.social", "your_app_password")
post_text(session, "Hello BlueSky!")

Usage

Authentication

Create a session using your BlueSky handle and an App Password (not your main password):

from bsky_bridge import BskySession

session = BskySession("your_handle.bsky.social", "your_app_password")

Sessions are automatically saved to .bsky_sessions/ and reused. To use a custom directory:

session = BskySession("your_handle.bsky.social", "your_app_password", session_dir="/path/to/sessions")

Posting Text

from bsky_bridge import BskySession, post_text

session = BskySession("your_handle.bsky.social", "your_app_password")

# Simple post
post_text(session, "Hello BlueSky!")

# Mentions, links, and hashtags are automatically detected
post_text(session, "Hey @friend.bsky.social check out https://example.com #coding")

Posting a Single Image

from bsky_bridge import BskySession, post_image

session = BskySession("your_handle.bsky.social", "your_app_password")

post_image(
    session,
    "Check out this photo!",
    "/path/to/image.jpg",
    alt_text="A beautiful sunset"
)

Posting Multiple Images

Post up to 4 images in a single post:

from bsky_bridge import BskySession, post_images

session = BskySession("your_handle.bsky.social", "your_app_password")

post_images(session, "My photo gallery!", [
    {"path": "/path/to/image1.jpg", "alt": "First image"},
    {"path": "/path/to/image2.jpg", "alt": "Second image"},
    {"path": "/path/to/image3.jpg", "alt": "Third image"},
    {"path": "/path/to/image4.jpg", "alt": "Fourth image"},
])

Specifying Languages

Help BlueSky's feed algorithms by specifying post languages:

from bsky_bridge import post_text, post_image

# Multilingual text post
post_text(session, "Bonjour! Hello!", langs=["fr", "en-US"])

# Image post with languages
post_image(
    session,
    "Belle photo! Beautiful photo!",
    "/path/to/image.jpg",
    alt_text="Landscape",
    langs=["fr", "en-US"]
)

Reply Controls (Threadgate)

Control who can reply to your posts using the reply_to parameter:

from bsky_bridge import post_text

# No one can reply
post_text(session, "This is a statement.", reply_to="nobody")

# Only mentioned users can reply
post_text(session, "Hey @friend.bsky.social what do you think?", reply_to="mentions")

# Only people you follow can reply
post_text(session, "Question for my friends", reply_to="following")

# Only your followers can reply
post_text(session, "Followers only discussion", reply_to="followers")

# Combine multiple rules
post_text(session, "Limited discussion", reply_to=["mentions", "following"])

Available options:

Works with all post functions (post_text, post_image, post_images).

Making Custom API Calls

Use the session to make authenticated calls to any AT Protocol endpoint:

# GET request
profile = session.api_call(
    "app.bsky.actor.getProfile",
    method="GET",
    params={"actor": "someone.bsky.social"}
)

# POST request
session.api_call(
    "com.atproto.repo.createRecord",
    method="POST",
    json={
        "repo": session.did,
        "collection": "app.bsky.feed.like",
        "record": {
            "$type": "app.bsky.feed.like",
            "subject": {"uri": "at://...", "cid": "..."},
            "createdAt": "2024-01-01T00:00:00Z"
        }
    }
)

Logging Out

session.logout()  # Clears tokens and deletes session file

Image Handling

Images are automatically processed before upload:

Rate Limiting

The library automatically handles BlueSky's rate limits:

• Detects HTTP 429 responses
• Reads Retry-After and RateLimit-Reset headers
• Falls back to exponential backoff (1s, 2s, 4s...)
• Retries up to 3 times before raising an error

API Reference

BskySession

BskySession(handle: str, app_password: str, session_dir: str = None)

Functions

Contributing

Contributions are welcome! Please submit issues for bugs and pull requests for new features.

License

MIT License