Logging from Python code in Blender

In this article we take a look at using logging inside Blender. When things take an unexpected turn, which they always do, it is great to know what is going on behind all the nice GUIs and user-friendly operators. Python’s standard library with a very flexible and extendable logging module.

To familiarize yourself with Python’s logging module itself, we can recommend the Logging HOWTO by Vinay Sajip.

Using logging in your Python module

The general approach to logging is to use the module’s name as the logger name, so your module can have this at the top:

import logging

log = logging.getLogger(__name__)

Loggers use a hierarchy of dotted names, so if you want to create a sub-logger (for example to use in an operator), you can use log = logging.getLogger(__name__ + '.my_sublogger').

To log something, use one of the error, warning, info, or debug functions (for details, see the API documentation). Be careful which one you choose, though: errors and warnings are shown on the console by default, so they can be seen by anyone. Only use those sparingly, for those things you intend to be seen by end users.

The default configuration

We keep Blender’s Python as default and standard as possible. As a result, you can just grab a Python tutorial, apply it to Blender, and get the results you’d expect. This also means that the logging configuration is bog standard. This means that by default

1. the name of the logger is not shown;
2. only log entries at levels CRITICAL, ERROR, and WARNING are shown.

Point 1. is important for the way you write your log messages; you have to write sentences that can be understood without knowing their context (which is a good idea anyway). Point 2. tells you at which levels to log for developers/debugging (INFO and DEBUG), and at which levels to log for artists (WARNING and above). However, and this is important: never assume that people read the log file. Communication with the user of your code should happen through Blender’s GUI.

Configuring logging

Which logs you want to see, and which you don’t, is personal and depends on your needs of the moment. As such, we can’t ship Blender with a default other than Python’s default, as there won’t be one default that satisfies everybody. This also means that your addon should not configure the logging module.

To set up the logging module to your needs, create a file $HOME/.config/blender/{version}/scripts/startup/setup_logging.py (this is on Linux, but you’re likely a developer, so you’ll know where to find this directory). If the folder doesn’t exist yet, create it. I like to put something like this in there:

import logging

logging.basicConfig(level=logging.INFO,
                    format='%(asctime)-15s %(levelname)8s %(name)s %(message)s')

for name in ('blender_id', 'blender_cloud'):
    logging.getLogger(name).setLevel(logging.DEBUG)

def register():
    pass

The register function is there just to stop Blender from nagging when it’s scanning for addons etc.

Conclusion

Now you know how to use logging, and how to configure Python’s logging module for your own personal preference. Enjoy not having to remove all those print() statements before you publish your addon!