Feature Requests item #668905, was opened at 2003-01-16 16:07 Message generated for change (Comment added) made by richard You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=355470&aid=668905&group_id=5470

Category: Documentation Group: None Status: Open Resolution: Accepted Priority: 5 Submitted By: Richard Jones (richard) Assigned to: Vinay Sajip (vsajip) Summary: logging module documentation

Initial Comment: I believe the logging module documentation needs to give an example of how to simply log to a file. The following example snippet could be appropriate:

import logging logger = logging.getLogger('myapp') hdlr = FileHandler('/var/myapp/debug.log') hdlr.setFormatter(Formatter('%(asctime)s %(level)s %(message)s')) logger.addHandler(hdlr) logger.setLevel(DEBUG)

----------------------------------------------------------------------

Date: 2004-03-16 15:04

Message: Logged In: YES user_id=6405

Accepting any file-like object, as the Twisted logging API does, would be nice. I wouldn't object to having to write "basicConfig(file('path/to/file'))"

Thanks for looking into this Vinay!

----------------------------------------------------------------------

Comment By: Vinay Sajip (vsajip) Date: 2004-03-16 01:47

Message: Logged In: YES user_id=308438

I assume no one would pass an empty for filename or fmtstr, as this would make no sense. So I test for both None and the empty string at the same time using the "if value:" idiom. I have tried to be consistent with the view that wherever possible, logging should not generate spurious output (e.g. throwing exceptions), even when errors occur.

----------------------------------------------------------------------

Comment By: Drew Perttula (drewp) Date: 2004-03-16 00:19

Message: Logged In: YES user_id=127598

ITYM "if filename is not None" , "if fmtstr is None", and "Formatter(fmtstr)". I like the feature a lot, otherwise.

For the record, the next most common things I do to a logger is to adjust its root's level to DEBUG but set the level of the channels I -don't- want to see back to INFO. (Therefore, any new channels will get output as DEBUG until I put them in the exclusion list.) I doubt this belongs in basicConfig, but if there became a convenience method to do it, I'd sure use it :)

----------------------------------------------------------------------

Comment By: Vinay Sajip (vsajip) Date: 2004-03-15 22:48

Message: Logged In: YES user_id=308438

How about if I modify basicConfig as follows?

def basicConfig(filename=None, fmtstr=None, mode="w"): """ Do basic configuration for the logging system.

If a filename is specified, create a FileHandler using it, otherwise create a StreamHandler. The created handler is added to the root logger. If a format string is specified, it will be used to initialize the Formatter - otherwise, a suitable default will be used. The mode is only used when a filename is specified, to determine how the file is to be opened. """ if len(root.handlers) == 0: if filename: hdlr = FileHandler(filename, mode) else: hdlr = StreamHandler() if not fmtstr: fmtstr = BASIC_FORMAT fmt = Formatter(fs) hdlr.setFormatter(fmt) root.addHandler(hdlr)

----------------------------------------------------------------------

Comment By: Richard Jones (richard) Date: 2004-03-10 08:21

Message: Logged In: YES user_id=6405

Please consider adding a simpler interface for people who just want to log to a file:

import logging logger = logging.open('/var/log/myapp.log')

which does the equivalent of:

import logging logger = logging.getLogger('<default>') hdlr = logging.FileHandler('/var/log/myapp.log') formatter = logging.Formatter('%(asctime)s %(levelname)s %(message)s') hdlr.setFormatter(formatter) logger.addHandler(hdlr) logger.setLevel(logging.INFO)

which is what I expect most users will want when they first see this module. If they then want to mess around with additional handers, or different formatting or whatever, then they can read the reference doc.

Please make the simplest use-case much simpler!

----------------------------------------------------------------------

Comment By: Raymond Hettinger (rhettinger) Date: 2004-01-01 18:10

Message: Logged In: YES user_id=80475

I would also like to see a more thorough set of introductory examples. The second page of the unittest documentation could serve as a model -- it attempts to cover the 90% of what you need to know in a single page of examples. As it stands now, the documentation for the logging module is formidable. Those wanting to take advantage of the module face a steep learning curve from rather heavyweight documentation -- it's complexity exceeds that of almost all modules except for the email and xml packages.

Assigning to Vinay Sajip to work with Anthony to improve the docs.

----------------------------------------------------------------------

Comment By: Anthony Baxter (anthonybaxter) Date: 2003-07-08 16:32

Message: Logged In: YES user_id=29957

Why was this closed? nnorwitz's doc fixes, as seen in CVS or http://www.python.org/dev/doc/devel/lib/module-logging.html have no examples section.

Running the current logging module docs past a number of python coders here produced a consistent "what the heck?" response - the opening introduction provides no indications of how to use the package. This is a problem for me, right now, so I'm re-opening and assigning to myself to fix.

----------------------------------------------------------------------

Comment By: Raymond Hettinger (rhettinger) Date: 2003-06-28 16:37

Message: Logged In: YES user_id=80475

Reviewed. Closing RFE.

----------------------------------------------------------------------

Comment By: Neal Norwitz (nnorwitz) Date: 2003-01-26 08:36

Message: Logged In: YES user_id=33168

I just updated the logging documentation. Could you please review for accuracy and completeness?

----------------------------------------------------------------------