From: Ben Darnell Date: Mon, 4 Mar 2013 03:47:30 +0000 (-0500) Subject: Organize release notes and add highlights section. X-Git-Tag: v3.0.0~62 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7f2bcfe831cdf90c0ce79b3fc4b558d0837f374b;p=thirdparty%2Ftornado.git Organize release notes and add highlights section. --- diff --git a/website/sphinx/releases/next.rst b/website/sphinx/releases/next.rst index 0932867c9..ecaeb8704 100644 --- a/website/sphinx/releases/next.rst +++ b/website/sphinx/releases/next.rst @@ -4,8 +4,55 @@ What's new in the next release of Tornado In progress ----------- -General -~~~~~~~ +Highlights +^^^^^^^^^^ + +* The ``callback`` argument to many asynchronous methods is now optional, + and these methods return a `Future`. The `tornado.gen` module now + understands `Futures`, and these methods can be used directly without + a `gen.Task` wrapper. +* New function `IOLoop.current` returns the `IOLoop` that is running + on the current thread (as opposed to `IOLoop.instance`, which + returns a specific thread's (usually the main thread's) IOLoop. +* New class `tornado.netutil.Resolver` provides an asynchronous + interface to DNS resolution. The default implementation is still + blocking, but non-blocking implementations are available using one + of three optional dependencies: `~tornado.netutil.ThreadedResolver` + using the `concurrent.futures` thread pool, + `~tornado.platform.caresresolver.CaresResolver` using the `pycares` + library, or `~tornado.platform.twisted.TwistedResolver` using `twisted` +* Tornado's logging is now less noisy, and it no longer goes directly + to the root logger, allowing for finer-grained configuration. +* New class `tornado.process.Subprocess` wraps `subprocess.Popen` with + `PipeIOStream` access to the child's file descriptors. +* `IOLoop` now has a static ``configure`` method like the one on + `AsyncHTTPClient`, which can be used to select an IOLoop implementation + other than the default. +* `IOLoop` can now optionally use a monotonic clock if available + (see below for more details). + + +Backwards-incompatible changes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Python 2.5 is no longer supported. Python 3 is now supported in a single + codebase instead of using ``2to3`` +* The `tornado.database` module has been removed. It is now available + as a separate package, `torndb `_ +* Functions that take an ``io_loop`` parameter now default to + `IOLoop.current()` instead of `IOLoop.instance()`. +* Empty HTTP request arguments are no longer ignored. This applies to + ``HTTPRequest.arguments`` and ``RequestHandler.get_argument[s]`` + in WSGI and non-WSGI modes. +* `tornado.netutil.TCPServer` has moved to its own module, `tornado.tcpserver`. +* The Tornado test suite now requires ``unittest2`` when run on Python 2.6. + + +Detailed changes by module +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Multiple modules +~~~~~~~~~~~~~~~~ * Tornado no longer logs to the root logger. Details on the new logging scheme can be found under the `tornado.log` module. Note that in some @@ -13,7 +60,6 @@ General in order to see any output (perhaps just calling ``logging.basicConfig()``), although both `IOLoop.start()` and `tornado.options.parse_command_line` will do this for you. -* Installation under Python 3 no longer uses ``2to3``. * On python 3.2+, methods that take an ``ssl_options`` argument (on `SSLIOStream`, `TCPServer`, and `HTTPServer`) now accept either a dictionary of options or an `ssl.SSLContext` object. @@ -21,12 +67,6 @@ General for working with threads. `concurrent.futures` is in the standard library for Python 3.2+, and can be installed on older versions with ``pip install futures``. -* The `tornado.database` module has been removed. It is now available - as a separate package, `torndb `_ -* Python 2.5 is no longer supported. -* The Tornado test suite now requires ``unittest2`` when run on Python 2.6. -* Functions that take an ``io_loop`` parameter now default to - `IOLoop.current()` instead of `IOLoop.instance()`. `tornado.autoreload` ~~~~~~~~~~~~~~~~~~~~ @@ -43,13 +83,13 @@ General `tornado.auth` ~~~~~~~~~~~~~~ -* The `tornado.auth` mixin classes now define a method - ``get_auth_http_client``, which can be overridden to use a non-default - `AsyncHTTPClient` instance (e.g. to use a different `IOLoop`) * Asynchronous methods defined in `tornado.auth` now return a `Future`, and their ``callback`` argument is optional. The `Future` interface is preferred as it offers better error handling (the previous interface just logged a warning and returned None). +* The `tornado.auth` mixin classes now define a method + ``get_auth_http_client``, which can be overridden to use a non-default + `AsyncHTTPClient` instance (e.g. to use a different `IOLoop`) * Subclasses of `OAuthMixin` are encouraged to override `_oauth_get_user_future` instead of `_oauth_get_user`, although both methods are still supported. @@ -75,26 +115,22 @@ General `tornado.gen` ~~~~~~~~~~~~~ -* Functions using `gen.engine` may now yield ``Future`` objects. -* Fixed a memory leak involving ``gen.engine``, `RequestHandler.flush`, - and clients closing connections while output is being written. -* Yielding a large list no longer has quadratic performance. * New decorator ``@gen.coroutine`` is available as an alternative to ``@gen.engine``. It automatically returns a `Future`, and within the function instead of calling a callback you return a value with ``raise gen.Return(value)`` (or simply ``return value`` in Python 3.3). +* Generators may now yield ``Future`` objects. +* Fixed a memory leak involving generators, `RequestHandler.flush`, + and clients closing connections while output is being written. +* Yielding a large list no longer has quadratic performance. `tornado.httpclient` ~~~~~~~~~~~~~~~~~~~~ -* The ``max_clients`` argument to `AsyncHTTPClient` is now a keyword-only - argument. -* Keyword arguments to `AsyncHTTPClient.configure` are no longer used - when instantiating an implementation subclass directly. -* Secondary `AsyncHTTPClient` callbacks (``streaming_callback``, - ``header_callback``, and ``prepare_curl_callback``) now respect - `StackContext`. +* `AsyncHTTPClient.fetch` now returns a ``Future`` and its callback argument + is optional. When the future interface is used, any error will be raised + automatically, as if `HTTPResponse.rethrow` was called. * `AsyncHTTPClient.configure` and all `AsyncHTTPClient` constructors now take a ``defaults`` keyword argument. This argument should be a dictionary, and its values will be used in place of corresponding @@ -105,9 +141,13 @@ General ``use_gzip``, ``proxy_password``, ``allow_nonstandard_methods``, and ``validate_cert`` have been moved from `HTTPRequest` to the client implementations. -* `AsyncHTTPClient.fetch` now returns a ``Future`` and its callback argument - is optional. When the future interface is used, any error will be raised - automatically, as if `HTTPResponse.rethrow` was called. +* The ``max_clients`` argument to `AsyncHTTPClient` is now a keyword-only + argument. +* Keyword arguments to `AsyncHTTPClient.configure` are no longer used + when instantiating an implementation subclass directly. +* Secondary `AsyncHTTPClient` callbacks (``streaming_callback``, + ``header_callback``, and ``prepare_curl_callback``) now respect + `StackContext`. `tornado.httpserver` ~~~~~~~~~~~~~~~~~~~~ @@ -127,23 +167,18 @@ General `tornado.ioloop` ~~~~~~~~~~~~~~~~ -* `IOLoop` now uses `signal.set_wakeup_fd` where available (Python 2.6+ - on Unix) to avoid a race condition that could result in Python signal - handlers being delayed. -* New method `IOLoop.add_callback_from_signal` is safe to use in a signal - handler (the regular `add_callback` method may deadlock). -* New method `IOLoop.add_future` to run a callback on the IOLoop when - an asynchronous ``Future`` finishes. * New function `IOLoop.current` returns the ``IOLoop`` that is running on the current thread (as opposed to `IOLoop.instance`, which returns a specific thread's (usually the main thread's) IOLoop). +* New method `IOLoop.add_future` to run a callback on the IOLoop when + an asynchronous ``Future`` finishes. +* `IOLoop` now has a static ``configure`` method like the one on + `AsyncHTTPClient`, which can be used to select an IOLoop implementation + other than the default. * The `IOLoop` poller implementations (``select``, ``epoll``, ``kqueue``) are now available as distinct subclasses of `IOLoop`. Instantiating `IOLoop` will continue to automatically choose the best available implementation. -* `IOLoop` now has a static ``configure`` method like the one on - `AsyncHTTPClient`, which can be used to select an IOLoop implementation - other than the default. * The `IOLoop` constructor has a new keyword argument ``time_func``, which can be used to set the time function used when scheduling callbacks. This is most useful with the `time.monotonic()` function, introduced @@ -156,20 +191,29 @@ General a time relative to `IOLoop.time`, not `time.time`. (`time.time` will continue to work only as long as the IOLoop's ``time_func`` argument is not used). +* New convenience method `IOLoop.run_sync` can be used to start an IOLoop + just long enough to run a single coroutine. +* New method `IOLoop.add_callback_from_signal` is safe to use in a signal + handler (the regular `add_callback` method may deadlock). +* `IOLoop` now uses `signal.set_wakeup_fd` where available (Python 2.6+ + on Unix) to avoid a race condition that could result in Python signal + handlers being delayed. * Method `IOLoop.running()` has been removed. * `IOLoop` has been refactored to better support subclassing. * `IOLoop.add_callback` and `add_callback_from_signal` now take ``*args, **kwargs`` to pass along to the callback. -* New convenience method `IOLoop.run_sync` can be used to start an IOLoop - just long enough to run a single coroutine. `tornado.iostream` ~~~~~~~~~~~~~~~~~~ -* New class `tornado.iostream.PipeIOStream` provides the IOStream - interface on pipe file descriptors. +* `IOStream.connect` now has an optional ``server_hostname`` argument + which will be used for SSL certificate validation when applicable. + Additionally, when supported (on Python 3.2+), this hostname + will be sent via SNI (and this is supported by `tornado.simple_httpclient`) * Much of `IOStream` has been refactored into a separate class `BaseIOStream`. +* New class `tornado.iostream.PipeIOStream` provides the IOStream + interface on pipe file descriptors. * `IOStream` now raises a new exception `tornado.iostream.StreamClosedError` when you attempt to read or write after the stream has been closed (by either side). @@ -179,14 +223,10 @@ General * `IOStream.close` now has an ``exc_info`` argument (similar to the one used in the `logging` module) that can be used to set the stream's ``error`` attribute when closing it. -* `IOStream.connect` now has an optional ``server_hostname`` argument - which will be used for SSL certificate validation when applicable. - Additionally, when supported (on Python 3.2+), this hostname - will be sent via SNI (and this is supported by `tornado.simple_httpclient`) -* Fixed a major performance regression when run on PyPy (introduced in - Tornado 2.3). * `IOStream.read_until_close` now works correctly when it is called while there is buffered data. +* Fixed a major performance regression when run on PyPy (introduced in + Tornado 2.3). `tornado.log` ~~~~~~~~~~~~~ @@ -198,47 +238,55 @@ General `tornado.netutil` ~~~~~~~~~~~~~~~~~ -* `tornado.netutil.bind_sockets` no longer sets ``AI_ADDRCONFIG``; this will - cause it to bind to both ipv4 and ipv6 more often than before. +* New class `tornado.netutil.Resolver` provides an asynchronous + interface to DNS resolution. The default implementation is still + blocking, but non-blocking implementations are available using one + of three optional dependencies: `~tornado.netutil.ThreadedResolver` + using the `concurrent.futures` thread pool, + `~tornado.platform.caresresolver.CaresResolver` using the `pycares` + library, or `~tornado.platform.twisted.TwistedResolver` using `twisted` +* New function `tornado.netutil.is_valid_ip` returns true if a given string + is a valid IP (v4 or v6) address. * `tornado.netutil.bind_sockets` has a new ``flags`` argument that can be used to pass additional flags to ``getaddrinfo``. -* New class `tornado.netutil.Resolver` provides an asynchronous - interface to `socket.getaddrinfo`. The interface is based on (but - does not require) `concurrent.futures`. When used with - `concurrent.futures.ThreadPoolExecutor`, it allows for DNS - resolution without blocking the main thread. -* `tornado.netutil.TCPServer` has moved to its own module, `tornado.tcpserver`. +* `tornado.netutil.bind_sockets` no longer sets ``AI_ADDRCONFIG``; this will + cause it to bind to both ipv4 and ipv6 more often than before. * `tornado.netutil.bind_sockets` now works when Python was compiled with ``--disable-ipv6`` but IPv6 DNS resolution is available on the system. -* New function `tornado.netutil.is_valid_ip` returns true if a given string - is a valid IP (v4 or v6) address. +* `tornado.netutil.TCPServer` has moved to its own module, `tornado.tcpserver`. `tornado.options` ~~~~~~~~~~~~~~~~~ +* The class underlying the functions in `tornado.options` is now public + (`tornado.options.OptionParser`). This can be used to create multiple + independent option sets, such as for subcommands. * `tornado.options.parse_config_file` now configures logging automatically by default, in the same way that `parse_command_line` does. * New function `tornado.options.add_parse_callback` schedules a callback to be run after the command line or config file has been parsed. The keyword argument ``final=False`` can be used on either parsing function to supress these callbacks. -* Function `tornado.options.enable_pretty_logging` has been moved to the - `tornado.log` module. * `tornado.options.define` now takes a ``callback`` argument. This callback will be run with the new value whenever the option is changed. This is especially useful for options that set other options, such as by reading from a config file. * `tornado.option.parse_command_line` ``--help`` output now goes to ``stderr`` rather than ``stdout``. -* The class underlying the functions in `tornado.options` is now public - (`tornado.options.OptionParser`). This can be used to create multiple - independent option sets, such as for subcommands. * `tornado.options.options` is no longer a subclass of `dict`; attribute-style access is now required. * `tornado.options.options` (and `OptionParser` instances generally) now have a `mockable()` method that returns a wrapper object compatible with `mock.patch`. +* Function `tornado.options.enable_pretty_logging` has been moved to the + `tornado.log` module. + +`tornado.platform.caresresolver` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* New module containing an asynchronous implementation of the `Resolver` + interface, using the `pycares` library. `tornado.platform.twisted` ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -246,6 +294,8 @@ General * New class `tornado.platform.twisted.TwistedIOLoop` allows Tornado code to be run on the Twisted reactor (as opposed to the existing `TornadoReactor`, which bridges the gap in the other direction). +* New class `tornado.platform.twisted.TwistedResolver` is an asynchronous + implementation of the `Resolver` interface. `tornado.process` ~~~~~~~~~~~~~~~~~ @@ -300,6 +350,12 @@ General `tornado.testing` ~~~~~~~~~~~~~~~~~ +* New function `tornado.testing.bind_unused_port` both chooses a port + and binds a socket to it, so there is no risk of another process + using the same port. ``get_unused_port`` is now deprecated. +* New decorator `tornado.testing.gen_test` can be used to allow for + yielding `tornado.gen` objects in tests, as an alternative to the + ``stop`` and ``wait`` methods of `AsyncTestCase`. * `tornado.testing.AsyncTestCase` and friends now extend ``unittest2.TestCase`` when it is available (and continue to use the standard ``unittest`` module when ``unittest2`` is not available) @@ -308,9 +364,6 @@ General * The command-line interface to `tornado.testing.main` now supports additional arguments from the underlying `unittest` module: ``verbose``, ``quiet``, ``failfast``, ``catch``, ``buffer``. -* New function `tornado.testing.bind_unused_port` both chooses a port - and binds a socket to it, so there is no risk of another process - using the same port. ``get_unused_port`` is now deprecated. * The deprecated ``--autoreload`` option of `tornado.testing.main` has been removed. Use ``python -m tornado.autoreload`` as a prefix command instead. @@ -321,9 +374,6 @@ General instead of putting all possible options in `tornado.testing.main`. * `AsyncHTTPTestCase` no longer calls `AsyncHTTPClient.close` for tests that use the singleton `IOLoop.instance`. -* New decorator `tornado.testing.gen_test` can be used to allow for - yielding `tornado.gen` objects in tests, as an alternative to the - ``stop`` and ``wait`` methods of `AsyncTestCase`. * `LogTrapTestCase` no longer fails when run in unknown logging configurations. This allows tests to be run under nose, which does its own log buffering (`LogTrapTestCase` doesn't do anything useful in this @@ -337,34 +387,34 @@ General `tornado.web` ~~~~~~~~~~~~~ -* The ``Date`` HTTP header is now set by default on all responses. +* `RequestHandler.set_header` now overwrites previous header values + case-insensitively. +* `tornado.web.RequestHandler` has new attributes ``path_args`` and + ``path_kwargs``, which contain the positional and keyword arguments + that are passed to the ``get``/``post``/etc method. These attributes + are set before those methods are called, so they are available during + ``prepare()`` +* `tornado.web.ErrorHandler` no longer requires XSRF tokens on ``POST`` + requests, so posts to an unknown url will always return 404 instead of + complaining about XSRF tokens. * Several methods related to HTTP status codes now take a ``reason`` keyword argument to specify an alternate "reason" string (i.e. the "Not Found" in "HTTP/1.1 404 Not Found"). It is now possible to set status codes other than those defined in the spec, as long as a reason string is given. +* The ``Date`` HTTP header is now set by default on all responses. * ``Etag``/``If-None-Match`` requests now work with `StaticFileHandler`. * `StaticFileHandler` no longer sets ``Cache-Control: public`` unnecessarily. -* `tornado.web.ErrorHandler` no longer requires XSRF tokens on ``POST`` - requests, so posts to an unknown url will always return 404 instead of - complaining about XSRF tokens. -* `tornado.web.RequestHandler` has new attributes ``path_args`` and - ``path_kwargs``, which contain the positional and keyword arguments - that are passed to the ``get``/``post``/etc method. These attributes - are set before those methods are called, so they are available during - ``prepare()`` * When gzip is enabled in a `tornado.web.Application`, appropriate ``Vary: Accept-Encoding`` headers are now sent. * It is no longer necessary to pass all handlers for a host in a single `Application.add_handlers` call. Now the request will be matched against the handlers for any ``host_pattern`` that includes the request's ``Host`` header. -* `RequestHandler.set_header` now overwrites previous header values - case-insensitively. `tornado.websocket` ~~~~~~~~~~~~~~~~~~~ -* `WebSocketHandler` has new methods `ping` and `on_pong` to send pings - to the browser (not supported on the ``draft76`` protocol) * Client-side WebSocket support is now available: `tornado.websocket.WebSocketConnect` +* `WebSocketHandler` has new methods `ping` and `on_pong` to send pings + to the browser (not supported on the ``draft76`` protocol)