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:

jsonschema.SchemaError – if any schema is invalid

call(nsid, input=None, headers={}, **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.

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

Return type:

dict or generator iterator

Raises:

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

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

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

server

XRPC server implementation.

exception lexrpc.server.Redirect(to)[source]

Bases: Exception

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

Uses the HTTP 302 status code.

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

__init__(to)[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:

jsonschema.SchemaError – 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

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

flask_server

Flask handler for /xrpc/... endpoints.

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]
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:

jsonschema.SchemaError – if any schema is invalid

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: