Merge pull request tornadoweb#2563 from bdarnell/docs-update

docs: Various updates

docs/concurrent.rst

@@ -11,9 +11,7 @@
 
      .. class:: Future
 
-        ``tornado.concurrent.Future`` is an alias for `asyncio.Future`
-        on Python 3. On Python 2, it provides an equivalent
-        implementation.
+        ``tornado.concurrent.Future`` is an alias for `asyncio.Future`.
 
         In Tornado, the main way in which applications interact with
         ``Future`` objects is by ``awaiting`` or ``yielding`` them in

docs/conda.yml

@@ -5,4 +5,5 @@ dependencies:
   - pip:
     - sphinx
     - sphinx-rtd-theme
+    - sphinxcontrib-asyncio
     - Twisted

docs/conf.py

@@ -18,6 +18,7 @@
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
+    "sphinxcontrib.asyncio",
 ]
 
 primary_domain = "py"
@@ -37,6 +38,7 @@
     "tornado.platform.asyncio",
     "tornado.platform.caresresolver",
     "tornado.platform.twisted",
+    "tornado.simple_httpclient",
 ]
 # I wish this could go in a per-module file...
 coverage_ignore_classes = [

docs/escape.rst

@@ -17,19 +17,15 @@
 
    Byte/unicode conversions
    ------------------------
-   These functions are used extensively within Tornado itself,
-   but should not be directly needed by most applications.  Note that 
-   much of the complexity of these functions comes from the fact that
-   Tornado supports both Python 2 and Python 3.
 
    .. autofunction:: utf8
    .. autofunction:: to_unicode
    .. function:: native_str
+   .. function:: to_basestring
 
-      Converts a byte or unicode string into type `str`.  Equivalent to
-      `utf8` on Python 2 and `to_unicode` on Python 3.
-
-   .. autofunction:: to_basestring
+      Converts a byte or unicode string into type `str`. These functions
+      were used to help transition from Python 2 to Python 3 but are now
+      deprecated aliases for `to_unicode`.
 
    .. autofunction:: recursive_unicode
 

docs/gen.rst

@@ -13,27 +13,27 @@
 
    .. autofunction:: coroutine
 
+   .. autoexception:: Return
+
    Utility functions
    -----------------
 
-   .. autoexception:: Return
-
-   .. autofunction:: with_timeout
+   .. autofunction:: with_timeout(timeout: Union[float, datetime.timedelta], future: Yieldable, quiet_exceptions: Union[Type[Exception], Tuple[Type[Exception], ...]] = ())
 
    .. autofunction:: sleep
 
-   .. autodata:: moment
-      :annotation:
-
    .. autoclass:: WaitIterator
       :members:
 
-   .. autofunction:: multi
+   .. autofunction:: multi(Union[List[Yieldable], Dict[Any, Yieldable]], quiet_exceptions: Union[Type[Exception], Tuple[Type[Exception], ...]] = ())
 
-   .. autofunction:: multi_future
+   .. autofunction:: multi_future(Union[List[Yieldable], Dict[Any, Yieldable]], quiet_exceptions: Union[Type[Exception], Tuple[Type[Exception], ...]] = ())
 
    .. autofunction:: convert_yielded
 
    .. autofunction:: maybe_future
 
    .. autofunction:: is_coroutine_function
+
+   .. autodata:: moment
+      :annotation:

docs/httpclient.rst

@@ -47,7 +47,9 @@ Implementations
 ~~~~~~~~~~~~~~~
 
 .. automodule:: tornado.simple_httpclient
-   :members:
+
+   .. autoclass:: SimpleAsyncHTTPClient
+      :members:
 
 .. module:: tornado.curl_httpclient
 

docs/httpserver.rst

@@ -5,5 +5,8 @@
 
    HTTP Server
    -----------
-   .. autoclass:: HTTPServer
+   .. autoclass:: HTTPServer(request_callback: Union[httputil.HTTPServerConnectionDelegate, Callable[[httputil.HTTPServerRequest], None]], no_keep_alive: bool = False, xheaders: bool = False, ssl_options: Union[Dict[str, Any], ssl.SSLContext] = None, protocol: str = None, decompress_request: bool = False, chunk_size: int = None, max_header_size: int = None, idle_connection_timeout: float = None, body_timeout: float = None, max_body_size: int = None, max_buffer_size: int = None, trusted_downstream: List[str] = None)
       :members:
+
+      The public interface of this class is mostly inherited from
+      `.TCPServer` and is documented under that class.

docs/ioloop.rst

@@ -45,10 +45,3 @@
    .. automethod:: IOLoop.time
    .. autoclass:: PeriodicCallback
       :members:
-
-   Methods for subclasses
-   ^^^^^^^^^^^^^^^^^^^^^^
-
-   .. automethod:: IOLoop.initialize
-   .. automethod:: IOLoop.close_fd
-   .. automethod:: IOLoop.split_fd

docs/locks.rst

@@ -10,9 +10,10 @@ similar to those provided in the standard library's `asyncio package
 
 .. warning::
 
-   Note that these primitives are not actually thread-safe and cannot be used in
-   place of those from the standard library--they are meant to coordinate Tornado
-   coroutines in a single-threaded app, not to protect shared objects in a
+   Note that these primitives are not actually thread-safe and cannot
+   be used in place of those from the standard library's `threading`
+   module--they are meant to coordinate Tornado coroutines in a
+   single-threaded app, not to protect shared objects in a
    multithreaded app.
 
 .. automodule:: tornado.locks

docs/releases/v4.2.0.rst

@@ -162,7 +162,7 @@ Then the Tornado equivalent is::
 * The `.IOLoop` constructor now has a ``make_current`` keyword argument
   to control whether the new `.IOLoop` becomes `.IOLoop.current()`.
 * Third-party implementations of `.IOLoop` should accept ``**kwargs``
-  in their `~.IOLoop.initialize` methods and pass them to the superclass
+  in their ``IOLoop.initialize`` methods and pass them to the superclass
   implementation.
 * `.PeriodicCallback` is now more efficient when the clock jumps forward
   by a large amount.

docs/requirements.txt

@@ -1,3 +1,4 @@
 sphinx>1.8.2
+sphinxcontrib-asyncio
 sphinx_rtd_theme
 Twisted

docs/web.rst

@@ -9,7 +9,7 @@
 
    Request handlers
    ----------------
-   .. autoclass:: RequestHandler
+   .. autoclass:: RequestHandler(...)
 
    Entry points
    ^^^^^^^^^^^^
@@ -50,11 +50,24 @@
    Input
    ^^^^^
 
-   .. automethod:: RequestHandler.get_argument
+   The ``argument`` methods provide support for HTML form-style
+   arguments. These methods are available in both singular and plural
+   forms because HTML forms are ambiguous and do not distinguish
+   between a singular argument and a list containing one entry. If you
+   wish to use other formats for arguments (for example, JSON), parse
+   ``self.request.body`` yourself::
+
+       def prepare(self):
+           if self.request.headers['Content-Type'] == 'application/x-json':
+               self.args = json_decode(self.request.body)
+           # Access self.args directly instead of using self.get_argument.
+
+
+   .. automethod:: RequestHandler.get_argument(name: str, default: Union[None, str, RAISE] = RAISE, strip: bool = True) -> Optional[str]
    .. automethod:: RequestHandler.get_arguments
-   .. automethod:: RequestHandler.get_query_argument
+   .. automethod:: RequestHandler.get_query_argument(name: str, default: Union[None, str, RAISE] = RAISE, strip: bool = True) -> Optional[str]
    .. automethod:: RequestHandler.get_query_arguments
-   .. automethod:: RequestHandler.get_body_argument
+   .. automethod:: RequestHandler.get_body_argument(name: str, default: Union[None, str, RAISE] = RAISE, strip: bool = True) -> Optional[str]
    .. automethod:: RequestHandler.get_body_arguments
    .. automethod:: RequestHandler.decode_argument
    .. attribute:: RequestHandler.request
@@ -147,8 +160,7 @@
 
    Application configuration
    -----------------------------
-   .. autoclass:: Application
-      :members:
+   .. autoclass:: Application(handlers: List[Union[Rule, Tuple]] = None, default_host: str = None, transforms: List[Type[OutputTransform]] = None, **settings)
 
       .. attribute:: settings
 
@@ -266,6 +278,12 @@
            should be a dictionary of keyword arguments to be passed to the
            handler's ``initialize`` method.
 
+   .. automethod:: Application.listen
+   .. automethod:: Application.add_handlers(handlers: List[Union[Rule, Tuple]])
+   .. automethod:: Application.get_handler_delegate
+   .. automethod:: Application.reverse_url
+   .. automethod:: Application.log_request
+
    .. autoclass:: URLSpec
 
       The ``URLSpec`` class is also available under the name ``tornado.web.url``.

tornado/auth.py

@@ -102,7 +102,7 @@ def authenticate_redirect(
 
         .. versionchanged:: 6.0
 
-           The ``callback`` argument was removed and this method no
+            The ``callback`` argument was removed and this method no
             longer returns an awaitable object. It is now an ordinary
             synchronous function.
         """
@@ -128,7 +128,7 @@ async def get_authenticated_user(
 
         .. versionchanged:: 6.0
 
-           The ``callback`` argument was removed. Use the returned
+            The ``callback`` argument was removed. Use the returned
             awaitable object instead.
         """
         handler = cast(RequestHandler, self)

tornado/concurrent.py

@@ -14,17 +14,15 @@
 # under the License.
 """Utilities for working with ``Future`` objects.
 
-``Futures`` are a pattern for concurrent programming introduced in
-Python 3.2 in the `concurrent.futures` package, and also adopted (in a
-slightly different form) in Python 3.4's `asyncio` package. This
-package defines a ``Future`` class that is an alias for `asyncio.Future`
-when available, and a compatible implementation for older versions of
-Python. It also includes some utility functions for interacting with
-``Future`` objects.
-
-While this package is an important part of Tornado's internal
+Tornado previously provided its own ``Future`` class, but now uses
+`asyncio.Future`. This module contains utility functions for working
+with `asyncio.Future` in a way that is backwards-compatible with
+Tornado's old ``Future`` implementation.
+
+While this module is an important part of Tornado's internal
 implementation, applications rarely need to interact with it
 directly.
+
 """
 
 import asyncio

tornado/escape.py

@@ -24,7 +24,7 @@
 import re
 import urllib.parse
 
-from tornado.util import unicode_type, basestring_type
+from tornado.util import unicode_type
 
 import typing
 from typing import Union, Any, Optional, Dict, List, Callable
@@ -76,7 +76,10 @@ def json_encode(value: Any) -> str:
 
 
 def json_decode(value: Union[str, bytes]) -> Any:
-    """Returns Python objects for the given JSON string."""
+    """Returns Python objects for the given JSON string.
+
+    Supports both `str` and `bytes` inputs.
+    """
     return json.loads(to_basestring(value))
 
 
@@ -231,39 +234,7 @@ def to_unicode(value: Union[None, str, bytes]) -> Optional[str]:  # noqa: F811
 # When dealing with the standard library across python 2 and 3 it is
 # sometimes useful to have a direct conversion to the native string type
 native_str = to_unicode
-
-_BASESTRING_TYPES = (basestring_type, type(None))
-
-
-@typing.overload
-def to_basestring(value: str) -> str:
-    pass
-
-
-@typing.overload  # noqa: F811
-def to_basestring(value: bytes) -> str:
-    pass
-
-
-@typing.overload  # noqa: F811
-def to_basestring(value: None) -> None:
-    pass
-
-
-def to_basestring(value: Union[None, str, bytes]) -> Optional[str]:  # noqa: F811
-    """Converts a string argument to a subclass of basestring.
-
-    In python2, byte and unicode strings are mostly interchangeable,
-    so functions that deal with a user-supplied argument in combination
-    with ascii string constants can use either and should return the type
-    the user supplied.  In python3, the two types are not interchangeable,
-    so this method is needed to convert byte strings to unicode.
-    """
-    if isinstance(value, _BASESTRING_TYPES):
-        return value
-    if not isinstance(value, bytes):
-        raise TypeError("Expected bytes, unicode, or None; got %r" % type(value))
-    return value.decode("utf-8")
+to_basestring = to_unicode
 
 
 def recursive_unicode(obj: Any) -> Any: