[Python-checkins] bpo-37331: Clarify format of socket handler messages in the documentation. (GH-14234) (GH-14235)

Vinay Sajip webhook-mailer at python.org
Wed Jun 19 10:42:39 EDT 2019


https://github.com/python/cpython/commit/d7232f0e4646803f0bbaede6e1fa124156135512
commit: d7232f0e4646803f0bbaede6e1fa124156135512
branch: 3.8
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: Vinay Sajip <vinay_sajip at yahoo.co.uk>
date: 2019-06-19T15:42:35+01:00
summary:

bpo-37331: Clarify format of socket handler messages in the documentation. (GH-14234) (GH-14235)

(cherry picked from commit f06b569305cf604f070776ea3f800ed61fdd7d61)

files:
M Doc/library/logging.handlers.rst

diff --git a/Doc/library/logging.handlers.rst b/Doc/library/logging.handlers.rst
index dee9a84e3337..b48d50f9e9e5 100644
--- a/Doc/library/logging.handlers.rst
+++ b/Doc/library/logging.handlers.rst
@@ -470,7 +470,12 @@ sends logging output to a network socket. The base class uses a TCP socket.
    .. method:: makePickle(record)
 
       Pickles the record's attribute dictionary in binary format with a length
-      prefix, and returns it ready for transmission across the socket.
+      prefix, and returns it ready for transmission across the socket. The
+      details of this operation are equivalent to::
+
+          data = pickle.dumps(record_attr_dict, 1)
+          datalen = struct.pack('>L', len(data))
+          return datalen + data
 
       Note that pickles aren't completely secure. If you are concerned about
       security, you may want to override this method to implement a more secure
@@ -481,8 +486,12 @@ sends logging output to a network socket. The base class uses a TCP socket.
 
    .. method:: send(packet)
 
-      Send a pickled string *packet* to the socket. This function allows for
-      partial sends which can happen when the network is busy.
+      Send a pickled byte-string *packet* to the socket. The format of the sent
+      byte-string is as described in the documentation for
+      :meth:`~SocketHandler.makePickle`.
+
+      This function allows for partial sends, which can happen when the network
+      is busy.
 
 
    .. method:: createSocket()
@@ -543,7 +552,8 @@ over UDP sockets.
 
    .. method:: send(s)
 
-      Send a pickled string to a socket.
+      Send a pickled byte-string to a socket. The format of the sent byte-string
+      is as described in the documentation for :meth:`SocketHandler.makePickle`.
 
 
 .. _syslog-handler:



More information about the Python-checkins mailing list