# Classic

`rpyc.utils.classic.``connect_channel`(channel)

  Creates an RPyC connection over the given `channel`

  Parameters: | channel – the `rpyc.core.channel.Channel` instance
  Returns: | an RPyC connection exposing `SlaveService`

`rpyc.utils.classic.``connect_stream`(stream)

  Creates an RPyC connection over the given stream

  Parameters: | channel – the `rpyc.core.stream.Stream` instance
  Returns: | an RPyC connection exposing `SlaveService`

`rpyc.utils.classic.``connect_stdpipes`()

  Creates an RPyC connection over the standard pipes (`stdin` and `stdout`)

  Returns: | an RPyC connection exposing `SlaveService`

`rpyc.utils.classic.``connect_pipes`(input, output)

  Creates an RPyC connection over two pipes

  Parameters:

  - input – the input pipe
  - output – the output pipe

  Returns: | an RPyC connection exposing `SlaveService`

`rpyc.utils.classic.``connect`(host, port=18812, ipv6=False, keepalive=False)

  Creates a socket connection to the given host and port.

  Parameters:

  - host – the host to connect to
  - port – the TCP port
  - ipv6 – whether to create an IPv6 socket or IPv4

  Returns: | an RPyC connection exposing `SlaveService`

`rpyc.utils.classic.``unix_connect`(path)

  Creates a socket connection to the given host and port.

  Parameters: | path – the path to the unix domain socket
  Returns: | an RPyC connection exposing `SlaveService`

`rpyc.utils.classic.``ssl_connect`(host, port=18821, keyfile=None, certfile=None, ca_certs=None, cert_reqs=None, ssl_version=None, ciphers=None, ipv6=False)

  Creates a secure (`SSL`) socket connection to the given host and port, authenticating with the given certfile and CA file.

  Parameters:

  - host – the host to connect to
  - port – the TCP port to use
  - ipv6 – whether to create an IPv6 socket or an IPv4 one

  The following arguments are passed directly to ssl.wrap_socket:

  Parameters:

  - keyfile – see `ssl.wrap_socket`. May be `None`
  - certfile – see `ssl.wrap_socket`. May be `None`
  - ca_certs – see `ssl.wrap_socket`. May be `None`
  - cert_reqs – see `ssl.wrap_socket`. By default, if `ca_cert` is specified, the requirement is set to `CERT_REQUIRED`; otherwise it is set to `CERT_NONE`
  - ssl_version – see `ssl.wrap_socket`. The default is `PROTOCOL_TLSv1`
  - ciphers – see `ssl.wrap_socket`. May be `None`. New in Python 2.7/3.2

  Returns: | an RPyC connection exposing `SlaveService`

`rpyc.utils.classic.``ssh_connect`(remote_machine, remote_port)

  Connects to the remote server over an SSH tunnel. See `rpyc.utils.factory.ssh_connect()` for more info.

  Parameters:

  - remote_machine – the `plumbum.remote.RemoteMachine` instance
  - remote_port – the remote TCP port

  Returns: | an RPyC connection exposing `SlaveService`

`rpyc.utils.classic.``connect_subproc`(server_file=None)

  Runs an RPyC classic server as a subprocess and returns an RPyC connection to it over stdio

  Parameters: | server_file – The full path to the server script (`rpyc_classic.py`). If not given, `which rpyc_classic.py` will be attempted.
  Returns: | an RPyC connection exposing `SlaveService`

`rpyc.utils.classic.``connect_thread`()

  Starts a SlaveService on a thread and connects to it. Useful for testing purposes. See `rpyc.utils.factory.connect_thread()`

  Returns: | an RPyC connection exposing `SlaveService`

`rpyc.utils.classic.``connect_multiprocess`(args={})

  Starts a SlaveService on a multiprocess process and connects to it. Useful for testing purposes and running multicore code thats uses shared memory. See `rpyc.utils.factory.connect_multiprocess()`

  Returns: | an RPyC connection exposing `SlaveService`

`rpyc.utils.classic.``upload`(conn, localpath, remotepath, filter=None, ignore_invalid=False, chunk_size=16000)

  uploads a file or a directory to the given remote path

  Parameters:

  - localpath – the local file or directory
  - remotepath – the remote path
  - filter – a predicate that accepts the filename and determines whether it should be uploaded; None means any file
  - chunk_size – the IO chunk size

`rpyc.utils.classic.``download`(conn, remotepath, localpath, filter=None, ignore_invalid=False, chunk_size=16000)

  download a file or a directory to the given remote path

  Parameters:

  - localpath – the local file or directory
  - remotepath – the remote path
  - filter – a predicate that accepts the filename and determines whether it should be downloaded; None means any file
  - chunk_size – the IO chunk size

