To help with debugging, you can configure Minx to output log messages. This page details how to go about doing this.

Simple Configuration

Logging to Console

In your Minx start-up script, before creating a minx.core.wm object, create a minx.core.config and customize its logger attribute. The minx.core.config.logger attribute is a complicated dict-of-dict-of-dict structure. While you can mess around with that directly, the minx.core.config class provides a few functions to ease the pain.

A fairly common logging target is the console. The following start-up script will achieve that:

   #!/usr/bin/env python

   import minx

   conf = minx.core.config()
   conf.log_to_console()

   minx.core.wm(conf).start()

That's it. If you save the above Python script as ~/.minx/init.py and run it as described in the building and testing instructions, you will see log messages of various events output to STDERR.

Remember: you will have to adjust the Python module search path to be able to import the minx module. We have not shown that here. As mentioned above, the build and test HOWTO has the gory details.

Logging to a File

Another very common logging target is a file. To send log messages to a file, try something like this:

   #!/usr/bin/env python

   import os
   import minx

   conf = minx.core.config()
   conf.log_to_file(os.path.join(os.environ['HOME'], '.minx', 'log'))

   minx.core.wm(conf).start()

With the above configuration, you should see Minx's log messages in ~/.minx/log. If the ~/.minx directory does not already exist, you will have to create it.

Again, remember to adjust the Python module search path to be able to import minx.

Logging Verbosity

When logging is turned on as shown above, by default, Minx will output warnings, errors, and critical error messages. You can increase or decrease the amount of log messages by adjusting the logging level as shown below:

   #!/usr/bin/env python

   import os, logging
   import minx

   conf = minx.core.config()
   conf.log_to_file(os.path.join(os.environ['HOME'], '.minx', 'log'))
   conf.log_level(logging.DEBUG)

   minx.core.wm(conf).start()

Now, ~/.minx/log will contain debug and informational messages in addition to warnings, errors, and critical messages.

Let's say you only want to see errors and critical errors. Then, instead of logging.DEBUG, use logging.ERROR. See the Python documentation for the supported logging levels.

Complete Control of Logging Configuration

If, for some reason, the above simple logging setups don't meet your needs, you will have to get your hands dirty with the minx.core.config.logger attribute's dict-of-dict-of-dict structure.

Rotating Logs

To start off, let's see how to setup a rotating set of log files:

   #!/usr/bin/env python

   import os, logging
   import minx

   conf = minx.core.config()
   handler = conf.logger['handlers']['minx_handler']
   handler['class'      ] = 'logging.handlers.RotatingFileHandler'
   handler['filename'   ] = os.path.join(os.environ['HOME'], '.minx', 'log')
   handler['maxBytes'   ] = 1024 * 1024
   handler['backupCount'] = 4

   minx.core.wm(conf).start()

This will create a set of five rotating logs in ~/.minx: log, log.1, log.2, log.3, and log.4. The maximum size of each log will be 1MB.

minx.core.config.logger

Now, let's have a closer look at exactly what is in the minx.core.config.logger attribute. As mentioned earlier, minx.core.config.logger is a dict-of-dict-of-dict. Its default value is shown below (using indentation rather than braces):

   minx.core.config.logger:
      version: 1
      formatters:
         minx_formatter:
            format:  %(asctime)s.%(msecs)03d %(levelname)-9s%(name)-18s%(lineno)-5s%(funcName)s\n    %(message)s
            datefmt: %Y-%m-%d %H:%M:%S
      filters:
         minx_filter:
            (): _minx_logging_filter
      handlers:
         minx_handler:
            class: logging.NullHandler
            formatter: minx_formatter
            filters: minx_filter
      loggers:
         minx:
            handlers: minx_handler

Log Message Formatter

If you don't like the format of Minx's log messages, you can change it by twiddling the minx_formatter dict as shown below:

   #!/usr/bin/env python

   import os
   import minx

   conf = minx.core.config()
   formatter = conf.logger['formatters']['minx_formatter']
   formatter['format'] = '%(levelname)s: %(message)s'
   conf.log_to_console()

   minx.core.wm(conf).start()

Take a look at the Python documentation for the low-down on what you can put into the format string and for the details of changing the timestamp.

The Log Message Filter

The default log message format prints the logger name, function name, and source file line number. All Minx loggers are rooted in the minx logger namespace. It seems redundant to have the "minx." prefix in each logger name. Thus, we use a filter to remove this prefix from each log record.

Furthermore, the function name and line number output by the minxlib module are incorrect. So, the above-mentioned filter removes these things as well for log messages emitted by minxlib.

If you're using Minx in conjunction with another library that has identically named modules, you may want to disable Minx's log message filter, which you can do by deleting the filter from the handler as shown below:

   #!/usr/bin/env python

   import os
   import minx

   conf = minx.core.config()
   handler = conf.logger['handlers']['minx_handler']
   del handler['filters']
   conf.log_to_console()

   minx.core.wm(conf).start()

If you disable the filter, you will likely also want to adjust the formatter to take the extra "minx." prefix for each log record. And be aware that the function names and line numbers for messages from minxlib will be incorrect.

Full Control

Instead of modifying the logging parameters provided by minx.core.config.logger, you can simply install your own configuration dictionary. Have a look at the Python documentation for the gory details.