iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

reSTify PEP 282 (#358)

This commit is contained in:
Huang Huang 2017-08-22 01:07:20 +08:00 committed by Brett Cannon
parent a5101b1988
commit f22e81b255
1 changed files with 441 additions and 411 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

600
pep-0282.txt
View File

@ -2,62 +2,68 @@ PEP: 282
Title: A Logging System Title: A Logging System
Version: $Revision$ Version: $Revision$
Last-Modified: $Date$ Last-Modified: $Date$
Author: vinay_sajip at red-dove.com (Vinay Sajip), Author: vinay_sajip at red-dove.com (Vinay Sajip), trentm@activestate.com (Trent Mick)
trentm@activestate.com (Trent Mick)
Status: Final Status: Final
Type: Standards Track Type: Standards Track
Content-Type: text/x-rst
Created: 4-Feb-2002 Created: 4-Feb-2002
Python-Version: 2.3 Python-Version: 2.3
Post-History: Post-History:
Abstract Abstract
========
This PEP describes a proposed logging package for Python's This PEP describes a proposed logging package for Python's
standard library. standard library.
Basically the system involves the user creating one or more logger Basically the system involves the user creating one or more logger
objects on which methods are called to log debugging notes, objects on which methods are called to log debugging notes,
general information, warnings, errors etc. Different logging general information, warnings, errors etc. Different logging
'levels' can be used to distinguish important messages from less 'levels' can be used to distinguish important messages from less
important ones. important ones.
A registry of named singleton logger objects is maintained so that A registry of named singleton logger objects is maintained so that
1) different logical logging streams (or 'channels') exist 1) different logical logging streams (or 'channels') exist
(say, one for 'zope.zodb' stuff and another for (say, one for 'zope.zodb' stuff and another for
'mywebsite'-specific stuff) 'mywebsite'-specific stuff)
2) one does not have to pass logger object references around. 2) one does not have to pass logger object references around.
The system is configurable at runtime. This configuration The system is configurable at runtime. This configuration
mechanism allows one to tune the level and type of logging done mechanism allows one to tune the level and type of logging done
while not touching the application itself. while not touching the application itself.
Motivation Motivation
==========
If a single logging mechanism is enshrined in the standard If a single logging mechanism is enshrined in the standard
library, 1) logging is more likely to be done 'well', and 2) library, 1) logging is more likely to be done 'well', and 2)
multiple libraries will be able to be integrated into larger multiple libraries will be able to be integrated into larger
applications which can be logged reasonably coherently. applications which can be logged reasonably coherently.
Influences Influences
==========
This proposal was put together after having studied the This proposal was put together after having studied the
following logging packages: following logging packages:
o java.util.logging in JDK 1.4 (a.k.a. JSR047) [1] * java.util.logging in JDK 1.4 (a.k.a. JSR047) [1]_
o log4j [2] * log4j [2]_
o the Syslog package from the Protomatter project [3] * the Syslog package from the Protomatter project [3]_
o MAL's mx.Log package [4] * MAL's mx.Log package [4]_
Simple Example Simple Example
==============
This shows a very simple example of how the logging package can be This shows a very simple example of how the logging package can be
used to generate simple logging output on stderr. used to generate simple logging output on stderr.
::
--------- mymodule.py ------------------------------- --------- mymodule.py -------------------------------
import logging import logging
@ -98,9 +104,9 @@ Simple Example
INFO:MyApp: Ending my app INFO:MyApp: Ending my app
The above example shows the default output format. All The above example shows the default output format. All
aspects of the output format should be configurable, so that aspects of the output format should be configurable, so that
you could have output formatted like this: you could have output formatted like this::
2002-04-19 07:56:58,174 MyModule DEBUG - Doin' stuff... 2002-04-19 07:56:58,174 MyModule DEBUG - Doin' stuff...
@ -110,44 +116,47 @@ Simple Example
Control Flow Control Flow
============
Applications make logging calls on *Logger* objects. Loggers are Applications make logging calls on **Logger** objects. Loggers are
organized in a hierarchical namespace and child Loggers inherit organized in a hierarchical namespace and child Loggers inherit
some logging properties from their parents in the namespace. some logging properties from their parents in the namespace.
Logger names fit into a "dotted name" namespace, with dots Logger names fit into a "dotted name" namespace, with dots
(periods) indicating sub-namespaces. The namespace of logger (periods) indicating sub-namespaces. The namespace of logger
objects therefore corresponds to a single tree data structure. objects therefore corresponds to a single tree data structure.
::
"" is the root of the namespace "" is the root of the namespace
"Zope" would be a child node of the root "Zope" would be a child node of the root
"Zope.ZODB" would be a child node of "Zope" "Zope.ZODB" would be a child node of "Zope"
These Logger objects create *LogRecord* objects which are passed These Logger objects create **LogRecord** objects which are passed
to *Handler* objects for output. Both Loggers and Handlers may to **Handler** objects for output. Both Loggers and Handlers may
use logging *levels* and (optionally) *Filters* to decide if they use logging **levels** and (optionally) **Filters** to decide if they
are interested in a particular LogRecord. When it is necessary to are interested in a particular LogRecord. When it is necessary to
output a LogRecord externally, a Handler can (optionally) use a output a LogRecord externally, a Handler can (optionally) use a
*Formatter* to localize and format the message before sending it **Formatter** to localize and format the message before sending it
to an I/O stream. to an I/O stream.
Each Logger keeps track of a set of output Handlers. By default Each Logger keeps track of a set of output Handlers. By default
all Loggers also send their output to all Handlers of their all Loggers also send their output to all Handlers of their
ancestor Loggers. Loggers may, however, also be configured to ancestor Loggers. Loggers may, however, also be configured to
ignore Handlers higher up the tree. ignore Handlers higher up the tree.
The APIs are structured so that calls on the Logger APIs can be The APIs are structured so that calls on the Logger APIs can be
cheap when logging is disabled. If logging is disabled for a cheap when logging is disabled. If logging is disabled for a
given log level, then the Logger can make a cheap comparison test given log level, then the Logger can make a cheap comparison test
and return. If logging is enabled for a given log level, the and return. If logging is enabled for a given log level, the
Logger is still careful to minimize costs before passing the Logger is still careful to minimize costs before passing the
LogRecord into the Handlers. In particular, localization and LogRecord into the Handlers. In particular, localization and
formatting (which are relatively expensive) are deferred until the formatting (which are relatively expensive) are deferred until the
Handler requests them. Handler requests them.
The overall Logger hierarchy can also have a level associated with The overall Logger hierarchy can also have a level associated with
it, which takes precedence over the levels of individual Loggers. it, which takes precedence over the levels of individual Loggers.
This is done through a module-level function: This is done through a module-level function::
def disable(lvl): def disable(lvl):
""" """
@ -158,8 +167,9 @@ Control Flow
Levels Levels
======
The logging levels, in increasing order of importance, are: The logging levels, in increasing order of importance, are::
DEBUG DEBUG
INFO INFO
@ -167,28 +177,28 @@ Levels
ERROR ERROR
CRITICAL CRITICAL
The term CRITICAL is used in preference to FATAL, which is used by The term CRITICAL is used in preference to FATAL, which is used by
log4j. The levels are conceptually the same - that of a serious, log4j. The levels are conceptually the same - that of a serious,
or very serious, error. However, FATAL implies death, which in or very serious, error. However, FATAL implies death, which in
Python implies a raised and uncaught exception, traceback, and Python implies a raised and uncaught exception, traceback, and
exit. Since the logging module does not enforce such an outcome exit. Since the logging module does not enforce such an outcome
from a FATAL-level log entry, it makes sense to use CRITICAL in from a FATAL-level log entry, it makes sense to use CRITICAL in
preference to FATAL. preference to FATAL.
These are just integer constants, to allow simple comparison of These are just integer constants, to allow simple comparison of
importance. Experience has shown that too many levels can be importance. Experience has shown that too many levels can be
confusing, as they lead to subjective interpretation of which confusing, as they lead to subjective interpretation of which
level should be applied to any particular log request. level should be applied to any particular log request.
Although the above levels are strongly recommended, the logging Although the above levels are strongly recommended, the logging
system should not be prescriptive. Users may define their own system should not be prescriptive. Users may define their own
levels, as well as the textual representation of any levels. User levels, as well as the textual representation of any levels. User
defined levels must, however, obey the constraints that they are defined levels must, however, obey the constraints that they are
all positive integers and that they increase in order of all positive integers and that they increase in order of
increasing severity. increasing severity.
User-defined logging levels are supported through two module-level User-defined logging levels are supported through two module-level
functions: functions::
def getLevelName(lvl): def getLevelName(lvl):
"""Return the text for level 'lvl'.""" """Return the text for level 'lvl'."""
@ -202,27 +212,28 @@ Levels
... ...
Loggers Loggers
=======
Each Logger object keeps track of a log level (or threshold) that Each Logger object keeps track of a log level (or threshold) that
it is interested in, and discards log requests below that level. it is interested in, and discards log requests below that level.
A *Manager* class instance maintains the hierarchical namespace of A **Manager** class instance maintains the hierarchical namespace of
named Logger objects. Generations are denoted with dot-separated named Logger objects. Generations are denoted with dot-separated
names: Logger "foo" is the parent of Loggers "foo.bar" and names: Logger "foo" is the parent of Loggers "foo.bar" and
"foo.baz". "foo.baz".
The Manager class instance is a singleton and is not directly The Manager class instance is a singleton and is not directly
exposed to users, who interact with it using various module-level exposed to users, who interact with it using various module-level
functions. functions.
The general logging method is: The general logging method is::
class Logger: class Logger:
def log(self, lvl, msg, *args, **kwargs): def log(self, lvl, msg, *args, **kwargs):
"""Log 'str(msg) % args' at logging level 'lvl'.""" """Log 'str(msg) % args' at logging level 'lvl'."""
... ...
However, convenience functions are defined for each logging level: However, convenience functions are defined for each logging level::
class Logger: class Logger:
def debug(self, msg, *args, **kwargs): ... def debug(self, msg, *args, **kwargs): ...
@ -231,30 +242,30 @@ Loggers
def error(self, msg, *args, **kwargs): ... def error(self, msg, *args, **kwargs): ...
def critical(self, msg, *args, **kwargs): ... def critical(self, msg, *args, **kwargs): ...
Only one keyword argument is recognized at present - "exc_info". Only one keyword argument is recognized at present - "exc_info".
If true, the caller wants exception information to be provided in If true, the caller wants exception information to be provided in
the logging output. This mechanism is only needed if exception the logging output. This mechanism is only needed if exception
information needs to be provided at *any* logging level. In the information needs to be provided at **any** logging level. In the
more common case, where exception information needs to be added to more common case, where exception information needs to be added to
the log only when errors occur, i.e. at the ERROR level, then the log only when errors occur, i.e. at the ERROR level, then
another convenience method is provided: another convenience method is provided::
class Logger: class Logger:
def exception(self, msg, *args): ... def exception(self, msg, *args): ...
This should only be called in the context of an exception handler, This should only be called in the context of an exception handler,
and is the preferred way of indicating a desire for exception and is the preferred way of indicating a desire for exception
information in the log. The other convenience methods are information in the log. The other convenience methods are
intended to be called with exc_info only in the unusual situation intended to be called with exc_info only in the unusual situation
where you might want to provide exception information in the where you might want to provide exception information in the
context of an INFO message, for example. context of an INFO message, for example.
The "msg" argument shown above will normally be a format string; The "msg" argument shown above will normally be a format string;
however, it can be any object x for which str(x) returns the however, it can be any object x for which ``str(x)`` returns the
format string. This facilitates, for example, the use of an format string. This facilitates, for example, the use of an
object which fetches a locale- specific message for an object which fetches a locale- specific message for an
internationalized/localized application, perhaps using the internationalized/localized application, perhaps using the
standard gettext module. An outline example: standard gettext module. An outline example::
class Message: class Message:
"""Represents a message""" """Represents a message"""
@ -268,10 +279,10 @@ Loggers
logger.info(Message("abc"), ...) logger.info(Message("abc"), ...)
Gathering and formatting data for a log message may be expensive, Gathering and formatting data for a log message may be expensive,
and a waste if the logger was going to discard the message anyway. and a waste if the logger was going to discard the message anyway.
To see if a request will be honoured by the logger, the To see if a request will be honoured by the logger, the
isEnabledFor() method can be used: ``isEnabledFor()`` method can be used::
class Logger: class Logger:
def isEnabledFor(self, lvl): def isEnabledFor(self, lvl):
@ -281,188 +292,198 @@ Loggers
""" """
... ...
so instead of this expensive and possibly wasteful DOM to XML so instead of this expensive and possibly wasteful DOM to XML
conversion: conversion::
... ...
hamletStr = hamletDom.toxml() hamletStr = hamletDom.toxml()
log.info(hamletStr) log.info(hamletStr)
... ...
one can do this: one can do this::
if log.isEnabledFor(logging.INFO): if log.isEnabledFor(logging.INFO):
hamletStr = hamletDom.toxml() hamletStr = hamletDom.toxml()
log.info(hamletStr) log.info(hamletStr)
When new loggers are created, they are initialized with a level When new loggers are created, they are initialized with a level
which signifies "no level". A level can be set explicitly using which signifies "no level". A level can be set explicitly using
the setLevel() method: the ``setLevel()`` method::
class Logger: class Logger:
def setLevel(self, lvl): ... def setLevel(self, lvl): ...
If a logger's level is not set, the system consults all its If a logger's level is not set, the system consults all its
ancestors, walking up the hierarchy until an explicitly set level ancestors, walking up the hierarchy until an explicitly set level
is found. That is regarded as the "effective level" of the is found. That is regarded as the "effective level" of the
logger, and can be queried via the getEffectiveLevel() method: logger, and can be queried via the getEffectiveLevel() method::
def getEffectiveLevel(self): ... def getEffectiveLevel(self): ...
Loggers are never instantiated directly. Instead, a module-level Loggers are never instantiated directly. Instead, a module-level
function is used: function is used::
def getLogger(name=None): ... def getLogger(name=None): ...
If no name is specified, the root logger is returned. Otherwise, If no name is specified, the root logger is returned. Otherwise,
if a logger with that name exists, it is returned. If not, a new if a logger with that name exists, it is returned. If not, a new
logger is initialized and returned. Here, "name" is synonymous logger is initialized and returned. Here, "name" is synonymous
with "channel name". with "channel name".
Users can specify a custom subclass of Logger to be used by the Users can specify a custom subclass of Logger to be used by the
system when instantiating new loggers: system when instantiating new loggers::
def setLoggerClass(klass): ... def setLoggerClass(klass): ...
The passed class should be a subclass of Logger, and its __init__ The passed class should be a subclass of Logger, and its ``__init__``
method should call Logger.__init__. method should call ``Logger.__init__``.
Handlers Handlers
========
Handlers are responsible for doing something useful with a given Handlers are responsible for doing something useful with a given
LogRecord. The following core Handlers will be implemented: ``LogRecord``. The following core Handlers will be implemented:
- StreamHandler: A handler for writing to a file-like object. - ``StreamHandler``: A handler for writing to a file-like object.
- FileHandler: A handler for writing to a single file or set - ``FileHandler``: A handler for writing to a single file or set
of rotating files. of rotating files.
- SocketHandler: A handler for writing to remote TCP ports. - ``SocketHandler``: A handler for writing to remote TCP ports.
- DatagramHandler: A handler for writing to UDP sockets, for - ``DatagramHandler``: A handler for writing to UDP sockets, for
low-cost logging. Jeff Bauer already had such a system [5]. low-cost logging. Jeff Bauer already had such a system [5]_.
- MemoryHandler: A handler that buffers log records in memory - ``MemoryHandler``: A handler that buffers log records in memory
until the buffer is full or a particular condition occurs until the buffer is full or a particular condition occurs
[1]. [1]_.
- SMTPHandler: A handler for sending to email addresses via SMTP. - ``SMTPHandler``: A handler for sending to email addresses via SMTP.
- SysLogHandler: A handler for writing to Unix syslog via UDP. - ``SysLogHandler``: A handler for writing to Unix syslog via UDP.
- NTEventLogHandler: A handler for writing to event logs on - ``NTEventLogHandler``: A handler for writing to event logs on
Windows NT, 2000 and XP. Windows NT, 2000 and XP.
- HTTPHandler: A handler for writing to a Web server with - ``HTTPHandler``: A handler for writing to a Web server with
either GET or POST semantics. either GET or POST semantics.
Handlers can also have levels set for them using the Handlers can also have levels set for them using the
setLevel() method: ``setLevel()`` method::
def setLevel(self, lvl): ... def setLevel(self, lvl): ...
The FileHandler can be set up to create a rotating set of log The FileHandler can be set up to create a rotating set of log
files. In this case, the file name passed to the constructor is files. In this case, the file name passed to the constructor is
taken as a "base" file name. Additional file names for the taken as a "base" file name. Additional file names for the
rotation are created by appending .1, .2, etc. to the base file rotation are created by appending .1, .2, etc. to the base file
name, up to a maximum as specified when rollover is requested. name, up to a maximum as specified when rollover is requested.
The setRollover method is used to specify a maximum size for a log The setRollover method is used to specify a maximum size for a log
file and a maximum number of backup files in the rotation. file and a maximum number of backup files in the rotation.
::
def setRollover(maxBytes, backupCount): ... def setRollover(maxBytes, backupCount): ...
If maxBytes is specified as zero, no rollover ever occurs and the If maxBytes is specified as zero, no rollover ever occurs and the
log file grows indefinitely. If a non-zero size is specified, log file grows indefinitely. If a non-zero size is specified,
when that size is about to be exceeded, rollover occurs. The when that size is about to be exceeded, rollover occurs. The
rollover method ensures that the base file name is always the most rollover method ensures that the base file name is always the most
recent, .1 is the next most recent, .2 the next most recent after recent, .1 is the next most recent, .2 the next most recent after
that, and so on. that, and so on.
There are many additional handlers implemented in the test/example There are many additional handlers implemented in the test/example
scripts provided with [6] - for example, XMLHandler and scripts provided with [6]_ - for example, XMLHandler and
SOAPHandler. SOAPHandler.
LogRecords LogRecords
==========
A LogRecord acts as a receptacle for information about a A LogRecord acts as a receptacle for information about a
logging event. It is little more than a dictionary, though it logging event. It is little more than a dictionary, though it
does define a getMessage method which merges a message with does define a ``getMessage`` method which merges a message with
optional runarguments. optional runarguments.
Formatters Formatters
==========
A Formatter is responsible for converting a LogRecord to a string A Formatter is responsible for converting a LogRecord to a string
representation. A Handler may call its Formatter before writing a representation. A Handler may call its Formatter before writing a
record. The following core Formatters will be implemented: record. The following core Formatters will be implemented:
- Formatter: Provide printf-like formatting, using the % operator. - ``Formatter``: Provide printf-like formatting, using the % operator.
- BufferingFormatter: Provide formatting for multiple - ``BufferingFormatter``: Provide formatting for multiple
messages, with header and trailer formatting support. messages, with header and trailer formatting support.
Formatters are associated with Handlers by calling setFormatter() Formatters are associated with Handlers by calling ``setFormatter()``
on a handler: on a handler::
def setFormatter(self, form): ... def setFormatter(self, form): ...
Formatters use the % operator to format the logging message. The Formatters use the % operator to format the logging message. The
format string should contain %(name)x and the attribute dictionary format string should contain ``%(name)x`` and the attribute dictionary
of the LogRecord is used to obtain message-specific data. The of the LogRecord is used to obtain message-specific data. The
following attributes are provided: following attributes are provided:
%(name)s Name of the logger (logging channel) ======================= ======================================================
``%(name)s`` Name of the logger (logging channel)
%(levelno)s Numeric logging level for the message (DEBUG, ``%(levelno)s`` Numeric logging level for the message (DEBUG,
INFO, WARN, ERROR, CRITICAL) INFO, WARN, ERROR, CRITICAL)
%(levelname)s Text logging level for the message ("DEBUG", "INFO", ``%(levelname)s`` Text logging level for the message ("DEBUG", "INFO",
"WARN", "ERROR", "CRITICAL") "WARN", "ERROR", "CRITICAL")
%(pathname)s Full pathname of the source file where the logging ``%(pathname)s`` Full pathname of the source file where the logging
call was issued (if available) call was issued (if available)
%(filename)s Filename portion of pathname ``%(filename)s`` Filename portion of pathname
%(module)s Module from which logging call was made ``%(module)s`` Module from which logging call was made
%(lineno)d Source line number where the logging call was issued ``%(lineno)d`` Source line number where the logging call was issued
(if available) (if available)
%(created)f Time when the LogRecord was created (time.time() ``%(created)f`` Time when the LogRecord was created (``time.time()``
return value) return value)
%(asctime)s Textual time when the LogRecord was created ``%(asctime)s`` Textual time when the LogRecord was created
%(msecs)d Millisecond portion of the creation time ``%(msecs)d`` Millisecond portion of the creation time
%(relativeCreated)d Time in milliseconds when the LogRecord was created, ``%(relativeCreated)d`` Time in milliseconds when the LogRecord was created,
relative to the time the logging module was loaded relative to the time the logging module was loaded
(typically at application startup time) (typically at application startup time)
%(thread)d Thread ID (if available) ``%(thread)d`` Thread ID (if available)
%(message)s The result of record.getMessage(), computed just as ``%(message)s`` The result of record.getMessage(), computed just as
the record is emitted the record is emitted
======================= ======================================================
If a formatter sees that the format string includes "(asctime)s", If a formatter sees that the format string includes "(asctime)s",
the creation time is formatted into the LogRecord's asctime the creation time is formatted into the LogRecord's asctime
attribute. To allow flexibility in formatting dates, Formatters attribute. To allow flexibility in formatting dates, Formatters
are initialized with a format string for the message as a whole, are initialized with a format string for the message as a whole,
and a separate format string for date/time. The date/time format and a separate format string for date/time. The date/time format
string should be in time.strftime format. The default value for string should be in time.strftime format. The default value for
the message format is "%(message)s". The default date/time format the message format is "%(message)s". The default date/time format
is ISO8601. is ISO8601.
The formatter uses a class attribute, "converter", to indicate how The formatter uses a class attribute, "converter", to indicate how
to convert a time from seconds to a tuple. By default, the value to convert a time from seconds to a tuple. By default, the value
of "converter" is "time.localtime". If needed, a different of "converter" is "time.localtime". If needed, a different
converter (e.g. "time.gmtime") can be set on an individual converter (e.g. "time.gmtime") can be set on an individual
formatter instance, or the class attribute changed to affect all formatter instance, or the class attribute changed to affect all
formatter instances. formatter instances.
Filters Filters
=======
When level-based filtering is insufficient, a Filter can be called When level-based filtering is insufficient, a Filter can be called
by a Logger or Handler to decide if a LogRecord should be output. by a Logger or Handler to decide if a LogRecord should be output.
Loggers and Handlers can have multiple filters installed, and any Loggers and Handlers can have multiple filters installed, and any
one of them can veto a LogRecord being output. one of them can veto a LogRecord being output.
::
class Filter: class Filter:
def filter(self, record): def filter(self, record):
@ -472,140 +493,149 @@ Filters
appropriate by the filter. appropriate by the filter.
""" """
The default behaviour allows a Filter to be initialized with a The default behaviour allows a Filter to be initialized with a
Logger name. This will only allow through events which are Logger name. This will only allow through events which are
generated using the named logger or any of its children. For generated using the named logger or any of its children. For
example, a filter initialized with "A.B" will allow events logged example, a filter initialized with "A.B" will allow events logged
by loggers "A.B", "A.B.C", "A.B.C.D", "A.B.D" etc. but not "A.BB", by loggers "A.B", "A.B.C", "A.B.C.D", "A.B.D" etc. but not "A.BB",
"B.A.B" etc. If initialized with the empty string, all events are "B.A.B" etc. If initialized with the empty string, all events are
passed by the Filter. This filter behaviour is useful when it is passed by the Filter. This filter behaviour is useful when it is
desired to focus attention on one particular area of an desired to focus attention on one particular area of an
application; the focus can be changed simply by changing a filter application; the focus can be changed simply by changing a filter
attached to the root logger. attached to the root logger.
There are many examples of Filters provided in [6]. There are many examples of Filters provided in [6]_.
Configuration Configuration
=============
The main benefit of a logging system like this is that one can The main benefit of a logging system like this is that one can
control how much and what logging output one gets from an control how much and what logging output one gets from an
application without changing that application's source code. application without changing that application's source code.
Therefore, although configuration can be performed through the Therefore, although configuration can be performed through the
logging API, it must also be possible to change the logging logging API, it must also be possible to change the logging
configuration without changing an application at all. For configuration without changing an application at all. For
long-running programs like Zope, it should be possible to change long-running programs like Zope, it should be possible to change
the logging configuration while the program is running. the logging configuration while the program is running.
Configuration includes the following: Configuration includes the following:
- What logging level a logger or handler should be interested in. - What logging level a logger or handler should be interested in.
- What handlers should be attached to which loggers. - What handlers should be attached to which loggers.
- What filters should be attached to which handlers and loggers. - What filters should be attached to which handlers and loggers.
- Specifying attributes specific to certain handlers and filters. - Specifying attributes specific to certain handlers and filters.
In general each application will have its own requirements for how In general each application will have its own requirements for how
a user may configure logging output. However, each application a user may configure logging output. However, each application
will specify the required configuration to the logging system will specify the required configuration to the logging system
through a standard mechanism. through a standard mechanism.
The most simple configuration is that of a single handler, writing The most simple configuration is that of a single handler, writing
to stderr, attached to the root logger. This configuration is set to stderr, attached to the root logger. This configuration is set
up by calling the basicConfig() function once the logging module up by calling the ``basicConfig()`` function once the logging module
has been imported. has been imported.
::
def basicConfig(): ... def basicConfig(): ...
For more sophisticated configurations, this PEP makes no specific For more sophisticated configurations, this PEP makes no specific
proposals, for the following reasons: proposals, for the following reasons:
- A specific proposal may be seen as prescriptive. - A specific proposal may be seen as prescriptive.
- Without the benefit of wide practical experience in the - Without the benefit of wide practical experience in the
Python community, there is no way to know whether any given Python community, there is no way to know whether any given
configuration approach is a good one. That practice can't configuration approach is a good one. That practice can't
really come until the logging module is used, and that means really come until the logging module is used, and that means
until *after* Python 2.3 has shipped. until **after** Python 2.3 has shipped.
- There is a likelihood that different types of applications - There is a likelihood that different types of applications
may require different configuration approaches, so that no may require different configuration approaches, so that no
"one size fits all". "one size fits all".
The reference implementation [6] has a working configuration file The reference implementation [6]_ has a working configuration file
format, implemented for the purpose of proving the concept and format, implemented for the purpose of proving the concept and
suggesting one possible alternative. It may be that separate suggesting one possible alternative. It may be that separate
extension modules, not part of the core Python distribution, are extension modules, not part of the core Python distribution, are
created for logging configuration and log viewing, supplemental created for logging configuration and log viewing, supplemental
handlers and other features which are not of interest to the bulk handlers and other features which are not of interest to the bulk
of the community. of the community.
Thread Safety Thread Safety
=============
The logging system should support thread-safe operation without The logging system should support thread-safe operation without
any special action needing to be taken by its users. any special action needing to be taken by its users.
Module-Level Functions Module-Level Functions
======================
To support use of the logging mechanism in short scripts and small To support use of the logging mechanism in short scripts and small
applications, module-level functions debug(), info(), warn(), applications, module-level functions ``debug()``, ``info()``, ``warn()``,
error(), critical() and exception() are provided. These work in ``error()``, ``critical()`` and ``exception()`` are provided. These work in
the same way as the correspondingly named methods of Logger - in the same way as the correspondingly named methods of Logger - in
fact they delegate to the corresponding methods on the root fact they delegate to the corresponding methods on the root
logger. A further convenience provided by these functions is that logger. A further convenience provided by these functions is that
if no configuration has been done, basicConfig() is automatically if no configuration has been done, ``basicConfig()`` is automatically
called. called.
At application exit, all handlers can be flushed by calling the function At application exit, all handlers can be flushed by calling the function::
def shutdown(): ... def shutdown(): ...
This will flush and close all handlers. This will flush and close all handlers.
Implementation Implementation
==============
The reference implementation is Vinay Sajip's logging module [6]. The reference implementation is Vinay Sajip's logging module [6]_.
Packaging Packaging
=========
The reference implementation is implemented as a single module. The reference implementation is implemented as a single module.
This offers the simplest interface - all users have to do is This offers the simplest interface - all users have to do is
"import logging" and they are in a position to use all the "import logging" and they are in a position to use all the
functionality available. functionality available.
References References
==========
[1] java.util.logging .. [1] java.util.logging
http://java.sun.com/j2se/1.4/docs/guide/util/logging/ http://java.sun.com/j2se/1.4/docs/guide/util/logging/
[2] log4j: a Java logging package .. [2] log4j: a Java logging package
http://jakarta.apache.org/log4j/docs/index.html http://jakarta.apache.org/log4j/docs/index.html
[3] Protomatter's Syslog .. [3] Protomatter's Syslog
http://protomatter.sourceforge.net/1.1.6/index.html http://protomatter.sourceforge.net/1.1.6/index.html
http://protomatter.sourceforge.net/1.1.6/javadoc/com/protomatter/syslog/syslog-whitepaper.html http://protomatter.sourceforge.net/1.1.6/javadoc/com/protomatter/syslog/syslog-whitepaper.html
[4] MAL mentions his mx.Log logging module: .. [4] MAL mentions his mx.Log logging module:
https://mail.python.org/pipermail/python-dev/2002-February/019767.html https://mail.python.org/pipermail/python-dev/2002-February/019767.html
[5] Jeff Bauer's Mr. Creosote .. [5] Jeff Bauer's Mr. Creosote
http://starship.python.net/crew/jbauer/creosote/ http://starship.python.net/crew/jbauer/creosote/
[6] Vinay Sajip's logging module. .. [6] Vinay Sajip's logging module.
http://www.red-dove.com/python_logging.html http://www.red-dove.com/python_logging.html
Copyright Copyright
=========
This document has been placed in the public domain. This document has been placed in the public domain.
..
Local Variables: Local Variables:
mode: indented-text mode: indented-text
indent-tabs-mode: nil indent-tabs-mode: nil
sentence-end-double-space: t sentence-end-double-space: t
fill-column: 70 fill-column: 70
End: End: