Factories

RPyC connection factories: ease the creation of a connection for the common cases)

exception rpyc.utils.factory.DiscoveryError[source]
exception rpyc.utils.factory.ForbiddenError[source]
rpyc.utils.factory.connect_channel(channel, service=<class 'rpyc.core.service.VoidService'>, config={})[source]

creates a connection over a given channel

Parameters:
  • channel – the channel to use

  • service – the local service to expose (defaults to Void)

  • config – configuration dict

Returns:

an RPyC connection

rpyc.utils.factory.connect_stream(stream, service=<class 'rpyc.core.service.VoidService'>, config={})[source]

creates a connection over a given stream

Parameters:
  • stream – the stream to use

  • service – the local service to expose (defaults to Void)

  • config – configuration dict

Returns:

an RPyC connection

rpyc.utils.factory.connect_pipes(input, output, service=<class 'rpyc.core.service.VoidService'>, config={})[source]

creates a connection over the given input/output pipes

Parameters:
  • input – the input pipe

  • output – the output pipe

  • service – the local service to expose (defaults to Void)

  • config – configuration dict

Returns:

an RPyC connection

rpyc.utils.factory.connect_stdpipes(service=<class 'rpyc.core.service.VoidService'>, config={})[source]

creates a connection over the standard input/output pipes

Parameters:
  • service – the local service to expose (defaults to Void)

  • config – configuration dict

Returns:

an RPyC connection

rpyc.utils.factory.connect(host, port, service=<class 'rpyc.core.service.VoidService'>, config={}, ipv6=False, keepalive=False)[source]

creates a socket-connection to the given host and port

Parameters:
  • host – the hostname to connect to

  • port – the TCP port to use

  • service – the local service to expose (defaults to Void)

  • config – configuration dict

  • ipv6 – whether to create an IPv6 socket (defaults to False)

  • keepalive – whether to set TCP keepalive on the socket (defaults to False)

Returns:

an RPyC connection

rpyc.utils.factory.unix_connect(path, service=<class 'rpyc.core.service.VoidService'>, config={})[source]

creates a socket-connection to the given unix domain socket

Parameters:
  • path – the path to the unix domain socket

  • service – the local service to expose (defaults to Void)

  • config – configuration dict

Returns:

an RPyC connection

rpyc.utils.factory.ssl_connect(host, port, keyfile=None, certfile=None, ca_certs=None, cert_reqs=None, ssl_version=None, ciphers=None, service=<class 'rpyc.core.service.VoidService'>, config={}, ipv6=False, keepalive=False, verify_mode=None)[source]

creates an SSL-wrapped connection to the given host (encrypted and authenticated).

Parameters:
  • host – the hostname to connect to

  • port – the TCP port to use

  • service – the local service to expose (defaults to Void)

  • config – configuration dict

  • ipv6 – whether to create an IPv6 socket or an IPv4 one(defaults to False)

  • keepalive – whether to set TCP keepalive on the socket (defaults to False)

  • 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

  • verify_mode – see ssl.SSLContext.verify_mode

Returns:

an RPyC connection

rpyc.utils.factory.ssh_connect(remote_machine, remote_port, service=<class 'rpyc.core.service.VoidService'>, config={})[source]

Connects to an RPyC server over an SSH tunnel (created by plumbum). See Plumbum tunneling for further details.

Note

This function attempts to allocate a free TCP port for the underlying tunnel, but doing so is inherently prone to a race condition with other processes who might bind the same port before sshd does. Albeit unlikely, there is no sure way around it.

Parameters:
  • remote_machine – an plumbum.remote.RemoteMachine instance

  • remote_port – the port of the remote server

  • service – the local service to expose (defaults to Void)

  • config – configuration dict

Returns:

an RPyC connection

rpyc.utils.factory.discover(service_name, host=None, registrar=None, timeout=2)[source]

discovers hosts running the given service

Parameters:
  • service_name – the service to look for

  • host – limit the discovery to the given host only (None means any host)

  • registrar – use this registry client to discover services. if None, use the default UDPRegistryClient with the default settings.

  • timeout – the number of seconds to wait for a reply from the registry if no hosts are found, raises DiscoveryError

Raises:

DiscoveryError if no server is found

Returns:

a list of (ip, port) pairs

rpyc.utils.factory.connect_by_service(service_name, host=None, registrar=None, timeout=2, service=<class 'rpyc.core.service.VoidService'>, config={})[source]

create a connection to an arbitrary server that exposes the requested service

Parameters:
  • service_name – the service to discover

  • host – limit discovery to the given host only (None means any host)

  • service – the local service to expose (defaults to Void)

  • config – configuration dict

Raises:

DiscoveryError if no server is found

Returns:

an RPyC connection

rpyc.utils.factory.connect_subproc(args, service=<class 'rpyc.core.service.VoidService'>, config={})[source]

runs an rpyc server on a child process that and connects to it over the stdio pipes. uses the subprocess module.

Parameters:
  • args – the args to Popen, e.g., [“python”, “-u”, “myfile.py”]

  • service – the local service to expose (defaults to Void)

  • config – configuration dict

rpyc.utils.factory.connect_thread(service=<class 'rpyc.core.service.VoidService'>, config={}, remote_service=<class 'rpyc.core.service.VoidService'>, remote_config={})[source]

starts an rpyc server on a new thread, bound to an arbitrary port, and connects to it over a socket.

Parameters:
  • service – the local service to expose (defaults to Void)

  • config – configuration dict

  • remote_service – the remote service to expose (of the server; defaults to Void)

  • remote_config – remote configuration dict (of the server)

rpyc.utils.factory.connect_multiprocess(service=<class 'rpyc.core.service.VoidService'>, config={}, remote_service=<class 'rpyc.core.service.VoidService'>, remote_config={}, args={})[source]

starts an rpyc server on a new process, bound to an arbitrary port, and connects to it over a socket. Basically a copy of connect_thread(). However if args is used and if these are shared memory then changes will be bi-directional. That is we now have access to shared memory.

Parameters:
  • service – the local service to expose (defaults to Void)

  • config – configuration dict

  • remote_service – the remote service to expose (of the server; defaults to Void)

  • remote_config – remote configuration dict (of the server)

  • args – dict of local vars to pass to new connection, form {‘name’:var}

Contributed by @tvanzyl