GitHub - MarshalX/atproto: The AT Protocol (Bluesky) SDK for Python

Autogenerated from lexicons, well type hinted, documented, sync and async SDK for Python
Documentation • Guides • Examples • Atmosphere lexicons • Discord Bluesky API

The AT Protocol SDK

⚠️ Under construction. Until the 1.0.0 release compatibility between versions is not guaranteed.

from atproto import Client, client_utils


def main():
    client = Client()
    profile = client.login('my-handle', 'my-password')
    print('Welcome,', profile.display_name)

    text = client_utils.TextBuilder().text('Hello World from ').link('Python SDK', 'https://atproto.blue')
    post = client.send_post(text)
    client.like(post.uri, post.cid)


if __name__ == '__main__':
    main()

Code snippet of async version

import asyncio

from atproto import AsyncClient, client_utils


async def main():
    client = AsyncClient()
    profile = await client.login('my-handle', 'my-password')
    print('Welcome,', profile.display_name)

    text = client_utils.TextBuilder().text('Hello World from ').link('Python SDK', 'https://atproto.blue')
    post = await client.send_post(text)
    await client.like(post.uri, post.cid)


if __name__ == '__main__':
    asyncio.run(main())

Installing

pip install atproto

Python 3.9 or higher.

What you get

This SDK attempts to implement everything that ATProto provides. There is support for Lexicon schemas, XRPC clients, OAuth, Firehose, Jetstream, Identity, DID keys, signatures, and more. All models, queries, and procedures are generated automatically. The main focus is on the lexicons of atproto.com and bsky.app, but there is no vendor lock on it. Point the code generator at your own lexicon schemas and it produces the same typed models and clients for them. The SDK also provides utilities to work with CID, NSID, AT URI schemes, DAG-CBOR, CAR files, DID documents and more.

Sync and async clients with identical method sets.
Type hints everywhere, so your IDE can navigate the whole protocol.
A high-level client for common tasks, with the complete XRPC surface underneath it.
OAuth and app passwords, with PAR, PKCE, DPoP and token refresh handled for you.
Real-time streaming over the Firehose or Jetstream, including archive backfill.
Your own lexicons, compiled into an importable package by atp gen custom.
Third-party lexicons, ready to import: pip install atproto-lexicons adds typed models and client methods for the services of the Atmosphere. Search them at lex.atproto.blue.

Documentation

The documentation is live at atproto.blue.


🚀 Quickstart	Install, log in, post, read a timeline
📚 Guides	Posting, reading, streaming, identity, errors
💡 Examples	Every runnable example, inlined
🧩 Custom lexicons	Generate models and clients from your own lexicons
🪐 Atmosphere lexicons	Third-party lexicons, generated ahead of time
🛠 The `atp` CLI	The code generator's command line
🔐 OAuth	Log users in without their password
💬 Direct messages	Chats, messages, and reactions
🔥 Firehose & Jetstream	Data streaming from the whole network
🌐 Identity	DID and handle resolvers
📖 Model reference	Every lexicon on the network, as a Pydantic model
🍿 Feed generator	Build a custom feed, end to end

This is the SDK's documentation, not the protocol's. For the protocol itself, see atproto.com and bsky.network/docs.

SDK structure

The SDK is built upon the following components:

Package	Description
`atproto`	Import shortcuts to other packages.
`atproto_cli`	CLI tool to generate code.
`atproto_client`	XRPC Client, data models, and utils like rich text helper.
`atproto_codegen`	Code generator of models, clients, and namespaces.
`atproto_core`	Tools to work with NSID, AT URI Schemes, CID, CAR files, and DID Documents.
`atproto_crypto`	Crypto utils like multibase, signature verification, work with DID keys.
`atproto_firehose`	Firehose (data streaming) client and models.
`atproto_identity`	Identity resolvers for DID, Handle, AT Protocol data, signing keys.
`atproto_jetstream`	Jetstream v2 (data streaming) client and models.
`atproto_lexicon`	Lexicon parser.
`atproto_oauth`	OAuth client with PAR, PKCE, DPoP, scopes and session storage.
`atproto_server`	Server-side utils like JWT.
`atproto_subscription`	Websocket subscription runtime behind the streaming clients.

I highly recommend that you use the atproto package to import everything that you need. It contains shortcuts to all other packages.

Getting help

You can get help in several ways:

Report bugs, request new features by creating an issue.
Ask questions by starting a discussion.
Ask questions in Discord server.

Change log

The full change log is available in CHANGES.md.

Contributing

Contributions of all sizes are welcome. The contribution guidelines will be presented later.

License

MIT

MarshalX/atproto

Measured star growth

About

README.md