# 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 to ssl.SSLContext and its corresponding methods:

  Parameters:

    - keyfile – see `ssl.SSLContext.load_cert_chain`. May be `None`

    - certfile – see `ssl.SSLContext.load_cert_chain`. May be `None`

    - ca_certs – see `ssl.SSLContext.load_verify_locations`. May be `None`

    - cert_reqs – see `ssl.SSLContext.verify_mode`. 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.SSLContext`. The default is defined by `ssl.create_default_context`

    - ciphers – see `ssl.SSLContext.set_ciphers`. 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=64000)

  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=64000)

  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=64000)

  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=64000)

  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, globals=None, def_=True)

  “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

  Note

  While it is not forbidden to “teleport” functions across different Python versions, it may result in errors due to Python bytecode differences. It is recommended to ensure both the client and the server are of the same Python version when using this function.

  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, serve_interval=0.0, sleep_interval=0.1)

  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.

rpyc.utils.helpers.classpartial(*args, **kwargs)

  Bind arguments to a class’s __init__.

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