API Reference

This page contains the full reference guide for using the logset API.

Module	Description
console	Functions that set up loggers that emit messages to the console (sys.stderr)
file	Functions that set up loggers that write message to file. (Optionally rotating the file based on size or time).

console module

The console module provides functions for setting up loggers that emit messages to the console (sys.stderr).

logset.console.debug(logger, format=None, *, fallback_format='%(message)s', clear_existing=True, propagate=False)

Sets up a logger to write to the console at the DEBUG level

debug(logger)

Sets up the indicated logger to write to the console (sys.stderr) at the DEBUG level. Specifically, the command adds a DEBUG-level sys.stderr StreamHandler to the logger, and ensures the logger’s level is at the DEBUG level or lower.

The logger may either be a logger name (as a string), or a logging.Logger object. If the logger has any pre-existing sys.stderr StreamHandlers, then those handlers are removed to prevent doubling log messages. Returns the new sys.stderr StreamHandler.

Formatting

debug(..., format)
debug(..., format=None, *, fallback_format)

Use format to specify the format used for log messages. The format may be a %-style logging format string, or a logging.Formatter object. Logging strings are sufficient for most cases, but we note that advanced users can achieve more fine-grained control by using a logging.Formatter object.

If format=None (the default), and the logger has pre-existing sys.stderr StreamHandlers, then the format will default to the format of the first such handler that has a formatter. If no such handler is found, the format will be set to the value specified by fallback_format. By default, fallback_format is set to the logged message, equivalent to the formatting string "%(message)s".

Advanced Options

debug(..., *, clear_existing=False)
debug(..., *, propagate=True)

Advanced options that can lead to “double-logging” bugs. Set clear_existing=False to disable the removal of pre-existing sys.stderr StreamHandlers.

By default, this command sets logger.propagate=False, which stops this logger’s events from being propagated to ancestor loggers. Set propagate=True to allow event propagation.

Args:

• logger (str | logging.Logger) – The name of a logger or logging.Logger object that should emit messages to the console at the DEBUG level.

• format (str | logging.Formatter, optional) – An optional %-style logging format string, or logging.Formatter object used to set the format of logged messages. Defaults to the format of the first pre-existing sys.stderr StreamHandler with a formatter, or to fallback_format if no such handler exists.

• fallback_format (str | logging.Formatter) – The log format used when format is not specified, and there is no pre-existing sys.stderr StreamHandler with a formatter

• clear_existing (bool) – True (default) to remove any pre-existing sys.stderr StreamHandlers. False to disable this behavior.

• propagate (bool) – True to allow this logger’s events to propagate to ancestor loggers. False (default) to prevent propagation.

Returns:

logging.StreamHandler – The logger’s new DEBUG-level sys.stderr StreamHandler

logset.console.info(logger, format=None, *, fallback_format='%(message)s', clear_existing=True, propagate=False)

Sets up a logger to write to the console at the INFO level

info(logger)

Sets up the indicated logger to write to the console (sys.stderr) at the INFO level. Specifically, the command adds a INFO-level sys.stderr StreamHandler to the logger, and ensures the logger’s level is at the INFO level or lower.

The logger may either be a logger name (as a string), or a logging.Logger object. If the logger has any pre-existing sys.stderr StreamHandlers, then those handlers are removed to prevent doubling log messages. Returns the new sys.stderr StreamHandler.

Formatting

info(..., format)
info(..., format=None, *, fallback_format)

Use format to specify the format used for log messages. The format may be a %-style logging format string, or a logging.Formatter object. Logging strings are sufficient for most cases, but we note that advanced users can achieve more fine-grained control by using a logging.Formatter object.

If format=None (the default), and the logger has pre-existing sys.stderr StreamHandlers, then the format will default to the format of the first such handler that has a formatter. If no such handler is found, the format will be set to the value specified by fallback_format. By default, fallback_format is set to the logged message, equivalent to the formatting string "%(message)s".

Advanced Options

info(..., *, clear_existing=False)
info(..., *, propagate=True)

Advanced options that can lead to “double-logging” bugs. Set clear_existing=False to disable the removal of pre-existing sys.stderr StreamHandlers.

By default, this command sets logger.propagate=False, which stops this logger’s events from being propagated to ancestor loggers. Set propagate=True to allow event propagation.

Args:

