atproto

class atproto.AsyncClient(base_url: str | None = None, *args: Any, **kwargs: Any)

Bases: AsyncSessionDispatchMixin, SessionMethodsMixin, TimeMethodsMixin, HeadersConfigurationMethodsMixin, AsyncClientRaw

High-level client for XRPC of ATProto.

async clone() Self

Clone the client instance.

Used to customize atproto proxy and set of labeler services.

Returns:

Cloned client instance.

async delete_follow(follow_uri: str) bool

Alias for unfollow

async delete_like(like_uri: str) bool

Alias for unlike

async delete_post(post_uri: str) bool

Delete post.

Parameters:

post_uri – AT URI of the post.

Returns:

Success status.

Return type:

bool

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async delete_repost(repost_uri: str) bool

Alias for unrepost

async follow(subject: str) CreateRecordResponse

Follow the profile.

Parameters:

subject – DID of the profile.

Returns:

Reference to the created record.

Return type:

models.AppBskyGraphFollow.CreateRecordResponse

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async get_author_feed(actor: str, cursor: str | None = None, filter: str | None = None, limit: int | None = None) Response

Get author (profile) feed.

Parameters:
  • actor – Actor (handle or DID).

  • cursor – Cursor of the last like in the previous page.

  • filter – Filter.

  • limit – Limit count of likes to return.

Returns:

Feed.

Return type:

models.AppBskyFeedGetAuthorFeed.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async get_followers(actor: str, cursor: str | None = None, limit: int | None = None) Response

Get followers of the profile.

Parameters:
  • actor – Actor (handle or DID).

  • cursor – Cursor of the next page.

  • limit – Limit count of followers to return.

Returns:

Followers.

Return type:

models.AppBskyGraphGetFollowers.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async get_follows(actor: str, cursor: str | None = None, limit: int | None = None) Response

Get follows of the profile.

Parameters:
  • actor – Actor (handle or DID).

  • cursor – Cursor of the next page.

  • limit – Limit count of follows to return.

Returns:

Follows.

Return type:

models.AppBskyGraphGetFollows.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async get_likes(uri: str, cid: str | None = None, cursor: str | None = None, limit: int | None = None) Response

Get likes.

Parameters:
  • uri – AT URI.

  • cid – CID.

  • cursor – Cursor of the last like in the previous page.

  • limit – Limit count of likes to return.

Returns:

Likes.

Return type:

models.AppBskyFeedGetLikes.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async get_post(post_rkey: str, profile_identify: str | None = None, cid: str | None = None) GetRecordResponse

Get post.

Parameters:
  • post_rkey – ID (slug) of the post.

  • profile_identify – Handler or DID. Who created the post.

  • cid – The CID of the version of the post.

Returns:

Post.

Return type:

models.AppBskyFeedPost.GetRecordResponse

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async get_post_thread(uri: str, depth: int | None = None, parent_height: int | None = None) Response

Get post thread.

Parameters:
  • uri – AT URI.

  • depth – Depth of the thread.

  • parent_height – Height of the parent post.

Returns:

Post thread.

Return type:

models.AppBskyFeedGetPostThread.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async get_posts(uris: List[str]) Response

Get posts.

Parameters:

uris – Uris (AT URI).

Example

client.get_posts(['at://did:plc:kvwvcn5iqfooopmyzvb4qzba/app.bsky.feed.post/3k2yihcrp6f2c'])
Returns:

Posts.

Return type:

models.AppBskyFeedGetPosts.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async get_profile(actor: str) ProfileViewDetailed

Get profile.

Parameters:

actor – Actor (handle or DID).

Returns:

Profile.

Return type:

models.AppBskyActorDefs.ProfileViewDetailed

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async get_profiles(actors: List[str]) Response

Get profiles.

Parameters:

actors – List of actors (handles or DIDs).

Returns:

Profiles.

Return type:

models.AppBskyActorGetProfiles.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async get_reposted_by(uri: str, cid: str | None = None, cursor: str | None = None, limit: int | None = None) Response

Get reposted by (reposts).

Parameters:
  • uri – AT URI.

  • cid – CID.

  • cursor – Cursor of the last like in the previous page.

  • limit – Limit count of likes to return.

Returns:

Reposts.

Return type:

