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 withExpiredToken
and we have a session stored, the access token will be refreshed withcom.atproto.server.refreshSession
and then the original request will be retried.- __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
headerrefresh_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
orcom.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:
- 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
- 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:
- Returns:
output
- Return type:
- 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:
xrpc_server (lexrpc.Server)
app (flask.Flask)
- class lexrpc.flask_server.XrpcEndpoint(server)[source]
Bases:
View
Handles inbound XRPC query and procedure (but not subscription) methods.
- server
- Type:
lexrpc.Server
- 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.
- class lexrpc.base.Base(lexicons=None, validate=True)[source]
Bases:
object
Base class for both XRPC client and server.
Attributes: * defs (dict): lexicons. Key is str NSID with optional fragment, value is
dict lexicon preprocessed to be JSON Schema compatible.
- __init__(lexicons=None, validate=True)[source]
Constructor.
- Parameters:
- 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
- decode_params(method_nsid, params)[source]
Decodes encoded parameter values.
Based on https://atproto.com/specs/xrpc#lexicon-http-endpoints
- Parameters:
- Returns:
maps str names to decoded boolean, number, str, and array values
- Return type:
- Raises:
ValueError – if a parameter value can’t be decoded
NotImplementedError – if no method lexicon is registered for the given NSID