• logger (str | logging.Logger) – The name of a logger or logging.Logger object that should emit messages to the console at the INFO level.

• format (str | logging.Formatter, optional) – An optional %-style logging format string, or logging.Formatter object used to set the format of logged messages. Defaults to the format of the first pre-existing sys.stderr StreamHandler with a formatter, or to fallback_format if no such handler exists.

• fallback_format (str | logging.Formatter) – The log format used when format is not specified, and there is no pre-existing sys.stderr StreamHandler with a formatter

• clear_existing (bool) – True (default) to remove any pre-existing sys.stderr StreamHandlers. False to disable this behavior.

• propagate (bool) – True to allow this logger’s events to propagate to ancestor loggers. False (default) to prevent propagation.

Returns:

logging.StreamHandler – The logger’s new INFO-level sys.stderr StreamHandler

logset.console.warning(logger, format=None, *, fallback_format='%(message)s', clear_existing=True, propagate=False)

Sets up a logger to write to the console at the WARNING level

warning(logger)

Sets up the indicated logger to write to the console (sys.stderr) at the WARNING level. Specifically, the command adds a WARNING-level sys.stderr StreamHandler to the logger, and ensures the logger’s level is at the WARNING level or lower.

The logger may either be a logger name (as a string), or a logging.Logger object. If the logger has any pre-existing sys.stderr StreamHandlers, then those handlers are removed to prevent doubling log messages. Returns the new sys.stderr StreamHandler.

Formatting

warning(..., format)
warning(..., format=None, *, fallback_format)

Use format to specify the format used for log messages. The format may be a %-style logging format string, or a logging.Formatter object. Logging strings are sufficient for most cases, but we note that advanced users can achieve more fine-grained control by using a logging.Formatter object.

If format=None (the default), and the logger has pre-existing sys.stderr StreamHandlers, then the format will default to the format of the first such handler that has a formatter. If no such handler is found, the format will be set to the value specified by fallback_format. By default, fallback_format is set to the logged message, equivalent to the formatting string "%(message)s".

Advanced Options

warning(..., *, clear_existing=False)
warning(..., *, propagate=True)

Advanced options that can lead to “double-logging” bugs. Set clear_existing=False to disable the removal of pre-existing sys.stderr StreamHandlers.

By default, this command sets logger.propagate=False, which stops this logger’s events from being propagated to ancestor loggers. Set propagate=True to allow event propagation.

Args:

• logger (str | logging.Logger) – The name of a logger or logging.Logger object that should emit messages to the console at the WARNING level.

• format (str | logging.Formatter, optional) – An optional %-style logging format string, or logging.Formatter object used to set the format of logged messages. Defaults to the format of the first pre-existing sys.stderr StreamHandler with a formatter, or to fallback_format if no such handler exists.

• fallback_format (str | logging.Formatter) – The log format used when format is not specified, and there is no pre-existing sys.stderr StreamHandler with a formatter

• clear_existing (bool) – True (default) to remove any pre-existing sys.stderr StreamHandlers. False to disable this behavior.

• propagate (bool) – True to allow this logger’s events to propagate to ancestor loggers. False (default) to prevent propagation.

Returns:

logging.StreamHandler – The logger’s new WARNING-level sys.stderr StreamHandler

logset.console.error(logger, format=None, *, fallback_format='%(message)s', clear_existing=True, propagate=False)

Sets up a logger to write to the console at the ERROR level

error(logger)

Sets up the indicated logger to write to the console (sys.stderr) at the ERROR level. Specifically, the command adds a ERROR-level sys.stderr StreamHandler to the logger, and ensures the logger’s level is at the ERROR level or lower.

The logger may either be a logger name (as a string), or a logging.Logger object. If the logger has any pre-existing sys.stderr StreamHandlers, then those handlers are removed to prevent doubling log messages. Returns the new sys.stderr StreamHandler.

Formatting

error(..., format)
error(..., format=None, *, fallback_format)

Use format to specify the format used for log messages. The format may be a %-style logging format string, or a logging.Formatter object. Logging strings are sufficient for most cases, but we note that advanced users can achieve more fine-grained control by using a logging.Formatter object.

If format=None (the default), and the logger has pre-existing sys.stderr StreamHandlers, then the format will default to the format of the first such handler that has a formatter. If no such handler is found, the format will be set to the value specified by fallback_format. By default, fallback_format is set to the logged message, equivalent to the formatting string "%(message)s".