models.AppBskyFeedGetRepostedBy.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async get_timeline(algorithm: str | None = None, cursor: str | None = None, limit: int | None = None) Response

Get home timeline.

Parameters:
  • algorithm – Algorithm.

  • cursor – Cursor of the last like in the previous page.

  • limit – Limit count of likes to return.

Returns:

Home timeline.

Return type:

models.AppBskyFeedGetTimeline.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async like(uri: str, cid: str) CreateRecordResponse

Like the record.

Parameters:
  • cid – The CID of the record.

  • uri – The URI of the record.

Note

Record could be post, custom feed, etc.

Returns:

Reference to the created record.

Return type:

models.AppBskyFeedLike.CreateRecordResponse

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async login(login: str | None = None, password: str | None = None, session_string: str | None = None) ProfileViewDetailed

Authorize a client and get profile info.

Parameters:
  • login – Handle/username of the account.

  • password – Main or app-specific password of the account.

  • session_string – Session string (use export_session_string to get it).

Note

Either session_string or login and password should be provided.

Returns:

Profile information.

Return type:

models.AppBskyActorDefs.ProfileViewDetailed

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async mute(actor: str) bool

Mute actor (profile).

Parameters:

actor – Actor (handle or DID).

Returns:

Success status.

Return type:

bool

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async post(text: str | TextBuilder, profile_identify: str | None = None, reply_to: ReplyRef | None = None, embed: Main | Main | Main | Main | None = None, langs: List[str] | None = None, facets: List[Main] | None = None) CreateRecordResponse

Alias for send_post

async repost(uri: str, cid: str) CreateRecordResponse

Repost post.

Parameters:
  • cid – The CID of the post.

  • uri – The URI of the post.

Returns:

Reference to the reposted record.

Return type:

models.AppBskyFeedRepost.CreateRecordResponse

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async resolve_handle(handle: str) Response

Resolve the handle.

Parameters:

handle – Handle.

Returns:

Resolved handle (DID).

Return type:

models.ComAtprotoIdentityResolveHandle.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async send_image(text: str | TextBuilder, image: bytes, image_alt: str, profile_identify: str | None = None, reply_to: ReplyRef | None = None, langs: List[str] | None = None, facets: List[Main] | None = None) CreateRecordResponse

Send post with attached image.

Note

If profile_identify is not provided will be sent to the current profile.

Parameters:
  • text – Text of the post.

  • image – Binary image to attach.

  • image_alt – Text version of the image.

  • profile_identify – Handle or DID. Where to send post.

  • reply_to – Root and parent of the post to reply to.

  • langs – List of used languages in the post.

  • facets – List of facets (rich text items).

Returns:

Reference to the created record.

Return type:

models.AppBskyFeedPost.CreateRecordResponse

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async send_images(text: str | TextBuilder, images: List[bytes], image_alts: List[str] | None = None, profile_identify: str | None = None, reply_to: ReplyRef | None = None, langs: List[str] | None = None, facets: List[Main] | None = None) CreateRecordResponse

Send post with multiple attached images (up to 4 images).

Note

If profile_identify is not provided will be sent to the current profile.

Parameters:
  • text – Text of the post.

  • images – List of binary images to attach. The length must be less than or equal to 4.

  • image_alts – List of text version of the images. The length should be shorter than or equal to the length of images.

  • profile_identify – Handle or DID. Where to send post.

  • reply_to – Root and parent of the post to reply to.

  • langs – List of used languages in the post.

  • facets – List of facets (rich text items).

Returns:

Reference to the created record.

Return type:

models.AppBskyFeedPost.CreateRecordResponse

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async send_post(text: str | TextBuilder, profile_identify: str | None = None, reply_to: ReplyRef | None = None, embed: Main | Main | Main | Main | None = None, langs: List[str] | None = None, facets: List[Main] | None = None) CreateRecordResponse

Send post.

Note

If profile_identify is not provided will be sent to the current profile.

The async default language is en. Available languages are async defined in atproto.xrpc_client.models.languages.

Parameters:
  • text – Text of the post.

  • profile_identify – Handle or DID. Where to send post.

  • reply_to – Root and parent of the post to reply to.

  • embed – Embed models that should be attached to the post.

  • langs – List of used languages in the post.

  • facets – List of facets (rich text items).

Returns:

Reference to the created record.

Return type:

