Utils
Factories
- connect_channel(channel, service = VoidService, config = {}) - creates an RPyC connection, exposing the given service with the given config, from a channel object
- connect_stream(stream, service = VoidService, config = {}) - creates an RPyC connection, exposing the given service with the given config, from a stream object
- connect_pipes(input, output, service = VoidService, config = {}) - creates an RPyC connection, exposing the given service with the given config, from a two pipe objects
- connect_stdpipes(service = VoidService, config = {}) - creates an RPyC connection, exposing the given service with the given config, from a the standard IO pipes (sys.stdin and sys.stdout)
- connect(host, port, service = VoidService, config = {}) - creates an RPyC connection, exposing the given service with the given config, over a TCP socket to the given host at the given port
- tls_connect(host, port, username, password, service = VoidService, config = {}) - creates an authenticated and encrypted RPyC connection, exposing the given service with the given config, over a TCP socket to the given host at the given port. Authentication is done using the given username and password pair
- discover(service_name, host = None) - returns a list of (host, port) pairs of servers exposing the given services. If host is not None, only servers running on host are returned
- connect_by_serivce(service_name, host = None, service = VoidService, config = {}) - creates an RPyC connection, exposing the given service with the given config, to an arbitrary server that exposes the requested service name. If host is not None, only servers running on host are used.
- connect_subproc(args, service = VoidService, config = {}) - creates a child process (subprocess) by running the given command line arguments, and attaches to it using its standard IO pipes. Returns an RPyC connection exposing the given service with the given config. Useful for workload distribution or true multitasking in python.
- connect_thread(service = VoidService, config = {}, remote_service = VoidService, remote_config = {}) - creates an in-process thread running the given service (remote_service) with the given config (remote_config), and connects to it over a socket. Returns an RPyC connection exposing the given service with the given config. Useful for testing.
Classic
classic is a namespace that exposes all the factories listed above (except for discover and connect_by_service) exposing the SlaveService (instead of the VoidService).
Helpers
The helpers module contains the following utility functions:
- buffiter(proxy, chunk = 2, max_chunk = 1000, factor = 2) - creates a buffered iterator object over the given proxy. Buffered iterators save a considerable amount of network ping-pong when iterating over an iterator. Instead of next() being invoked on the other party every time, a chunk of elements is sent at once, and next() is invoked mostly in the local process.
- async(proxy) - creates an asynchronous wrapper over the given proxy, that when invoked, returns an AsyncResult.
- timed(asyncproxy, timeout) - returns a wrapper over an AsyncProxy (created by async above), that has a timeout.
Remoting
The remoting module exposes common file, debugging and stdio utilities useful in the classic mode:
- download - downloads a remote directory or file
- upload - uploads a local directory or a file to the other party
- upload_package - uploads a python package to the other side
- update_module - replaces an existing python module on the other side
- obtain(proxy) - obtains (creates a local by-value copy) of a remote object (uses pickle)
- deliver(conn, localobj) - delivers 'localobj' to the other side of the connection (by-value), returning a proxy to the newly created one (uses pickle)
- redirected_stdio(conn) - redirects stdio the pipes to the client
- pm(conn) - remote post-mortem debugger (pdb.pm)
- interact(conn) - runs an interactive python shell on the server
Server
The server modules implements a RPyC server over TCP, with two serving methods: threaded and forking. The ThreadedServer creates a thread to server each client, while the ForkingServer (*NIX) creates a subprocess per each client. The ThreadedServer works on both Windows and *NIX, and is the recommended serving method.
The constructor of Server takes the following parameters:
- service - the service to expose
- hostname - the hostname to bind to, i.e., 0.0.0.0 (anyone can connect) or 127.0.0.1 (localhost connections only). Default is 0.0.0.0.
- port - the port to bind to. 0 means any free port, any other number specifies the port number. Default is 0.
- backlog - the listener backlog. Default is 10.
- authenticator - the authenticator function which is used to authenticate accepted connections. Default is None, which means authentication is disabled.
- auto_register - whether to automatically register/unregister with a registry server. If True, it starts a background thread to re-register the server at a constant interval. Default is True.
- protocol_config - the config dict for the protocol. Default is {}, which means the default config is used.
API:
- close() - closes the server (terminates serving, releases all resources, unregisters the server from a registry server)
- fileno() - returns the listener socket file descriptor
- register() - registers the server with a registry server
- unregister() - unregisters the server from a registry server
- start() - starts the server. It works until the server is closed or a KeyboardInterrupt is received.
Authenticators
Authenticators are functions that take the accepted socket as their only parameter, perform some authentication procedure on the client, and either raise AuthenticationError or return a socket object to be used to serve the connection. The built-in VdbAuthenticator relies on tlslite to authenticate the socket against a database of users and passwords. It then returns a TLSConnection object, which wraps the original socket and encrypts the transportation. Authenticators don't have to return a new socket, for instance, here's an authenticator that requires the client to be "polite":
def polite_authenticator(sock):
greeting = sock.recv(5)
if greeting != "Hello":
raise AuthenticatorError("so rude!")
return sock # this is a polite client
Registry
The registry module contains the RegistryServer and various utilities that are coupled with it
API:
- RegistryServer with start() and stop() methods
- discover_service(name, ip = "255.255.255.255", timeout = 2) - performs a discovery of all servers in the given subnet, waiting for replies for 'timeout' seconds. Returns a list of (host, port) pairs.
Twisted (unstable)
A partial integration of RPyC with twisted is provided. It allows you to work with RPyC in a reactor model to some degree. The synchronous nature of the RPyC protocol does not play nicely with the reactor model, so the integration is only partial.
