Server¶
API¶
A snekrpc server hosts a number of services. A service is defined by subclassing Service and marking some methods with command(). The class argument name is optional, but recommended in order to register a definitive name with the snekrpc system.
import snekrpc
class EchoService(snekrpc.Service, name='echo'):
@snekrpc.command()
def echo(self, value: str) -> str:
return value
A server is created by setting a URL to define the transport to use, as well as the interface and port to bind to (default: tcp://127.0.0.1:12321). A codec can also be set for encoding/decoding to/from bytes for transfer over the transport (default: msgpack).
Once a Server instance has been created, you can add services with the add_service() method, which will expose the service using the name set in the class definition.
server = snekrpc.Server('tcp://0.0.0.0:12321', codec='json')
server.add_service(EchoService())
server.serve()
Notes:
- The server registers a hidden
_metaservice automatically to provide metadata to clients. add_service()accepts annameargument if you want the service exposed under a different name.Server(remote_tracebacks=True)will include tracebacks in error responses.
Command metadata¶
The clients rely on command metadata to fill in front-end details. Use param()
for parameter docs or to hide parameters from display in help output.
class EchoService(snekrpc.Service, name='echo'):
@snekrpc.command()
def echo(self, value: str) -> str:
return value
Streaming¶
If a command returns a generator, the values yielde d will be streamed to clients. If the first argument (and only the first argument) passed into a command is a generator, values will stream in from the client.
class StreamService(snekrpc.Service, name='stream'):
@snekrpc.command()
def echo(self, values: Iterable[str]) -> Iterable[str]:
yield from values
CLI¶
A server can also be started directly with the snekrpc CLI using the -S,--server flag. Services are added using -s,--service.
# bind with the default: tcp://127.0.0.1:12321
$ snekrpc --server --service health --service file
$ snekrpc --server --url unix:///tmp/snekrpc.sock --service health
Only Service classes which have been registered will be available. There are a few built-in services (use snekrpc --list services to see them). Others can be added by module path and optionally given a different name by appending :<name>:
$ snekrpc --server --service echo_service.EchoService:echo
You can also import a module directly, in which case the service can be referenced by it's registered name:
$ snekrpc --server --import echo_service --service echo