From: Ben Darnell Date: Sun, 26 Mar 2017 21:10:47 +0000 (-0400) Subject: Release notes and doc updates for 4.5 X-Git-Tag: v4.5.0~11 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=987291b495ced9d1e7fcc42fd10138ec67abd5a9;p=thirdparty%2Ftornado.git Release notes and doc updates for 4.5 --- diff --git a/docs/index.rst b/docs/index.rst index 38025ccb7..9905fe7d6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -66,7 +66,7 @@ installed in this way, so you may wish to download a copy of the source tarball or clone the `git repository `_ as well. -**Prerequisites**: Tornado 4.3 runs on Python 2.7, and 3.3+ +**Prerequisites**: Tornado runs on Python 2.7, and 3.3+ For Python 2, version 2.7.9 or newer is *strongly* recommended for the improved SSL support. In addition to the requirements which will be installed automatically by ``pip`` or ``setup.py install``, @@ -77,8 +77,7 @@ the following optional packages may be useful: `~tornado.netutil.ThreadedResolver`. It is needed only on Python 2; Python 3 includes this package in the standard library. * `pycurl `_ is used by the optional - ``tornado.curl_httpclient``. Libcurl version 7.19.3.1 or higher is required; - version 7.21.1 or higher is recommended. + ``tornado.curl_httpclient``. Libcurl version 7.22 or higher is required. * `Twisted `_ may be used with the classes in `tornado.platform.twisted`. * `pycares `_ is an alternative diff --git a/docs/releases.rst b/docs/releases.rst index a9bfa1c51..42a723dcc 100644 --- a/docs/releases.rst +++ b/docs/releases.rst @@ -4,6 +4,7 @@ Release notes .. toctree:: :maxdepth: 2 + releases/v4.5.0 releases/v4.4.2 releases/v4.4.1 releases/v4.4.0 diff --git a/docs/releases/v4.5.0.rst b/docs/releases/v4.5.0.rst new file mode 100644 index 000000000..627f714d9 --- /dev/null +++ b/docs/releases/v4.5.0.rst @@ -0,0 +1,210 @@ +What's new in Tornado 4.5 +========================= + +Xxx XX, 2017 +------------ + +New module +~~~~~~~~~~ + +- `tornado.routing` provides a more flexible routing system than the one built in + to `.Application`. + +General changes +~~~~~~~~~~~~~~~ + +- Reduced the number of circular references, reducing memory usage and + improving performance. + +`tornado.autoreload` +~~~~~~~~~~~~~~~~~~~~ + +- Autoreload is now compatible with the `asyncio` event loop. +- Autoreload no longer attempts to close the `.IOLoop` and all registered + file descriptors before restarting; it relies on the ``CLOEXEC`` flag + being set instead. + +`tornado.concurrent` +~~~~~~~~~~~~~~~~~~~~ + +- Suppressed some "'NoneType' object not callback" messages that could + be logged at shutdown. + +`tornado.gen` +~~~~~~~~~~~~~ + +- ``yield None`` is now equivalent to ``yield gen.moment``. + `~tornado.gen.moment` is deprecated. This improves compatibility with + `asyncio`. +- Fixed an issue in which a generator object could be garbage + collected prematurely (most often when weak references are used. +- New function `.is_coroutine_function` identifies functions wrapped + by `.coroutine` or `.engine`. + +``tornado.http1connection`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- The ``Transfer-Encoding`` header is now parsed case-insensitively. + +`tornado.httpclient` +~~~~~~~~~~~~~~~~~~~~ + +- ``SimpleAsyncHTTPClient`` now follows 308 redirects. +- ``CurlAsyncHTTPClient`` will no longer accept protocols other than + ``http`` and ``https``. To override this, set ``pycurl.PROTOCOLS`` + and ``pycurl.REDIR_PROTOCOLS`` in a ``prepare_curl_callback``. +- ``CurlAsyncHTTPClient`` now supports digest authentication for proxies + (in addition to basic auth) via the new ``proxy_auth_mode`` argument. +- The minimum supported version of ``libcurl`` is now ``7.22.0``. + +`tornado.httpserver` +~~~~~~~~~~~~~~~~~~~~ + +- `.HTTPServer` now accepts the keyword argument + ``trusted_downstream`` which controls the parsing of + ``X-Forwarded-For`` headers. This header may be a list or set of IP + addresses of trusted proxies which will be skipped in the + ``X-Forwarded-For`` list. +- The ``no_keep_alive`` argument works again. + +`tornado.httputil` +~~~~~~~~~~~~~~~~~~ + +- `.url_concat` correctly handles fragments and existing query arguments. + +`tornado.ioloop` +~~~~~~~~~~~~~~~~ + +- Fixed 100% CPU usage after a callback returns an empty list or dict. +- `.IOLoop.add_callback` now uses a lockless implementation which + makes it safe for use from ``__del__`` methods. This improves + performance of calls to `~.IOLoop.add_callback` from the `.IOLoop` + thread, and slightly decreases it for calls from other threads. + +`tornado.iostream` +~~~~~~~~~~~~~~~~~~ + +- `memoryview` objects are now permitted as arguments to `~.BaseIOStream.write`. +- The internal memory buffers used by `.IOStream` now use `bytearray` + instead of a list of `bytes`, improving performance. +- Futures returned by `~.BaseIOStream.write` are no longer orphaned if a second + call to ``write`` occurs before the previous one is finished. + +`tornado.log` +~~~~~~~~~~~~~ + +- Colored log output is now supported on Windows if the + `colorama `_ library + is installed and the application calls ``colorama.init()`` at + startup. +- The signature of the `.LogFormatter` constructor has been changed to + make it compatible with `logging.config.dictConfig`. + +`tornado.netutil` +~~~~~~~~~~~~~~~~~ + +- Worked around an issue that caused "LookupError: unknown encoding: + latin1" errors on Solaris. + +`tornado.process` +~~~~~~~~~~~~~~~~~ + +- `.Subprocess` no longer causes "subprocess still running" warnings on Python 3.6. +- Improved error handling in `.cpu_count`. + +`tornado.tcpclient` +~~~~~~~~~~~~~~~~~~~ + +- `.TCPClient` now supports a ``source_ip`` and ``source_port`` argument. +- Improved error handling for environments where IPv6 support is incomplete. + +`tornado.tcpserver` +~~~~~~~~~~~~~~~~~~~ + +- `.TCPServer.handle_stream` implementations may now be native coroutines. +- Stopping a `.TCPServer` twice no longer raises an exception. + +`tornado.web` +~~~~~~~~~~~~~ + +- `.RedirectHandler` now supports substituting parts of the matched + URL into the redirect location using `str.format` syntax. +- New methods `.RequestHandler.render_linked_js`, + `.RequestHandler.render_embed_js`, + `.RequestHandler.render_linked_css`, and + `.RequestHandler.render_embed_css` can be overridden to customize + the output of `.UIModule`. + + +`tornado.websocket` +~~~~~~~~~~~~~~~~~~~ + +- `.WebSocketHandler.on_message` implementations may now be + coroutines. New messages will not be processed until the previous + ``on_message`` coroutine has finished. +- The ``websocket_ping_interval`` and ``websocket_ping_timeout`` + application settings can now be used to enable a periodic ping of + the websocket connection, allowing dropped connections to be + detected and closed. +- Headers set by `.RequestHandler.prepare` or + `.RequestHandler.set_default_headers` are now sent as a part of the + websocket handshake. +- Return values from `.WebSocketHandler.get_compression_options` may now include + the keys ``compression_level`` and ``mem_level`` to set gzip parameters. + The default compression level is now 6 instead of 9. + +Demos +~~~~~ + +- A new file upload demo is available in the `file_upload + `_ + directory. +- A new `.TCPClient` and `.TCPServer` demo is available in the + `tcpecho `_ directory. +- Minor updates have been made to several existing demos, including + updates to more recent versions of jquery. + +Credits +~~~~~~~ + +The following people contributed commits to this release: + +- A\. Jesse Jiryu Davis +- Aaron Opfer +- Akihiro Yamazaki +- Alexander +- Andreas Røsdal +- Andrew Rabert +- Andrew Sumin +- Antoine Pietri +- Antoine Pitrou +- Artur Stawiarski +- Ben Darnell +- Brian Mego +- Dario +- Doug Vargas +- Eugene Dubovoy +- Iver Jordal +- JZQT +- James Maier +- Jeff Hunter +- Leynos +- Mark Henderson +- Michael V. DePalatis +- Min RK +- Mircea Ulinic +- Ping +- Ping Yang +- Riccardo Magliocchetti +- Samuel Chen +- Samuel Dion-Girardeau +- Scott Meisburger +- Shawn Ding +- TaoBeier +- Thomas Kluyver +- Vadim Semenov +- matee +- mike820324 +- stiletto +- zhimin +- 依云 diff --git a/docs/web.rst b/docs/web.rst index 5439b474b..77f2fff4c 100644 --- a/docs/web.rst +++ b/docs/web.rst @@ -71,6 +71,8 @@ before those methods are called, so the values are available during `prepare`. + .. automethod:: RequestHandler.data_received + Output ^^^^^^ @@ -89,8 +91,10 @@ .. automethod:: RequestHandler.send_error .. automethod:: RequestHandler.write_error .. automethod:: RequestHandler.clear - .. automethod:: RequestHandler.data_received - + .. automethod:: RequestHandler.render_linked_js + .. automethod:: RequestHandler.render_embed_js + .. automethod:: RequestHandler.render_linked_css + .. automethod:: RequestHandler.render_embed_css Cookies ^^^^^^^ diff --git a/setup.py b/setup.py index f8dce8984..14caff8cc 100644 --- a/setup.py +++ b/setup.py @@ -103,7 +103,7 @@ http://api.mongodb.org/python/current/installation.html#osx kwargs = {} -version = "4.5.dev1" +version = "4.5b1" with open('README.rst') as f: kwargs['long_description'] = f.read() diff --git a/tornado/__init__.py b/tornado/__init__.py index a7edfea5f..548c6272d 100644 --- a/tornado/__init__.py +++ b/tornado/__init__.py @@ -25,5 +25,5 @@ from __future__ import absolute_import, division, print_function # is zero for an official release, positive for a development branch, # or negative for a release candidate or beta (after the base version # number has been incremented) -version = "4.5.dev1" -version_info = (4, 5, 0, -100) +version = "4.5b1" +version_info = (4, 5, 0, -99) diff --git a/tornado/gen.py b/tornado/gen.py index c8f3a9b8d..9ac1d6e35 100644 --- a/tornado/gen.py +++ b/tornado/gen.py @@ -339,6 +339,8 @@ def _make_coroutine_wrapper(func, replace_callback): def is_coroutine_function(func): """Return whether *func* is a coroutine function, i.e. a function wrapped with `~.gen.coroutine`. + + .. versionadded:: 4.5 """ return getattr(func, '__tornado_coroutine__', False) @@ -961,6 +963,9 @@ coroutines that are likely to yield Futures that are ready instantly. Usage: ``yield gen.moment`` .. versionadded:: 4.0 + +.. deprecated:: 4.5 + ``yield None`` is now equivalent to ``yield gen.moment``. """ moment.set_result(None) diff --git a/tornado/httpclient.py b/tornado/httpclient.py index 8e1e37646..6f45367ca 100644 --- a/tornado/httpclient.py +++ b/tornado/httpclient.py @@ -423,6 +423,9 @@ class HTTPRequest(object): .. versionadded:: 4.2 The ``ssl_options`` argument. + + .. versionadded:: 4.5 + The ``proxy_auth_mode`` argument. """ # Note that some of these attributes go through property setters # defined below. diff --git a/tornado/httpserver.py b/tornado/httpserver.py index cde37d5d3..6ae32e6f7 100644 --- a/tornado/httpserver.py +++ b/tornado/httpserver.py @@ -131,6 +131,9 @@ class HTTPServer(TCPServer, Configurable, .. versionchanged:: 4.2 `HTTPServer` is now a subclass of `tornado.util.Configurable`. + + .. versionchanged:: 4.5 + Added the ``trusted_downstream`` argument. """ def __init__(self, *args, **kwargs): # Ignore args to __init__; real initialization belongs in diff --git a/tornado/iostream.py b/tornado/iostream.py index 0f9d62856..691251ad2 100644 --- a/tornado/iostream.py +++ b/tornado/iostream.py @@ -374,11 +374,15 @@ class BaseIOStream(object): 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. + completed. + + The ``data`` argument may be of type `bytes` or `memoryview`. .. versionchanged:: 4.0 Now returns a `.Future` if no callback is given. + + .. versionchanged:: 4.5 + Added support for `memoryview` arguments. """ self._check_closed() if data: diff --git a/tornado/log.py b/tornado/log.py index 50fb0e4ad..f870da4ae 100644 --- a/tornado/log.py +++ b/tornado/log.py @@ -95,6 +95,10 @@ class LogFormatter(logging.Formatter): See the colorama documentation for details. __ https://pypi.python.org/pypi/colorama + + .. versionchanged:: 4.5 + Added support for ``colorama``. Changed the constructor + signature to be compatible with `logging.config.dictConfig`. """ DEFAULT_FORMAT = '%(color)s[%(levelname)1.1s %(asctime)s %(module)s:%(lineno)d]%(end_color)s %(message)s' DEFAULT_DATE_FORMAT = '%y%m%d %H:%M:%S' diff --git a/tornado/routing.py b/tornado/routing.py index 56fb5e7df..6762dc05b 100644 --- a/tornado/routing.py +++ b/tornado/routing.py @@ -12,16 +12,23 @@ # License for the specific language governing permissions and limitations # under the License. -"""Basic routing implementation. +"""Flexible routing implementation. -Tornado routes HTTP requests to appropriate handlers using `Router` class implementations. +Tornado routes HTTP requests to appropriate handlers using `Router` +class implementations. The `tornado.web.Application` class is a +`Router` implementation and may be used directly, or the classes in +this module may be used for additional flexibility. The `RuleRouter` +class can match on more criteria than `.Application`, or the `Router` +interface can be subclassed for maximum customization. -`Router` interface extends `~.httputil.HTTPServerConnectionDelegate` to provide additional -routing capabilities. This also means that any `Router` implementation can be used directly -as a ``request_callback`` for `~.httpserver.HTTPServer` constructor. +`Router` interface extends `~.httputil.HTTPServerConnectionDelegate` +to provide additional routing capabilities. This also means that any +`Router` implementation can be used directly as a ``request_callback`` +for `~.httpserver.HTTPServer` constructor. -`Router` subclass must implement a ``find_handler`` method to provide a suitable -`~.httputil.HTTPMessageDelegate` instance to handle the request: +`Router` subclass must implement a ``find_handler`` method to provide +a suitable `~.httputil.HTTPMessageDelegate` instance to handle the +request: .. code-block:: python @@ -44,16 +51,18 @@ as a ``request_callback`` for `~.httpserver.HTTPServer` constructor. router = CustomRouter() server = HTTPServer(router) -The main responsibility of `Router` implementation is to provide a mapping from a request -to `~.httputil.HTTPMessageDelegate` instance that will handle this request. In the example above -we can see that routing is possible even without instantiating an `~.web.Application`. +The main responsibility of `Router` implementation is to provide a +mapping from a request to `~.httputil.HTTPMessageDelegate` instance +that will handle this request. In the example above we can see that +routing is possible even without instantiating an `~.web.Application`. -For routing to `~.web.RequestHandler` implementations we need an `~.web.Application` instance. -`~.web.Application.get_handler_delegate` provides a convenient way to create -`~.httputil.HTTPMessageDelegate` for a given request and `~.web.RequestHandler`. +For routing to `~.web.RequestHandler` implementations we need an +`~.web.Application` instance. `~.web.Application.get_handler_delegate` +provides a convenient way to create `~.httputil.HTTPMessageDelegate` +for a given request and `~.web.RequestHandler`. -Here is a simple example of how we can we route to `~.web.RequestHandler` subclasses -by HTTP method: +Here is a simple example of how we can we route to +`~.web.RequestHandler` subclasses by HTTP method: .. code-block:: python @@ -81,16 +90,18 @@ by HTTP method: router = HTTPMethodRouter(Application()) server = HTTPServer(router) -`ReversibleRouter` interface adds the ability to distinguish between the routes and -reverse them to the original urls using route's name and additional arguments. -`~.web.Application` is itself an implementation of `ReversibleRouter` class. +`ReversibleRouter` interface adds the ability to distinguish between +the routes and reverse them to the original urls using route's name +and additional arguments. `~.web.Application` is itself an +implementation of `ReversibleRouter` class. -`RuleRouter` and `ReversibleRuleRouter` are implementations of `Router` and `ReversibleRouter` -interfaces and can be used for creating rule-based routing configurations. +`RuleRouter` and `ReversibleRuleRouter` are implementations of +`Router` and `ReversibleRouter` interfaces and can be used for +creating rule-based routing configurations. -Rules are instances of `Rule` class. They contain a `Matcher`, which provides the logic for -determining whether the rule is a match for a particular request and a target, which can be -one of the following. +Rules are instances of `Rule` class. They contain a `Matcher`, which +provides the logic for determining whether the rule is a match for a +particular request and a target, which can be one of the following. 1) An instance of `~.httputil.HTTPServerConnectionDelegate`: @@ -159,6 +170,9 @@ In the example below `RuleRouter` is used to route between applications: server = HTTPServer(router) For more information on application-level routing see docs for `~.web.Application`. + +.. versionadded:: 4.5 + """ from __future__ import absolute_import, division, print_function diff --git a/tornado/tcpclient.py b/tornado/tcpclient.py index 2d6825028..33074bd58 100644 --- a/tornado/tcpclient.py +++ b/tornado/tcpclient.py @@ -169,6 +169,9 @@ class TCPClient(object): Similarly, when the user requires a certain source port, it can be specified using the ``source_port`` arg. + + .. versionchanged:: 4.5 + Added the ``source_ip`` and ``source_port`` arguments. """ addrinfo = yield self.resolver.resolve(host, port, af) connector = _Connector( diff --git a/tornado/web.py b/tornado/web.py index a04cc3a60..6d6ce92e7 100644 --- a/tornado/web.py +++ b/tornado/web.py @@ -1864,6 +1864,8 @@ class Application(ReversibleRouter): `StaticFileHandler` can be specified with the ``static_handler_class`` setting. + .. versionchanged:: 4.5 + Integration with the new `tornado.routing` module. """ def __init__(self, handlers=None, default_host=None, transforms=None, **settings): @@ -2248,6 +2250,9 @@ class RedirectHandler(RequestHandler): Use Python's :ref:`format string syntax ` to customize how values are substituted. + + .. versionchanged:: 4.5 + Added support for substitutions into the destination URL. """ def initialize(self, url, permanent=True): self._url = url diff --git a/tornado/websocket.py b/tornado/websocket.py index 1fafed777..65243572f 100644 --- a/tornado/websocket.py +++ b/tornado/websocket.py @@ -126,6 +126,13 @@ class WebSocketHandler(tornado.web.RequestHandler): to show the "accept this certificate" dialog but has nowhere to show it. You must first visit a regular HTML page using the same certificate to accept it before the websocket connection will succeed. + + If the application setting ``websocket_ping_interval`` has a non-zero + value, a ping will be sent periodically, and the connection will be + closed if a response is not received before the ``websocket_ping_timeout``. + + .. versionchanged:: 4.5 + Added ``websocket_ping_interval`` and ``websocket_ping_timeout``. """ def __init__(self, application, request, **kwargs): super(WebSocketHandler, self).__init__(application, request, **kwargs) @@ -194,7 +201,7 @@ class WebSocketHandler(tornado.web.RequestHandler): def ping_interval(self): """The interval for websocket keep-alive pings. - Set ws_ping_interval = 0 to disable pings. + Set websocket_ping_interval = 0 to disable pings. """ return self.settings.get('websocket_ping_interval', None) @@ -250,11 +257,12 @@ class WebSocketHandler(tornado.web.RequestHandler): will be enabled. The contents of the dict may be used to control the following compression options: - ``compression_level`` specifies the compression level. + ``compression_level`` specifies the compression level. ``mem_level`` specifies the amount of memory used for the internal compression state. - - These parameters are documented in details here: https://docs.python.org/3.6/library/zlib.html#zlib.compressobj + + These parameters are documented in details here: + https://docs.python.org/3.6/library/zlib.html#zlib.compressobj .. versionadded:: 4.1