click-loguru 1.3.8

Logging to stderr and file for click applications.

click_loguru initializes click CLI-based programs for logging via the loguru logger. It can optionally log to a log file with a logfile-retention policy and with command-line arguments captured. It can also optionally log run time, CPU use, and peak memory use of user CLI functions.

Log file names will include the name of your program and (if your application uses subcommands via @click.group()), the name of the subcommand. Log files are (optionally) numbered, with a retention policy specified. Log files can be enabled or disabled per-subcommand and written to a subdirectory that your application specifies.

Global CLI options control verbose/quiet levels and log file creation. The values of these global options are accessible, along with the path to the log file, from your application.

Instantiation

click_loguru objects are instantiated from the ClickLoguru class as:

click_loguru = ClickLoguru(name,
                           version,
                           retention=4,
                           stderr_format_func=None,
                           log_dir_parent="./logs",
                           file_log_level="DEBUG",
                           stderr_log_level="INFO",
                           timer_log_level="debug",
  )

where:

• name is the name of your application

• version is the version string of your application

• retention is the log file retention policy. If set to a non-zero value, the log files will be given by logs/NAME[-SUBCOMMAND]_n.log where `NAME is the name of your application, SUBCOMMAND is the group subcommand (if you are using click groups), and n is an integer number. The value of retention specifies the number of log files to be kept.

• stderr_format_func is the format function to be used for messages to stderr, as defined by loguru. Default is very short, with INFO-level messages having no level name printed.

• log_dir_parent sets the location of the log file directory. This value may be overridden per-command.

• file_log_level sets the level of logging to the log file.

• stderr_log_level sets the level of logging to stderr. This value may be overridden by the --quiet or --verbose options.

• timer_log_level is the level at which elapsed_time results will be logged.

Methods

The ClickLoguru class defines the following methods:

• logging_options is a decorator to be used for your application’s CLI function. This decorator defines the global options that allows control of quiet, verbose, and log file booleans.

• stash_subcommand is a decorator to be used for the CLI method for applications which define subcommands.

• init_logger is a decorator which must be used for each subcommand. It allows override of the default log_dir_parent established at instantiation, as well as turning off file logging for that command by setting log file to False.

• log_elapsed_time is a decorator which causes the elapsed wall-clock time and CPU time in seconds for the (sub)command to be emitted at the level specified by the level= argument (debug by default).

• get_global_options is a method that returns the context object associated with the global options. The context object is printable. The attributes of the context object are the booleans verbose, quiet, and log file, the string subcommand showing the subcommand that was invoked, and log file_handler_id if your code wishes to manipulate the handler directly.

• user_global_options_callback is a method to be used as a callback when your code declares a global option. Values of these global options will be stored in a user global options context dictionary.

• get_user_global_options is a method to retrieve a dictionary of values of user global options.

• elapsed_timer is a method that accepts a single argument, phase. The next invocation of this method will produce a log entry at timer_log_level showing the elapsed wall clock and CPU time. If phase is None, the next invocation will not produce a message.

• log_peak_memory_use is a method that results in the peak memory usage for the function and children of the function to be emitted at a level specified by the level= keyword (debug is default). This functionality is somewhat expensive in that it requires an additional thread, so the global option --profile_mem must be enabled.

See the simple test CLI application for usage examples.

Prerequisites

Python 3.6 or greater is required. This package is tested under Linux, MacOS, and Windows using Python 3.9.