Permalink
Browse files

Minor doc updates for modules A-E

  • Loading branch information...
bdarnell committed Mar 16, 2013
1 parent d577bc5 commit f7a2fad709f557b4dc3e0b0ce16ceb6f6ca2b654
Showing with 32 additions and 20 deletions.
  1. +15 −10 tornado/autoreload.py
  2. +6 −0 tornado/concurrent.py
  3. +1 −1 tornado/curl_httpclient.py
  4. +10 −9 tornado/escape.py
View
@@ -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 @@
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
View
@@ -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
@@ -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
View
@@ -54,7 +54,7 @@
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 extra_params_cb(url):
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()

0 comments on commit f7a2fad

Please sign in to comment.