[ python-Feature Requests-668905 ] logging module documentation

[SourceForge.net]

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) 
 
 

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

>Comment By: Vinay Sajip (vsajip)
Date: 2004-03-15 14: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-15 13: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 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?

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

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=355470&aid=668905&group_id=5470