# Protocol

The RPyC protocol

exception rpyc.core.protocol.PingError

  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={})

  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()

    closes the connection, releasing all held resources

  property closed

    Indicates whether the connection has been closed or not

  fileno()

    Returns the connectin’s underlying file descriptor

  ping(data=None, timeout=3)

    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)

    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)

    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()

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

  serve_threaded(thread_count=10)

    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)

    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)

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

    Raises:

      any exception that the requets may be generated

    Returns:

      the result of the request

  async_request(handler, *args, **kwargs)

    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