Advantages of logging vs. print() + logging best practices

Question

I'm currently working on 1.0.0 release of pyftpdlib module. This new release will introduce some backward incompatible changes in that certain APIs will no longer accept bytes but unicode. While I'm at it, as part of this breackage, I was contemplating the possibility to get rid of my logging functions, which currently use the print statement, and use the logging module instead.

As of right now pyftpdlib delegates the logging to 3 functions:

def log(s):
   """Log messages intended for the end user."""
   print s

def logline(s):
   """Log commands and responses passing through the command channel."""
   print s

def logerror(s):
   """Log traceback outputs occurring in case of errors."""
   print >> sys.stderr, s

The user willing to customize logs (e.g. write them to a file) is supposed to just overwrite these 3 functions as in:

>>> from pyftpdlib import ftpserver
>>>
>>> def log2file(s):
...        open('ftpd.log', 'a').write(s)
...
>>> ftpserver.log = ftpserver.logline = ftpserver.logerror = log2file

Now I'm wondering: what benefits would imply to get rid of this approach and use logging module instead? From a module vendor perspective, how exactly am I supposed to expose logging functionalities in my module? Am I supposed to do this:

import logging
logger = logging.getLogger("pyftpdlib")

...and state in my doc that "logger" is the object which is supposed to be used in case the user wants to customize how logs behave? Is it legitimate to deliberately set a pre-defined format output as in:

FORMAT = '[%(asctime)] %(message)s'
logging.basicConfig(format=FORMAT)
logger = logging.getLogger('pyftpdlib')

...?

Can you think of a third-party module I can take cues from where the logging functionality is exposed and consolidated as part of the public API?

Thanks in advance.

Answer 1

libraries (ftp server or client library) should never initialize the logging system. So it's ok to instantiate a logger object and to point at logging.basicConfig in the documentation (or provide a function along the lines of basicConfig with fancier output and let the user choose among his logging configuration strategy, plain basicConfig or library provided configuration)

frameworks (e.g. django) or servers (ftp server daemon) should initialize the logging system to a reasonable default and allow for customization of logging system configuration.

Answer 2

Typically libraries should just create a NullHandler handler, which is simply a do nothing handler. The end user or application developer who uses your library can then configure the logging system. See the section Configuring Logging for a Library in the logging documentation for more information. In particular, see the note which begins

It is strongly advised that you do not add any handlers other than NullHandler to your library's loggers.

In your case I would simply create a logging handler, as per the logging documentation,

import logging
logging.getLogger('pyftpdlib').addHandler(logging.NullHandler())

Edit The logging implementation sketched out in the question seems perfectly reasonable. In your documentation just mention logger and discuss or point users to the logging.setLevel and logging.setFormatter methods for customising the output from your library. Rather than using logging.basicConfig(format=FORMAT) you could consider using logging.config.fileConfig to manage the settings for your output and document the configuration file somewhere in your documentation, again pointing the user to the logging module documentation for the format expected in this file.

Answer 3

Here is a resource I used to make a customizable logger. I didn't change much, I just added an if statement, and pass in whether or not I want to log to a file or just the console.

Check this Colorer out. It's really nice for colorizing the output so DEBUG looks different than WARN which looks different than INFO.

The Logging module bundles a heck of a lot of nice functionality, like SMTP logging, file rotation logging (so you can save a couple old log files, but not make 100s of them every time something goes wrong).

If you ever want to migrate to Python 3, using the logging module will remove the need to change your print statements.

Logging is awesome depending on what you're doing, I've only lightly used it before to see where I am in a program (if you're running this function, color this way), but it has significantly more power than a regular print statement.

Answer 4

You can look at Django (just create a sample project) and see how it initialize logger subsystem.

There is also a contextual logger helper that I've written some time ago - this logger automatically takes name of module/class/function is was initialized from. This is very useful for debug messages where you can see right-through that module spits the messages and how the call flow goes.