StreamReader¶

classasyncio.StreamReader¶

Represents a reader object that provides APIs to read datafrom the IO stream. As anasynchronous iterable, theobject supports theasyncfor statement.

It is not recommended to instantiateStreamReader objectsdirectly; useopen_connection() andstart_server()instead.

feed_eof()¶

Acknowledge the EOF.

asyncread(n=-1)¶

Read up ton bytes from the stream.

Ifn is not provided or set to-1,read until EOF, then return all readbytes.If EOF was received and the internal buffer is empty,return an emptybytes object.

Ifn is0, return an emptybytes object immediately.

Ifn is positive, return at mostn availablebytesas soon as at least 1 byte is available in the internal buffer.If EOF is received before any byte is read, return an emptybytes object.

asyncreadline()¶

Read one line, where “line” is a sequence of bytesending with\n.

If EOF is received and\n was not found, the methodreturns partially read data.

If EOF is received and the internal buffer is empty,return an emptybytes object.

asyncreadexactly(n)¶

Read exactlyn bytes.

Raise anIncompleteReadError if EOF is reached beforencan be read. Use theIncompleteReadError.partialattribute to get the partially read data.

asyncreaduntil(separator=b'\n')¶

Read data from the stream untilseparator is found.

On success, the data and separator will be removed from theinternal buffer (consumed). Returned data will include theseparator at the end.

If the amount of data read exceeds the configured stream limit, aLimitOverrunError exception is raised, and the datais left in the internal buffer and can be read again.

If EOF is reached before the complete separator is found,anIncompleteReadError exception is raised, and the internalbuffer is reset. TheIncompleteReadError.partial attributemay contain a portion of the separator.

Theseparator may also be a tuple of separators. In thiscase the return value will be the shortest possible that has anyseparator as the suffix. For the purposes ofLimitOverrunError,the shortest possible separator is considered to be the one thatmatched.

Added in version 3.5.2.

Changed in version 3.13:Theseparator parameter may now be atuple ofseparators.

at_eof()¶

ReturnTrue if the buffer is empty andfeed_eof()was called.

StreamWriter¶

classasyncio.StreamWriter¶

Represents a writer object that provides APIs to write datato the IO stream.

It is not recommended to instantiateStreamWriter objectsdirectly; useopen_connection() andstart_server()instead.

write(data)¶

The method attempts to write thedata to the underlying socket immediately.If that fails, the data is queued in an internal write buffer until it can besent.

The method should be used along with thedrain() method:

stream.write(data)awaitstream.drain()

writelines(data)¶

The method writes a list (or any iterable) of bytes to the underlying socketimmediately.If that fails, the data is queued in an internal write buffer until it can besent.

The method should be used along with thedrain() method:

stream.writelines(lines)awaitstream.drain()

close()¶

The method closes the stream and the underlying socket.

The method should be used, though not mandatory,along with thewait_closed() method:

stream.close()awaitstream.wait_closed()

can_write_eof()¶

ReturnTrue if the underlying transport supportsthewrite_eof() method,False otherwise.

write_eof()¶

Close the write end of the stream after the buffered writedata is flushed.

transport¶

Return the underlying asyncio transport.

get_extra_info(name,default=None)¶

Access optional transport information; seeBaseTransport.get_extra_info() for details.

asyncdrain()¶

Wait until it is appropriate to resume writing to the stream.Example:

writer.write(data)awaitwriter.drain()

This is a flow control method that interacts with the underlyingIO write buffer. When the size of the buffer reachesthe high watermark,drain() blocks until the size of thebuffer is drained down to the low watermark and writing canbe resumed. When there is nothing to wait for, thedrain()returns immediately.

asyncstart_tls(sslcontext,*,server_hostname=None,ssl_handshake_timeout=None,ssl_shutdown_timeout=None)¶

Upgrade an existing stream-based connection to TLS.

Parameters:

• sslcontext: a configured instance ofSSLContext.

• server_hostname: sets or overrides the host name that the targetserver’s certificate will be matched against.

• ssl_handshake_timeout is the time in seconds to wait for the TLShandshake to complete before aborting the connection.60.0 secondsifNone (default).

• ssl_shutdown_timeout is the time in seconds to wait for the SSL shutdownto complete before aborting the connection.30.0 seconds ifNone(default).

Added in version 3.11.

Changed in version 3.12:Added thessl_shutdown_timeout parameter.

is_closing()¶

ReturnTrue if the stream is closed or in the process ofbeing closed.

Added in version 3.7.

asyncwait_closed()¶

Wait until the stream is closed.

Should be called afterclose() to wait until the underlyingconnection is closed, ensuring that all data has been flushedbefore e.g. exiting the program.

Added in version 3.7.

Examples¶

importasyncioasyncdeftcp_echo_client(message):reader,writer=awaitasyncio.open_connection('127.0.0.1',8888)print(f'Send:{message!r}')writer.write(message.encode())awaitwriter.drain()data=awaitreader.read(100)print(f'Received:{data.decode()!r}')print('Close the connection')writer.close()awaitwriter.wait_closed()asyncio.run(tcp_echo_client('Hello World!'))

importasyncioasyncdefhandle_echo(reader,writer):data=awaitreader.read(100)message=data.decode()addr=writer.get_extra_info('peername')print(f"Received{message!r} from{addr!r}")print(f"Send:{message!r}")writer.write(data)awaitwriter.drain()print("Close the connection")writer.close()awaitwriter.wait_closed()asyncdefmain():server=awaitasyncio.start_server(handle_echo,'127.0.0.1',8888)addrs=', '.join(str(sock.getsockname())forsockinserver.sockets)print(f'Serving on{addrs}')asyncwithserver:awaitserver.serve_forever()asyncio.run(main())

importasyncioimporturllib.parseimportsysasyncdefprint_http_headers(url):url=urllib.parse.urlsplit(url)ifurl.scheme=='https':reader,writer=awaitasyncio.open_connection(url.hostname,443,ssl=True)else:reader,writer=awaitasyncio.open_connection(url.hostname,80)query=(f"HEAD{url.pathor'/'} HTTP/1.0\r\n"f"Host:{url.hostname}\r\n"f"\r\n")writer.write(query.encode('latin-1'))whileTrue:line=awaitreader.readline()ifnotline:breakline=line.decode('latin1').rstrip()ifline:print(f'HTTP header>{line}')# Ignore the body, close the socketwriter.close()awaitwriter.wait_closed()url=sys.argv[1]asyncio.run(print_http_headers(url))

pythonexample.pyhttp://example.com/path/page.html

pythonexample.pyhttps://example.com/path/page.html

importasyncioimportsocketasyncdefwait_for_data():# Get a reference to the current event loop because# we want to access low-level APIs.loop=asyncio.get_running_loop()# Create a pair of connected sockets.rsock,wsock=socket.socketpair()# Register the open socket to wait for data.reader,writer=awaitasyncio.open_connection(sock=rsock)# Simulate the reception of data from the networkloop.call_soon(wsock.send,'abc'.encode())# Wait for datadata=awaitreader.read(100)# Got data, we are done: close the socketprint("Received:",data.decode())writer.close()awaitwriter.wait_closed()# Close the second socketwsock.close()asyncio.run(wait_for_data())