Viewing logs

Finesse contains a comprehensive logging system, issuing useful information during the parsing, building, running and output phases of a kat or Python script.

Making log messages visible

Depending on how you run Finesse, log messages with WARNING level or higher may already by default get printed to the standard output. This is the case when running Finesse interactively such as via a Jupyter notebook or IPython shell, or via the command line interface. If you run Finesse via a normal Python shell or via the python command, however, logging will not be enabled by default in order to give scripts maximum flexibility over how log messages are handled.

In any case, you may still wish to control the level of the messages made visible by the logging system, such as to show INFO and/or DEBUG messages in addition to WARNING and ERROR messages. If you use Finesse via a script or notebook or terminal, you have three options:

Option 1: use command line interface option

The command line interface (CLI) supports changing the log verbosity via option flags. See the CLI docs for more information.

Option 2: call ‘finesse.config.configure’

The function finesse.config.configure() can be imported from finesse and used to set the printed log level:

from finesse import configure

configure(log_level="info")  # ...or one of "debug", "warning", "error", "critical".

# Info or higher logs emitted by code from now on will be shown.

Logs with level at or above that which you specify will from this point onwards be displayed.

Option 3: wrap your code in a ‘finesse.utilities.misc.logs’ context

The context manager logs() provides a quick way to turn on verbose logging for a small block of code:

from finesse import Model
from finesse.utilities import logs

model = Model()

with logs(level="info"):
    # Info messages emitted by the following call get printed to stderr.
    model.parse("laser l1 P=1")

Option 4: configure via the Python ‘logging’ module

This approach with the logging module is useful if you use Finesse as part of a collection of other Python programs or libraries, where you wish to configure logging for all of these tools together in one place:

import logging

# Configure logging for all subsequent libraries.

# Any INFO or higher logs emitted during the import of the following libraries will
# be printed to stderr.
import matplotlib
import finesse

Configuring logging via this method is the most powerful, and allows you to send log messages to files or over the web and to apply custom formatting to messages. For more information, see for instance this Python logging guide.

Filtering log channels

You may wish to exclude a particular channel from being displayed by the logging system. You can do this by passing a list of channels to be excluded to the log_exclude parameter of configure(). Simple wildcards are supported: use * for zero or more characters, ? to match zero or one of the previous character, [seq] to match any character in seq, and [!seq] to match any character not in seq. For example, to exclude all script logs you could write configure(log_exclude=["*script*]).