Advanced Options

error(..., *, clear_existing=False)
error(..., *, propagate=True)

Advanced options that can lead to “double-logging” bugs. Set clear_existing=False to disable the removal of pre-existing sys.stderr StreamHandlers.

By default, this command sets logger.propagate=False, which stops this logger’s events from being propagated to ancestor loggers. Set propagate=True to allow event propagation.

Args:

• logger (str | logging.Logger) – The name of a logger or logging.Logger object that should emit messages to the console at the ERROR level.

• format (str | logging.Formatter, optional) – An optional %-style logging format string, or logging.Formatter object used to set the format of logged messages. Defaults to the format of the first pre-existing sys.stderr StreamHandler with a formatter, or to fallback_format if no such handler exists.

• fallback_format (str | logging.Formatter) – The log format used when format is not specified, and there is no pre-existing sys.stderr StreamHandler with a formatter

• clear_existing (bool) – True (default) to remove any pre-existing sys.stderr StreamHandlers. False to disable this behavior.

• propagate (bool) – True to allow this logger’s events to propagate to ancestor loggers. False (default) to prevent propagation.

Returns:

logging.StreamHandler – The logger’s new ERROR-level sys.stderr StreamHandler

logset.console.critical(logger, format=None, *, fallback_format='%(message)s', clear_existing=True, propagate=False)

Sets up a logger to write to the console at the CRITICAL level

critical(logger)

Sets up the indicated logger to write to the console (sys.stderr) at the CRITICAL level. Specifically, the command adds a CRITICAL-level sys.stderr StreamHandler to the logger, and ensures the logger’s level is at the CRITICAL level or lower.

The logger may either be a logger name (as a string), or a logging.Logger object. If the logger has any pre-existing sys.stderr StreamHandlers, then those handlers are removed to prevent doubling log messages. Returns the new sys.stderr StreamHandler.

Formatting

critical(..., format)
critical(..., format=None, *, fallback_format)

Use format to specify the format used for log messages. The format may be a %-style logging format string, or a logging.Formatter object. Logging strings are sufficient for most cases, but we note that advanced users can achieve more fine-grained control by using a logging.Formatter object.

If format=None (the default), and the logger has pre-existing sys.stderr StreamHandlers, then the format will default to the format of the first such handler that has a formatter. If no such handler is found, the format will be set to the value specified by fallback_format. By default, fallback_format is set to the logged message, equivalent to the formatting string "%(message)s".

Advanced Options

critical(..., *, clear_existing=False)
critical(..., *, propagate=True)

Advanced options that can lead to “double-logging” bugs. Set clear_existing=False to disable the removal of pre-existing sys.stderr StreamHandlers.

By default, this command sets logger.propagate=False, which stops this logger’s events from being propagated to ancestor loggers. Set propagate=True to allow event propagation.

Args:

• logger (str | logging.Logger) – The name of a logger or logging.Logger object that should emit messages to the console at the CRITICAL level.

• format (str | logging.Formatter, optional) – An optional %-style logging format string, or logging.Formatter object used to set the format of logged messages. Defaults to the format of the first pre-existing sys.stderr StreamHandler with a formatter, or to fallback_format if no such handler exists.

• fallback_format (str | logging.Formatter) – The log format used when format is not specified, and there is no pre-existing sys.stderr StreamHandler with a formatter

• clear_existing (bool) – True (default) to remove any pre-existing sys.stderr StreamHandlers. False to disable this behavior.

• propagate (bool) – True to allow this logger’s events to propagate to ancestor loggers. False (default) to prevent propagation.

Returns:

logging.StreamHandler – The logger’s new CRITICAL-level sys.stderr StreamHandler

file module

The file module provides functions for setting up loggers that write logs to file, with options for rotating log files based on size or fixed time intervals.

logset.file.debug(logger, path, format=None, *, fallback_format='%(message)s', rotate_bytes=None, rotate_when=None, rotate_interval=1, backup_count=1, make_parents=False, delay=False, clear_existing=True, propagate=False, **handler_kwargs)

Sets up a logger to write to file at the DEBUG level

debug(logger, path)

