From: Sadie Bartholomew Date: Sat, 9 Feb 2019 00:35:55 +0000 (+0000) Subject: Minor formatting & grammatical etc. edits to docs X-Git-Tag: v6.0.0b1~2^2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=49241f3e853e640bb241c982b549be55d2eaad61;p=thirdparty%2Ftornado.git Minor formatting & grammatical etc. edits to docs --- diff --git a/docs/faq.rst b/docs/faq.rst index 5515cc926..1628073a3 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -74,8 +74,8 @@ See the :doc:`Asynchronous I/O ` chapter of the Tornado user's guide for more on blocking and asynchronous functions. -My code is asynchronous, but it's not running in parallel in two browser tabs. ------------------------------------------------------------------------------- +My code is asynchronous. Why is it not running in parallel in two browser tabs? +------------------------------------------------------------------------------- Even when a handler is asynchronous and non-blocking, it can be surprisingly tricky to verify this. Browsers will recognize that you are trying to diff --git a/docs/guide/coroutines.rst b/docs/guide/coroutines.rst index 29f614cce..aa8f62896 100644 --- a/docs/guide/coroutines.rst +++ b/docs/guide/coroutines.rst @@ -39,7 +39,7 @@ decorator. Native coroutines are the recommended form whenever possible. Only use decorated coroutines when compatibility with older versions of Python -is required. Examples in the tornado documentation will generally use +is required. Examples in the Tornado documentation will generally use the native form. Translation between the two forms is generally straightforward:: @@ -58,30 +58,35 @@ Translation between the two forms is generally straightforward:: # special exception. # Return normally raise gen.Return(b) return b -Other differences between the two forms of coroutine are: - -- Native coroutines are generally faster. -- Native coroutines can use ``async for`` and ``async with`` - statements which make some patterns much simpler. -- Native coroutines do not run at all unless you ``await`` or - ``yield`` them. Decorated coroutines can start running "in the - background" as soon as they are called. Note that for both kinds of - coroutines it is important to use ``await`` or ``yield`` so that - any exceptions have somewhere to go. -- Decorated coroutines have additional integration with the - `concurrent.futures` package, allowing the result of - ``executor.submit`` to be yielded directly. For native coroutines, - use `.IOLoop.run_in_executor` instead. -- Decorated coroutines support some shorthand for waiting on multiple - objects by yielding a list or dict. Use `tornado.gen.multi` to do - this in native coroutines. -- Decorated coroutines can support integration with other packages - including Twisted via a registry of conversion functions. - To access this functionality in native coroutines, use - `tornado.gen.convert_yielded`. -- Decorated coroutines always return a `.Future` object. Native - coroutines return an *awaitable* object that is not a `.Future`. In - Tornado the two are mostly interchangeable. +Other differences between the two forms of coroutine are outlined below. + +- Native coroutines: + + - are generally faster. + - can use ``async for`` and ``async with`` + statements which make some patterns much simpler. + - do not run at all unless you ``await`` or + ``yield`` them. Decorated coroutines can start running "in the + background" as soon as they are called. Note that for both kinds of + coroutines it is important to use ``await`` or ``yield`` so that + any exceptions have somewhere to go. + +- Decorated coroutines: + + - have additional integration with the + `concurrent.futures` package, allowing the result of + ``executor.submit`` to be yielded directly. For native coroutines, + use `.IOLoop.run_in_executor` instead. + - support some shorthand for waiting on multiple + objects by yielding a list or dict. Use `tornado.gen.multi` to do + this in native coroutines. + - can support integration with other packages + including Twisted via a registry of conversion functions. + To access this functionality in native coroutines, use + `tornado.gen.convert_yielded`. + - always return a `.Future` object. Native + coroutines return an *awaitable* object that is not a `.Future`. In + Tornado the two are mostly interchangeable. How it works ~~~~~~~~~~~~ diff --git a/docs/guide/intro.rst b/docs/guide/intro.rst index 778573bbb..8d87ba62b 100644 --- a/docs/guide/intro.rst +++ b/docs/guide/intro.rst @@ -29,4 +29,4 @@ alternative to `WSGI `_. While it is possible to use the Tornado HTTP server as a container for other WSGI frameworks (`.WSGIContainer`), this combination has limitations and to take full advantage of Tornado you will need to use -the Tornado's web framework and HTTP server together. +Tornado's web framework and HTTP server together. diff --git a/docs/guide/running.rst b/docs/guide/running.rst index edf469a96..43fe3f18b 100644 --- a/docs/guide/running.rst +++ b/docs/guide/running.rst @@ -22,8 +22,9 @@ configuring a WSGI container to find your application, you write a Configure your operating system or process manager to run this program to start the server. Please note that it may be necessary to increase the number of open files per process (to avoid "Too many open files"-Error). -To raise this limit (setting it to 50000 for example) you can use the ulimit command, -modify /etc/security/limits.conf or setting ``minfds`` in your supervisord config. +To raise this limit (setting it to 50000 for example) you can use the +``ulimit`` command, modify ``/etc/security/limits.conf`` or set +``minfds`` in your `supervisord `_ config. Processes and ports ~~~~~~~~~~~~~~~~~~~ @@ -50,8 +51,8 @@ main function: This is the easiest way to start multiple processes and have them all share the same port, although it has some limitations. First, each -child process will have its own IOLoop, so it is important that -nothing touch the global IOLoop instance (even indirectly) before the +child process will have its own ``IOLoop``, so it is important that +nothing touches the global ``IOLoop`` instance (even indirectly) before the fork. Second, it is difficult to do zero-downtime updates in this model. Finally, since all the processes share the same port it is more difficult to monitor them individually. @@ -67,10 +68,10 @@ to present a single address to outside visitors. Running behind a load balancer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When running behind a load balancer like nginx, it is recommended to -pass ``xheaders=True`` to the `.HTTPServer` constructor. This will tell -Tornado to use headers like ``X-Real-IP`` to get the user's IP address -instead of attributing all traffic to the balancer's IP address. +When running behind a load balancer like `nginx `_, +it is recommended to pass ``xheaders=True`` to the `.HTTPServer` constructor. +This will tell Tornado to use headers like ``X-Real-IP`` to get the user's +IP address instead of attributing all traffic to the balancer's IP address. This is a barebones nginx config file that is structurally similar to the one we use at FriendFeed. It assumes nginx and the Tornado servers @@ -169,7 +170,7 @@ You can serve static files from Tornado by specifying the ], **settings) This setting will automatically make all requests that start with -``/static/`` serve from that static directory, e.g., +``/static/`` serve from that static directory, e.g. ``http://localhost:8888/static/foo.png`` will serve the file ``foo.png`` from the specified static directory. We also automatically serve ``/robots.txt`` and ``/favicon.ico`` from the static directory @@ -248,7 +249,7 @@ individual flag takes precedence): server down in a way that debug mode cannot currently recover from. * ``compiled_template_cache=False``: Templates will not be cached. * ``static_hash_cache=False``: Static file hashes (used by the - ``static_url`` function) will not be cached + ``static_url`` function) will not be cached. * ``serve_traceback=True``: When an exception in a `.RequestHandler` is not caught, an error page including a stack trace will be generated. diff --git a/docs/guide/structure.rst b/docs/guide/structure.rst index 8e8dc026a..407edf414 100644 --- a/docs/guide/structure.rst +++ b/docs/guide/structure.rst @@ -178,7 +178,7 @@ In addition to ``get()``/``post()``/etc, certain other methods in necessary. On every request, the following sequence of calls takes place: -1. A new `.RequestHandler` object is created on each request +1. A new `.RequestHandler` object is created on each request. 2. `~.RequestHandler.initialize()` is called with the initialization arguments from the `.Application` configuration. ``initialize`` should typically just save the arguments passed into member @@ -206,12 +206,12 @@ overridden methods include: disconnects; applications may choose to detect this case and halt further processing. Note that there is no guarantee that a closed connection can be detected promptly. -- `~.RequestHandler.get_current_user` - see :ref:`user-authentication` +- `~.RequestHandler.get_current_user` - see :ref:`user-authentication`. - `~.RequestHandler.get_user_locale` - returns `.Locale` object to use - for the current user + for the current user. - `~.RequestHandler.set_default_headers` - may be used to set additional headers on the response (such as a custom ``Server`` - header) + header). Error Handling ~~~~~~~~~~~~~~ @@ -260,7 +260,7 @@ redirect users elsewhere. There is also an optional parameter considered permanent. The default value of ``permanent`` is ``False``, which generates a ``302 Found`` HTTP response code and is appropriate for things like redirecting users after successful -``POST`` requests. If ``permanent`` is true, the ``301 Moved +``POST`` requests. If ``permanent`` is ``True``, the ``301 Moved Permanently`` HTTP response code is used, which is useful for e.g. redirecting to a canonical URL for a page in an SEO-friendly manner. diff --git a/docs/guide/templates.rst b/docs/guide/templates.rst index 8755d25e1..9230be23e 100644 --- a/docs/guide/templates.rst +++ b/docs/guide/templates.rst @@ -66,9 +66,9 @@ directory as your Python file, you could render this template with: :hide: Tornado templates support *control statements* and *expressions*. -Control statements are surrounded by ``{%`` and ``%}``, e.g., +Control statements are surrounded by ``{%`` and ``%}``, e.g. ``{% if len(items) > 2 %}``. Expressions are surrounded by ``{{`` and -``}}``, e.g., ``{{ items[0] }}``. +``}}``, e.g. ``{{ items[0] }}``. Control statements more or less map exactly to Python statements. We support ``if``, ``for``, ``while``, and ``try``, all of which are @@ -78,7 +78,7 @@ detail in the documentation for the `tornado.template`. Expressions can be any Python expression, including function calls. Template code is executed in a namespace that includes the following -objects and functions (Note that this list applies to templates +objects and functions. (Note that this list applies to templates rendered using `.RequestHandler.render` and `~.RequestHandler.render_string`. If you're using the `tornado.template` module directly outside of a `.RequestHandler` many @@ -136,7 +136,8 @@ that appear in certain locations, such as in Javascript or CSS, may need additional escaping. Additionally, either care must be taken to always use double quotes and `.xhtml_escape` in HTML attributes that may contain untrusted content, or a separate escaping function must be used for -attributes (see e.g. http://wonko.com/post/html-escaping) +attributes (see e.g. +`this blog post `_). Internationalization ~~~~~~~~~~~~~~~~~~~~ @@ -212,7 +213,7 @@ formats: the ``.mo`` format used by `gettext` and related tools, and a simple ``.csv`` format. An application will generally call either `tornado.locale.load_translations` or `tornado.locale.load_gettext_translations` once at startup; see those -methods for more details on the supported formats.. +methods for more details on the supported formats. You can get the list of supported locales in your application with `tornado.locale.get_supported_locales()`. The user's locale is chosen @@ -234,7 +235,7 @@ packaged with their own CSS and JavaScript. For example, if you are implementing a blog, and you want to have blog entries appear on both the blog home page and on each blog entry page, you can make an ``Entry`` module to render them on both pages. First, -create a Python module for your UI modules, e.g., ``uimodules.py``:: +create a Python module for your UI modules, e.g. ``uimodules.py``:: class Entry(tornado.web.UIModule): def render(self, entry, show_comments=False): diff --git a/docs/index.rst b/docs/index.rst index d078fd5b5..ac5ac6196 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -21,7 +21,7 @@ Quick links ----------- * Current version: |version| (`download from PyPI `_, :doc:`release notes `) -* `Source (github) `_ +* `Source (GitHub) `_ * Mailing lists: `discussion `_ and `announcements `_ * `Stack Overflow `_ * `Wiki `_ diff --git a/docs/web.rst b/docs/web.rst index fbf2e826e..46697a248 100644 --- a/docs/web.rst +++ b/docs/web.rst @@ -28,7 +28,7 @@ The arguments to these methods come from the `.URLSpec`: Any capturing groups in the regular expression become arguments to the HTTP verb methods (keyword arguments if the group is named, - positional arguments if its unnamed). + positional arguments if it's unnamed). To support a method not on this list, override the class variable ``SUPPORTED_METHODS``:: @@ -159,7 +159,8 @@ Application configuration - ----------------------------- + ------------------------- + .. autoclass:: Application(handlers: List[Union[Rule, Tuple]] = None, default_host: str = None, transforms: List[Type[OutputTransform]] = None, **settings) .. attribute:: settings @@ -197,7 +198,7 @@ `RequestHandler` object). The default implementation writes to the `logging` module's root logger. May also be customized by overriding `Application.log_request`. - * ``serve_traceback``: If true, the default error page + * ``serve_traceback``: If ``True``, the default error page will include the traceback of the error. This option is new in Tornado 3.2; previously this functionality was controlled by the ``debug`` setting. @@ -224,7 +225,7 @@ * ``login_url``: The `authenticated` decorator will redirect to this url if the user is not logged in. Can be further customized by overriding `RequestHandler.get_login_url` - * ``xsrf_cookies``: If true, :ref:`xsrf` will be enabled. + * ``xsrf_cookies``: If ``True``, :ref:`xsrf` will be enabled. * ``xsrf_cookie_version``: Controls the version of new XSRF cookies produced by this server. Should generally be left at the default (which will always be the highest supported diff --git a/tornado/auth.py b/tornado/auth.py index 3757a1548..db6d29065 100644 --- a/tornado/auth.py +++ b/tornado/auth.py @@ -840,7 +840,7 @@ class GoogleOAuth2Mixin(OAuth2Mixin): * In the OAuth section of the page, select Create New Client ID. * Set the Redirect URI to point to your auth handler * Copy the "Client secret" and "Client ID" to the application settings as - {"google_oauth": {"key": CLIENT_ID, "secret": CLIENT_SECRET}} + ``{"google_oauth": {"key": CLIENT_ID, "secret": CLIENT_SECRET}}`` .. versionadded:: 3.2 """ diff --git a/tornado/concurrent.py b/tornado/concurrent.py index b7bb15c01..9d77170c8 100644 --- a/tornado/concurrent.py +++ b/tornado/concurrent.py @@ -176,7 +176,7 @@ def future_set_result_unless_cancelled( ) -> None: """Set the given ``value`` as the `Future`'s result, if not cancelled. - Avoids asyncio.InvalidStateError when calling set_result() on + Avoids ``asyncio.InvalidStateError`` when calling ``set_result()`` on a cancelled `asyncio.Future`. .. versionadded:: 5.0 @@ -192,10 +192,10 @@ def future_set_exception_unless_cancelled( If the Future is already canceled, logs the exception instead. If this logging is not desired, the caller should explicitly check - the state of the Future and call Future.set_exception instead of + the state of the Future and call ``Future.set_exception`` instead of this wrapper. - Avoids asyncio.InvalidStateError when calling set_exception() on + Avoids ``asyncio.InvalidStateError`` when calling ``set_exception()`` on a cancelled `asyncio.Future`. .. versionadded:: 6.0 @@ -223,7 +223,7 @@ def future_set_exc_info( .. versionchanged:: 6.0 If the future is already cancelled, this function is a no-op. - (previously asyncio.InvalidStateError would be raised) + (previously ``asyncio.InvalidStateError`` would be raised) """ if exc_info[1] is None: diff --git a/tornado/httpclient.py b/tornado/httpclient.py index e02c60e3d..73c9e7b57 100644 --- a/tornado/httpclient.py +++ b/tornado/httpclient.py @@ -470,11 +470,11 @@ class HTTPRequest(object): ``simple_httpclient`` (unsupported by ``curl_httpclient``). Overrides ``validate_cert``, ``ca_certs``, ``client_key``, and ``client_cert``. - :arg bool allow_ipv6: Use IPv6 when available? Default is true. + :arg bool allow_ipv6: Use IPv6 when available? Default is True. :arg bool expect_100_continue: If true, send the ``Expect: 100-continue`` header and wait for a continue response before sending the request body. Only supported with - simple_httpclient. + ``simple_httpclient``. .. note:: @@ -570,34 +570,35 @@ class HTTPResponse(object): Attributes: - * request: HTTPRequest object + * ``request``: HTTPRequest object - * code: numeric HTTP status code, e.g. 200 or 404 + * ``code``: numeric HTTP status code, e.g. 200 or 404 - * reason: human-readable reason phrase describing the status code + * ``reason``: human-readable reason phrase describing the status code - * headers: `tornado.httputil.HTTPHeaders` object + * ``headers``: `tornado.httputil.HTTPHeaders` object - * effective_url: final location of the resource after following any + * ``effective_url``: final location of the resource after following any redirects - * buffer: ``cStringIO`` object for response body + * ``buffer``: ``cStringIO`` object for response body - * body: response body as bytes (created on demand from ``self.buffer``) + * ``body``: response body as bytes (created on demand from ``self.buffer``) - * error: Exception object, if any + * ``error``: Exception object, if any - * request_time: seconds from request start to finish. Includes all network - operations from DNS resolution to receiving the last byte of data. - Does not include time spent in the queue (due to the ``max_clients`` option). - If redirects were followed, only includes the final request. + * ``request_time``: seconds from request start to finish. Includes all + network operations from DNS resolution to receiving the last byte of + data. Does not include time spent in the queue (due to the + ``max_clients`` option). If redirects were followed, only includes + the final request. - * start_time: Time at which the HTTP operation started, based on `time.time` - (not the monotonic clock used by `.IOLoop.time`). May be ``None`` if the request - timed out while in the queue. + * ``start_time``: Time at which the HTTP operation started, based on + `time.time` (not the monotonic clock used by `.IOLoop.time`). May + be ``None`` if the request timed out while in the queue. - * time_info: dictionary of diagnostic timing information from the request. - Available data are subject to change, but currently uses timings + * ``time_info``: dictionary of diagnostic timing information from the + request. Available data are subject to change, but currently uses timings available from http://curl.haxx.se/libcurl/c/curl_easy_getinfo.html, plus ``queue``, which is the delay (if any) introduced by waiting for a slot under `AsyncHTTPClient`'s ``max_clients`` setting. diff --git a/tornado/ioloop.py b/tornado/ioloop.py index 14f73c83e..9ae16e2ec 100644 --- a/tornado/ioloop.py +++ b/tornado/ioloop.py @@ -878,7 +878,7 @@ class PeriodicCallback(object): self._timeout = None def is_running(self) -> bool: - """Return True if this `.PeriodicCallback` has been started. + """Returns ``True`` if this `.PeriodicCallback` has been started. .. versionadded:: 4.1 """ diff --git a/tornado/iostream.py b/tornado/iostream.py index a9bf977bd..8c01cb5e9 100644 --- a/tornado/iostream.py +++ b/tornado/iostream.py @@ -657,15 +657,15 @@ class BaseIOStream(object): self._write_buffer = None # type: ignore def reading(self) -> bool: - """Returns true if we are currently reading from the stream.""" + """Returns ``True`` if we are currently reading from the stream.""" return self._read_future is not None def writing(self) -> bool: - """Returns true if we are currently writing to the stream.""" + """Returns ``True`` if we are currently writing to the stream.""" return bool(self._write_buffer) def closed(self) -> bool: - """Returns true if the stream has been closed.""" + """Returns ``True`` if the stream has been closed.""" return self._closed def set_nodelay(self, value: bool) -> None: @@ -1053,7 +1053,7 @@ class BaseIOStream(object): self.io_loop.update_handler(self.fileno(), self._state) def _is_connreset(self, exc: BaseException) -> bool: - """Return true if exc is ECONNRESET or equivalent. + """Return ``True`` if exc is ECONNRESET or equivalent. May be overridden in subclasses. """ @@ -1335,7 +1335,7 @@ class IOStream(BaseIOStream): except socket.error as e: # Sometimes setsockopt will fail if the socket is closed # at the wrong time. This can happen with HTTPServer - # resetting the value to false between requests. + # resetting the value to ``False`` between requests. if e.errno != errno.EINVAL and not self._is_connreset(e): raise @@ -1441,7 +1441,7 @@ class SSLIOStream(IOStream): future_set_result_unless_cancelled(future, self) def _verify_cert(self, peercert: Any) -> bool: - """Returns True if peercert is valid according to the configured + """Returns ``True`` if peercert is valid according to the configured validation mode and hostname. The ssl handshake already tested the certificate for a valid diff --git a/tornado/netutil.py b/tornado/netutil.py index d570ff96d..9338ced3b 100644 --- a/tornado/netutil.py +++ b/tornado/netutil.py @@ -281,7 +281,7 @@ def add_accept_handler( def is_valid_ip(ip: str) -> bool: - """Returns true if the given string is a well-formed IP address. + """Returns ``True`` if the given string is a well-formed IP address. Supports IPv4 and IPv6. """ diff --git a/tornado/testing.py b/tornado/testing.py index 66e18c37e..fdfda44ae 100644 --- a/tornado/testing.py +++ b/tornado/testing.py @@ -293,8 +293,8 @@ class AsyncTestCase(unittest.TestCase): ``timeout`` keyword argument or globally with the ``ASYNC_TEST_TIMEOUT`` environment variable. - If ``condition`` is not None, the `.IOLoop` will be restarted - after `stop()` until ``condition()`` returns true. + If ``condition`` is not ``None``, the `.IOLoop` will be restarted + after `stop()` until ``condition()`` returns ``True``. .. versionchanged:: 3.1 Added the ``ASYNC_TEST_TIMEOUT`` environment variable. @@ -398,18 +398,18 @@ class AsyncHTTPTestCase(AsyncTestCase): """Convenience method to synchronously fetch a URL. The given path will be appended to the local server's host and - port. Any additional kwargs will be passed directly to + port. Any additional keyword arguments will be passed directly to `.AsyncHTTPClient.fetch` (and so could be used to pass ``method="POST"``, ``body="..."``, etc). If the path begins with http:// or https://, it will be treated as a full URL and will be fetched as-is. - If ``raise_error`` is True, a `tornado.httpclient.HTTPError` will + If ``raise_error`` is ``True``, a `tornado.httpclient.HTTPError` will be raised if the response code is not 200. This is the same behavior as the ``raise_error`` argument to `.AsyncHTTPClient.fetch`, but - the default is False here (it's True in `.AsyncHTTPClient`) because - tests often need to deal with non-200 response codes. + the default is ``False`` here (it's ``True`` in `.AsyncHTTPClient`) + because tests often need to deal with non-200 response codes. .. versionchanged:: 5.0 Added support for absolute URLs. @@ -631,7 +631,7 @@ class ExpectLog(logging.Filter): Useful to make tests of error conditions less noisy, while still leaving unexpected log entries visible. *Not thread safe.* - The attribute ``logged_stack`` is set to true if any exception + The attribute ``logged_stack`` is set to ``True`` if any exception stack trace was logged. Usage:: @@ -694,7 +694,7 @@ def main(**kwargs: Any) -> None: """A simple test runner. This test runner is essentially equivalent to `unittest.main` from - the standard library, but adds support for tornado-style option + the standard library, but adds support for Tornado-style option parsing and log formatting. It is *not* necessary to use this `main` function to run tests using `AsyncTestCase`; these tests are self-contained and can run with any test runner. @@ -703,8 +703,8 @@ def main(**kwargs: Any) -> None: python -m tornado.testing tornado.test.web_test - See the standard library unittest module for ways in which tests can - be specified. + See the standard library ``unittest`` module for ways in which + tests can be specified. Projects with many tests may wish to define a test script like ``tornado/test/runtests.py``. This script should define a method @@ -727,7 +727,7 @@ def main(**kwargs: Any) -> None: .. versionchanged:: 5.0 This function produces no output of its own; only that produced - by the `unittest` module (Previously it would add a PASS or FAIL + by the `unittest` module (previously it would add a PASS or FAIL log message). """ from tornado.options import define, options, parse_command_line diff --git a/tornado/util.py b/tornado/util.py index db0be6c8a..c1dc7c756 100644 --- a/tornado/util.py +++ b/tornado/util.py @@ -131,8 +131,8 @@ class GzipDecompressor(object): def import_object(name: str) -> Any: """Imports an object by name. - import_object('x') is equivalent to 'import x'. - import_object('x.y.z') is equivalent to 'from x.y import z'. + ``import_object('x')`` is equivalent to ``import x``. + ``import_object('x.y.z')`` is equivalent to ``from x.y import z``. >>> import tornado.escape >>> import_object('tornado.escape') is tornado.escape @@ -292,7 +292,9 @@ class Configurable(object): """Returns the base class of a configurable hierarchy. This will normally return the class in which it is defined. - (which is *not* necessarily the same as the cls classmethod parameter). + (which is *not* necessarily the same as the ``cls`` classmethod + parameter). + """ raise NotImplementedError() @@ -430,7 +432,7 @@ class ArgReplacer(object): def timedelta_to_seconds(td): # type: (datetime.timedelta) -> float - """Equivalent to td.total_seconds() (introduced in python 2.7).""" + """Equivalent to ``td.total_seconds()`` (introduced in Python 2.7).""" return td.total_seconds() diff --git a/tornado/web.py b/tornado/web.py index 8207ccab7..6545430e1 100644 --- a/tornado/web.py +++ b/tornado/web.py @@ -238,8 +238,8 @@ class RequestHandler(object): initialize = _initialize # type: Callable[..., None] """Hook for subclass initialization. Called for each request. - A dictionary passed as the third argument of a url spec will be - supplied as keyword arguments to initialize(). + A dictionary passed as the third argument of a ``URLSpec`` will be + supplied as keyword arguments to ``initialize()``. Example:: @@ -814,7 +814,7 @@ class RequestHandler(object): If the given chunk is a dictionary, we write it as JSON and set the Content-Type of the response to be ``application/json``. (if you want to send JSON as a different ``Content-Type``, call - set_header *after* calling write()). + ``set_header`` *after* calling ``write()``). Note that lists are not converted to JSON because of a potential cross-site security vulnerability. All JSON output should be diff --git a/tornado/websocket.py b/tornado/websocket.py index 50665c694..c9c5b5d79 100644 --- a/tornado/websocket.py +++ b/tornado/websocket.py @@ -498,9 +498,9 @@ class WebSocketHandler(tornado.web.RequestHandler): implement WebSockets support this header, and non-browser clients do not have the same cross-site security concerns). - Should return True to accept the request or False to reject it. - By default, rejects all requests with an origin on a host other - than this one. + Should return ``True`` to accept the request or ``False`` to + reject it. By default, rejects all requests with an origin on + a host other than this one. This is a security protection against cross site scripting attacks on browsers, since WebSockets are allowed to bypass the usual same-origin @@ -520,7 +520,7 @@ class WebSocketHandler(tornado.web.RequestHandler): for more. To accept all cross-origin traffic (which was the default prior to - Tornado 4.0), simply override this method to always return true:: + Tornado 4.0), simply override this method to always return ``True``:: def check_origin(self, origin): return True @@ -1281,7 +1281,7 @@ class WebSocketProtocol13(WebSocketProtocol): ) def is_closing(self) -> bool: - """Return true if this connection is closing. + """Return ``True`` if this connection is closing. The connection is considered closing if either side has initiated its closing handshake or if the stream has been