### Navigation - [index](# "General Index") - [modules](# "Python Module Index") | - [next](# "tornado.netutil — Miscellaneous network utilities") | - [previous](# "tornado.ioloop — Main event loop") | - [Tornado 4.4.dev1 documentation](#) » - [Asynchronous networking](#) » # `tornado.iostream` — Convenient wrappers for non-blocking sockets Utility classes to write to and read from non-blocking files and sockets. Contents: - [`BaseIOStream`](# "tornado.iostream.BaseIOStream"): Generic interface for reading and writing. - [`IOStream`](# "tornado.iostream.IOStream"): Implementation of BaseIOStream using non-blocking sockets. - [`SSLIOStream`](# "tornado.iostream.SSLIOStream"): SSL-aware version of IOStream. - [`PipeIOStream`](# "tornado.iostream.PipeIOStream"): Pipe-based IOStream implementation. ### Base class *class *`tornado.iostream.``BaseIOStream`(*io_loop=None*, *max_buffer_size=None*, *read_chunk_size=None*, *max_write_buffer_size=None*)[[source]](#) A utility class to write to and read from a non-blocking file or socket. We support a non-blocking `write()` and a family of `read_*()` methods.All of the methods take an optional `callback` argument and return a[`Future`](# "tornado.concurrent.Future") only if no callback is given. When the operation completes,the callback will be run or the [`Future`](# "tornado.concurrent.Future") will resolve with the dataread (or `None` for `write()`). All outstanding `Futures` willresolve with a [`StreamClosedError`](# "tornado.iostream.StreamClosedError") when the stream is closed; usersof the callback interface will be notified via[`BaseIOStream.set_close_callback`](# "tornado.iostream.BaseIOStream.set_close_callback") instead. When a stream is closed due to an error, the IOStream's `error`attribute contains the exception object. Subclasses must implement [`fileno`](# "tornado.iostream.BaseIOStream.fileno"), [`close_fd`](# "tornado.iostream.BaseIOStream.close_fd"), [`write_to_fd`](# "tornado.iostream.BaseIOStream.write_to_fd"),[`read_from_fd`](# "tornado.iostream.BaseIOStream.read_from_fd"), and optionally [`get_fd_error`](# "tornado.iostream.BaseIOStream.get_fd_error"). [`BaseIOStream`](# "tornado.iostream.BaseIOStream") constructor. <table class="docutils field-list" frame="void" rules="none"><col class="field-name"/><col class="field-body"/><tbody valign="top"><tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"><li><strong>io_loop</strong> – The <a class="reference internal" href="ioloop.html#tornado.ioloop.IOLoop" title="tornado.ioloop.IOLoop"><code class="xref py py-obj docutils literal"><span class="pre">IOLoop</span></code></a> to use; defaults to <a class="reference internal" href="ioloop.html#tornado.ioloop.IOLoop.current" title="tornado.ioloop.IOLoop.current"><code class="xref py py-obj docutils literal"><span class="pre">IOLoop.current</span></code></a>.Deprecated since Tornado 4.1.</li><li><strong>max_buffer_size</strong> – Maximum amount of incoming data to buffer;defaults to 100MB.</li><li><strong>read_chunk_size</strong> – Amount of data to read at one time from theunderlying transport; defaults to 64KB.</li><li><strong>max_write_buffer_size</strong> – Amount of outgoing data to buffer;defaults to unlimited.</li></ul></td></tr></tbody></table> Changed in version 4.0: Add the `max_write_buffer_size` parameter. Changed default`read_chunk_size` to 64KB. ### Main interface `BaseIOStream.``write`(*data*, *callback=None*)[[source]](#) Asynchronously write the given data to this stream. If `callback` is given, we call it when all of the buffered writedata has been successfully written to the stream. If there waspreviously buffered write data and an old write callback, thatcallback is simply overwritten with this new callback. If no `callback` is given, this method returns a [`Future`](# "tornado.concurrent.Future") thatresolves (with a result of `None`) when the write has beencompleted. If [`write`](# "tornado.iostream.BaseIOStream.write") is called again before that [`Future`](# "tornado.concurrent.Future") hasresolved, the previous future will be orphaned and will never resolve. Changed in version 4.0: Now returns a [`Future`](# "tornado.concurrent.Future") if no callback is given. `BaseIOStream.``read_bytes`(*num_bytes*, *callback=None*, *streaming_callback=None*, *partial=False*)[[source]](#) Asynchronously read a number of bytes. If a `streaming_callback` is given, it will be called with chunksof data as they become available, and the final result will be empty.Otherwise, the result is all the data that was read.If a callback is given, it will be run with the data as an argument;if not, this method returns a [`Future`](# "tornado.concurrent.Future"). If `partial` is true, the callback is run as soon as we haveany bytes to return (but never more than `num_bytes`) Changed in version 4.0: Added the `partial` argument. The callback argument is nowoptional and a [`Future`](# "tornado.concurrent.Future") will be returned if it is omitted. `BaseIOStream.``read_until`(*delimiter*, *callback=None*, *max_bytes=None*)[[source]](#) Asynchronously read until we have found the given delimiter. The result includes all the data read including the delimiter.If a callback is given, it will be run with the data as an argument;if not, this method returns a [`Future`](# "tornado.concurrent.Future"). If `max_bytes` is not None, the connection will be closedif more than `max_bytes` bytes have been read and the delimiteris not found. Changed in version 4.0: Added the `max_bytes` argument. The `callback` argument isnow optional and a [`Future`](# "tornado.concurrent.Future") will be returned if it is omitted. `BaseIOStream.``read_until_regex`(*regex*, *callback=None*, *max_bytes=None*)[[source]](#) Asynchronously read until we have matched the given regex. The result includes the data that matches the regex and anythingthat came before it. If a callback is given, it will be runwith the data as an argument; if not, this method returns a[`Future`](# "tornado.concurrent.Future"). If `max_bytes` is not None, the connection will be closedif more than `max_bytes` bytes have been read and the regex isnot satisfied. Changed in version 4.0: Added the `max_bytes` argument. The `callback` argument isnow optional and a [`Future`](# "tornado.concurrent.Future") will be returned if it is omitted. `BaseIOStream.``read_until_close`(*callback=None*, *streaming_callback=None*)[[source]](#) Asynchronously reads all data from the socket until it is closed. If a `streaming_callback` is given, it will be called with chunksof data as they become available, and the final result will be empty.Otherwise, the result is all the data that was read.If a callback is given, it will be run with the data as an argument;if not, this method returns a [`Future`](# "tornado.concurrent.Future"). Note that if a `streaming_callback` is used, data will beread from the socket as quickly as it becomes available; thereis no way to apply backpressure or cancel the reads. If flowcontrol or cancellation are desired, use a loop with[`read_bytes(partial=True)`](# "tornado.iostream.BaseIOStream.read_bytes") instead. Changed in version 4.0: The callback argument is now optional and a [`Future`](# "tornado.concurrent.Future") willbe returned if it is omitted. `BaseIOStream.``close`(*exc_info=False*)[[source]](#) Close this stream. If `exc_info` is true, set the `error` attribute to the currentexception from [`sys.exc_info`](https://docs.python.org/3.4/library/sys.html#sys.exc_info "(in Python v3.4)") [https://docs.python.org/3.4/library/sys.html#sys.exc_info] (or if `exc_info` is a tuple,use that instead of [`sys.exc_info`](https://docs.python.org/3.4/library/sys.html#sys.exc_info "(in Python v3.4)") [https://docs.python.org/3.4/library/sys.html#sys.exc_info]). `BaseIOStream.``set_close_callback`(*callback*)[[source]](#) Call the given callback when the stream is closed. This is not necessary for applications that use the [`Future`](# "tornado.concurrent.Future")interface; all outstanding `Futures` will resolve with a[`StreamClosedError`](# "tornado.iostream.StreamClosedError") when the stream is closed. `BaseIOStream.``closed`()[[source]](#) Returns true if the stream has been closed. `BaseIOStream.``reading`()[[source]](#) Returns true if we are currently reading from the stream. `BaseIOStream.``writing`()[[source]](#) Returns true if we are currently writing to the stream. `BaseIOStream.``set_nodelay`(*value*)[[source]](#) Sets the no-delay flag for this stream. By default, data written to TCP streams may be held for a timeto make the most efficient use of bandwidth (according toNagle's algorithm). The no-delay flag requests that data bewritten as soon as possible, even if doing so would consumeadditional bandwidth. This flag is currently defined only for TCP-based `IOStreams`. New in version 3.1. ### Methods for subclasses `BaseIOStream.``fileno`()[[source]](#) Returns the file descriptor for this stream. `BaseIOStream.``close_fd`()[[source]](#) Closes the file underlying this stream. `close_fd` is called by [`BaseIOStream`](# "tornado.iostream.BaseIOStream") and should not be calledelsewhere; other users should call [`close`](# "tornado.iostream.BaseIOStream.close") instead. `BaseIOStream.``write_to_fd`(*data*)[[source]](#) Attempts to write `data` to the underlying file. Returns the number of bytes written. `BaseIOStream.``read_from_fd`()[[source]](#) Attempts to read from the underlying file. Returns `None` if there was nothing to read (the socketreturned [`EWOULDBLOCK`](https://docs.python.org/3.4/library/errno.html#errno.EWOULDBLOCK "(in Python v3.4)") [https://docs.python.org/3.4/library/errno.html#errno.EWOULDBLOCK] or equivalent), otherwisereturns the data. When possible, should return no more than`self.read_chunk_size` bytes at a time. `BaseIOStream.``get_fd_error`()[[source]](#) Returns information about any error on the underlying file. This method is called after the [`IOLoop`](# "tornado.ioloop.IOLoop") has signaled an error on thefile descriptor, and should return an Exception (such as [`socket.error`](https://docs.python.org/3.4/library/socket.html#socket.error "(in Python v3.4)") [https://docs.python.org/3.4/library/socket.html#socket.error]with additional information, or None if no such information isavailable. ### Implementations *class *`tornado.iostream.``IOStream`(*socket*, **args*, ***kwargs*)[[source]](#) Socket-based [`IOStream`](# "tornado.iostream.IOStream") implementation. This class supports the read and write methods from [`BaseIOStream`](# "tornado.iostream.BaseIOStream")plus a [`connect`](# "tornado.iostream.IOStream.connect") method. The `socket` parameter may either be connected or unconnected.For server operations the socket is the result of calling[`socket.accept`](https://docs.python.org/3.4/library/socket.html#socket.socket.accept "(in Python v3.4)") [https://docs.python.org/3.4/library/socket.html#socket.socket.accept]. For client operations thesocket is created with [`socket.socket`](https://docs.python.org/3.4/library/socket.html#socket.socket "(in Python v3.4)") [https://docs.python.org/3.4/library/socket.html#socket.socket], and may either beconnected before passing it to the [`IOStream`](# "tornado.iostream.IOStream") or connected with[`IOStream.connect`](# "tornado.iostream.IOStream.connect"). A very simple (and broken) HTTP client using this class: ~~~ import tornado.ioloop import tornado.iostream import socket def send_request(): stream.write(b"GET / HTTP/1.0\r\nHost: friendfeed.com\r\n\r\n") stream.read_until(b"\r\n\r\n", on_headers) def on_headers(data): headers = {} for line in data.split(b"\r\n"): parts = line.split(b":") if len(parts) == 2: headers[parts[0].strip()] = parts[1].strip() stream.read_bytes(int(headers[b"Content-Length"]), on_body) def on_body(data): print(data) stream.close() tornado.ioloop.IOLoop.current().stop() if __name__ == '__main__': s = socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0) stream = tornado.iostream.IOStream(s) stream.connect(("friendfeed.com", 80), send_request) tornado.ioloop.IOLoop.current().start() ~~~ `connect`(*address*, *callback=None*, *server_hostname=None*)[[source]](#) Connects the socket to a remote address without blocking. May only be called if the socket passed to the constructor wasnot previously connected. The address parameter is in thesame format as for [`socket.connect`](https://docs.python.org/3.4/library/socket.html#socket.socket.connect "(in Python v3.4)") [https://docs.python.org/3.4/library/socket.html#socket.socket.connect] forthe type of socket passed to the IOStream constructor,e.g. an `(ip, port)` tuple. Hostnames are accepted here,but will be resolved synchronously and block the IOLoop.If you have a hostname instead of an IP address, the [`TCPClient`](# "tornado.tcpclient.TCPClient")class is recommended instead of calling this method directly.[`TCPClient`](# "tornado.tcpclient.TCPClient") will do asynchronous DNS resolution and handleboth IPv4 and IPv6. If `callback` is specified, it will be called with noarguments when the connection is completed; if not this methodreturns a [`Future`](# "tornado.concurrent.Future") (whose result after a successfulconnection will be the stream itself). In SSL mode, the `server_hostname` parameter will be usedfor certificate validation (unless disabled in the`ssl_options`) and SNI (if supported; requires Python2.7.9+). Note that it is safe to call [`IOStream.write`](# "tornado.iostream.BaseIOStream.write") while the connection is pending, inwhich case the data will be written as soon as the connectionis ready. Calling [`IOStream`](# "tornado.iostream.IOStream") read methods before the socket isconnected works on some platforms but is non-portable. Changed in version 4.0: If no callback is given, returns a [`Future`](# "tornado.concurrent.Future"). Changed in version 4.2: SSL certificates are validated by default; pass`ssl_options=dict(cert_reqs=ssl.CERT_NONE)` or asuitably-configured [`ssl.SSLContext`](https://docs.python.org/3.4/library/ssl.html#ssl.SSLContext "(in Python v3.4)") [https://docs.python.org/3.4/library/ssl.html#ssl.SSLContext] to the[`SSLIOStream`](# "tornado.iostream.SSLIOStream") constructor to disable. `start_tls`(*server_side*, *ssl_options=None*, *server_hostname=None*)[[source]](#) Convert this [`IOStream`](# "tornado.iostream.IOStream") to an [`SSLIOStream`](# "tornado.iostream.SSLIOStream"). This enables protocols that begin in clear-text mode andswitch to SSL after some initial negotiation (such as the`STARTTLS` extension to SMTP and IMAP). This method cannot be used if there are outstanding readsor writes on the stream, or if there is any data in theIOStream's buffer (data in the operating system's socketbuffer is allowed). This means it must generally be usedimmediately after reading or writing the last clear-textdata. It can also be used immediately after connecting,before any reads or writes. The `ssl_options` argument may be either an [`ssl.SSLContext`](https://docs.python.org/3.4/library/ssl.html#ssl.SSLContext "(in Python v3.4)") [https://docs.python.org/3.4/library/ssl.html#ssl.SSLContext]object or a dictionary of keyword arguments for the[`ssl.wrap_socket`](https://docs.python.org/3.4/library/ssl.html#ssl.wrap_socket "(in Python v3.4)") [https://docs.python.org/3.4/library/ssl.html#ssl.wrap_socket] function. The `server_hostname` argumentwill be used for certificate validation unless disabledin the `ssl_options`. This method returns a [`Future`](# "tornado.concurrent.Future") whose result is the new[`SSLIOStream`](# "tornado.iostream.SSLIOStream"). After this method has been called,any other operation on the original stream is undefined. If a close callback is defined on this stream, it will betransferred to the new stream. New in version 4.0. Changed in version 4.2: SSL certificates are validated by default; pass`ssl_options=dict(cert_reqs=ssl.CERT_NONE)` or asuitably-configured [`ssl.SSLContext`](https://docs.python.org/3.4/library/ssl.html#ssl.SSLContext "(in Python v3.4)") [https://docs.python.org/3.4/library/ssl.html#ssl.SSLContext] to disable. *class *`tornado.iostream.``SSLIOStream`(**args*, ***kwargs*)[[source]](#) A utility class to write to and read from a non-blocking SSL socket. If the socket passed to the constructor is already connected,it should be wrapped with: ~~~ ssl.wrap_socket(sock, do_handshake_on_connect=False, **kwargs) ~~~ before constructing the [`SSLIOStream`](# "tornado.iostream.SSLIOStream"). Unconnected sockets will bewrapped when [`IOStream.connect`](# "tornado.iostream.IOStream.connect") is finished. The `ssl_options` keyword argument may either be an[`ssl.SSLContext`](https://docs.python.org/3.4/library/ssl.html#ssl.SSLContext "(in Python v3.4)") [https://docs.python.org/3.4/library/ssl.html#ssl.SSLContext] object or a dictionary of keywords argumentsfor [`ssl.wrap_socket`](https://docs.python.org/3.4/library/ssl.html#ssl.wrap_socket "(in Python v3.4)") [https://docs.python.org/3.4/library/ssl.html#ssl.wrap_socket] `wait_for_handshake`(*callback=None*)[[source]](#) Wait for the initial SSL handshake to complete. If a `callback` is given, it will be called with noarguments once the handshake is complete; otherwise thismethod returns a [`Future`](# "tornado.concurrent.Future") which will resolve to thestream itself after the handshake is complete. Once the handshake is complete, information such asthe peer's certificate and NPN/ALPN selections may beaccessed on `self.socket`. This method is intended for use on server-side streamsor after using [`IOStream.start_tls`](# "tornado.iostream.IOStream.start_tls"); it should not be usedwith [`IOStream.connect`](# "tornado.iostream.IOStream.connect") (which already waits for thehandshake to complete). It may only be called once per stream. New in version 4.2. *class *`tornado.iostream.``PipeIOStream`(*fd*, **args*, ***kwargs*)[[source]](#) Pipe-based [`IOStream`](# "tornado.iostream.IOStream") implementation. The constructor takes an integer file descriptor (such as one returnedby [`os.pipe`](https://docs.python.org/3.4/library/os.html#os.pipe "(in Python v3.4)") [https://docs.python.org/3.4/library/os.html#os.pipe]) rather than an open file object. Pipes are generallyone-way, so a [`PipeIOStream`](# "tornado.iostream.PipeIOStream") can be used for reading or writing but notboth. ### Exceptions *exception *`tornado.iostream.``StreamBufferFullError`[[source]](#) Exception raised by [`IOStream`](# "tornado.iostream.IOStream") methods when the buffer is full. *exception *`tornado.iostream.``StreamClosedError`(*real_error=None*)[[source]](#) Exception raised by [`IOStream`](# "tornado.iostream.IOStream") methods when the stream is closed. Note that the close callback is scheduled to run *after* othercallbacks on the stream (to allow for buffered data to be processed),so you may see this error before you see the close callback. The `real_error` attribute contains the underlying error that causedthe stream to close (if any). Changed in version 4.3: Added the `real_error` attribute. *exception *`tornado.iostream.``UnsatisfiableReadError`[[source]](#) Exception raised when a read cannot be satisfied. Raised by `read_until` and `read_until_regex` with a `max_bytes`argument. © Copyright 2009-2016, The Tornado Authors. Created using [Sphinx](http://sphinx-doc.org/) 1.3.5.