Streams (generic high-level API)

Streams provide a generic, high-level API to work with connection-oriented transports using file-like, blocking and flow-controlled API.

Utility classes

class StreamBuffer(transport=None, timeout=None)

A stream buffer.

This is a utility class that is used to by Stream to implement the read side buffering.

get_buffer_size()

Return the size of the buffer.

set_buffer_limits(high=None, low=None)

Set the low and high watermarks for the read buffer.

feed(data)

Add data to the buffer.

feed_eof()

Set the EOF condition.

feed_error(exc)

Set the error condition to exc.

class Stream(transport, mode='rw', autoclose=False, timeout=None)

A byte stream.

This class implements buffered, flow controlled and blocking read/write access on top of a transport.

A stream works with bytes instances. To create a stream that works with unicode strings, you can wrap it with a io.TextIOWrapper.

The transport argument specifies the transport on top of which to create the stream.

The mode argument can be 'r' for a read-only stream, 'w' for a write-only stream, or 'rw' for a read-write stream.

The autoclose argument controls whether the underlying transport will be closed in the close() method. Be careful with this as the close method is called from the io.BufferedIOBase destructor, which may lead to unexpected closing of the transport when the stream goes out of scope.

transport

Return the transport wrapped by this stream.

wrap(encoding, **textio_args)

Return a io.TextIOWrapper that wraps the stream.

The wrapper provides text IO on top of the byte stream, using the specified encoding. The textio_args keyword arguments are additional keyword arguments passed to the TextIOWrapper constructor. Unless another buffering scheme is specified, the write_through option is enabled.

readable()

Return whether the stream is readable.

writable()

Return whether the stream is writable.

closed

Return whether the stream is closed.

buffer

Return the StreamBuffer for this stream.

switchpoint read(size=-1)

Read up to size bytes.

This function reads from the buffer multiple times until the requested number of bytes can be satisfied. This means that this function may block to wait for more data, even if some data is available. The only time a short read is returned, is on EOF or error.

If size is not specified or negative, read until EOF.

switchpoint read1(size=-1)

Read up to size bytes.

This function reads from the buffer only once. It is useful in case you need to read a large input, and want to do so efficiently. If size is big enough, then this method will return the chunks passed into the memory buffer verbatim without any copying or slicing.

switchpoint readline(limit=-1, delim=b'\n')

Read a single line.

If EOF is reached before a full line can be read, a partial line is returned. If limit is specified, at most this many bytes will be read.

switchpoint readlines(hint=-1)

Read lines until EOF, and return them as a list.

If hint is specified, then stop reading lines as soon as the total size of all lines exceeds hint.

switchpoint write(data)

Write data to the transport.

This method will block if the transport’s write buffer is at capacity.

switchpoint writelines(seq)

Write the elements of the sequence seq to the transport.

This method will block if the transport’s write buffer is at capacity.

switchpoint write_eof()

Close the write direction of the transport.

This method will block if the transport’s write buffer is at capacity.

switchpoint close()

Close the stream.

If autoclose was passed to the constructor then the underlying transport will be closed as well.

Stream Protocol

class StreamProtocol(timeout=None)

Byte stream protocol.

The timeout argument specifies a default timeout for protocol operations.

stream

A Stream instance, providing blocking, flow controlled read and write access to the underlying transport.

Stream Client and Server

class StreamClient(timeout=None)

A stream client.

stream

An alias for self.protocol.reader

switchpoint read(size=-1)

A shorthand for self.stream.read().

switchpoint read1(size=-1)

A shorthand for self.stream.read1().

switchpoint readline(limit=-1, delim=b'\n')

A shorthand for self.stream.readline().

switchpoint readlines(hint=-1)

A shorthand for self.stream.readlines().

switchpoint write(data)

A shorthand for self.stream.write().

switchpoint write_eof()

A shorthand for self.stream.write_eof().

switchpoint writelines(seq)

A shorthand for self.stream.writelines().

class StreamServer(stream_handler, timeout=None)

A stream server.

The stream_handler argument is a handler function to handle client connections. The handler will be called as stream_handler(stream, transport, protocol). The handler for each connection will run in a separate fiber so it can use blocking I/O on the stream. When the handler returns, the stream is closed.

See Example 2: echo server, using a StreamServer for an example.