# Factories

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

`rpyc.utils.factory.``connect_channel`(channel, service=<class 'rpyc.core.service.VoidService'>, config={})

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

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

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

  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)

  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 use IPv6 or not

  Returns: | an RPyC connection

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

  creates a socket-connection to the given host and port

  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)

  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

  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

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

  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)

  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, service=<class 'rpyc.core.service.VoidService'>, config={})

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

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

  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
  - server_service – the remote service to expose (of the server; defaults to Void)
  - server_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={})

  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 memmory.

  Parameters:

  - service – the local service to expose (defaults to Void)
  - config – configuration dict
  - server_service – the remote service to expose (of the server; defaults to Void)
  - server_config – remote configuration dict (of the server)
  - args – dict of local vars to pass to new connection, form {‘name’:var}

  Contributed by @tvanzyl