Logging¶

The pwfdf-api uses the pwfdf-api logging namespace to report progress and status. Although the command line interface includes options to automatically configure logging options, you will need to configure the logs explicitly when working within a Python session. In addition to Python’s standard logging library, you can use the pwfdf_api.logging package to quickly configure the pwfdf-api logger.

In brief, the module is split into two modules. The console module contains commands that configure the logging stream to sys.stderr (the standard logging stream), and the file module contains functions that configure logging to file.

Each module contains three commands designed to mimic the logging options from the pwfdf-api command line interface. These are:

Command	Description
verbose	Configures a logging stream to log at the DEBUG level
info	Configures a logging stream to log at the INFO level
quiet	Configures a logging stream to log at the WARNING level

So you can mimic the command line console logs using:

# Mimics the --verbose option
pwfdf_api.logging.console.verbose()

# Mimics the default log
pwfdf_api.logging.console.info()

# Mimics the --quiet option
pwfdf_api.logging.console.quiet()

And you can log to file using similar commands from the file module. Note that these commands require a file path as input:

# Creates a DEBUG-level file log
pwfdf_api.logging.file.verbose('my-debug-log.txt')

# And an INFO-level log
pwfdf_api.logging.file.info('my-info-log.txt')

# And a WARNING-level log
pwfdf_api.logging.file.quiet('my-warning-log.txt')

To prevent duplicate logs, the commands will delete any pre-existing pwfdf-api logging handlers with the same target. For example, an existing sys.stderr console logger, or an existing file logger that logs to the same file.

Note

You can have multiple different file logs running simultaneously. The commands will only remove pre-existing file loggers that target the same file.

Rotating Logs¶

In some cases, it can be useful to rotate file logs after they reach a given size. For example, to help avoid “log bloat” for an automated process. You can implement a rotating file log using the rotate_bytes option. This option specifies a maximum allowed file size (in bytes) before the log file rotates to a new file:

pwfdf_api.logging.file.verbose("my-log.txt", rotate_bytes=500000)

By default, rotating logs will save 1 backup log file (the previous log file), or you can use the backup_count option to specify a different number of log files instead:

pwfdf_api.logging.file.verbose("my-log.txt", rotate_bytes=500000, backup_count=3)

The backup file names will be the log file name with .1, .2, .3, etc. appended to the end. The first backup (.1) is the most recent previous log file, .2 is the second most recent, and so on.

Log Format¶

By default, the logging commands will use the associated log formats used by the command line interface. These are:

Log Type	Format String	Description
Console	`"%(message)s"`	Just the logging message
File	`%(asctime)s - %(name)s - %(message)s"`	Timestamp, logger name, and message

Alternatively, use the format input to specify an explicit logging format string. For example:

pwfdf_api.logging.console.verbose(format='%(asctime)s - %(message)s')

You can also set format=None, in which case the logger will attempt to inherit the format of a pre-existing logger with the same target. For example:

# Inherits format from existing console logger
pwfdf_api.logging.console.verbose(format=None)