Sets up the indicated logger to write to the indicated file at the DEBUG level. Specifically, adds a DEBUG-level FileHandler to the logger, and ensures that the logger’s level is at the DEBUG level or lower.

The logger may either be a logger name (as a string) or a logging.Logger object. If the logger has any pre-existing handlers targeting the same file, then those handlers are removed to prevent doubling log messages. Returns the new FileHandler. Refer to the syntaxes below for option to implement a RotatingFileHandler (which rotates the log file after reaching a maximum size), or a TimedRotatingFileHandler (which rotates after a fixed time interval).

Formatting

debug(..., format)
debug(..., format=None, *, fallback_format)

Use format to specify the format used for log messages. The format may be a %-style logging format string, or a logging.Formatter object. Logging strings are sufficient for most cases, but we note that advanced users can achieve more fine-grained control by using a logging.Formatter object.

If format=None (the default), and the logger has pre-existing handlers that target the same file, then the format will default to the format of the first such handler that has a formatter. If no such handler is found, the format will be set to the value specified by fallback_format. By default, fallback_format is set to the logged message, equivalent to the formatting string "%(message)s".

Rotating Files

debug(..., *, rotate_bytes)
debug(..., *, rotate_when, rotate_interval)
debug(..., *, backup_count)

Options for implementing rotating file logs. Setting rotate_bytes will add a RotatingFileHandler to the logger (as opposed to a basic FileHandler). The log file will rotate after the file size reaches the indicated number of bytes. Alternatively, use rotate_when and rotate_interval to use a TimedRotatingFileHandler, which will rotate the log file on the specified interval. (Refer to the TimedRotatingFileHandler docs for supported options). For either type of rotating file log, use backup_count to specify the number of backup file logs that should be saved after rotation.

File Creation

debug(..., *, make_parents=True)
debug(..., *, delay=True)

Options for creating the log file. By default, raises a FileNotFoundError if the log file parent folder does not exist. Set make_parents=True to create the parent folder as needed.

Use delay to control when the log file is created. By default, opens/creates the log file immediately. Set delay = True to defer opening/creating the log file until the first message is emitted.

Advanced Options

debug(..., *, clear_existing=False)
debug(..., *, propagate=True)

Advanced options that can lead to “double-logging” bugs. Set clear_existing=False to disable the removal of pre-existing handlers that target the same file.

By default, this command sets logger.propagate=False, which stops this logger’s events from being propagated to ancestor loggers. Set propagate=True to allow event propagation.

Handler Constructor

debug(..., **handler_kwargs)

Specifies additional options that should be passed to the FileHandler, RotatingFileHandler, or TimedRotatingFileHandler constructor, as appropriate.

Args:

• logger (str | logging.Logger) – The name of a logger or logging.Logger object that should write messages to file at the DEBUG level

• path (str | pathlib.Path) – The path to the file where messages should be written

• format (str | logging.Formatter, optional) – An optional %-style logging format string, or logging.Formatter object used to set the format of logged messages. Defaults to the format of the first pre-existing handler that targets the same file and has a formatter, or to fallback_format if no such handler exists

• fallback_format (str | logging.Formatter) – The log format to use when format is not specified, and there is not pre-existing handler that targets the same file and has a formatter

• rotate_bytes (int) – A maximum file size (in bytes) for rotating log files

• rotate_when (str) – The type of interval to use for timed rotation

• rotate_interval (int) – The length of the interval for timed rotation. Defaults to 1

• backup_count (int) – The number of backup log files that should be preserved. Defaults to 1

• clear_existing (bool) – True (default) to remove any pre-existing handlers that target the same file. False to disable this behavior.

• propagate (bool) – True to allow this logger’s events to propagate to ancestor loggers. False (default) to prevent propagation.

• **handler_kwargs (Any) – Additional parameters passed to the constructor of the new FileHandler, RotatingFileHandler, or TimedRotatingFileHandler object.

Returns:

FileHandler | RotatingFileHandler | TimedRotatingFileHandler – The logger’s new DEBUG-level file handler

logset.file.info(logger, path, format=None, *, fallback_format='%(message)s', rotate_bytes=None, rotate_when=None, rotate_interval=1, backup_count=1, make_parents=False, delay=False, clear_existing=True, propagate=False, **handler_kwargs)

Sets up a logger to write to file at the INFO level

info(logger, path)

