lexrpc package

Reference documentation.

client

XRPC client implementation.

TODO:

  • asyncio support for subscription websockets

class lexrpc.client.Client(address='https://bsky.social/', access_token=None, refresh_token=None, headers=None, session_callback=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

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

Constructor.

Parameters:

  • address (str) – base URL of XRPC server, eg https://bsky.social/

  • access_token (str) – optional, will be sent in Authorization header

  • refresh_token (str) – optional; used to refresh access token

  • headers (dict) – optional, HTTP headers to include in every request

  • session_callback (callable, dict => None) – called when a new session is created with new access and refresh tokens. This callable is passed one positional argument, the dict JSON output from com.atproto.server.createSession or com.atproto.server.refreshSession.

  • kwargs – passed through to Base

Raises:

ValidationError – if any schema is invalid

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:

server

XRPC server implementation.

exception lexrpc.server.Redirect(to, status=302)[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

__init__(to, status=302)[source]
class lexrpc.server.Server(**kwargs)[source]

Bases: Base

XRPC server base class. Subclass to implement specific methods.

__init__(**kwargs)[source]

Constructor.

Parameters:

kwargs – passed through to Base

Raises:

ValidationError – if any schema is invalid

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 lexrpc.flask_server.Subscriber(ip, user_agent, args, start)

Bases: tuple

lexrpc.flask_server.init_flask(xrpc_server, app)[source]

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

Parameters:
class lexrpc.flask_server.XrpcEndpoint(server)[source]

Bases: View

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

server
Type:

lexrpc.Server

__init__(server)[source]
dispatch_request(nsid)[source]

The actual view function behavior. Subclasses must override this and return a valid response. Any variables from the URL rule are passed as keyword arguments.

lexrpc.flask_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 lexrpc.base.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.

__init__(message, name=None, **kwargs)[source]
exception lexrpc.base.ValidationError[source]

Bases: ValueError

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

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

Bases: object

Base class for both XRPC client and server.

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

Constructor.

Parameters:

  • lexicons (sequence of dict) – lexicons, optional. If not provided, defaults to the official, built in com.atproto and app.bsky lexicons.

  • validate (bool) – whether to validate schemas, parameters, and input and output bodies

  • truncate (bool) – whether to truncate string values that are longer than their maxGraphemes or maxLength in their lexicon

Raises:

ValidationError – if any schema is invalid

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: