lexrpc package

Reference documentation.

client

XRPC client implementation.

TODO:

  • asyncio support for subscription websockets

class Client(address='https://bsky.social/', access_token=None, refresh_token=None, headers=None, session_callback=None, auth=None, **kwargs)[source]

Bases: Base

XRPC client.

Calling com.atproto.server.createSession will store the returned session and include its acccess token in subsequent requests. If a request fails with ExpiredToken and we have a session stored, the access token will be refreshed with com.atproto.server.refreshSession and then the original request will be retried.

address

base URL of XRPC server, eg https://bsky.social/

Type:

str

session

createSession response with accessJwt, refreshJwt`, handle, and did

Type:

dict

headers

HTTP headers to include in every request

Type:

dict

auth

optional, used to authenticate requests

Type:

AuthBase

call(nsid, input=None, headers={}, decode=True, **params)[source]

Makes a remote XRPC method call.

Parameters:

  • nsid (str) – method NSID

  • input (dict or bytes) – input body, optional for subscriptions

  • headers (dict) – HTTP headers to include in this request. Overrides any headers passed to the constructor.

  • decode (bool) – if this is a subscription, decode header and payload before returning, otherwise return raw bytes

  • params – optional method parameters

Returns:

for queries and procedures, decoded JSON object, or None if the method has no output. For subscriptions, generator of messages from server, as (dict header, dict payload) tuple if decode is True, bytes otherwise.

Return type:

dict or generator iterator

Raises:

  • NotImplementedError – if the given NSID is not found in any of the loaded lexicons

  • ValidationError – if the parameters, input, or returned output don’t validate against the method’s schemas

  • RequestException – if the connection or HTTP request to the remote server failed

server

XRPC server implementation.

exception Redirect(to, status=302, headers=None)[source]

Bases: Exception

Raised by XRPC handlers to direct the server to serve an HTTP redirect.

Whether this is official supported by the XRPC spec is still TBD: https://github.com/bluesky-social/atproto/discussions/1228

to

URL to redirect to

Type:

str

status

HTTP status code, defaults to 302

Type:

int

class Server(**kwargs)[source]

Bases: Base

XRPC server base class. Subclass to implement specific methods.

method(nsid)[source]

XRPC method decorator. Use on each function that implements a method.

Parameters:

nsid (str)

register(nsid, fn)[source]

Registers an XRPC method decorator. Alternative to method().

Parameters:

  • nsid (str)

  • fn (callable)

call(nsid, input=None, **params)[source]

Calls an XRPC query or procedure method.

For subscriptions, returns a generator that yields (header dict, payload dict) tuples to be DAG-CBOR encoded and sent to the websocket client.

Parameters:

  • nsid (str) – method NSID

  • input (dict or bytes) – input body, optional for subscriptions

  • params – optional parameters

Returns:

output

Return type:

dict

Raises:

  • NotImplementedError – if the given NSID is not implemented or found in any of the loaded lexicons

  • ValidationError – if the parameters, input, or returned output don’t validate against the method’s schemas

flask_server

Flask handler for /xrpc/... endpoints.

class Subscriber(ip, user_agent, args, start)

Bases: tuple

init_flask(xrpc_server, app)[source]

Connects a lexrpc.Server to serve /xrpc/... on a Flask app.

Parameters:

  • xrpc_server (lexrpc.Server)

  • app (Flask)

class XrpcEndpoint(server)[source]

Bases: View

Handles inbound XRPC query and procedure (but not subscription) methods.

server
Type:

lexrpc.Server

subscription(xrpc_server, nsid)[source]

Generates websocket handlers for inbound XRPC subscription methods.

Note that this calls the XRPC method on a different thread, so that it can block on it there while still periodically checking in the request thread that the websocket client is still connected.

Parameters:

  • xrpc_server (lexrpc.Server)

  • nsid (str) – XRPC method NSID

base

Base code shared by both server and client.

exception XrpcError(message, name=None, **kwargs)[source]

Bases: ValueError

A named error in an XRPC call.

name is the error, eg RepoNotFound in com.atproto.sync.getRepo. message is the human-readable string error message.

exception ValidationError[source]

Bases: ValueError

Raised when an object or XRPC input or output doesn’t match its schema.

class Base(lexicons=None, validate=True, truncate=False)[source]

Bases: object

Base class for both XRPC client and server.

validate(nsid, type, obj)[source]

If configured to do so, validates a ATProto value against its lexicon.

Returns None if the object validates, otherwise raises an exception.

Does nothing if this object was initialized with validate=False.

Parameters:

  • nsid (str) – method NSID

  • type (str) – input, output, parameters, or record

  • obj (dict) – JSON object

Returns:

obj, either unchanged, or possible a modified copy if

truncate is enabled and a string value was too long

Return type:

dict

Raises:

  • NotImplementedError – if no lexicon exists for the given NSID, or the lexicon does not define a schema for the given type

  • ValidationError – if the object is invalid

static validate_mime_type(mime_type, accept, name='')[source]

Validates that a MIME type matches an accept range.

For validating blob types. Returns None if the accept is empty or mime_type matches, otherwise raises an exception.

https://atproto.com/specs/lexicon#field-type-definitions

Parameters:

  • mime_type (str)

  • accept (sequence of str) – blob accept field value, list of MIME type patterns, eg image/jpeg, image/*, or */*.

  • name – blob field name, only used in exception message

Raises:

ValidationError – if mime_type doesn’t match any pattern in accept

encode_params(params)[source]

Encodes decoded parameter values.

Based on https://atproto.com/specs/xrpc#lexicon-http-endpoints

Parameters:

params (dict) – maps str names to boolean, number, str, or list values

Returns:

URL-encoded query parameter string

Return type:

bytes

decode_params(method_nsid, params)[source]

Decodes encoded parameter values.

Based on https://atproto.com/specs/xrpc#lexicon-http-endpoints

Parameters:

  • method_nsid (str)

  • params (sequence of (str, str) tuple) – name/value mappings

Returns:

maps str names to decoded boolean, number, str, and array values

Return type:

dict

Raises: