From: Ben Darnell Date: Sun, 27 Apr 2014 00:13:46 +0000 (-0400) Subject: Update docs for changes in 3.3. X-Git-Tag: v4.0.0b1~92 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5a1497dfaf8e4252972a41e9e22d077423675437;p=thirdparty%2Ftornado.git Update docs for changes in 3.3. --- diff --git a/docs/concurrent.rst b/docs/concurrent.rst index 378adc9a4..051c91ab1 100644 --- a/docs/concurrent.rst +++ b/docs/concurrent.rst @@ -3,43 +3,25 @@ .. automodule:: tornado.concurrent :members: + :exclude-members: Future, TracebackFuture - .. py:class:: Future + .. autoclass:: Future - A ``Future`` encapsulates the result of an asynchronous - operation. In synchronous applications ``Futures`` are used - to wait for the result from a thread or process pool; in - Tornado they are normally used with `.IOLoop.add_future` or by - yielding them in a `.gen.coroutine`. + Consumer methods + ^^^^^^^^^^^^^^^^ - If the `concurrent.futures` package is available, - `tornado.concurrent.Future` is simply an alias for - `concurrent.futures.Future`. Otherwise, we support the same - interface with a few limitations: + .. automethod:: Future.result + .. automethod:: Future.exception + .. automethod:: Future.exc_info + .. automethod:: Future.add_done_callback + .. automethod:: Future.done + .. automethod:: Future.running + .. automethod:: Future.cancel + .. automethod:: Future.cancelled - * It is an error to call `result` or `exception` before the - ``Future`` has completed. - * Cancellation is not supported. + Producer methods + ^^^^^^^^^^^^^^^^ - .. py:method:: result() - - If the operation succeeded, return its result. If it failed, - re-raise its exception. - - .. py:method:: exception() - - If the operation raised an exception, return the `Exception` - object. Otherwise returns None. - - .. py:method:: add_done_callback(fn) - - Attaches the given callback to the `Future`. It will be invoked - with the `Future` as its argument when it has finished running - and its result is available. In Tornado consider using - `.IOLoop.add_future` instead of calling `add_done_callback` - directly. - - .. py:method:: done() - - Returns True if the future has finished running and its - `result` and `exception` methods are available. + .. automethod:: Future.set_result + .. automethod:: Future.set_exception + .. automethod:: Future.set_exc_info diff --git a/docs/ioloop.rst b/docs/ioloop.rst index 6978c39c2..bd364cc4d 100644 --- a/docs/ioloop.rst +++ b/docs/ioloop.rst @@ -16,6 +16,7 @@ .. automethod:: IOLoop.instance .. automethod:: IOLoop.initialized .. automethod:: IOLoop.install + .. automethod:: IOLoop.clear_instance .. automethod:: IOLoop.start .. automethod:: IOLoop.stop .. automethod:: IOLoop.run_sync diff --git a/docs/releases/next.rst b/docs/releases/next.rst index bc3337c01..e08593c68 100644 --- a/docs/releases/next.rst +++ b/docs/releases/next.rst @@ -77,17 +77,11 @@ Backwards-compatibility notes * Now works on Python 2.6. -`tornado.simple_httpclient` -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``tornado.simple_httpclient`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * Improved default cipher suite selection (Python 2.7+). -`tornado.speedups` -~~~~~~~~~~~~~~~~~~ - -* The C extension now builds on windows in both 32 and 64-bit modes. -* The fallback mechanism for detecting a missing C compiler now - works correctly on Mac OS X. `tornado.stack_context` ~~~~~~~~~~~~~~~~~~~~~~~ @@ -120,3 +114,5 @@ Backwards-compatibility notes values when the other side closes. * The C speedup module now builds correctly with MSVC, and can support messages larger than 2GB on 64-bit systems. +* The fallback mechanism for detecting a missing C compiler now + works correctly on Mac OS X. diff --git a/docs/releases/v3.2.0.rst b/docs/releases/v3.2.0.rst index 7e5299e9f..3e9593934 100644 --- a/docs/releases/v3.2.0.rst +++ b/docs/releases/v3.2.0.rst @@ -32,7 +32,7 @@ New modules `tornado.concurrent` ~~~~~~~~~~~~~~~~~~~~ -* `.TracebackFuture` now accepts a ``timeout`` keyword argument (although +* ``TracebackFuture`` now accepts a ``timeout`` keyword argument (although it is still incorrect to use a non-zero timeout in non-blocking code). ``tornado.curl_httpclient`` diff --git a/tornado/concurrent.py b/tornado/concurrent.py index ab7b65c3a..3ae2f7270 100644 --- a/tornado/concurrent.py +++ b/tornado/concurrent.py @@ -43,8 +43,15 @@ class ReturnValueIgnoredError(Exception): class Future(object): """Placeholder for an asynchronous result. - Similar to `concurrent.futures.Future`, but not thread-safe (and - therefore faster for use with single-threaded event loops. + A ``Future`` encapsulates the result of an asynchronous + operation. In synchronous applications ``Futures`` are used + to wait for the result from a thread or process pool; in + Tornado they are normally used with `.IOLoop.add_future` or by + yielding them in a `.gen.coroutine`. + + `tornado.concurrent.Future` is similar to + `concurrent.futures.Future`, but not thread-safe (and therefore + faster for use with single-threaded event loops). In addition to ``exception`` and ``set_exception``, methods ``exc_info`` and ``set_exc_info`` are supported to capture tracebacks in Python 2. @@ -52,6 +59,14 @@ class Future(object): Python 2 futures backport this information is discarded. This functionality was previously available in a separate class ``TracebackFuture``, which is now a deprecated alias for this class. + + .. versionchanged:: 3.3 + `tornado.concurrent.Future` is always a thread-unsafe ``Future`` + with support for the ``exc_info`` methods. Previously it would + be an alias for the thread-safe `concurrent.futures.Future` + if that package was available and fall back to the thread-unsafe + implementation if it was not. + """ def __init__(self): self._done = False @@ -61,18 +76,33 @@ class Future(object): self._callbacks = [] def cancel(self): + """Cancel the operation, if possible. + + Tornado ``Futures`` do not support cancellation, so this method always + returns False. + """ return False def cancelled(self): + """Returns True if the operation has been cancelled. + + Tornado ``Futures`` do not support cancellation, so this method + always returns False. + """ return False def running(self): + """Returns True if this operation is currently running.""" return not self._done def done(self): + """Returns True if the future has finished running.""" return self._done def result(self, timeout=None): + """If the operation succeeded, return its result. If it failed, + re-raise its exception. + """ if self._result is not None: return self._result if self._exc_info is not None: @@ -83,6 +113,9 @@ class Future(object): return self._result def exception(self, timeout=None): + """If the operation raised an exception, return the `Exception` + object. Otherwise returns None. + """ if self._exception is not None: return self._exception else: @@ -90,25 +123,45 @@ class Future(object): return None def add_done_callback(self, fn): + """Attaches the given callback to the `Future`. + + It will be invoked with the `Future` as its argument when the Future + has finished running and its result is available. In Tornado + consider using `.IOLoop.add_future` instead of calling + `add_done_callback` directly. + """ if self._done: fn(self) else: self._callbacks.append(fn) def set_result(self, result): + """Sets the result of a ``Future``. + + It is undefined to call any of the ``set`` methods more than once + on the same object. + """ self._result = result self._set_done() def set_exception(self, exception): + """Sets the exception of a ``Future.``""" self._exception = exception self._set_done() def exc_info(self): + """Returns a tuple in the same format as `sys.exc_info` or None. + + .. versionadded:: 3.3 + """ return self._exc_info def set_exc_info(self, exc_info): - """Traceback-aware replacement for - `~concurrent.futures.Future.set_exception`. + """Sets the exception information of a ``Future.`` + + Preserves tracebacks on Python 2. + + .. versionadded:: 3.3 """ self._exc_info = exc_info self.set_exception(exc_info[1]) diff --git a/tornado/iostream.py b/tornado/iostream.py index 651a3a899..1376bade9 100644 --- a/tornado/iostream.py +++ b/tornado/iostream.py @@ -71,8 +71,13 @@ class BaseIOStream(object): """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 callbacks (since writing and reading are - non-blocking and asynchronous). + All of the methods take an optional ``callback`` argument and return a + `.Future` only if no callback is given. When the operation completes, + the callback will be run or the `.Future` will resolve with the data + read (or ``None`` for ``write()``). All outstanding ``Futures`` will + resolve with a `StreamClosedError` when the stream is closed; users + of the callback interface will be notified via + `.BaseIOStream.set_close_callback` instead. When a stream is closed due to an error, the IOStream's ``error`` attribute contains the exception object. @@ -147,10 +152,16 @@ class BaseIOStream(object): return None def read_until_regex(self, regex, callback=None): - """Run ``callback`` when we read the given regex pattern. + """Asynchronously read until we have matched the given regex. - The callback will get the data read (including the data that - matched the regex and anything that came before it) as an argument. + The result includes the data that matches the regex and anything + that came before it. If a callback is given, it will be run + with the data as an argument; if not, this method returns a + `.Future`. + + .. versionchanged:: 3.3 + The callback argument is now optional and a `.Future` will + be returned if it is omitted. """ future = self._set_read_callback(callback) self._read_regex = re.compile(regex) @@ -158,10 +169,15 @@ class BaseIOStream(object): return future def read_until(self, delimiter, callback=None): - """Run ``callback`` when we read the given delimiter. + """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`. - The callback will get the data read (including the delimiter) - as an argument. + .. versionchanged:: 3.3 + The callback argument is now optional and a `.Future` will + be returned if it is omitted. """ future = self._set_read_callback(callback) self._read_delimiter = delimiter @@ -169,12 +185,17 @@ class BaseIOStream(object): return future def read_bytes(self, num_bytes, callback=None, streaming_callback=None): - """Run callback when we read the given number of bytes. + """Asynchronously read a number of bytes. If a ``streaming_callback`` is given, it will be called with chunks - of data as they become available, and the argument to the final - ``callback`` will be empty. Otherwise, the ``callback`` gets - the data as an argument. + of 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`. + + .. versionchanged:: 3.3 + The callback argument is now optional and a `.Future` will + be returned if it is omitted. """ future = self._set_read_callback(callback) assert isinstance(num_bytes, numbers.Integral) @@ -184,15 +205,17 @@ class BaseIOStream(object): return future def read_until_close(self, callback=None, streaming_callback=None): - """Reads all data from the socket until it is closed. + """Asynchronously reads all data from the socket until it is closed. If a ``streaming_callback`` is given, it will be called with chunks - of data as they become available, and the argument to the final - ``callback`` will be empty. Otherwise, the ``callback`` gets the - data as an argument. - - Subject to ``max_buffer_size`` limit from `IOStream` constructor if - a ``streaming_callback`` is not used. + of 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`. + + .. versionchanged:: 3.3 + The callback argument is now optional and a `.Future` will + be returned if it is omitted. """ future = self._set_read_callback(callback) self._streaming_callback = stack_context.wrap(streaming_callback) @@ -207,12 +230,20 @@ class BaseIOStream(object): return future def write(self, data, callback=None): - """Write the given data to this stream. + """Asynchronously write the given data to this stream. If ``callback`` is given, we call it when all of the buffered write data has been successfully written to the stream. If there was previously buffered write data and an old write callback, that callback is simply overwritten with this new callback. + + If no ``callback`` is given, this method returns a `.Future` that + resolves (with a result of ``None``) when the write has been + completed. If `write` is called again before that `.Future` has + resolved, the previous future will be orphaned and will never resolve. + + .. versionchanged:: 3.3 + Now returns a `.Future` if no callback is given. """ assert isinstance(data, bytes_type) self._check_closed() @@ -238,7 +269,12 @@ class BaseIOStream(object): return future def set_close_callback(self, callback): - """Call the given callback when the stream is closed.""" + """Call the given callback when the stream is closed. + + This is not necessary for applications that use the `.Future` + interface; all outstanding ``Futures`` will resolve with a + `StreamClosedError` when the stream is closed. + """ self._close_callback = stack_context.wrap(callback) def close(self, exc_info=False): @@ -741,7 +777,8 @@ class IOStream(BaseIOStream): not previously connected. The address parameter is in the same format as for `socket.connect `, i.e. a ``(host, port)`` tuple. If ``callback`` is specified, - it will be called when the connection is completed. + it will be called when the connection is completed; if not + this method returns a `.Future`. If specified, the ``server_hostname`` parameter will be used in SSL connections for certificate validation (if requested in @@ -753,6 +790,9 @@ class IOStream(BaseIOStream): which case the data will be written as soon as the connection is ready. Calling `IOStream` read methods before the socket is connected works on some platforms but is non-portable. + + .. versionchanged:: 3.3 + If no callback is given, returns a `.Future`. """ self._connecting = True try: diff --git a/tornado/web.py b/tornado/web.py index e2ef7eef4..4b9300fbe 100644 --- a/tornado/web.py +++ b/tornado/web.py @@ -2299,6 +2299,11 @@ class GZipContentEncoding(OutputTransform): """Applies the gzip content encoding to the response. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11 + + .. versionchanged:: 3.3 + Now compresses all mime types beginning with ``text/``, instead + of just a whitelist. (the whitelist is still used for certain + non-text mime types). """ # Whitelist of compressible mime types (in addition to any types # beginning with "text/").