Sets up the indicated logger to write to the indicated file at the INFO level. Specifically, adds a INFO-level FileHandler to the logger, and ensures that the logger’s level is at the INFO level or lower.

The logger may either be a logger name (as a string) or a logging.Logger object. If the logger has any pre-existing handlers targeting the same file, then those handlers are removed to prevent doubling log messages. Returns the new FileHandler. Refer to the syntaxes below for option to implement a RotatingFileHandler (which rotates the log file after reaching a maximum size), or a TimedRotatingFileHandler (which rotates after a fixed time interval).

Formatting

info(..., format)
info(..., format=None, *, fallback_format)

Use format to specify the format used for log messages. The format may be a %-style logging format string, or a logging.Formatter object. Logging strings are sufficient for most cases, but we note that advanced users can achieve more fine-grained control by using a logging.Formatter object.

If format=None (the default), and the logger has pre-existing handlers that target the same file, then the format will default to the format of the first such handler that has a formatter. If no such handler is found, the format will be set to the value specified by fallback_format. By default, fallback_format is set to the logged message, equivalent to the formatting string "%(message)s".

Rotating Files

info(..., *, rotate_bytes)
info(..., *, rotate_when, rotate_interval)
info(..., *, backup_count)

Options for implementing rotating file logs. Setting rotate_bytes will add a RotatingFileHandler to the logger (as opposed to a basic FileHandler). The log file will rotate after the file size reaches the indicated number of bytes. Alternatively, use rotate_when and rotate_interval to use a TimedRotatingFileHandler, which will rotate the log file on the specified interval. (Refer to the TimedRotatingFileHandler docs for supported options). For either type of rotating file log, use backup_count to specify the number of backup file logs that should be saved after rotation.

File Creation

info(..., *, make_parents=True)
info(..., *, delay=True)

Options for creating the log file. By default, raises a FileNotFoundError if the log file parent folder does not exist. Set make_parents=True to create the parent folder as needed.

Use delay to control when the log file is created. By default, opens/creates the log file immediately. Set delay = True to defer opening/creating the log file until the first message is emitted.

Advanced Options

info(..., *, clear_existing=False)
info(..., *, propagate=True)

Advanced options that can lead to “double-logging” bugs. Set clear_existing=False to disable the removal of pre-existing handlers that target the same file.

By default, this command sets logger.propagate=False, which stops this logger’s events from being propagated to ancestor loggers. Set propagate=True to allow event propagation.

Handler Constructor

info(..., **handler_kwargs)

Specifies additional options that should be passed to the FileHandler, RotatingFileHandler, or TimedRotatingFileHandler constructor, as appropriate.

Args:

• logger (str | logging.Logger) – The name of a logger or logging.Logger object that should write messages to file at the INFO level

• path (str | pathlib.Path) – The path to the file where messages should be written

• format (str | logging.Formatter, optional) – An optional %-style logging format string, or logging.Formatter object used to set the format of logged messages. Defaults to the format of the first pre-existing handler that targets the same file and has a formatter, or to fallback_format if no such handler exists

• fallback_format (str | logging.Formatter) – The log format to use when format is not specified, and there is not pre-existing handler that targets the same file and has a formatter

• rotate_bytes (int) – A maximum file size (in bytes) for rotating log files

• rotate_when (str) – The type of interval to use for timed rotation

• rotate_interval (int) – The length of the interval for timed rotation. Defaults to 1

• backup_count (int) – The number of backup log files that should be preserved. Defaults to 1

• clear_existing (bool) – True (default) to remove any pre-existing handlers that target the same file. False to disable this behavior.

• propagate (bool) – True to allow this logger’s events to propagate to ancestor loggers. False (default) to prevent propagation.

• **handler_kwargs (Any) – Additional parameters passed to the constructor of the new FileHandler, RotatingFileHandler, or TimedRotatingFileHandler object.

Returns:

FileHandler | RotatingFileHandler | TimedRotatingFileHandler – The logger’s new INFO-level file handler

logset.file.warning(logger, path, format=None, *, fallback_format='%(message)s', rotate_bytes=None, rotate_when=None, rotate_interval=1, backup_count=1, make_parents=False, delay=False, clear_existing=True, propagate=False, **handler_kwargs)

Sets up a logger to write to file at the WARNING level

warning(logger, path)

