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 aio.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 theio.BufferedIOBase
destructor, which may lead to unexpected closing of the transport when the stream goes out of scope.-
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¶
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.