# Streams

An abstraction layer over OS-dependent file-like objects, that provides a consistent view of a duplex byte stream.

class rpyc.core.stream.Stream

  Base Stream

  close()

    closes the stream, releasing any system resources associated with it

  property closed

    tests whether the stream is closed or not

  fileno()

    returns the stream’s file descriptor

  poll(timeout)

    indicates whether the stream has data to read (within timeout seconds)

  read(count)

    reads exactly count bytes, or raise EOFError

    Parameters

      count – the number of bytes to read

    Returns

      read data

  write(data)

    writes the entire data, or raise EOFError

    Parameters

      data – a string of binary data

class rpyc.core.stream.SocketStream(sock)

  A stream over a socket

  classmethod connect(host, port, **kwargs)

    factory method that creates a `SocketStream` over a socket connected to host and port

    Parameters

      - host – the host name

      - port – the TCP port

      - family – specify a custom socket family

      - socktype – specify a custom socket type

      - proto – specify a custom socket protocol

      - timeout – connection timeout (default is 3 seconds)

      - nodelay – set the TCP_NODELAY socket option

      - keepalive – enable TCP keepalives. The value should be a boolean, but on Linux, it can also be an integer specifying the keepalive interval (in seconds)

      - ipv6 – if True, creates an IPv6 socket (`AF_INET6`); otherwise an IPv4 (`AF_INET`) socket is created

    Returns

      a `SocketStream`

  classmethod unix_connect(path, timeout=3)

    factory method that creates a `SocketStream` over a unix domain socket located in path

    Parameters

      - path – the path to the unix domain socket

      - timeout – socket timeout

  classmethod ssl_connect(host, port, ssl_kwargs, **kwargs)

    factory method that creates a `SocketStream` over an SSL-wrapped socket, connected to host and port with the given credentials.

    Parameters

      - host – the host name

      - port – the TCP port

      - ssl_kwargs – a dictionary of keyword arguments to be passed directly to `ssl.wrap_socket`

      - kwargs – additional keyword arguments: `family`, `socktype`, `proto`, `timeout`, `nodelay`, passed directly to the `socket` constructor, or `ipv6`.

      - ipv6 – if True, creates an IPv6 socket (`AF_INET6`); otherwise an IPv4 (`AF_INET`) socket is created

    Returns

      a `SocketStream`

  property closed

    tests whether the stream is closed or not

  close()

    closes the stream, releasing any system resources associated with it

  fileno()

    returns the stream’s file descriptor

  read(count)

    reads exactly count bytes, or raise EOFError

    Parameters

      count – the number of bytes to read

    Returns

      read data

  write(data)

    writes the entire data, or raise EOFError

    Parameters

      data – a string of binary data

class rpyc.core.stream.TunneledSocketStream(sock)

  A socket stream over an SSH tunnel (terminates the tunnel when the connection closes)

  close()

    closes the stream, releasing any system resources associated with it

class rpyc.core.stream.Win32PipeStream(incoming, outgoing)

  A stream over two simplex pipes (one used to input, another for output). This is an implementation for Windows pipes (which suck)

  fileno()

    returns the stream’s file descriptor

  property closed

    tests whether the stream is closed or not

  close()

    closes the stream, releasing any system resources associated with it

  read(count)

    reads exactly count bytes, or raise EOFError

    Parameters

      count – the number of bytes to read

    Returns

      read data

  write(data)

    writes the entire data, or raise EOFError

    Parameters

      data – a string of binary data

  poll(timeout, interval=0.001)

    a Windows version of select()

class rpyc.core.stream.NamedPipeStream(handle, is_server_side)

  A stream over two named pipes (one used to input, another for output). Windows implementation.

  classmethod create_server(pipename, connect=True)

    factory method that creates a server-side `NamedPipeStream`, over a newly-created named pipe of the given name.

    Parameters

      - pipename – the name of the pipe. It will be considered absolute if it starts with `\\.`; otherwise `\\.\pipe\rpyc` will be prepended.

      - connect – whether to connect on creation or not

    Returns

      a `NamedPipeStream` instance

  connect_server()

    connects the server side of an unconnected named pipe (blocks until a connection arrives)

  classmethod create_client(pipename)

    factory method that creates a client-side `NamedPipeStream`, over a newly-created named pipe of the given name.

    Parameters

      pipename – the name of the pipe. It will be considered absolute if it starts with `\\.`; otherwise `\\.\pipe\rpyc` will be prepended.

    Returns

      a `NamedPipeStream` instance

  close()

    closes the stream, releasing any system resources associated with it

  read(count)

    reads exactly count bytes, or raise EOFError

    Parameters

      count – the number of bytes to read

    Returns

      read data

  write(data)

    writes the entire data, or raise EOFError

    Parameters

      data – a string of binary data

  poll(timeout, interval=0.001)

    Windows version of select()

class rpyc.core.stream.PipeStream(incoming, outgoing)

  A stream over two simplex pipes (one used to input, another for output)

  classmethod from_std()

    factory method that creates a PipeStream over the standard pipes (`stdin` and `stdout`)

    Returns

      a `PipeStream` instance

  classmethod create_pair()

    factory method that creates two pairs of anonymous pipes, and creates two PipeStreams over them. Useful for `fork()`.

    Returns

      a tuple of two `PipeStream` instances

  property closed

    tests whether the stream is closed or not

  close()

    closes the stream, releasing any system resources associated with it

  fileno()

    returns the stream’s file descriptor

  read(count)

    reads exactly count bytes, or raise EOFError

    Parameters

      count – the number of bytes to read

    Returns

      read data

  write(data)

    writes the entire data, or raise EOFError

    Parameters

      data – a string of binary data

# Channel

Channel is an abstraction layer over streams that works with packets of data, rather than an endless stream of bytes, and adds support for compression.

class rpyc.core.channel.Channel(stream, compress=True)

  Channel implementation.

  Note: In order to avoid problems with all sorts of line-buffered transports, we deliberately add `\n` at the end of each frame.

  close()

    closes the channel and underlying stream

  property closed

    indicates whether the underlying stream has been closed

  fileno()

    returns the file descriptor of the underlying stream

  poll(timeout)

    polls the underlying steam for data, waiting up to timeout seconds

  recv()

    Receives the next packet (or frame) from the underlying stream. This method will block until the packet has been read completely

    Returns

      string of data

  send(data)

    Sends the given string of data as a packet over the underlying stream. Blocks until the packet has been sent.

    Parameters

      data – the byte string to send as a packet