Sets up the indicated logger to write to the indicated file at the WARNING level. Specifically, adds a WARNING-level FileHandler to the logger, and ensures that the logger’s level is at the WARNING level or lower.

The logger may either be a logger name (as a string) or a logging.Logger object. If the logger has any pre-existing handlers targeting the same file, then those handlers are removed to prevent doubling log messages. Returns the new FileHandler. Refer to the syntaxes below for option to implement a RotatingFileHandler (which rotates the log file after reaching a maximum size), or a TimedRotatingFileHandler (which rotates after a fixed time interval).

Formatting

warning(..., format)
warning(..., format=None, *, fallback_format)

Use format to specify the format used for log messages. The format may be a %-style logging format string, or a logging.Formatter object. Logging strings are sufficient for most cases, but we note that advanced users can achieve more fine-grained control by using a logging.Formatter object.

If format=None (the default), and the logger has pre-existing handlers that target the same file, then the format will default to the format of the first such handler that has a formatter. If no such handler is found, the format will be set to the value specified by fallback_format. By default, fallback_format is set to the logged message, equivalent to the formatting string "%(message)s".

Rotating Files

warning(..., *, rotate_bytes)
warning(..., *, rotate_when, rotate_interval)
warning(..., *, backup_count)

Options for implementing rotating file logs. Setting rotate_bytes will add a RotatingFileHandler to the logger (as opposed to a basic FileHandler). The log file will rotate after the file size reaches the indicated number of bytes. Alternatively, use rotate_when and rotate_interval to use a TimedRotatingFileHandler, which will rotate the log file on the specified interval. (Refer to the TimedRotatingFileHandler docs for supported options). For either type of rotating file log, use backup_count to specify the number of backup file logs that should be saved after rotation.

File Creation

warning(..., *, make_parents=True)
warning(..., *, delay=True)

Options for creating the log file. By default, raises a FileNotFoundError if the log file parent folder does not exist. Set make_parents=True to create the parent folder as needed.

Use delay to control when the log file is created. By default, opens/creates the log file immediately. Set delay = True to defer opening/creating the log file until the first message is emitted.

Advanced Options

warning(..., *, clear_existing=False)
warning(..., *, propagate=True)

Advanced options that can lead to “double-logging” bugs. Set clear_existing=False to disable the removal of pre-existing handlers that target the same file.

By default, this command sets logger.propagate=False, which stops this logger’s events from being propagated to ancestor loggers. Set propagate=True to allow event propagation.

Handler Constructor

warning(..., **handler_kwargs)

Specifies additional options that should be passed to the FileHandler, RotatingFileHandler, or TimedRotatingFileHandler constructor, as appropriate.

Args:

• logger (str | logging.Logger) – The name of a logger or logging.Logger object that should write messages to file at the WARNING level

• path (str | pathlib.Path) – The path to the file where messages should be written

• format (str | logging.Formatter, optional) – An optional %-style logging format string, or logging.Formatter object used to set the format of logged messages. Defaults to the format of the first pre-existing handler that targets the same file and has a formatter, or to fallback_format if no such handler exists

• fallback_format (str | logging.Formatter) – The log format to use when format is not specified, and there is not pre-existing handler that targets the same file and has a formatter

• rotate_bytes (int) – A maximum file size (in bytes) for rotating log files

• rotate_when (str) – The type of interval to use for timed rotation

• rotate_interval (int) – The length of the interval for timed rotation. Defaults to 1

• backup_count (int) – The number of backup log files that should be preserved. Defaults to 1

• clear_existing (bool) – True (default) to remove any pre-existing handlers that target the same file. False to disable this behavior.

• propagate (bool) – True to allow this logger’s events to propagate to ancestor loggers. False (default) to prevent propagation.

• **handler_kwargs (Any) – Additional parameters passed to the constructor of the new FileHandler, RotatingFileHandler, or TimedRotatingFileHandler object.

Returns:

FileHandler | RotatingFileHandler | TimedRotatingFileHandler – The logger’s new WARNING-level file handler

logset.file.error(logger, path, format=None, *, fallback_format='%(message)s', rotate_bytes=None, rotate_when=None, rotate_interval=1, backup_count=1, make_parents=False, delay=False, clear_existing=True, propagate=False, **handler_kwargs)

Sets up a logger to write to file at the ERROR level

