diff options
Diffstat (limited to 'Doc/library/logging.rst')
| -rw-r--r-- | Doc/library/logging.rst | 316 |
1 files changed, 163 insertions, 153 deletions
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 @@ and :meth:`flush` methods). 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 @@ sends logging output to a disk file. It inherits the output functionality from 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 @@ this value. 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 @@ module, supports rotation of disk log files. :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 @@ timed intervals. 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 @@ sends logging output to a network socket. The base class uses a TCP socket. 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 @@ over UDP sockets. 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 @@ supports sending logging messages to a remote or local Unix syslog. :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 @@ extensions for Python installed. 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 @@ supports sending logging messages to an email address via SMTP. *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 @@ should, then :meth:`flush` is expected to do the needful. 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 @@ should, then :meth:`flush` is expected to do the needful. 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 @@ supports sending logging messages to a Web server, using either ``GET`` or *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 @@ Currently, the useful mapping keys in a :class:`LogRecord` are: 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 @@ initialized with the empty string, all events are passed. 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 @@ made, and any exception information to be logged. *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 @@ __ context-info_ 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`, |