# 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, 'connid': None, 'credentials': None, 'endpoints': None, 'exposed_prefix': 'exposed_', 'import_custom_exceptions': False, 'include_local_traceback': True, 'instantiate_custom_exceptions': False, 'instantiate_oldstyle_exceptions': False, 'log_exceptions': True, 'logger': None, 'propagate_KeyboardInterrupt_locally': True, 'propagate_SystemExit_locally': False, 'safe_attrs': {'__isub__', '__delitem__', '__len__', '__mod__', '__sub__', '__rdivmod__', '__rfloordiv__', '__length_hint__', '__divmod__', '__invert__', '__itruediv__', '__irshift__', '__le__', '__lt__', '__hash__', '__rmul__', '__rsub__', '__idiv__', '__enter__', '__long__', '__eq__', '__float__', '__setitem__', '__ge__', '__rlshift__', '__contains__', '__ifloordiv__', '__oct__', '__rdiv__', '__pow__', '__radd__', '__add__', '__str__', '__rpow__', 'next', '__neg__', '__rxor__', '__rshift__', '__ipow__', '__next__', '__iadd__', '__repr__', '__ilshift__', '__rrshift__', '__new__', '__truediv__', '__hex__', '__iand__', '__getslice__', '__cmp__', '__ixor__', '__setslice__', '__gt__', '__exit__', '__xor__', '__doc__', '__mul__', '__ior__', '__ne__', '__and__', '__ror__', '__div__', '__imod__', '__rtruediv__', '__getitem__', '__or__', '__index__', '__lshift__', '__delslice__', '__abs__', '__nonzero__', '__floordiv__', '__int__', '__pos__', '__rand__', '__iter__', '__bool__', '__imul__', '__rmod__'}, '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 credentails 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

class `rpyc.core.protocol.``Connection`(service, channel, config={}, _lazy=False)

  The RPyC connection (AKA protocol).

  Parameters:

  - service – the `Service` to expose
  - channel – the `Channel` over which messages are passed
  - config – the connection’s configuration dict (overriding parameters from the `default configuration`)
  - _lazy – whether or not to initialize the service with the creation of the connection. Default is True. If set to False, you will need to call `_init_service()` manually later

  `close`(_catchall=True)

    closes the connection, releasing all held resources

  `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

  `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`(timeout=1)

    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.

  `serve_all`()

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

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

    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)

  `root`

    Fetches the root object (service) of the other party