`rpyc.utils.classic.``upload_package`(conn, module, remotepath=None, chunk_size=16000)

  uploads a module or a package to the remote party

  Parameters:

  - conn – the RPyC connection to use
  - module – the local module/package object to upload
  - remotepath – the remote path (if `None`, will default to the remote system’s python library (as reported by `distutils`)
  - chunk_size – the IO chunk size

  Note

  `upload_module` is just an alias to `upload_package`

  example:

      import foo.bar
      ...
      rpyc.classic.upload_package(conn, foo.bar)

`rpyc.utils.classic.``upload_module`(conn, module, remotepath=None, chunk_size=16000)

  uploads a module or a package to the remote party

  Parameters:

  - conn – the RPyC connection to use
  - module – the local module/package object to upload
  - remotepath – the remote path (if `None`, will default to the remote system’s python library (as reported by `distutils`)
  - chunk_size – the IO chunk size

  Note

  `upload_module` is just an alias to `upload_package`

  example:

      import foo.bar
      ...
      rpyc.classic.upload_package(conn, foo.bar)

`rpyc.utils.classic.``obtain`(proxy)

  obtains (copies) a remote object from a proxy object. the object is `pickled` on the remote side and `unpickled` locally, thus moved by value. changes made to the local object will not reflect remotely.

  Parameters: | proxy – an RPyC proxy object

  Note

  the remote object to must be `pickle`-able

  Returns: | a copy of the remote object

`rpyc.utils.classic.``deliver`(conn, localobj)

  delivers (recreates) a local object on the other party. the object is `pickled` locally and `unpickled` on the remote side, thus moved by value. changes made to the remote object will not reflect locally.

  Parameters:

  - conn – the RPyC connection
  - localobj – the local object to deliver

  Note

  the object must be `picklable`

  Returns: | a proxy to the remote object

`rpyc.utils.classic.``redirected_stdio`(conn)

  Redirects the other party’s `stdin`, `stdout` and `stderr` to those of the local party, so remote IO will occur locally.

  Example usage:

      with redirected_stdio(conn):
          conn.modules.sys.stdout.write("hello\n")   # will be printed locally

`rpyc.utils.classic.``pm`(conn)

  same as `pdb.pm()` but on a remote exception

  Parameters: | conn – the RPyC connection

`rpyc.utils.classic.``interact`(conn, namespace=None)

  remote interactive interpreter

  Parameters:

  - conn – the RPyC connection
  - namespace – the namespace to use (a `dict`)

class `rpyc.utils.classic.``MockClassicConnection`

  Mock classic RPyC connection object. Useful when you want the same code to run remotely or locally.

`rpyc.utils.classic.``teleport_function`(conn, func)

  “Teleports” a function (including nested functions/closures) over the RPyC connection. The function is passed in bytecode form and reconstructed on the other side.

  The function cannot have non-brinable defaults (e.g., `def f(x, y=[8]):`, since a `list` isn’t brinable), or make use of non-builtin globals (like modules). You can overcome the second restriction by moving the necessary imports into the function body, e.g.

      def f(x, y):
          import os
          return (os.getpid() + y) * x

  Parameters:

  - conn – the RPyC connection
  - func – the function object to be delivered to the other party

# Helpers

Helpers and wrappers for common RPyC tasks

`rpyc.utils.helpers.``buffiter`(obj, chunk=10, max_chunk=1000, factor=2)

  Buffered iterator - reads the remote iterator in chunks starting with chunk, multiplying the chunk size by factor every time, as an exponential-backoff, up to a chunk of max_chunk size.

  `buffiter` is very useful for tight loops, where you fetch an element from the other side with every iterator. Instead of being limited by the network’s latency after every iteration, `buffiter` fetches a “chunk” of elements every time, reducing the amount of network I/Os.

  Parameters:

  - obj – An iterable object (supports `iter()`)
  - chunk – the initial chunk size
  - max_chunk – the maximal chunk size
  - factor – the factor by which to multiply the chunk size after every iterator (up to max_chunk). Must be >= 1.

  Returns: | an iterator

  Example:

      cursor = db.get_cursor()
      for id, name, dob in buffiter(cursor.select("Id", "Name", "DoB")):
          print id, name, dob

`rpyc.utils.helpers.``restricted`(obj, attrs, wattrs=None)

  Returns a ‘restricted’ version of an object, i.e., allowing access only to a subset of its attributes. This is useful when returning a “broad” or “dangerous” object, where you don’t want the other party to have access to all of its attributes.

  New in version 3.2.

  Parameters:

  - obj – any object
  - attrs – the set of attributes exposed for reading (`getattr`) or writing (`setattr`). The same set will serve both for reading and writing, unless wattrs is explicitly given.
  - wattrs – the set of attributes exposed for writing (`setattr`). If `None`, `wattrs` will default to `attrs`. To disable setting attributes completely, set to an empty tuple `()`.

  Returns: | a restricted view of the object

  Example:

      class MyService(rpyc.Service):
          def exposed_open(self, filename):
              f = open(filename, "r")
              return rpyc.restricted(f, {"read", "close"})   # disallow access to `seek` or `write`

`rpyc.utils.helpers.``async`(proxy)

  Creates an async proxy wrapper over an existing proxy. Async proxies are cached. Invoking an async proxy will return an AsyncResult instead of blocking

class `rpyc.utils.helpers.``timed`(proxy, timeout)

  Creates a timed asynchronous proxy. Invoking the timed proxy will run in the background and will raise an `rpyc.core.async.AsyncResultTimeout` exception if the computation does not terminate within the given time frame

  Parameters:

  - proxy – any callable RPyC proxy
  - timeout – the maximal number of seconds to allow the operation to run

  Returns: | a `timed` wrapped proxy

  Example:

      t_sleep = rpyc.timed(conn.modules.time.sleep, 6) # allow up to 6 seconds
      t_sleep(4) # okay
      t_sleep(8) # will time out and raise AsyncResultTimeout

class `rpyc.utils.helpers.``BgServingThread`(conn, callback=None)

  Runs an RPyC server in the background to serve all requests and replies that arrive on the given RPyC connection. The thread is started upon the the instantiation of the `BgServingThread` object; you can use the `stop()` method to stop the server thread

  Example:

      conn = rpyc.connect(...)
      bg_server = BgServingThread(conn)
      ...
      bg_server.stop()

  Note

  For a more detailed explanation of asynchronous operation and the role of the `BgServingThread`, see Part 5: Asynchrounous Operation and Events

  `stop`()

    stop the server thread. once stopped, it cannot be resumed. you will have to create a new BgServingThread object later.