API Reference

snekrpc.interface

Server

Bases: Interface

add_service(service, name=None)

Register a service with the server.

You can register a service but keep it hidden from users by prefixing the name with an underscore.

snekrpc.service

Service base classes and helpers.

ServiceProxy

Client-side helper that exposes remote commands as callables.

__dir__()

Add remote command names to dir() results.

__getattr__(cmd_name)

Return a cached callable or lazily wrap the remote command.

__init__(name, client, command_metadata=True)

Cache remote service metadata and wrap remote commands.

When command_metadata is True, metadata will be loaded from the remote metadata service. When False, no metadata will be loaded. Otherwise, a sequence of command metadata can be provided directly.

ServiceSpec

Bases: Struct

Description of a callable signature.

from_service(svc, service_name=None) classmethod

Serialize a service definition for metadata responses.

StreamInitiator

Generator shim that ensures the generator is started.

__init__(gen)

Prime the generator while preserving the first item.

__iter__()

Yield the cached first item followed by the original stream.

wrap_call(proxy, cmd_name, cmd_spec=None)

Wrap a remote call in retry logic, handling stream outputs.

snekrpc.transport

Base transport abstractions.

Connection

Wrap an underlying socket-like object and handle message encoding.

url property

Return a string representation of the connection endpoint.

__enter__()

Allow context-manager usage.

__exit__(exc_type, exc, tb)

Close the connection when leaving a with block.

__init__(interface, addr)

Bind the connection to an interface instance and address.

close()

Close the underlying socket/resource.

recv()

Receive raw bytes.

send(data)

Send raw bytes.

Transport

Bases: ABC

Base transport class mirrored across clients and servers.

url property

Return the configured transport URL.

__init__(url)

Store the normalized URL for later use.

connect(client) abstractmethod

Connect to a remote endpoint and return a Connection.

join(timeout=None) abstractmethod

Block until the server threads exit.

serve(server) abstractmethod

Start serving RPC requests.

stop() abstractmethod

Stop serving and release resources.

create(url, *args, **kwargs)

Create a Transport instance for url.

snekrpc.codec

Codec base classes and helpers.

Codec

Bases: ABC

Base class for codecs that know how to encode/decode RPC payloads.

decode(data) abstractmethod

Deserialize bytes into Python objects.

encode(msg) abstractmethod

Serialize msg into bytes.

snekrpc.formatter

Formatter plugin infrastructure.

Formatter

Base class for converting RPC responses to user output.

format(res)

Return the raw value by default; subclasses can override.

print(res)

Print a formatted representation of res.

process(res)

Automatically iterate through generators and print results.

snekrpc.cli

Command-line entry points for interacting with local and remote servers.

Parser

Builds CLI parsers for both client and server workflows.

__init__()

Initialize the base parser and global argument definitions.

add_command_args(parser, cmd, single_flags=True)

Translate command metadata into argparse arguments.

add_global_args(parser)

Adds an argument group to parser for global arguments.

add_option_arg(parser, param, chars=None)

Add an individual option flag, handling bool/kwargs special cases.

add_service_args(parser, cls, alias)

Expose cls.__init__ parameters under the given service alias.

add_transport_args(parser, cls)

Expose transport constructor parameters with a unique prefix.

add_transport_exception(parser, name, exc)

Display an error group when a transport fails to import.

get_argument_help(doc=None, hint=None, default=None)

Build an argparse help string that includes hints and defaults.

get_argument_hint(hint)

Return a placeholder string usable as metavar text.

get_command_args(args)

Processes the command-line arguments and returns the arguments to pass to the selected command.

get_converter(hint)

Returns a type converter keyed to a specific typehint.

get_help(doc)

Return the first line of a documentation string.

get_prefixed_args(args)

Split parsed values into transport and service dictionaries.

main()

Processes command-line arguments and calls any selected command.

print_status(status)

Prints the server version and status data.

start_client(trn, parser, args)

Connect to the remote server and execute a command.

start_server(trn, args, svc_args)

Start an RPC server with the configured services.

io_stat_mode()

Return whether stdout is piped, redirected, or connected to a tty.

main()

Convenient entry-point.

parse_alias(name)

Split name into module and alias if : is present.