models.AppBskyFeedPost.CreateRecordResponse

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async unfollow(follow_uri: str) bool

Unfollow the profile.

Parameters:

follow_uri – AT URI of the follow.

Returns:

Success status.

Return type:

bool

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async unlike(like_uri: str) bool

Unlike the post.

Parameters:

like_uri – AT URI of the like.

Returns:

Success status.

Return type:

bool

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async unmute(actor: str) bool

Unmute actor (profile).

Parameters:

actor – Actor (handle or DID).

Returns:

Success status.

Return type:

bool

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async unrepost(repost_uri: str) bool

Unrepost the post (delete repost).

Parameters:

repost_uri – AT URI of the repost.

Returns:

Success status.

Return type:

bool

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async unsend(post_uri: str) bool

Alias for delete_post

async update_handle(handle: str) bool

Update the handle.

Parameters:

handle – New handle.

Returns:

Success status.

Return type:

bool

Raises:

atproto.exceptions.AtProtocolError – Base exception.

async upload_blob(data: bytes) Response

Upload blob.

Parameters:

data – Binary data.

Returns:

Uploaded blob reference.

Return type:

models.ComAtprotoRepoUploadBlob.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

class atproto.AsyncDidInMemoryCache(*args: Any, **kwargs: Any)

Bases: AsyncDidBaseCache

async clear() None

Clear cached DIDs.

Note

This method is used to clear all cached DIDs.

async delete(did: str) None

Delete cached DID.

Parameters:

did – DID.

async get(did: str) CachedDidResult | None

Get cached DID.

Parameters:

did – DID.

Returns:

Cached DID result or None if not found.

Return type:

CachedDidResult

async refresh(did: str, get_doc_callback: AsyncGetDocCallback) None

Refresh cached DID.

Parameters:
  • did – DID.

  • get_doc_callback – Get DID document callback.

async set(did: str, document: DidDocument) None

Set cached DID.

Parameters:
  • did – DID.

  • document – DID document.

class atproto.AsyncFirehoseSubscribeLabelsClient(params: dict | Params | None = None, base_uri: str | None = 'wss://mod.bsky.app/xrpc')

Bases: _AsyncWebsocketClient

Async firehose subscribe labels client.

Parameters:
  • params – Parameters model.

  • base_uri – Base websocket URI. Example: wss://bsky.social/xrpc.

class atproto.AsyncFirehoseSubscribeReposClient(params: dict | Params | None = None, base_uri: str | None = 'wss://bsky.network/xrpc')

Bases: _AsyncWebsocketClient

Async firehose subscribe repos client.

Parameters:
  • params – Parameters model.

  • base_uri – Base websocket URI. Example: wss://bsky.social/xrpc.

class atproto.AsyncIdResolver(plc_url: str | None = None, timeout: float | None = None, cache: AsyncDidBaseCache | None = None, backup_nameservers: List[str] | None = None)

Bases: object

Asynchronous Identity Resolver.

This resolver is used to resolve identities. DID and Handle identifies are supported.

Note

Default PLC directory URL is https://plc.directory. Default request timeout is 3 seconds.

Parameters:
  • plc_url – PLC directory URL.

  • timeout – Request timeout.

  • cache – DID cache.

property did: AsyncDidResolver

DID Resolver.

This resolver is used to resolve DIDs. PLC and Web DID methods are supported.

property handle: AsyncHandleResolver

Handle Resolver.

This resolver is used to resolve handles.

class atproto.AtUri(host: str, pathname: str, hash_: str, search_params: List[Tuple[str, Any]])

Bases: object

ATP URI Scheme.

Examples

Repository: at://alice.host.com

Repository: at://did:plc:bv6ggog3tya2z3vxsub7hnal

Collection: at://alice.host.com/io.example.song

Record: at://alice.host.com/io.example.song/3yI5-c1z-cc2p-1a

Record Field: at://alice.host.com/io.example.song/3yI5-c1z-cc2p-1a#/title

property collection: str

Get collection name.

classmethod from_str(uri: str) AtUri

Create AtUri instance from URI.

property hostname: str

Get hostname.

property http: str

Convert instance to HTTP URI.

property origin: str

Get origin.

property protocol: str

Get protocol.

property rkey: str

Get record key (rkey).

class atproto.AtprotoData(did: str, signing_key: str | None = None, handle: str | None = None, pds: str | None = None)