error(logger, path)

Sets up the indicated logger to write to the indicated file at the ERROR level. Specifically, adds a ERROR-level FileHandler to the logger, and ensures that the logger’s level is at the ERROR level or lower.

The logger may either be a logger name (as a string) or a logging.Logger object. If the logger has any pre-existing handlers targeting the same file, then those handlers are removed to prevent doubling log messages. Returns the new FileHandler. Refer to the syntaxes below for option to implement a RotatingFileHandler (which rotates the log file after reaching a maximum size), or a TimedRotatingFileHandler (which rotates after a fixed time interval).

Formatting

error(..., format)
error(..., format=None, *, fallback_format)

Use format to specify the format used for log messages. The format may be a %-style logging format string, or a logging.Formatter object. Logging strings are sufficient for most cases, but we note that advanced users can achieve more fine-grained control by using a logging.Formatter object.

If format=None (the default), and the logger has pre-existing handlers that target the same file, then the format will default to the format of the first such handler that has a formatter. If no such handler is found, the format will be set to the value specified by fallback_format. By default, fallback_format is set to the logged message, equivalent to the formatting string "%(message)s".

Rotating Files

error(..., *, rotate_bytes)
error(..., *, rotate_when, rotate_interval)
error(..., *, backup_count)

Options for implementing rotating file logs. Setting rotate_bytes will add a RotatingFileHandler to the logger (as opposed to a basic FileHandler). The log file will rotate after the file size reaches the indicated number of bytes. Alternatively, use rotate_when and rotate_interval to use a TimedRotatingFileHandler, which will rotate the log file on the specified interval. (Refer to the TimedRotatingFileHandler docs for supported options). For either type of rotating file log, use backup_count to specify the number of backup file logs that should be saved after rotation.

File Creation

error(..., *, make_parents=True)
error(..., *, delay=True)

Options for creating the log file. By default, raises a FileNotFoundError if the log file parent folder does not exist. Set make_parents=True to create the parent folder as needed.

Use delay to control when the log file is created. By default, opens/creates the log file immediately. Set delay = True to defer opening/creating the log file until the first message is emitted.

Advanced Options

error(..., *, clear_existing=False)
error(..., *, propagate=True)

Advanced options that can lead to “double-logging” bugs. Set clear_existing=False to disable the removal of pre-existing handlers that target the same file.

By default, this command sets logger.propagate=False, which stops this logger’s events from being propagated to ancestor loggers. Set propagate=True to allow event propagation.

Handler Constructor

error(..., **handler_kwargs)

Specifies additional options that should be passed to the FileHandler, RotatingFileHandler, or TimedRotatingFileHandler constructor, as appropriate.

Args:

• logger (str | logging.Logger) – The name of a logger or logging.Logger object that should write messages to file at the ERROR level

• path (str | pathlib.Path) – The path to the file where messages should be written

• format (str | logging.Formatter, optional) – An optional %-style logging format string, or logging.Formatter object used to set the format of logged messages. Defaults to the format of the first pre-existing handler that targets the same file and has a formatter, or to fallback_format if no such handler exists

• fallback_format (str | logging.Formatter) – The log format to use when format is not specified, and there is not pre-existing handler that targets the same file and has a formatter

• rotate_bytes (int) – A maximum file size (in bytes) for rotating log files

• rotate_when (str) – The type of interval to use for timed rotation

• rotate_interval (int) – The length of the interval for timed rotation. Defaults to 1

• backup_count (int) – The number of backup log files that should be preserved. Defaults to 1

• clear_existing (bool) – True (default) to remove any pre-existing handlers that target the same file. False to disable this behavior.

• propagate (bool) – True to allow this logger’s events to propagate to ancestor loggers. False (default) to prevent propagation.

• **handler_kwargs (Any) – Additional parameters passed to the constructor of the new FileHandler, RotatingFileHandler, or TimedRotatingFileHandler object.

Returns:

FileHandler | RotatingFileHandler | TimedRotatingFileHandler – The logger’s new ERROR-level file handler

logset.file.critical(logger, path, format=None, *, fallback_format='%(message)s', rotate_bytes=None, rotate_when=None, rotate_interval=1, backup_count=1, make_parents=False, delay=False, clear_existing=True, propagate=False, **handler_kwargs)

