AT Protocol SDK for Python

0.0.65 · active · verified Sun Apr 12

The `atproto` library is the official Python SDK for the AT Protocol, the decentralized social networking protocol behind Bluesky. It provides support for Lexicon Schemes, XRPC clients, Firehose, Identity, DID keys, signatures, and more, with all models, queries, and procedures automatically generated. As of version 0.0.65, the SDK is actively developed with frequent releases, though it remains in a pre-1.0.0 state where backward compatibility is not strictly guaranteed.

Warnings

breaking Python 3.8 support was officially dropped in `atproto` v0.0.63. Users on Python 3.8 must upgrade their Python version to 3.9 or newer.
Fix: Upgrade Python to 3.9 or later.
breaking Significant breaking changes occurred due to Pydantic v2 migration and `libipld` integration, particularly noticeable when upgrading from much older versions. These include: positional arguments for model instantiation are no longer supported (use keyword arguments); `createdAt` (camelCase) fields are now `created_at` (snake_case); the root namespace for Bluesky API calls changed from `client.bsky` to `client.app.bsky`; and fields conflicting with Pydantic reserved names have a `_` suffix (e.g., `validation` is now `validation_`).
Fix: Review the changelog for specific version updates. Update model instantiation to use keyword arguments, convert field names to snake_case, and adjust API calls to use the correct `client.app.bsky` namespace.
gotcha Version 0.0.60 contained a bug that broke session refreshing. This was fixed in version 0.0.61.
Fix: Upgrade to `atproto` v0.0.61 or higher.
gotcha The SDK is marked as 'Under construction' and 'Until the 1.0.0 release compatibility between versions is not guaranteed'. This means breaking changes can occur in minor versions without extensive prior notice.
Fix: Regularly review release notes and test your application when upgrading. Pin exact versions for production environments.
gotcha The high-level `Client` provides a simplified API ('syntax sugar') but does not cover the full range of AT Protocol functionalities. For advanced or niche operations, developers may need to interact with the lower-level XRPC API via namespaces (e.g., `client.com.atproto.server`) and models (from `atproto.models`).
Fix: Consult the official documentation for advanced usage and low-level API interactions.
gotcha Upgrading `websockets` to v15 and `pydantic` in `atproto` v0.0.63 may lead to 'differences in stability' or 'new strange warnings' from `pydantic`.
Fix: Report any unexpected stability issues or Pydantic warnings to the library maintainers for investigation.

Install

pip install atproto Install latest version

Imports

Client
```
from atproto import Client
```
AsyncClient
```
from atproto import AsyncClient
```
models
```
from atproto import models
```
Used for accessing low-level API models (e.g., `models.AppBskyFeedPost.Record`).
client_utils
```
from atproto import client_utils
```
Provides utility functions like `TextBuilder` for rich text posts.

Quickstart

This quickstart demonstrates how to initialize the synchronous `Client`, log in using environment variables for credentials, and send a simple text post to the AT Protocol network (e.g., Bluesky).

import os
from atproto import Client

def main():
    client = Client()
    try:
        # Use environment variables for sensitive credentials
        handle = os.environ.get('ATPROTO_USERNAME', 'your-handle.bsky.social')
        password = os.environ.get('ATPROTO_PASSWORD', 'your-app-password')

        profile = client.login(handle, password)
        print(f"Welcome, {profile.display_name}!")

        # Send a simple text post
        post_text = "Hello World from the AT Protocol Python SDK! #atproto #python"
        response = client.send_post(text=post_text)
        print(f"Posted: {post_text}\nURI: {response.uri}")

    except Exception as e:
        print(f"An error occurred: {e}")

if __name__ == '__main__':
    main()

view raw JSON →