From: Ben Darnell Date: Mon, 26 Feb 2018 13:15:43 +0000 (-0500) Subject: docs: Updates for sphinx 1.7 X-Git-Tag: v5.0.0~5^2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F2293%2Fhead;p=thirdparty%2Ftornado.git docs: Updates for sphinx 1.7 This introduced a new inherit-docstring option that we don't want (it currently breaks our docs build) and got stricter about `:arg` types. --- diff --git a/docs/conf.py b/docs/conf.py index 54eb65fb1..39345d282 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -25,6 +25,7 @@ default_role = 'py:obj' autodoc_member_order = "bysource" autoclass_content = "both" +autodoc_inherit_docstrings = False # Without this line sphinx includes a copy of object.__init__'s docstring # on any class that doesn't define __init__. diff --git a/tornado/httpclient.py b/tornado/httpclient.py index 77c48cf03..3547631da 100644 --- a/tornado/httpclient.py +++ b/tornado/httpclient.py @@ -321,8 +321,8 @@ class HTTPRequest(object): ssl_options=None): r"""All parameters except ``url`` are optional. - :arg string url: URL to fetch - :arg string method: HTTP method, e.g. "GET" or "POST" + :arg str url: URL to fetch + :arg str method: HTTP method, e.g. "GET" or "POST" :arg headers: Additional HTTP headers to pass on the request :type headers: `~tornado.httputil.HTTPHeaders` or `dict` :arg body: HTTP request body as a string (byte or unicode; if unicode @@ -338,9 +338,9 @@ class HTTPRequest(object): to pass a ``Content-Length`` in the headers as otherwise chunked encoding will be used, and many servers do not support chunked encoding on requests. New in Tornado 4.0 - :arg string auth_username: Username for HTTP authentication - :arg string auth_password: Password for HTTP authentication - :arg string auth_mode: Authentication mode; default is "basic". + :arg str auth_username: Username for HTTP authentication + :arg str auth_password: Password for HTTP authentication + :arg str auth_mode: Authentication mode; default is "basic". Allowed values are implementation-defined; ``curl_httpclient`` supports "basic" and "digest"; ``simple_httpclient`` only supports "basic" @@ -353,19 +353,19 @@ class HTTPRequest(object): :arg bool follow_redirects: Should redirects be followed automatically or return the 3xx response? Default True. :arg int max_redirects: Limit for ``follow_redirects``, default 5. - :arg string user_agent: String to send as ``User-Agent`` header + :arg str user_agent: String to send as ``User-Agent`` header :arg bool decompress_response: Request a compressed response from the server and decompress it after downloading. Default is True. New in Tornado 4.0. :arg bool use_gzip: Deprecated alias for ``decompress_response`` since Tornado 4.0. - :arg string network_interface: Network interface to use for request. + :arg str network_interface: Network interface to use for request. ``curl_httpclient`` only; see note below. - :arg callable streaming_callback: If set, ``streaming_callback`` will + :arg collections.abc.Callable streaming_callback: If set, ``streaming_callback`` will be run with each chunk of data as it is received, and ``HTTPResponse.body`` and ``HTTPResponse.buffer`` will be empty in the final response. - :arg callable header_callback: If set, ``header_callback`` will + :arg collections.abc.Callable header_callback: If set, ``header_callback`` will be run with each header line as it is received (including the first line, e.g. ``HTTP/1.0 200 OK\r\n``, and a final line containing only ``\r\n``. All lines include the trailing newline @@ -373,28 +373,28 @@ class HTTPRequest(object): response. This is most useful in conjunction with ``streaming_callback``, because it's the only way to get access to header data while the request is in progress. - :arg callable prepare_curl_callback: If set, will be called with + :arg collections.abc.Callable prepare_curl_callback: If set, will be called with a ``pycurl.Curl`` object to allow the application to make additional ``setopt`` calls. - :arg string proxy_host: HTTP proxy hostname. To use proxies, + :arg str proxy_host: HTTP proxy hostname. To use proxies, ``proxy_host`` and ``proxy_port`` must be set; ``proxy_username``, ``proxy_pass`` and ``proxy_auth_mode`` are optional. Proxies are currently only supported with ``curl_httpclient``. :arg int proxy_port: HTTP proxy port - :arg string proxy_username: HTTP proxy username - :arg string proxy_password: HTTP proxy password - :arg string proxy_auth_mode: HTTP proxy Authentication mode; + :arg str proxy_username: HTTP proxy username + :arg str proxy_password: HTTP proxy password + :arg str proxy_auth_mode: HTTP proxy Authentication mode; default is "basic". supports "basic" and "digest" :arg bool allow_nonstandard_methods: Allow unknown values for ``method`` argument? Default is False. :arg bool validate_cert: For HTTPS requests, validate the server's certificate? Default is True. - :arg string ca_certs: filename of CA certificates in PEM format, + :arg str ca_certs: filename of CA certificates in PEM format, or None to use defaults. See note below when used with ``curl_httpclient``. - :arg string client_key: Filename for client SSL key, if any. See + :arg str client_key: Filename for client SSL key, if any. See note below when used with ``curl_httpclient``. - :arg string client_cert: Filename for client SSL certificate, if any. + :arg str client_cert: Filename for client SSL certificate, if any. See note below when used with ``curl_httpclient``. :arg ssl.SSLContext ssl_options: `ssl.SSLContext` object for use in ``simple_httpclient`` (unsupported by ``curl_httpclient``). diff --git a/tornado/log.py b/tornado/log.py index 3074b6371..cda905c9b 100644 --- a/tornado/log.py +++ b/tornado/log.py @@ -115,13 +115,13 @@ class LogFormatter(logging.Formatter): style='%', color=True, colors=DEFAULT_COLORS): r""" :arg bool color: Enables color support. - :arg string fmt: Log message format. + :arg str fmt: Log message format. It will be applied to the attributes dict of log records. The text between ``%(color)s`` and ``%(end_color)s`` will be colored depending on the level if color support is on. :arg dict colors: color mappings from logging level to terminal color code - :arg string datefmt: Datetime format. + :arg str datefmt: Datetime format. Used for formatting ``(asctime)`` placeholder in ``prefix_fmt``. .. versionchanged:: 3.2 diff --git a/tornado/web.py b/tornado/web.py index 7bf5415d0..eaab91eed 100644 --- a/tornado/web.py +++ b/tornado/web.py @@ -309,7 +309,7 @@ class RequestHandler(object): """Sets the status code for our response. :arg int status_code: Response status code. - :arg string reason: Human-readable reason phrase describing the status + :arg str reason: Human-readable reason phrase describing the status code. If ``None``, it will be filled in from `http.client.responses` or "Unknown". @@ -2170,11 +2170,11 @@ class HTTPError(Exception): :arg int status_code: HTTP status code. Must be listed in `httplib.responses ` unless the ``reason`` keyword argument is given. - :arg string log_message: Message to be written to the log for this error + :arg str log_message: Message to be written to the log for this error (will not be shown to the user unless the `Application` is in debug mode). May contain ``%s``-style placeholders, which will be filled in with remaining positional parameters. - :arg string reason: Keyword-only argument. The HTTP "reason" phrase + :arg str reason: Keyword-only argument. The HTTP "reason" phrase to pass in the status line along with ``status_code``. Normally determined automatically from ``status_code``, but can be used to use a non-standard numeric code.