Sets up a logger to write to file at the CRITICAL level

critical(logger, path)

Sets up the indicated logger to write to the indicated file at the CRITICAL level. Specifically, adds a CRITICAL-level FileHandler to the logger, and ensures that the logger’s level is at the CRITICAL level or lower.

The logger may either be a logger name (as a string) or a logging.Logger object. If the logger has any pre-existing handlers targeting the same file, then those handlers are removed to prevent doubling log messages. Returns the new FileHandler. Refer to the syntaxes below for option to implement a RotatingFileHandler (which rotates the log file after reaching a maximum size), or a TimedRotatingFileHandler (which rotates after a fixed time interval).

Formatting

critical(..., format)
critical(..., format=None, *, fallback_format)

Use format to specify the format used for log messages. The format may be a %-style logging format string, or a logging.Formatter object. Logging strings are sufficient for most cases, but we note that advanced users can achieve more fine-grained control by using a logging.Formatter object.

If format=None (the default), and the logger has pre-existing handlers that target the same file, then the format will default to the format of the first such handler that has a formatter. If no such handler is found, the format will be set to the value specified by fallback_format. By default, fallback_format is set to the logged message, equivalent to the formatting string "%(message)s".

Rotating Files

critical(..., *, rotate_bytes)
critical(..., *, rotate_when, rotate_interval)
critical(..., *, backup_count)

Options for implementing rotating file logs. Setting rotate_bytes will add a RotatingFileHandler to the logger (as opposed to a basic FileHandler). The log file will rotate after the file size reaches the indicated number of bytes. Alternatively, use rotate_when and rotate_interval to use a TimedRotatingFileHandler, which will rotate the log file on the specified interval. (Refer to the TimedRotatingFileHandler docs for supported options). For either type of rotating file log, use backup_count to specify the number of backup file logs that should be saved after rotation.

File Creation

critical(..., *, make_parents=True)
critical(..., *, delay=True)

Options for creating the log file. By default, raises a FileNotFoundError if the log file parent folder does not exist. Set make_parents=True to create the parent folder as needed.

Use delay to control when the log file is created. By default, opens/creates the log file immediately. Set delay = True to defer opening/creating the log file until the first message is emitted.

Advanced Options

critical(..., *, clear_existing=False)
critical(..., *, propagate=True)

Advanced options that can lead to “double-logging” bugs. Set clear_existing=False to disable the removal of pre-existing handlers that target the same file.

By default, this command sets logger.propagate=False, which stops this logger’s events from being propagated to ancestor loggers. Set propagate=True to allow event propagation.

Handler Constructor

critical(..., **handler_kwargs)

Specifies additional options that should be passed to the FileHandler, RotatingFileHandler, or TimedRotatingFileHandler constructor, as appropriate.

Args:

• logger (str | logging.Logger) – The name of a logger or logging.Logger object that should write messages to file at the CRITICAL level

• path (str | pathlib.Path) – The path to the file where messages should be written

• format (str | logging.Formatter, optional) – An optional %-style logging format string, or logging.Formatter object used to set the format of logged messages. Defaults to the format of the first pre-existing handler that targets the same file and has a formatter, or to fallback_format if no such handler exists

• fallback_format (str | logging.Formatter) – The log format to use when format is not specified, and there is not pre-existing handler that targets the same file and has a formatter

• rotate_bytes (int) – A maximum file size (in bytes) for rotating log files

• rotate_when (str) – The type of interval to use for timed rotation

• rotate_interval (int) – The length of the interval for timed rotation. Defaults to 1

• backup_count (int) – The number of backup log files that should be preserved. Defaults to 1

• make_parents (bool) – True to create any parent folders needed to hold the log file. False (default) to not create parent folders.

• delay (bool) – True to delay creating the log file until the first message is emitted. False (default) to create the log file immediately.

• clear_existing (bool) – True (default) to remove any pre-existing handlers that target the same file. False to disable this behavior.

• propagate (bool) – True to allow this logger’s events to propagate to ancestor loggers. False (default) to prevent propagation.

• **handler_kwargs (Any) – Additional parameters passed to the constructor of the new FileHandler, RotatingFileHandler, or TimedRotatingFileHandler object.

Returns:

FileHandler | RotatingFileHandler | TimedRotatingFileHandler – The logger’s new CRITICAL-level file handler