Bases: object

Dataclass for atproto data.

did: str
classmethod from_did_doc(did_doc: DidDocument) AtprotoData

Create AT Protocol data from DID document.

Parameters:

did_doc – DID document.

Returns:

AT Protocol data.

Return type:

AtprotoData

handle: str | None = None
pds: str | None = None
signing_key: str | None = None
class atproto.CAR(root: CID, blocks: Dict[CID, dict])

Bases: object

CAR file.

property blocks: Dict[CID, dict]

Get blocks.

classmethod from_bytes(data: bytes) CAR

Decode CAR file.

Note

You could pass as data response of client.com.atproto.sync.get_repo, for example. And other responses of methods in the sync namespace.

Example

>>> from atproto import CAR, Client
>>> client = Client()
>>> client.login('my-handle', 'my-password')
>>> repo = client.com.atproto.sync.get_repo({'did': client.me.did})
>>> car_file = CAR.from_bytes(repo)
>>> print(car_file.root)
>>> print(car_file.blocks)
Parameters:

data – Content of the CAR file.

Returns:

Parsed CAR file.

Return type:

atproto.CAR

property root: CID

Get root.

class atproto.CID(_cid: str, version: int, codec: int, hash: atproto_core.cid.cid.Multihash)

Bases: object

codec: int
classmethod decode(value: str) CID
encode() str
hash: Multihash
version: int
class atproto.Client(base_url: str | None = None, *args: Any, **kwargs: Any)

Bases: SessionDispatchMixin, SessionMethodsMixin, TimeMethodsMixin, HeadersConfigurationMethodsMixin, ClientRaw

High-level client for XRPC of ATProto.

clone() Self

Clone the client instance.

Used to customize atproto proxy and set of labeler services.

Returns:

Cloned client instance.

delete_follow(follow_uri: str) bool

Alias for unfollow

delete_like(like_uri: str) bool

Alias for unlike

delete_post(post_uri: str) bool

Delete post.

Parameters:

post_uri – AT URI of the post.

Returns:

Success status.

Return type:

bool

Raises:

atproto.exceptions.AtProtocolError – Base exception.

delete_repost(repost_uri: str) bool

Alias for unrepost

follow(subject: str) CreateRecordResponse

Follow the profile.

Parameters:

subject – DID of the profile.

Returns:

Reference to the created record.

Return type:

models.AppBskyGraphFollow.CreateRecordResponse

Raises:

atproto.exceptions.AtProtocolError – Base exception.

get_author_feed(actor: str, cursor: str | None = None, filter: str | None = None, limit: int | None = None) Response

Get author (profile) feed.

Parameters:
  • actor – Actor (handle or DID).

  • cursor – Cursor of the last like in the previous page.

  • filter – Filter.

  • limit – Limit count of likes to return.

Returns:

Feed.

Return type:

models.AppBskyFeedGetAuthorFeed.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

get_followers(actor: str, cursor: str | None = None, limit: int | None = None) Response

Get followers of the profile.

Parameters:
  • actor – Actor (handle or DID).

  • cursor – Cursor of the next page.

  • limit – Limit count of followers to return.

Returns:

Followers.

Return type:

models.AppBskyGraphGetFollowers.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

get_follows(actor: str, cursor: str | None = None, limit: int | None = None) Response

Get follows of the profile.

Parameters:
  • actor – Actor (handle or DID).

  • cursor – Cursor of the next page.

  • limit – Limit count of follows to return.

Returns:

Follows.

Return type:

models.AppBskyGraphGetFollows.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

get_likes(uri: str, cid: str | None = None, cursor: str | None = None, limit: int | None = None) Response

Get likes.

Parameters:
  • uri – AT URI.

  • cid – CID.

  • cursor – Cursor of the last like in the previous page.

  • limit – Limit count of likes to return.

Returns:

Likes.

Return type:

models.AppBskyFeedGetLikes.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

get_post(post_rkey: str, profile_identify: str | None = None, cid: str | None = None) GetRecordResponse

Get post.

Parameters:
  • post_rkey – ID (slug) of the post.

  • profile_identify – Handler or DID. Who created the post.

  • cid – The CID of the version of the post.

Returns:

Post.

Return type:

models.AppBskyFeedPost.GetRecordResponse

Raises:

atproto.exceptions.AtProtocolError – Base exception.

get_post_thread(uri: str, depth: int | None = None, parent_height: int | None = None) Response

Get post thread.

Parameters:
  • uri – AT URI.

  • depth – Depth of the thread.

  • parent_height – Height of the parent post.

Returns:

Post thread.

Return type:

models.AppBskyFeedGetPostThread.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

get_posts(uris: List[str]) Response

Get posts.

Parameters:

uris – Uris (AT URI).

Example

client.get_posts(['at://did:plc:kvwvcn5iqfooopmyzvb4qzba/app.bsky.feed.post/3k2yihcrp6f2c'])
Returns:

Posts.

Return type:

models.AppBskyFeedGetPosts.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

get_profile(actor: str) ProfileViewDetailed

Get profile.

Parameters:

actor – Actor (handle or DID).

Returns:

Profile.

Return type:

models.AppBskyActorDefs.ProfileViewDetailed

Raises:

atproto.exceptions.AtProtocolError – Base exception.

get_profiles(actors: List[str]) Response

Get profiles.

Parameters:

actors – List of actors (handles or DIDs).

Returns:

Profiles.

Return type:

models.AppBskyActorGetProfiles.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

get_reposted_by(uri: str, cid: str | None = None, cursor: str | None = None, limit: int | None = None) Response

Get reposted by (reposts).

Parameters:
  • uri – AT URI.

  • cid – CID.

  • cursor – Cursor of the last like in the previous page.

  • limit – Limit count of likes to return.

Returns:

Reposts.

Return type:

models.AppBskyFeedGetRepostedBy.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

get_timeline(algorithm: str | None = None, cursor: str | None = None, limit: int | None = None) Response

Get home timeline.

Parameters:
  • algorithm – Algorithm.

  • cursor – Cursor of the last like in the previous page.

  • limit – Limit count of likes to return.

Returns:

Home timeline.

Return type:

models.AppBskyFeedGetTimeline.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

like(uri: str, cid: str) CreateRecordResponse

Like the record.

Parameters:
  • cid – The CID of the record.

  • uri – The URI of the record.

Note

Record could be post, custom feed, etc.

Returns:

Reference to the created record.

Return type:

models.AppBskyFeedLike.CreateRecordResponse

Raises:

atproto.exceptions.AtProtocolError – Base exception.

login(login: str | None = None, password: str | None = None, session_string: str | None = None) ProfileViewDetailed

Authorize a client and get profile info.

Parameters:
  • login – Handle/username of the account.

  • password – Main or app-specific password of the account.

  • session_string – Session string (use export_session_string to get it).

Note

Either session_string or login and password should be provided.

Returns:

Profile information.

Return type:

models.AppBskyActorDefs.ProfileViewDetailed

Raises:

atproto.exceptions.AtProtocolError – Base exception.

mute(actor: str) bool

Mute actor (profile).

Parameters:

actor – Actor (handle or DID).

Returns:

Success status.

Return type:

bool

Raises:

atproto.exceptions.AtProtocolError – Base exception.

post(text: str | TextBuilder, profile_identify: str | None = None, reply_to: ReplyRef | None = None, embed: Main | Main | Main | Main | None = None, langs: List[str] | None = None, facets: List[Main] | None = None) CreateRecordResponse

Alias for send_post

repost(uri: str, cid: str) CreateRecordResponse

Repost post.

Parameters:
  • cid – The CID of the post.

  • uri – The URI of the post.

Returns:

Reference to the reposted record.

Return type:

models.AppBskyFeedRepost.CreateRecordResponse

Raises:

atproto.exceptions.AtProtocolError – Base exception.

resolve_handle(handle: str) Response

Resolve the handle.

Parameters:

handle – Handle.

Returns:

Resolved handle (DID).

Return type:

models.ComAtprotoIdentityResolveHandle.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

send_image(text: str | TextBuilder, image: bytes, image_alt: str, profile_identify: str | None = None, reply_to: ReplyRef | None = None, langs: List[str] | None = None, facets: List[Main] | None = None) CreateRecordResponse

Send post with attached image.

Note

If profile_identify is not provided will be sent to the current profile.

Parameters:
  • text – Text of the post.

  • image – Binary image to attach.

  • image_alt – Text version of the image.

  • profile_identify – Handle or DID. Where to send post.

  • reply_to – Root and parent of the post to reply to.

  • langs – List of used languages in the post.

  • facets – List of facets (rich text items).

