lexrpc package

Reference documentation.

client

XRPC client implementation.

TODO:

• asyncio support for subscription websockets

class Client(address=None, access_token=None, refresh_token=None, session_callback=None, lexicons=None, validate=True, truncate=False, **requests_kwargs)

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

requests_kwargs

passed to requests.get()/requests.post()

Type:

dict

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

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 with JSON output, decoded JSON object or None if the method has no output. For non-JSON output, the full requests.Response object. For subscriptions, generator of messages from server, as (dict header, dict payload) tuple if decode is True, bytes otherwise.

Return type:

dict, Response, 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)

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)

Bases: Base

XRPC server base class. Subclass to implement specific methods.

method(nsid)

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

Parameters:

nsid (str)

register(nsid, fn)

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

Parameters:

• nsid (str)

• fn (callable)

call(nsid, input=None, **params)

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, limit_ips=False)

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

Parameters:

• xrpc_server (lexrpc.Server)

• app (Flask)

• limit_ips (bool) – whether to only allow one connection to event stream subscription methods per client IP. Defaults to False.

class XrpcEndpoint(server)

Bases: View

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

server

Type:

lexrpc.Server

subscription(xrpc_server, nsid, limit_ips=False)

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

• limit_ips (bool) – whether to only allow one connection to event stream subscription methods per client IP. Defaults to False.

base

Base code shared by both server and client.

exception XrpcError(message, name=None, **kwargs)

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

Bases: ValueError

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

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

Bases: object

Base class for both XRPC client and server.

validate(nsid, type, obj)

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='')

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)

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)

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:

• ValueError – if a parameter value can’t be decoded

• NotImplementedError – if no method lexicon is registered for the given NSID