Protocol

The RPyC protocol

exception rpyc.core.protocol.PingError[source]

The exception raised should Connection.ping() fail

rpyc.core.protocol.DEFAULT_CONFIG = {'allow_all_attrs': False, 'allow_delattr': False, 'allow_exposed_attrs': True, 'allow_getattr': True, 'allow_pickle': False, 'allow_public_attrs': False, 'allow_safe_attrs': True, 'allow_setattr': False, 'before_closed': None, 'bind_threads': False, 'close_catchall': False, 'connid': None, 'credentials': None, 'endpoints': None, 'exposed_prefix': 'exposed_', 'import_custom_exceptions': False, 'include_local_traceback': True, 'include_local_version': True, 'instantiate_custom_exceptions': False, 'instantiate_oldstyle_exceptions': False, 'log_exceptions': True, 'logger': None, 'propagate_KeyboardInterrupt_locally': True, 'propagate_SystemExit_locally': False, 'safe_attrs': {'__abs__', '__add__', '__and__', '__bool__', '__cmp__', '__contains__', '__delitem__', '__delslice__', '__div__', '__divmod__', '__doc__', '__enter__', '__eq__', '__exit__', '__float__', '__floordiv__', '__format__', '__ge__', '__getitem__', '__getslice__', '__gt__', '__hash__', '__hex__', '__iadd__', '__iand__', '__idiv__', '__ifloordiv__', '__ilshift__', '__imod__', '__imul__', '__index__', '__int__', '__invert__', '__ior__', '__ipow__', '__irshift__', '__isub__', '__iter__', '__itruediv__', '__ixor__', '__le__', '__len__', '__length_hint__', '__long__', '__lshift__', '__lt__', '__mod__', '__mul__', '__ne__', '__neg__', '__new__', '__next__', '__nonzero__', '__oct__', '__or__', '__pos__', '__pow__', '__radd__', '__rand__', '__rdiv__', '__rdivmod__', '__repr__', '__rfloordiv__', '__rlshift__', '__rmod__', '__rmul__', '__ror__', '__rpow__', '__rrshift__', '__rshift__', '__rsub__', '__rtruediv__', '__rxor__', '__setitem__', '__setslice__', '__str__', '__sub__', '__truediv__', '__xor__', 'next'}, 'sync_request_timeout': 30}

The default configuration dictionary of the protocol. You can override these parameters by passing a different configuration dict to the Connection class.

Note

You only need to override the parameters you want to change. There’s no need to repeat parameters whose values remain unchanged.

Parameter

Default value

Description

allow_safe_attrs

True

Whether to allow the use of safe attributes (only those listed as safe_attrs)

allow_exposed_attrs

True

Whether to allow exposed attributes (attributes that start with the exposed_prefix)

allow_public_attrs

False

Whether to allow public attributes (attributes that don’t start with _)

allow_all_attrs

False

Whether to allow all attributes (including private)

safe_attrs

set([...])

The set of attributes considered safe

exposed_prefix

"exposed_"

The prefix of exposed attributes

allow_getattr

True

Whether to allow getting of attributes (getattr)

allow_setattr

False

Whether to allow setting of attributes (setattr)

allow_delattr

False

Whether to allow deletion of attributes (delattr)

allow_pickle

False

Whether to allow the use of pickle

include_local_traceback

True

Whether to include the local traceback in the remote exception

instantiate_custom_exceptions

False

Whether to allow instantiation of custom exceptions (not the built in ones)

import_custom_exceptions

False

Whether to allow importing of exceptions from not-yet-imported modules

instantiate_oldstyle_exceptions

False

Whether to allow instantiation of exceptions which don’t derive from Exception. This is not applicable for Python 3 and later.

propagate_SystemExit_locally

False

Whether to propagate SystemExit locally (kill the server) or to the other party (kill the client)

propagate_KeyboardInterrupt_locally

False

Whether to propagate KeyboardInterrupt locally (kill the server) or to the other party (kill the client)

logger

None

The logger instance to use to log exceptions (before they are sent to the other party) and other events. If None, no logging takes place.

connid

None

Runtime: the RPyC connection ID (used mainly for debugging purposes)

credentials

None

Runtime: the credentials object that was returned by the server’s authenticator or None

endpoints

None

Runtime: The connection’s endpoints. This is a tuple made of the local socket endpoint (getsockname) and the remote one (getpeername). This is set by the server upon accepting a connection; client side connections do no have this configuration option set.

sync_request_timeout

30

Default timeout for waiting results

bind_threads

False

Whether to restrict request/reply by thread (experimental). The default value is False. Setting the environment variable RPYC_BIND_THREADS to “true” will enable this feature.

class rpyc.core.protocol.Connection(root, channel, config={})[source]

The RPyC connection (AKA protocol).

Objects referenced over the connection are either local or remote. This class retains a strong reference to local objects that is deleted when the reference count is zero. Remote/proxied objects have a life-cycle controlled by a different address space. Since garbage collection is handled on the remote end, a weak reference is used for netrefs.

Parameters:
  • root – the Service object to expose

  • channel – the Channel over which messages are passed

  • config – the connection’s configuration dict (overriding parameters from the default configuration)

close()[source]

closes the connection, releasing all held resources

property closed

Indicates whether the connection has been closed or not

fileno()[source]

Returns the connectin’s underlying file descriptor

ping(data=None, timeout=3)[source]

Asserts that the other party is functioning properly, by making sure the data is echoed back before the timeout expires

Parameters:
  • data – the data to send (leave None for the default buffer)

  • timeout – the maximal time to wait for echo

Raises:

PingError if the echoed data does not match

Raises:

EOFError if the remote host closes the connection

serve(timeout=1, wait_for_lock=True, waiting=<function Connection.<lambda>>)[source]

Serves a single request or reply that arrives within the given time frame (default is 1 sec). Note that the dispatching of a request might trigger multiple (nested) requests, thus this function may be reentrant.

Returns:

True if a request or reply were received, False otherwise.

poll(timeout=0)[source]

Serves a single transaction, should one arrives in the given interval. Note that handling a request/reply may trigger nested requests, which are all part of a single transaction.

Returns:

True if a transaction was served, False otherwise

serve_all()[source]

Serves all requests and replies for as long as the connection is alive.

serve_threaded(thread_count=10)[source]

Serves all requests and replies for as long as the connection is alive.

CAVEAT: using non-immutable types that require a netref to be constructed to serve a request, or invoking anything else that performs a sync_request, may timeout due to the sync_request reply being received by another thread serving the connection. A more conventional approach where each client thread opens a new connection would allow ThreadedServer to naturally avoid such multiplexing issues and is the preferred approach for threading procedures that invoke sync_request. See issue #345

poll_all(timeout=0)[source]

Serves all requests and replies that arrive within the given interval.

Returns:

True if at least a single transaction was served, False otherwise

sync_request(handler, *args)[source]

requests, sends a synchronous request (waits for the reply to arrive)

Raises:

any exception that the requests may be generated

Returns:

the result of the request

async_request(handler, *args, **kwargs)[source]

Send an asynchronous request (does not wait for it to finish)

Returns:

an rpyc.core.async_.AsyncResult object, which will eventually hold the result (or exception)

property root

Fetches the root object (service) of the other party