From: Vinay Sajip <vinay_sajip@yahoo.co.uk>
Date: Fri, 30 May 2014 17:46:02 +0000 (+0100)
Subject: Issue #21608: Updated HTTPHandler documentation.
X-Git-Tag: v2.7.8~37^2~66
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=ab2db5815c28314d3b7bd3d7c3d2e1b5932ea524;p=thirdparty%2FPython%2Fcpython.git

Issue #21608: Updated HTTPHandler documentation.
---

diff --git a/Doc/library/logging.handlers.rst b/Doc/library/logging.handlers.rst
index 3c05e9ae13de..d0f9be82f1e1 100644
--- a/Doc/library/logging.handlers.rst
+++ b/Doc/library/logging.handlers.rst
@@ -729,15 +729,29 @@ supports sending logging messages to a Web server, using either ``GET`` or
 
 .. class:: HTTPHandler(host, url, method='GET')
 
-   Returns a new instance of the :class:`HTTPHandler` class. The *host* can be
+   Returns a new instance of the :class:`HTTPHandler` class. The ``host`` can be
    of the form ``host:port``, should you need to use a specific port number.
-   If no *method* is specified, ``GET`` is used.
 
+   .. method:: mapLogRecord(record)
+
+      Provides a dictionary, based on ``record``, which is to be URL-encoded
+      and sent to the web server. The default implementation just returns
+      ``record.__dict__``. This method can be overridden if e.g. only a
+      subset of :class:`~logging.LogRecord` is to be sent to the web server, or
+      if more specific customization of what's sent to the server is required.
 
    .. method:: emit(record)
 
-      Sends the record to the Web server as a percent-encoded dictionary.
+      Sends the record to the Web server as an URL-encoded dictionary. The
+      :meth:`mapLogRecord` method is used to convert the record to the
+      dictionary to be sent.
 
+   .. note:: Since preparing a record for sending it to a Web server is not
+      the same as a generic formatting operation, using :meth:`setFormatter`
+      to specify a :class:`Formatter` for a :class:`HTTPHandler` has no effect.
+      Instead of calling :meth:`format`, this handler calls :meth:`mapLogRecord`
+      and then :func:`urllib.urlencode` to encode the dictionary in a form
+      suitable for sending to a Web server.
 
 .. seealso::
 
diff --git a/Lib/logging/handlers.py b/Lib/logging/handlers.py
index c45a3132ba7b..30ad0365f28d 100644
--- a/Lib/logging/handlers.py
+++ b/Lib/logging/handlers.py
@@ -1067,7 +1067,7 @@ class HTTPHandler(logging.Handler):
         """
         Default implementation of mapping the log record into a dict
         that is sent as the CGI data. Overwrite in your class.
-        Contributed by Franz  Glasner.
+        Contributed by Franz Glasner.
         """
         return record.__dict__