From: Ben Darnell Date: Sat, 16 Mar 2013 02:46:51 +0000 (-0400) Subject: Minor doc updates for modules A-E X-Git-Tag: v3.0.0~30 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f7a2fad709f557b4dc3e0b0ce16ceb6f6ca2b654;p=thirdparty%2Ftornado.git Minor doc updates for modules A-E --- diff --git a/tornado/autoreload.py b/tornado/autoreload.py index 90a8a8027..5d4c524e0 100644 --- a/tornado/autoreload.py +++ b/tornado/autoreload.py @@ -14,15 +14,24 @@ # License for the specific language governing permissions and limitations # under the License. -"""A module to automatically restart the server when a module is modified. +"""Automatically restart the server when a source file is modified. -Most applications should not call this module directly. Instead, pass the +Most applications should not access this module directly. Instead, pass the keyword argument ``debug=True`` to the `tornado.web.Application` constructor. This will enable autoreload mode as well as checking for changes to templates -and static resources. +and static resources. Note that restarting is a destructive operation +and any requests in progress will be aborted when the process restarts. -This module depends on IOLoop, so it will not work in WSGI applications -and Google AppEngine. It also will not work correctly when HTTPServer's +This module can also be used as a command-line wrapper around scripts +such as unit test runners. See the `main` method for details. + +The command-line wrapper and Application debug modes can be used together. +This combination is encouraged as the wrapper catches syntax errors and +other import-time failures, while debug mode catches changes once +the server has started. + +This module depends on `IOLoop`, so it will not work in WSGI applications +and Google App Engine. It also will not work correctly when `HTTPServer`'s multi-process mode is used. Reloading loses any Python interpreter command-line arguments (e.g. ``-u``) @@ -94,11 +103,7 @@ _io_loops = weakref.WeakKeyDictionary() def start(io_loop=None, check_time=500): - """Restarts the process automatically when a module is modified. - - We run on the I/O loop, and restarting is a destructive operation, - so will terminate any pending requests. - """ + """Begins watching source files for changes using the given `IOLoop`. """ io_loop = io_loop or ioloop.IOLoop.current() if io_loop in _io_loops: return diff --git a/tornado/concurrent.py b/tornado/concurrent.py index f8ad0e2fb..b71e1546e 100644 --- a/tornado/concurrent.py +++ b/tornado/concurrent.py @@ -13,6 +13,12 @@ # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the # License for the specific language governing permissions and limitations # under the License. +"""Utilities for working with the `concurrent.futures` package. + +This module also contains compatibility shims including a dummy +implementation of `concurrent.futures.Future` which can be used +when `concurrent.futures` is not available. +""" from __future__ import absolute_import, division, print_function, with_statement import functools diff --git a/tornado/curl_httpclient.py b/tornado/curl_httpclient.py index ba14db6ce..c5f08df4f 100644 --- a/tornado/curl_httpclient.py +++ b/tornado/curl_httpclient.py @@ -14,7 +14,7 @@ # License for the specific language governing permissions and limitations # under the License. -"""Blocking and non-blocking HTTP client implementations using pycurl.""" +"""Non-blocking HTTP client implementation using pycurl.""" from __future__ import absolute_import, division, print_function, with_statement diff --git a/tornado/escape.py b/tornado/escape.py index e565ff538..016fdade8 100644 --- a/tornado/escape.py +++ b/tornado/escape.py @@ -54,7 +54,7 @@ _XHTML_ESCAPE_DICT = {'&': '&', '<': '<', '>': '>', '"': '"'} def xhtml_escape(value): - """Escapes a string so it is valid within XML or XHTML.""" + """Escapes a string so it is valid within HTML or XML.""" return _XHTML_ESCAPE_RE.sub(lambda match: _XHTML_ESCAPE_DICT[match.group(0)], to_basestring(value)) @@ -86,7 +86,7 @@ def squeeze(value): def url_escape(value): - """Returns a valid URL-encoded version of the given value.""" + """Returns a URL-encoded version of the given value.""" return urllib_parse.quote_plus(utf8(value)) # python 3 changed things around enough that we need two separate @@ -231,9 +231,9 @@ def linkify(text, shorten=False, extra_params="", Parameters: - shorten: Long urls will be shortened for display. + * ``shorten``: Long urls will be shortened for display. - extra_params: Extra text to include in the link tag, or a callable + * ``extra_params``: Extra text to include in the link tag, or a callable taking the link as an argument and returning the extra text e.g. ``linkify(text, extra_params='rel="nofollow" class="external"')``, or:: @@ -245,12 +245,13 @@ def linkify(text, shorten=False, extra_params="", return 'class="external" rel="nofollow"' linkify(text, extra_params=extra_params_cb) - require_protocol: Only linkify urls which include a protocol. If this is - False, urls such as www.facebook.com will also be linkified. + * ``require_protocol``: Only linkify urls which include a protocol. If + this is False, urls such as www.facebook.com will also be linkified. - permitted_protocols: List (or set) of protocols which should be linkified, - e.g. linkify(text, permitted_protocols=["http", "ftp", "mailto"]). - It is very unsafe to include protocols such as "javascript". + * ``permitted_protocols``: List (or set) of protocols which should be + linkified, e.g. ``linkify(text, permitted_protocols=["http", "ftp", + "mailto"])``. It is very unsafe to include protocols such as + ``javascript``. """ if extra_params and not callable(extra_params): extra_params = " " + extra_params.strip()