[Python-checkins] cpython (3.5): Issue #20112: Improve BaseHTTPRequestHandler.error_message_format documentation

[berker.peksag]

https://hg.python.org/cpython/rev/a912ca4f507b
changeset:   101103:a912ca4f507b
branch:      3.5
parent:      101100:16461a0016bf
user:        Berker Peksag <berker.peksag at gmail.com>
date:        Sun Apr 24 01:51:02 2016 +0300
summary:
  Issue #20112: Improve BaseHTTPRequestHandler.error_message_format documentation

* Explain how 'error_message_format' is used by 'send_error' method
* Mention that 'responses' is used by 'send_response_only' and 'send_error' methods
* Replace 'class variables' with 'attributes'

Initial patch by Anastasia Filatova.

files:
  Doc/library/http.server.rst |  29 +++++++++---------------
  1 files changed, 11 insertions(+), 18 deletions(-)


diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst
--- a/Doc/library/http.server.rst
+++ b/Doc/library/http.server.rst
@@ -97,7 +97,6 @@
       :mod:`http.client` is used to parse the headers and it requires that the
       HTTP request provide a valid :rfc:`2822` style header.
 
-
    .. attribute:: rfile
 
       Contains an input stream, positioned at the start of the optional input
@@ -109,7 +108,7 @@
       client. Proper adherence to the HTTP protocol must be used when writing to
       this stream.
 
-   :class:`BaseHTTPRequestHandler` has the following class variables:
+   :class:`BaseHTTPRequestHandler` has the following attributes:
 
    .. attribute:: server_version
 
@@ -125,13 +124,10 @@
 
    .. attribute:: error_message_format
 
-      Specifies a format string for building an error response to the client. It
-      uses parenthesized, keyed format specifiers, so the format operand must be
-      a dictionary. The *code* key should be an integer, specifying the numeric
-      HTTP error code value. *message* should be a string containing a
-      (detailed) error message of what occurred, and *explain* should be an
-      explanation of the error code number. Default *message* and *explain*
-      values can found in the :attr:`responses` class variable.
+      Specifies a format string that should be used by :meth:`send_error` method
+      for building an error response to the client. The string is filled by
+      default with variables from :attr:`responses` based on the status code
+      that passed to :meth:`send_error`.
 
    .. attribute:: error_content_type
 
@@ -154,11 +150,11 @@
 
    .. attribute:: responses
 
-      This variable contains a mapping of error code integers to two-element tuples
+      This attribute contains a mapping of error code integers to two-element tuples
       containing a short and long message. For example, ``{code: (shortmessage,
       longmessage)}``. The *shortmessage* is usually used as the *message* key in an
-      error response, and *longmessage* as the *explain* key (see the
-      :attr:`error_message_format` class variable).
+      error response, and *longmessage* as the *explain* key.  It is used by
+      :meth:`send_response_only` and :meth:`send_error` methods.
 
    A :class:`BaseHTTPRequestHandler` instance has the following methods:
 
@@ -191,9 +187,9 @@
       specifies the HTTP error code, with *message* as an optional, short, human
       readable description of the error.  The *explain* argument can be used to
       provide more detailed information about the error; it will be formatted
-      using the :attr:`error_message_format` class variable and emitted, after
+      using the :attr:`error_message_format` attribute and emitted, after
       a complete set of headers, as the response body.  The :attr:`responses`
-      class variable holds the default values for *message* and *explain* that
+      attribute holds the default values for *message* and *explain* that
       will be used if no value is provided; for unknown codes the default value
       for both is the string ``???``.
 
@@ -201,7 +197,6 @@
          The error response includes a Content-Length header.
          Added the *explain* argument.
 
-
    .. method:: send_response(code, message=None)
 
       Adds a response header to the headers buffer and logs the accepted
@@ -217,7 +212,6 @@
          Headers are stored to an internal buffer and :meth:`end_headers`
          needs to be called explicitly.
 
-
    .. method:: send_header(keyword, value)
 
       Adds the HTTP header to an internal buffer which will be written to the
@@ -229,7 +223,6 @@
       .. versionchanged:: 3.2
          Headers are stored in an internal buffer.
 
-
    .. method:: send_response_only(code, message=None)
 
       Sends the response header only, used for the purposes when ``100
@@ -279,7 +272,7 @@
    .. method:: version_string()
 
       Returns the server software's version string. This is a combination of the
-      :attr:`server_version` and :attr:`sys_version` class variables.
+      :attr:`server_version` and :attr:`sys_version` attributes.
 
    .. method:: date_time_string(timestamp=None)
 

-- 
Repository URL: https://hg.python.org/cpython