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 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, include_pins: bool = False) → 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.
include_pins – Include pins.

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, auth_factor_token: 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).
auth_factor_token – Auth factor token (for Email 2FA).

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 | 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.

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).
image_aspect_ratio – Aspect ratio of the image.

Returns:

Reference to the created record.

Return type:

models.AppBskyFeedPost.CreateRecordResponse

Raises:

atproto.exceptions.AtProtocolError – Base exception.

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).
image_aspect_ratios – List of aspect ratios of the images. The length should be shorter than or equal to the length of images.

Returns:

Reference to the created record.

Return type:

models.AppBskyFeedPost.CreateRecordResponse

Raises:

atproto.exceptions.AtProtocolError – Base exception.

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.

Send post with attached video.

Note

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

Parameters:

text – Text of the post.
video – Binary video to attach.
video_alt – Text version of the video.
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).
video_aspect_ratio – Aspect ratio of the video.

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', recv_timeout: float | None = 300.0)¶

Bases: _AsyncWebsocketClient

Async firehose subscribe labels client.

Parameters:

params – Parameters model.
base_uri – Base websocket URI. Example: wss://bsky.social/xrpc.
recv_timeout – Reconnect to the server after this many seconds of inactivity. Default is 300 seconds (5 minutes).

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

Bases: _AsyncWebsocketClient

Async firehose subscribe repos client.

Parameters:

params – Parameters model.
base_uri – Base websocket URI. Example: wss://bsky.social/xrpc.
recv_timeout – Reconnect to the server after this many seconds of inactivity. Default is 30 seconds.

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.AsyncRequest(**kwargs: Any)¶

Bases: RequestBase

Class for handling requests errors and working with httpx.

Parameters:: **kwargs – Additional parameters for httpx.AsyncClient.

async close() → None¶

async get(*args: Any, **kwargs: Any) → Response¶

async post(*args: Any, **kwargs: Any) → Response¶

class atproto.AtUri(host: str, pathname: str = '', hash_: str = '', search_params: List[Tuple[str, Any]] | None = None)¶

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_relative_str(base: str, uri: str) → AtUri¶: Create AtUri instance from relative URI.

classmethod from_str(uri: str) → AtUri¶: Create AtUri instance from URI.

property hostname: str¶: Get hostname.

property http: str¶: Convert instance to HTTP URI.

classmethod make(handle_or_did: str, collection: str | None = None, rkey: str | None = None) → AtUri¶: Create AtUri instance from handle or DID.

property origin: str¶: Get origin.

property protocol: str¶: Get protocol.

property rkey: str¶: Get record key (rkey).

property search: str¶: Get search params.

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(version: int, codec: int, hash: atproto_core.cid.cid.Multihash, _stringified_form: str | NoneType = None, _raw_byte_form: str | NoneType = None)¶

Bases: object

codec: int¶

classmethod decode(value: str | bytes) → 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.

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, include_pins: bool = False) → 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.
include_pins – Include pins.

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, auth_factor_token: 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).
auth_factor_token – Auth factor token (for Email 2FA).

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 | 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 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).
image_aspect_ratio – Aspect ratio of the image.

Returns:

Reference to the created record.

Return type:

models.AppBskyFeedPost.CreateRecordResponse

Raises:

atproto.exceptions.AtProtocolError – Base exception.

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).
image_aspect_ratios – List of aspect ratios of the images. The length should be shorter than or equal to the length of images.

Returns:

Reference to the created record.

Return type:

models.AppBskyFeedPost.CreateRecordResponse

Raises:

atproto.exceptions.AtProtocolError – Base exception.

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.

Send post with attached video.

Note

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

Parameters:

text – Text of the post.
video – Binary video to attach.
video_alt – Text version of the video.
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).
video_aspect_ratio – Aspect ratio of the video.

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', recv_timeout: float | None = 300.0)¶

Bases: _WebsocketClient

Firehose subscribe labels client.

Parameters:

params – Parameters model.
base_uri – Base websocket URI. Example: wss://bsky.social/xrpc.
recv_timeout – Reconnect to the server after this many seconds of inactivity. Default is 300 seconds (5 minutes).

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

Bases: _WebsocketClient

Firehose subscribe repos client.

Parameters:

params – Parameters model.
base_uri – Base websocket URI. Example: wss://bsky.social/xrpc.
recv_timeout – Reconnect to the server after this many seconds of inactivity. Default is 30 seconds.

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.Request(**kwargs: Any)¶

Bases: RequestBase

Class for handling requests errors and working with httpx.

Parameters:: **kwargs – Additional parameters for httpx.Client.

close() → None¶

get(*args: Any, **kwargs: Any) → Response¶

post(*args: Any, **kwargs: Any) → Response¶

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¶

property access_jwt_payload: JwtPayload¶

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¶

property refresh_jwt_payload: JwtPayload¶

class atproto.SessionEvent(value)¶

Bases: Enum

An enumeration.

CREATE = 'create'¶

IMPORT = 'import'¶

REFRESH = 'refresh'¶

atproto.bytes_to_multibase(encoding: str, data: bytes) → str¶

Encode multibase.

Note

Multibase table is available here: https://github.com/multiformats/multibase/blob/master/multibase.csv

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 | Info | Identity | Account | Sync¶

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:

TokenDecodeError – If the given JWT is invalid.
TokenExpiredSignatureError – If the given JWT is expired.
TokenImmatureSignatureError – If the given JWT is immature.
TokenInvalidIssuedAtError – If the given JWT has invalid issued at.

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:

TokenDecodeError – If the given JWT is invalid.
TokenExpiredSignatureError – If the given JWT is expired.
TokenImmatureSignatureError – If the given JWT is immature.
TokenInvalidAudienceError – If the given JWT has invalid audience.
TokenInvalidIssuedAtError – If the given JWT has invalid issued at.
TokenInvalidSignatureError – If the given JWT has invalid signature.

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:

TokenDecodeError – If the given JWT is invalid.
TokenExpiredSignatureError – If the given JWT is expired.
TokenImmatureSignatureError – If the given JWT is immature.
TokenInvalidAudienceError – If the given JWT has invalid audience.
TokenInvalidIssuedAtError – If the given JWT has invalid issued at.
TokenInvalidSignatureError – If the given JWT has invalid signature.

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¶

atproto.exceptions