A new version of the Python logging package has been released. If you are using version 2.3 of later of Python, this release will not mean much to you - it is the same as recent checkins into Python CVS. However, this release fixes numerous bugs reported since the last independent release (0.4.7), and may be of interest to people using earlier versions of Python. What Does It Do? ================ The logging package offers the ability for any Python program to log events which occur during program execution. It's typically used to provide application diagnostics, warnings and error messages. In addition to capturing "what happened", "where it happened", "when it happened", "how important it is" and event specific data, you can configure, without changing the application source code, both the verbosity of logging and the routing of events to different destinations such as console, disk files, sockets, email addresses, Web servers, SOAP servers etc. etc. You can even change the configuration of a running program without stopping and restarting it! You can use the logging package in exception handlers, and it will include traceback information in the log. It's thread-safe, and very easy to use - just "import logging" and log away! Classes provided include: Logger - used to log messages for a particular area of an application. You can instantiate these wherever you want, there's no need to pass references to them around your application. You can log events based on importance levels of DEBUG (least important), INFO, WARN, ERROR, and CRITICAL (most important). You can define your own levels if the default levels don't meet your requirements. Handler - used to route events to particular destinations. Handlers included are: StreamHandler (for generalized streams, including console) FileHandler (for disk files - including log file rotation with size limits for log files) SocketHandler (for sending events to a TCP socket) DatagramHandler (for sending events to a UDP socket - faster, but less reliable than TCP) SMTPHandler (send events to arbitrary email addresses) HTTPHandler (send events to Web servers) SysLogHandler (send events to Unix syslog) MemoryHandler (batch up events and process them several at a time) NTEventLogHandler (send events to Windows NT event logs) There are also examples of XMLHandler and SOAPHandler in the distribution. Formatter - used to format events as text strings. Flexible "msg % arg_tuple" formatting is the basis for formatting, with flexible date/time formatting including ISO8601 and any strftime-based formats. Filter - used when filtering based on importance (DEBUG/INFO/WARNING/ERROR/CRITICAL) is not sufficient. The distribution includes examples of filters based on class matching, regular expression matching, value matching, and logger matching. In the unlikely event that you're daunted by all the apparent complexity, fear not. The package offers a simple function-based interface to allow very simple, almost casual use of the underlying features. In addition to the core logging functionality, you get the ability to configure logging using a ConfigParser-based text file format, a Tkinter-based GUI configurator which creates configuration files for you, and a simple network-based event receiver which receives events on TCP, UDP, HTTP and SOAP ports. This is suitable for testing and might perhaps serve as a model for your own event receivers. Also included are over 20 test scripts which serve both as test harnesses and examples of how to use the logging package. You can get more information from http://www.red-dove.com/python_logging.html There are "download" and "recent changes" links at the top of that page. API documentation is available at http://www.red-dove.com/logging/index.html As always, your feedback is most welcome (especially bug reports, patches and suggestions for improvement). Enjoy! Cheers Vinay Sajip Red Dove Consultants Ltd. Changes since the last independent release: =========================================== Traceback text is now cached. Tracebacks can be propagated across sockets as text. Added makeLogRecord() to allow a LogRecord to be created from a dictionary. Closing a handler now removes it from the internal list used by shutdown(). Made close() call flush() for handlers where this makes sense (thanks to Jim Jewett). The exc_info keyword parameter can be used to pass an exception tuple as well as a flag indicating that the current exception should be logged. A shutdown hook is registered to call shutdown() on application (Python) exit (thanks to Jim Jewett). Removed redundant error check in setLoggerClass(). Added RESET_ERROR to logging.config. SocketHandler now uses an exponential backoff strategy (thanks to Robert Olson). Made _listener global in stopListening(). Made listen() correctly pass the specified port. Removed some redundant imports in __init__.py. Added the record being processed as a parameter to handleError (thanks to Gordon den Otter for the idea). Handler.handle returns the result of applying the filter to the record (thanks to Gordon den Otter for the idea). Added a seek(0, 2) in RotatingFileHandler before the tell() call. This is because under Windows, tell() returns 0 until the first actual write (thanks to Gordon den Otter for the patch). Altered findCaller to not use inspect (thanks to Jeremy Hylton for the patch). Renamed warn and WARN to warning and WARNING. This may break existing code, but the standard Python module will use warning/WARNING rather than warn/WARN. The fatal and FATAL synonyms for critical and CRITICAL have also been removed. Added defaultEncoding and some support for encoding Unicode messages (thanks to Stéphane Bidoul for the suggestion). Added process ID to the list of LogRecord attributes. Modified Logger.removeHandler so that it does not close the handler on removal. Modified SMTPHandler to treat a single "to address" correctly (thanks to Anthony Baxter). Modified SMTPHandler to add a date header to the SMTP message (thanks to David Driver for the suggestion). Modified HTTPHandler to factor out the mapping of a LogRecord to a dictionary (thanks to Franz Glasner for the patch). Minor documentation corrections.