reformat some documentation of classes so methods and attributes are under the class directive
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index 775aef4..9cd3668 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -1514,19 +1514,19 @@
will be used.
-.. method:: StreamHandler.emit(record)
+ .. method:: emit(record)
- If a formatter is specified, it is used to format the record. The record is then
- written to the stream with a trailing newline. If exception information is
- present, it is formatted using :func:`traceback.print_exception` and appended to
- the stream.
+ If a formatter is specified, it is used to format the record. The record
+ is then written to the stream with a trailing newline. If exception
+ information is present, it is formatted using
+ :func:`traceback.print_exception` and appended to the stream.
-.. method:: StreamHandler.flush()
+ .. method:: flush()
- Flushes the stream by calling its :meth:`flush` method. Note that the
- :meth:`close` method is inherited from :class:`Handler` and so does nothing, so
- an explicit :meth:`flush` call may be needed at times.
+ Flushes the stream by calling its :meth:`flush` method. Note that the
+ :meth:`close` method is inherited from :class:`Handler` and so does
+ nothing, so an explicit :meth:`flush` call may be needed at times.
FileHandler
@@ -1546,14 +1546,14 @@
first call to :meth:`emit`. By default, the file grows indefinitely.
-.. method:: FileHandler.close()
+ .. method:: close()
- Closes the file.
+ Closes the file.
-.. method:: FileHandler.emit(record)
+ .. method:: emit(record)
- Outputs the record to the file.
+ Outputs the record to the file.
WatchedFileHandler
@@ -1588,11 +1588,11 @@
first call to :meth:`emit`. By default, the file grows indefinitely.
-.. method:: WatchedFileHandler.emit(record)
+ .. method:: emit(record)
- Outputs the record to the file, but first checks to see if the file has changed.
- If it has, the existing stream is flushed and closed and the file opened again,
- before outputting the record to the file.
+ Outputs the record to the file, but first checks to see if the file has
+ changed. If it has, the existing stream is flushed and closed and the
+ file opened again, before outputting the record to the file.
RotatingFileHandler
@@ -1624,14 +1624,15 @@
:file:`app.log.2`, :file:`app.log.3` etc. respectively.
-.. method:: RotatingFileHandler.doRollover()
+ .. method:: doRollover()
- Does a rollover, as described above.
+ Does a rollover, as described above.
-.. method:: RotatingFileHandler.emit(record)
+ .. method:: emit(record)
- Outputs the record to the file, catering for rollover as described previously.
+ Outputs the record to the file, catering for rollover as described
+ previously.
TimedRotatingFileHandler
@@ -1677,14 +1678,14 @@
files to delete, so changing the interval may leave old files lying around.
-.. method:: TimedRotatingFileHandler.doRollover()
+ .. method:: doRollover()
- Does a rollover, as described above.
+ Does a rollover, as described above.
-.. method:: TimedRotatingFileHandler.emit(record)
+ .. method:: emit(record)
- Outputs the record to the file, catering for rollover as described above.
+ Outputs the record to the file, catering for rollover as described above.
SocketHandler
@@ -1700,43 +1701,44 @@
communicate with a remote machine whose address is given by *host* and *port*.
-.. method:: SocketHandler.close()
+ .. method:: close()
- Closes the socket.
+ Closes the socket.
-.. method:: SocketHandler.emit()
+ .. method:: emit()
- Pickles the record's attribute dictionary and writes it to the socket in binary
- format. If there is an error with the socket, silently drops the packet. If the
- connection was previously lost, re-establishes the connection. To unpickle the
- record at the receiving end into a :class:`LogRecord`, use the
- :func:`makeLogRecord` function.
+ Pickles the record's attribute dictionary and writes it to the socket in
+ binary format. If there is an error with the socket, silently drops the
+ packet. If the connection was previously lost, re-establishes the
+ connection. To unpickle the record at the receiving end into a
+ :class:`LogRecord`, use the :func:`makeLogRecord` function.
-.. method:: SocketHandler.handleError()
+ .. method:: handleError()
- Handles an error which has occurred during :meth:`emit`. The most likely cause
- is a lost connection. Closes the socket so that we can retry on the next event.
+ Handles an error which has occurred during :meth:`emit`. The most likely
+ cause is a lost connection. Closes the socket so that we can retry on the
+ next event.
-.. method:: SocketHandler.makeSocket()
+ .. method:: makeSocket()
- This is a factory method which allows subclasses to define the precise type of
- socket they want. The default implementation creates a TCP socket
- (:const:`socket.SOCK_STREAM`).
+ This is a factory method which allows subclasses to define the precise
+ type of socket they want. The default implementation creates a TCP socket
+ (:const:`socket.SOCK_STREAM`).
-.. method:: SocketHandler.makePickle(record)
+ .. 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.
+ Pickles the record's attribute dictionary in binary format with a length
+ prefix, and returns it ready for transmission across the socket.
-.. method:: SocketHandler.send(packet)
+ .. 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 string *packet* to the socket. This function allows for
+ partial sends which can happen when the network is busy.
DatagramHandler
@@ -1753,23 +1755,23 @@
communicate with a remote machine whose address is given by *host* and *port*.
-.. method:: DatagramHandler.emit()
+ .. method:: emit()
- Pickles the record's attribute dictionary and writes it to the socket in binary
- format. If there is an error with the socket, silently drops the packet. To
- unpickle the record at the receiving end into a :class:`LogRecord`, use the
- :func:`makeLogRecord` function.
+ Pickles the record's attribute dictionary and writes it to the socket in
+ binary format. If there is an error with the socket, silently drops the
+ packet. To unpickle the record at the receiving end into a
+ :class:`LogRecord`, use the :func:`makeLogRecord` function.
-.. method:: DatagramHandler.makeSocket()
+ .. method:: makeSocket()
- The factory method of :class:`SocketHandler` is here overridden to create a UDP
- socket (:const:`socket.SOCK_DGRAM`).
+ The factory method of :class:`SocketHandler` is here overridden to create
+ a UDP socket (:const:`socket.SOCK_DGRAM`).
-.. method:: DatagramHandler.send(s)
+ .. method:: send(s)
- Send a pickled string to a socket.
+ Send a pickled string to a socket.
SysLogHandler
@@ -1791,22 +1793,22 @@
:const:`LOG_USER` is used.
-.. method:: SysLogHandler.close()
+ .. method:: close()
- Closes the socket to the remote host.
+ Closes the socket to the remote host.
-.. method:: SysLogHandler.emit(record)
+ .. method:: emit(record)
- The record is formatted, and then sent to the syslog server. If exception
- information is present, it is *not* sent to the server.
+ The record is formatted, and then sent to the syslog server. If exception
+ information is present, it is *not* sent to the server.
-.. method:: SysLogHandler.encodePriority(facility, priority)
+ .. method:: encodePriority(facility, priority)
- Encodes the facility and priority into an integer. You can pass in strings or
- integers - if strings are passed, internal mapping dictionaries are used to
- convert them to integers.
+ Encodes the facility and priority into an integer. You can pass in strings
+ or integers - if strings are passed, internal mapping dictionaries are
+ used to convert them to integers.
NTEventLogHandler
@@ -1834,45 +1836,45 @@
defaults to ``'Application'``.
-.. method:: NTEventLogHandler.close()
+ .. method:: close()
- At this point, you can remove the application name from the registry as a source
- of event log entries. However, if you do this, you will not be able to see the
- events as you intended in the Event Log Viewer - it needs to be able to access
- the registry to get the .dll name. The current version does not do this (in fact
- it doesn't do anything).
+ At this point, you can remove the application name from the registry as a
+ source of event log entries. However, if you do this, you will not be able
+ to see the events as you intended in the Event Log Viewer - it needs to be
+ able to access the registry to get the .dll name. The current version does
+ not do this (in fact it doesn't do anything).
-.. method:: NTEventLogHandler.emit(record)
+ .. method:: emit(record)
- Determines the message ID, event category and event type, and then logs the
- message in the NT event log.
+ Determines the message ID, event category and event type, and then logs
+ the message in the NT event log.
-.. method:: NTEventLogHandler.getEventCategory(record)
+ .. method:: getEventCategory(record)
- Returns the event category for the record. Override this if you want to specify
- your own categories. This version returns 0.
+ Returns the event category for the record. Override this if you want to
+ specify your own categories. This version returns 0.
-.. method:: NTEventLogHandler.getEventType(record)
+ .. method:: getEventType(record)
- Returns the event type for the record. Override this if you want to specify your
- own types. This version does a mapping using the handler's typemap attribute,
- which is set up in :meth:`__init__` to a dictionary which contains mappings for
- :const:`DEBUG`, :const:`INFO`, :const:`WARNING`, :const:`ERROR` and
- :const:`CRITICAL`. If you are using your own levels, you will either need to
- override this method or place a suitable dictionary in the handler's *typemap*
- attribute.
+ Returns the event type for the record. Override this if you want to
+ specify your own types. This version does a mapping using the handler's
+ typemap attribute, which is set up in :meth:`__init__` to a dictionary
+ which contains mappings for :const:`DEBUG`, :const:`INFO`,
+ :const:`WARNING`, :const:`ERROR` and :const:`CRITICAL`. If you are using
+ your own levels, you will either need to override this method or place a
+ suitable dictionary in the handler's *typemap* attribute.
-.. method:: NTEventLogHandler.getMessageID(record)
+ .. method:: getMessageID(record)
- Returns the message ID for the record. If you are using your own messages, you
- could do this by having the *msg* passed to the logger being an ID rather than a
- format string. Then, in here, you could use a dictionary lookup to get the
- message ID. This version returns 1, which is the base message ID in
- :file:`win32service.pyd`.
+ Returns the message ID for the record. If you are using your own messages,
+ you could do this by having the *msg* passed to the logger being an ID
+ rather than a format string. Then, in here, you could use a dictionary
+ lookup to get the message ID. This version returns 1, which is the base
+ message ID in :file:`win32service.pyd`.
SMTPHandler
@@ -1895,15 +1897,15 @@
*credentials* was added.
-.. method:: SMTPHandler.emit(record)
+ .. method:: emit(record)
- Formats the record and sends it to the specified addressees.
+ Formats the record and sends it to the specified addressees.
-.. method:: SMTPHandler.getSubject(record)
+ .. method:: getSubject(record)
- If you want to specify a subject line which is record-dependent, override this
- method.
+ If you want to specify a subject line which is record-dependent, override
+ this method.
MemoryHandler
@@ -1926,22 +1928,22 @@
Initializes the handler with a buffer of the specified capacity.
-.. method:: BufferingHandler.emit(record)
+ .. method:: emit(record)
- Appends the record to the buffer. If :meth:`shouldFlush` returns true, calls
- :meth:`flush` to process the buffer.
+ Appends the record to the buffer. If :meth:`shouldFlush` returns true,
+ calls :meth:`flush` to process the buffer.
-.. method:: BufferingHandler.flush()
+ .. method:: flush()
- You can override this to implement custom flushing behavior. This version just
- zaps the buffer to empty.
+ You can override this to implement custom flushing behavior. This version
+ just zaps the buffer to empty.
-.. method:: BufferingHandler.shouldFlush(record)
+ .. method:: shouldFlush(record)
- Returns true if the buffer is up to capacity. This method can be overridden to
- implement custom flushing strategies.
+ Returns true if the buffer is up to capacity. This method can be
+ overridden to implement custom flushing strategies.
.. class:: MemoryHandler(capacity[, flushLevel [, target]])
@@ -1952,25 +1954,27 @@
set using :meth:`setTarget` before this handler does anything useful.
-.. method:: MemoryHandler.close()
+ .. method:: close()
- Calls :meth:`flush`, sets the target to :const:`None` and clears the buffer.
+ Calls :meth:`flush`, sets the target to :const:`None` and clears the
+ buffer.
-.. method:: MemoryHandler.flush()
+ .. method:: flush()
- For a :class:`MemoryHandler`, flushing means just sending the buffered records
- to the target, if there is one. Override if you want different behavior.
+ For a :class:`MemoryHandler`, flushing means just sending the buffered
+ records to the target, if there is one. Override if you want different
+ behavior.
-.. method:: MemoryHandler.setTarget(target)
+ .. method:: setTarget(target)
- Sets the target handler for this handler.
+ Sets the target handler for this handler.
-.. method:: MemoryHandler.shouldFlush(record)
+ .. method:: shouldFlush(record)
- Checks for buffer full or a record at the *flushLevel* or higher.
+ Checks for buffer full or a record at the *flushLevel* or higher.
HTTPHandler
@@ -1989,9 +1993,9 @@
*method* is specified, ``GET`` is used.
-.. method:: HTTPHandler.emit(record)
+ .. method:: emit(record)
- Sends the record to the Web server as an URL-encoded dictionary.
+ Sends the record to the Web server as an URL-encoded dictionary.
.. _formatter-objects:
@@ -2079,38 +2083,42 @@
is used.
-.. method:: Formatter.format(record)
+ .. method:: format(record)
- The record's attribute dictionary is used as the operand to a string formatting
- operation. Returns the resulting string. Before formatting the dictionary, a
- couple of preparatory steps are carried out. The *message* attribute of the
- record is computed using *msg* % *args*. If the formatting string contains
- ``'(asctime)'``, :meth:`formatTime` is called to format the event time. If there
- is exception information, it is formatted using :meth:`formatException` and
- appended to the message. Note that the formatted exception information is cached
- in attribute *exc_text*. This is useful because the exception information can
- be pickled and sent across the wire, but you should be careful if you have more
- than one :class:`Formatter` subclass which customizes the formatting of exception
- information. In this case, you will have to clear the cached value after a
- formatter has done its formatting, so that the next formatter to handle the event
- doesn't use the cached value but recalculates it afresh.
+ The record's attribute dictionary is used as the operand to a string
+ formatting operation. Returns the resulting string. Before formatting the
+ dictionary, a couple of preparatory steps are carried out. The *message*
+ attribute of the record is computed using *msg* % *args*. If the
+ formatting string contains ``'(asctime)'``, :meth:`formatTime` is called
+ to format the event time. If there is exception information, it is
+ formatted using :meth:`formatException` and appended to the message. Note
+ that the formatted exception information is cached in attribute
+ *exc_text*. This is useful because the exception information can be
+ pickled and sent across the wire, but you should be careful if you have
+ more than one :class:`Formatter` subclass which customizes the formatting
+ of exception information. In this case, you will have to clear the cached
+ value after a formatter has done its formatting, so that the next
+ formatter to handle the event doesn't use the cached value but
+ recalculates it afresh.
-.. method:: Formatter.formatTime(record[, datefmt])
+ .. method:: formatTime(record[, datefmt])
- This method should be called from :meth:`format` by a formatter which wants to
- make use of a formatted time. This method can be overridden in formatters to
- provide for any specific requirement, but the basic behavior is as follows: if
- *datefmt* (a string) is specified, it is used with :func:`time.strftime` to
- format the creation time of the record. Otherwise, the ISO8601 format is used.
- The resulting string is returned.
+ This method should be called from :meth:`format` by a formatter which
+ wants to make use of a formatted time. This method can be overridden in
+ formatters to provide for any specific requirement, but the basic behavior
+ is as follows: if *datefmt* (a string) is specified, it is used with
+ :func:`time.strftime` to format the creation time of the
+ record. Otherwise, the ISO8601 format is used. The resulting string is
+ returned.
-.. method:: Formatter.formatException(exc_info)
+ .. method:: formatException(exc_info)
- Formats the specified exception information (a standard exception tuple as
- returned by :func:`sys.exc_info`) as a string. This default implementation just
- uses :func:`traceback.print_exception`. The resulting string is returned.
+ Formats the specified exception information (a standard exception tuple as
+ returned by :func:`sys.exc_info`) as a string. This default implementation
+ just uses :func:`traceback.print_exception`. The resulting string is
+ returned.
Filter Objects
@@ -2131,10 +2139,11 @@
through the filter. If no name is specified, allows every event.
-.. method:: Filter.filter(record)
+ .. method:: filter(record)
- Is the specified record to be logged? Returns zero for no, nonzero for yes. If
- deemed appropriate, the record may be modified in-place by this method.
+ Is the specified record to be logged? Returns zero for no, nonzero for
+ yes. If deemed appropriate, the record may be modified in-place by this
+ method.
LogRecord Objects
@@ -2165,10 +2174,11 @@
*func* was added.
-.. method:: LogRecord.getMessage()
+ .. method:: getMessage()
- Returns the message for this :class:`LogRecord` instance after merging any
- user-supplied arguments with the message.
+ Returns the message for this :class:`LogRecord` instance after merging any
+ user-supplied arguments with the message.
+
LoggerAdapter Objects
---------------------
@@ -2186,13 +2196,13 @@
Returns an instance of :class:`LoggerAdapter` initialized with an
underlying :class:`Logger` instance and a dict-like object.
-.. method:: LoggerAdapter.process(msg, kwargs)
+ .. method:: process(msg, kwargs)
- Modifies the message and/or keyword arguments passed to a logging call in
- order to insert contextual information. This implementation takes the
- object passed as *extra* to the constructor and adds it to *kwargs* using
- key 'extra'. The return value is a (*msg*, *kwargs*) tuple which has the
- (possibly modified) versions of the arguments passed in.
+ Modifies the message and/or keyword arguments passed to a logging call in
+ order to insert contextual information. This implementation takes the object
+ passed as *extra* to the constructor and adds it to *kwargs* using key
+ 'extra'. The return value is a (*msg*, *kwargs*) tuple which has the
+ (possibly modified) versions of the arguments passed in.
In addition to the above, :class:`LoggerAdapter` supports all the logging
methods of :class:`Logger`, i.e. :meth:`debug`, :meth:`info`, :meth:`warning`,