Feature Requests item #668905, was opened at 2003-01-16 05:07 Message generated for change (Comment added) made by vsajip 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-15 11: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-09 21: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 07: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 06: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 06:37

Message: Logged In: YES user_id=80475

Reviewed. Closing RFE.

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

Comment By: Neal Norwitz (nnorwitz) Date: 2003-01-25 21:36

Message: Logged In: YES user_id=33168

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

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