]> git.ipfire.org Git - thirdparty/tornado.git/commitdiff
Minor doc updates for modules A-E
authorBen Darnell <ben@bendarnell.com>
Sat, 16 Mar 2013 02:46:51 +0000 (22:46 -0400)
committerBen Darnell <ben@bendarnell.com>
Sat, 16 Mar 2013 02:50:19 +0000 (22:50 -0400)
tornado/autoreload.py
tornado/concurrent.py
tornado/curl_httpclient.py
tornado/escape.py

index 90a8a80272296d82f9490b9fcc124ff8e43fe93d..5d4c524e01c6c303345c5f982ac79066278e9629 100644 (file)
 # 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
index f8ad0e2fb65ac43475e086e8651d299e10d27581..b71e1546e56bd765016d4f971bc9af1b0a94a8bb 100644 (file)
 # 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
index ba14db6ce0c922fe9f0228b68a4805b187371b4d..c5f08df4f1427e80cfa14e5281a78f36cca9e0ca 100644 (file)
@@ -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
 
index e565ff538745bed81f9b93d798ad87d1a1eb4c4c..016fdade82bea68daf393d97b262b703136eaa01 100644 (file)
@@ -54,7 +54,7 @@ _XHTML_ESCAPE_DICT = {'&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;'}
 
 
 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()