truewire-bluesky

A typed, validated, async Python client for Bluesky's AT Protocol API: profiles, posts, threads, feeds, the follow graph, handle resolution, the Jetstream firehose, and writing posts.

Generated by Truewire from a spec of what the API puts on the wire, and checked against recordings of real responses — so the types are what the API sent, not what someone remembered.

pip install truewire-bluesky

Note: PyPI has an unrelated bluesky package (NSLS-II's experiment orchestration framework) that also imports as bluesky. The two cannot share an environment.

Reading needs no account

import asyncio

from bluesky import Bluesky


async def main() -> None:
  async with Bluesky.new() as client:
    profile = await client.actor.get_profile('bsky.app')
    print(profile['handle'], profile.get('followersCount'), 'followers')

    feed = await client.feed.get_author_feed(actor='bsky.app', limit=3)
    for entry in feed['feed']:
      print(entry['post']['record']['text'][:60])


asyncio.run(main())

The firehose

Jetstream is a public WebSocket of everything happening on the network, and needs no credentials either:

async with Bluesky.new() as client:
  async with client.jetstream.events(wanted_collections=['app.bsky.feed.post']) as stream:
    async for event in stream:
      print(event['kind'], event['did'])

Writing

Needs an app password (bsky.app → Settings → App Passwords), never the account password. The client creates the session and refreshes it for you.

from datetime import datetime, timezone

from bluesky import Bluesky
from bluesky.core.richtext import post as post_record

async with Bluesky.new(identifier='you.bsky.social', app_password='xxxx-xxxx-xxxx-xxxx') as client:
  session = await client.server.create_session()
  await client.repo.create_record(
    repo=session['did'],
    collection='app.bsky.feed.post',
    record=post_record(
      'Posted from a generated client — truewire.dev',
      created_at=datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z'),
      langs=['en'],
    ),
  )

post_record computes the link facets Bluesky needs to make a URL clickable, with the UTF-8 byte offsets it insists on.

Everything else

Twelve read endpoints, four write endpoints, cursor pagination on the ones that page, and TypeScript and Rust clients from the same spec.

Full documentation, the spec, and the recordings: https://github.com/truewire-dev/bluesky

MIT.