Returns:

Reference to the created record.

Return type:

models.AppBskyFeedPost.CreateRecordResponse

Raises:

atproto.exceptions.AtProtocolError – Base exception.

send_images(text: str | TextBuilder, images: List[bytes], image_alts: List[str] | None = None, profile_identify: str | None = None, reply_to: ReplyRef | None = None, langs: List[str] | None = None, facets: List[Main] | None = None) CreateRecordResponse

Send post with multiple attached images (up to 4 images).

Note

If profile_identify is not provided will be sent to the current profile.

Parameters:
  • text – Text of the post.

  • images – List of binary images to attach. The length must be less than or equal to 4.

  • image_alts – List of text version of the images. The length should be shorter than or equal to the length of images.

  • profile_identify – Handle or DID. Where to send post.

  • reply_to – Root and parent of the post to reply to.

  • langs – List of used languages in the post.

  • facets – List of facets (rich text items).

Returns:

Reference to the created record.

Return type:

models.AppBskyFeedPost.CreateRecordResponse

Raises:

atproto.exceptions.AtProtocolError – Base exception.

send_post(text: str | TextBuilder, profile_identify: str | None = None, reply_to: ReplyRef | None = None, embed: Main | Main | Main | Main | None = None, langs: List[str] | None = None, facets: List[Main] | None = None) CreateRecordResponse

Send post.

Note

If profile_identify is not provided will be sent to the current profile.

The default language is en. Available languages are defined in atproto.xrpc_client.models.languages.

Parameters:
  • text – Text of the post.

  • profile_identify – Handle or DID. Where to send post.

  • reply_to – Root and parent of the post to reply to.

  • embed – Embed models that should be attached to the post.

  • langs – List of used languages in the post.

  • facets – List of facets (rich text items).

Returns:

Reference to the created record.

Return type:

models.AppBskyFeedPost.CreateRecordResponse

Raises:

atproto.exceptions.AtProtocolError – Base exception.

unfollow(follow_uri: str) bool

Unfollow the profile.

Parameters:

follow_uri – AT URI of the follow.

Returns:

Success status.

Return type:

bool

Raises:

atproto.exceptions.AtProtocolError – Base exception.

unlike(like_uri: str) bool

Unlike the post.

Parameters:

like_uri – AT URI of the like.

Returns:

Success status.

Return type:

bool

Raises:

atproto.exceptions.AtProtocolError – Base exception.

unmute(actor: str) bool

Unmute actor (profile).

Parameters:

actor – Actor (handle or DID).

Returns:

Success status.

Return type:

bool

Raises:

atproto.exceptions.AtProtocolError – Base exception.

unrepost(repost_uri: str) bool

Unrepost the post (delete repost).

Parameters:

repost_uri – AT URI of the repost.

Returns:

Success status.

Return type:

bool

Raises:

atproto.exceptions.AtProtocolError – Base exception.

unsend(post_uri: str) bool

Alias for delete_post

update_handle(handle: str) bool

Update the handle.

Parameters:

handle – New handle.

Returns:

Success status.

Return type:

bool

Raises:

atproto.exceptions.AtProtocolError – Base exception.

upload_blob(data: bytes) Response

Upload blob.

Parameters:

data – Binary data.

Returns:

Uploaded blob reference.

Return type:

models.ComAtprotoRepoUploadBlob.Response

Raises:

atproto.exceptions.AtProtocolError – Base exception.

class atproto.DidDocument

Bases: BaseModel

DID document.

field also_known_as: List[str] | None = None
field id: str [Required]
field service: List[Service] | None = None
field verification_method: List[VerificationMethod] | None = None
classmethod from_dict(did_doc: Dict[str, Any] | Any) DidDocument

Parse a DID document.

Parameters:

did_doc – The raw DID document.

Returns:

The parsed DID document.

Return type:

DidDocument

get_did() str

Return the DID of the given DID document.

Returns:

The DID of the given DID document.

Return type:

str

get_did_key() str | None

Return the DID key of the given DID document.

Returns:

The DID key of the given DID document, or None if not found.

Return type:

str

get_feed_gen_endpoint() str | None

Return the feed generator endpoint of the given DID document.

Returns:

The feed generator endpoint of the given DID document, or None if not found.

Return type:

str

get_handle() str | None

Return the handle of the given DID document.

Returns:

The handle of the given DID document, or None if not found.

Return type:

str

get_notif_endpoint() str | None

Return the notification endpoint of the given DID document.

Returns:

The notification endpoint of the given DID document, or None if not found.

Return type:

str

get_pds_endpoint() str | None

Return the personal data server endpoint of the given DID document.

Returns:

The personal data server endpoint of the given DID document, or None if not found.

Return type:

str

get_service_endpoint(id_: str, type_: str) str | None

Return the service endpoint of the given DID document.

Parameters:
  • id – The service ID.

  • type – The service type.

Returns:

The service endpoint of the given DID document, or None if not found.

Return type:

str

get_signing_key() SigningKey | None

Return the signing key of the given DID document.

Returns:

The signing key of the given DID document, or None if not found.

Return type:

SigningKey

to_atproto_data() AtprotoData

Return the AtprotoData of the given DID document.

Returns:

The AtprotoData of the given DID document.

Return type:

AtprotoData

class atproto.DidInMemoryCache(*args: Any, **kwargs: Any)

Bases: DidBaseCache

clear() None

Clear cached DIDs.

Note

This method is used to clear all cached DIDs.

delete(did: str) None

Delete cached DID.

Parameters:

did – DID.

get(did: str) CachedDidResult | None

Get cached DID.

Parameters:

did – DID.

Returns:

Cached DID result or None if not found.

Return type:

CachedDidResult

refresh(did: str, get_doc_callback: GetDocCallback) None

Refresh cached DID.

Parameters:
  • did – DID.

  • get_doc_callback – Get DID document callback.

set(did: str, document: DidDocument) None

Set cached DID.

Parameters:
  • did – DID.

  • document – DID document.

class atproto.FirehoseSubscribeLabelsClient(params: dict | Params | None = None, base_uri: str | None = 'wss://mod.bsky.app/xrpc')

Bases: _WebsocketClient

Firehose subscribe labels client.

Parameters:
  • params – Parameters model.

  • base_uri – Base websocket URI. Example: wss://bsky.social/xrpc.

class atproto.FirehoseSubscribeReposClient(params: dict | Params | None = None, base_uri: str | None = 'wss://bsky.network/xrpc')

Bases: _WebsocketClient

Firehose subscribe repos client.

Parameters:
  • params – Parameters model.

  • base_uri – Base websocket URI. Example: wss://bsky.social/xrpc.

class atproto.IdResolver(plc_url: str | None = None, timeout: float | None = None, cache: DidBaseCache | None = None, backup_nameservers: List[str] | None = None)

Bases: object

Identity Resolver.

This resolver is used to resolve identities. DID and Handle identifies are supported.

Note

Default PLC directory URL is https://plc.directory. Default request timeout is 3 seconds.

Parameters:
  • plc_url – PLC directory URL.

  • timeout – Request timeout.

  • cache – DID cache.

property did: DidResolver

DID Resolver.

This resolver is used to resolve DIDs. PLC and Web DID methods are supported.

property handle: HandleResolver

Handle Resolver.

This resolver is used to resolve handles.

class atproto.JwtPayload

Bases: BaseModel

The payload of the JWT.

Based on https://www.rfc-editor.org/rfc/rfc7519#section-4.1

field aud: str | List[str] | None = None

Audience (DID).

field exp: int | None = None

Expiration Time.

field iat: int | None = None

Issued At.

field iss: str | None = None

Issuer (DID).

field jti: str | None = None

JWT ID. Presented in Refresh Token.

field nbf: int | None = None

Not Before. Not used by ATProto.

field scope: str | None = None

Scope. ATProto specific.

field sub: str | None = None

Subject (DID).

class atproto.Multikey(jwt_alg: str, key_bytes: bytes)

Bases: object

static from_str(multikey: str) Multikey

Create multikey from string.

Parameters:

multikey – Multikey.

Returns:

Multikey.

Return type:

Multikey

jwt_alg: str
key_bytes: bytes
to_str() str

Format multikey.

Returns:

Multikey.

Return type:

str

class atproto.NSID(segments: ~typing.List[str] = <factory>)

Bases: object

NameSpaced IDs (NSIDs).

Examples

com.example.status

io.social.getFeed

net.users.bob.ping

property authority: str

Get authority of NSID.

com.example.thing ^^^^^^^^^^^——–> example.com

delim joined self.segments[:-1][::-1]

classmethod from_str(nsid: str) NSID

Create NSID instance from string.

property name: str

Get name.

segments: List[str]
class atproto.Session(handle: str, did: str, access_jwt: str, refresh_jwt: str, pds_endpoint: str | NoneType = 'https://bsky.social')

Bases: object

access_jwt: str
copy() Session
classmethod decode(session_string: str) Session
did: str
encode() str
export() str

Alias for encode

handle: str
pds_endpoint: str | None = 'https://bsky.social'
refresh_jwt: str
class atproto.SessionEvent(value)

Bases: Enum

An enumeration.

CREATE = 'creat'
IMPORT = 'import'
REFRESH = 'refresh'
atproto.bytes_to_multibase(encoding: str, data: bytes) str

Encode multibase.

Parameters:
  • encoding – Encoding (the character from the table).

  • data – Data.

Returns:

Multibase encoded data.

Return type:

str

atproto.decode_jwt_payload(payload: str | bytes) JwtPayload

Decode the given JWT payload.

Parameters:

payload – The JWT payload to decode.

Returns:

The decoded payload of the given JWT.

Return type:

JwtPayload

atproto.get_did_key(key_type: str, key: str) str | None

Get DID key.

Parameters:
  • key_type – Key type.

  • key – Key.

Returns:

DID key or None if a key type is not supported.

Return type:

str

atproto.get_jwt_payload(jwt: str) JwtPayload

Return the payload of the given JWT.

Parameters:

jwt – The JWT to get the payload from.

Returns:

The payload of the given JWT.

Return type:

JwtPayload

atproto.multibase_to_bytes(data: str) bytes

Decode multibase.

Parameters:

data – Multibase encoded data.

Returns:

Decoded data.

Return type:

bytes

atproto.parse_jwt(jwt: str | bytes) Tuple[bytes, bytes, Dict[str, Any], bytes]

Parse the given JWT.

Parameters:

jwt – The JWT to parse.

Returns:

The parsed JWT: payload, signing input, header, signature.

Return type:

tuple of bytes, bytes, dict, bytes

atproto.parse_subscribe_labels_message(message: MessageFrame) Labels | Info

Parse Firehose labels message to the corresponding model.

Parameters:

message – Message frame.

Returns:

Corresponding message model.

Return type:

SubscribeLabelsMessage

atproto.parse_subscribe_repos_message(message: MessageFrame) Commit | Handle | Migrate | Tombstone | Info | Identity

Parse Firehose repositories message to the corresponding model.

Note

Use decode_inner_cbor only when required to increase performance.

Parameters:

message – Message frame.

Returns:

Corresponding message model.

Return type:

SubscribeReposMessage

atproto.validate_jwt_payload(payload: JwtPayload, leeway: int = 0) None

Validate the given JWT payload.

Parameters:
  • payload – The JWT payload to validate.

  • leeway – The leeway in seconds to accept when verifying time claims (exp, iat).

Returns:

The payload is valid.

Return type:

None

Raises:
atproto.verify_jwt(jwt: str, get_signing_key_callback: Callable[[str, bool], str], own_did: str | None = None) JwtPayload

Verify the given JWT.

Parameters:
  • jwt – The JWT to verify.

  • get_signing_key_callback – The callback to get the signing key.

  • own_did – The DID of the service (aud).

Returns:

The payload of the given JWT.

Return type:

JwtPayload

Raises:
async atproto.verify_jwt_async(jwt: str, get_signing_key_callback: Callable[[str, bool], Coroutine[Any, Any, str]], own_did: str | None = None) JwtPayload

Asynchronously verifies the given JWT.

Parameters:
  • jwt – The JWT to verify.

  • get_signing_key_callback – The callback to get the signing key.

  • own_did – The DID of the service (aud).

Returns:

The payload of the given JWT.

Return type:

JwtPayload

Raises:
atproto.verify_signature(did_key: str, signing_input: bytes, signature: bytes) bool

Verify signature.

Parameters:
  • did_key – DID key.

  • signing_input – Signing input (data).

  • signature – Signature.

Returns:

True if signature is valid, False otherwise.

Return type:

bool

Submodules