pdslogger Module

PDS RMS Node enhancements to the Python logger module.

The PdsLogger class provides a variety of enhancements to Python’s logging.Logger class. Use the PdsLogger() constructor or method get_logger() to create a new logger or access an existing one by name. To add the capabilities of PdsLogger to an existing logging.Logger, use as_pdslogger(). In this case, the behavior of the new PdsLogger will be identical to that of the given Logger, including all formatting, but the additional capabilities of PdsLogger will also become available.

It supports hierarchical logs, in which the log generated by a running task can be cleanly separated into individual sub-tasks. When a sub-task is completed, the log contains a summary of the numbers of logged messages by category and, optionally, the elapsed time. You create a new level in the hierarchy with open() and close them with close(). Alternatively, you can write:

with logger.open(...):
    # Write log messages here

to close the newly-opened section of the log automatically. A specific handler can be assigned to the PdsLogger as part of the open() call and it will automatically be removed upon closing. Use this feature, for example, to obtain separate log files for individual tasks or when processing a sequence of individual files.

The constructor allows the user to create additional error categories beyond the standard ones named “debug”, “info”, “warning”, etc. Each category can be assigned its own numeric level, where DEBUG=10, INFO=20, WARNING=30, ERROR=40, and CRITICAL=50. A level of None or HIDDEN means that messages with this alias are always suppressed.

The following additional message categories are used widely by the RMS Node and are defined by default:

  • “normal” (default level 20=INFO) is used for any normal outcome.

  • “header” (default level 20=INFO) is used for message headers following open() and summary messages following close().

  • “exception” (default level 50=CRITICAL) is used when an exception is encountered.

  • “ds_store” (default level 10=DEBUG) is used when a task encounters a “.DS_Store” file as managed by the MacOS Finder.

  • “dot_” (default level 40=ERROR) is used when a file beginning with “._” is encountered. These files are sometimes created by “tar” commands in MacOS.

  • “invisible” (default level 30=WARNING) is used if any other invisible file is encountered.

Of course, any of these default levels can be modified on a logger-by-logger basis.

Use set_limit() to specify a limit on the number of messages that can be associated with an alias. For example, if the limit on “info” messages is 100, then log messages after the hundredth will be suppressed, although the number of suppressed messages will still be tracked. At the end of the log, a tally of the messages associated with each alias is printed, including the number suppressed if the limit was exceeded.

PdsLogger supports a rich set of formatting options for the log records, which can be specified in the constructor or by using set_format(). By default, each log record automatically includes a time tag, log name, level, text message, and optional file path. Also, use add_root() and related methods to exercise more control over how file paths appear.

Use log() to log a message or else level-specific methods called debug(), info(), warning(), etc. Each of these methods receives a message string and arguments identical to the methods of the same name in logging.Logger. However, they take also an optional file path, which is automatically formatted to appear after the message text in the log.

Method exception() can be used inside a Python except clause to write an exception message into the log, including the stacktrace. If you desire greater control over how an exception is recorded in the log, you can use the LoggerException class or define your own subclass.

Simple tools are also provided to create handlers to assign to a PdsLogger using add_handler() and related methods:

  • file_handler() is a function that provides a rich set of options for constructing logging.FileHandler objects, which allow logs to be written to a file. The options include version numbering, appending a date or time to the file name, and daily rotations. file_handler() also supports the RMS Node’s filecache module, which allows log files to be seamlessly saved into cloud storage; simply pass in a URI or FCPath object instead of a local file path.

  • info_handler(), warnings_handler(), and error_handler() are simpler versions of the above, in which the level of message logging is implied.

  • stream_handler() is a function that creates handlers to write to an I/O stream such as sys.stdout or sys.stderr.

  • STDOUT_HANDLER is a pre-defined handler that prints all output to the terminal.

  • NULL_HANDLER is a pre-defined handler that suppresses all output.

Note that a PdsLogger will print message to the terminal if no handler has been assigned to it. As a result, if you really wish not to see any messages, you must assign it the NULL_HANDLER.

In the Macintosh Finder, log files are color-coded by the most severe message encountered within the file: green for “info”, yellow for warnings, red for errors, and violet for critical or fatal errors.

For extremely simple logging needs, four subclasses of PdsLogger are provided. EasyLogger prints all messages above a specified level of severity to the terminal. ErrorLogger only prints error messages. CriticalLogger only prints exceptions and other “critical” messages. NullLogger suppresses all messages, including logged exceptions. These four subclasses have the common trait that they cannot be assigned handlers.

class pdslogger.PdsLogger(logname, *, parent=None, levels={}, limits={}, roots=[], level=None, timestamps=None, digits=6, lognames=None, pid=False, indent=None, levelnames=None, blanklines=True, colors=True, maxdepth=6)[source]

Logger class adapted by PDS Ring-Moon Systems Node.

See https://rms-pdslogger.readthedocs.io/en/latest/module.html for details.

__init__(logname, *, parent=None, levels={}, limits={}, roots=[], level=None, timestamps=None, digits=6, lognames=None, pid=False, indent=None, levelnames=None, blanklines=True, colors=True, maxdepth=6)[source]

Constructor for a PdsLogger.

Parameters:

  • logname (str or Logger) – Name of the logger, to be appended to the given parent. Each logger name must be globally unique. If a Logger is given, its name is used and the given Logger is wrapped by the returned PdsLogger.

  • parent (str, logger, or PdsLogger, optional) – The parent name or parent logger for this new logger. By default, the logger defined by set_default_parent() is used. Use “” for no parent.

  • levels (dict, optional) – A dictionary of level names and their values. These override or augment the default level values. Use a negative level value to replace the default name for a level; for example, {‘VERY_BAD’: -CRITICAL} will cause “CRITICAL” errors to appear in the log as “VERY_BAD” errors instead. The case of level names is ignored.

  • limits (dict, optional) – A dictionary indicating the upper limit on the number of messages to log as a function of level name.

  • roots (str, Path, FCPath, or list[str, Path, or FCPath], optional) – Character strings to suppress if they appear at the beginning of file paths. Used to reduce the length of log entries when, for example, every file path is in a single subdirectory tree on the volume.

  • level (int or str, optional) – The minimum level or level name for a record to enter the log. By default, this is the minimum logging level, HIDDEN + 1, unless this PdsLogger is being derived from an existing Logger of the same name, in which case it will match the existing Logger’s level.

  • timestamps (bool, optional) – True to include timestamps in the log records. By default, this is True unless this PdsLogger is being derived from an existing Logger of the same name, in which case it is False.

  • digits (int, optional) – Number of fractional digits in the seconds field of the timestamp.

  • lognames (bool, optional) – True to include the name of the logger in the log records. By default, this is True unless this PdsLogger is being derived from an existing Logger of the same name, in which case it is False.

  • pid (bool, optional) – True to include the process ID in each log record.

  • indent (bool, optional) – True to include a sequence of dashes in each log record to provide a visual indication of the depth in a logging hierarchy. By default, this is True unless this PdsLogger is being derived from an existing Logger of the same name, in which case it is False.

  • levelnames (bool, optional) – True to include the name of the log level, e.g., “ERROR”, in the log records. By default, this is True unless this PdsLogger is being derived from an existing Logger of the same name, in which case it is False.

  • blanklines (bool, optional) – True to include a blank line in log files after a sub-logger is closed.

  • colors (bool, optional) – True to color-code any log files generated, for Macintosh only.

  • maxdepth (int, optional) – Maximum depth of the logging hierarchy, needed to prevent unlimited recursion.

Raises:

ValueError – If the log name is already in use of if the level name associated with a limit is unknown.

static get_logger(logname, *, parent=None, levels={}, limits={}, roots=[], level=None, timestamps=None, digits=None, lognames=None, pid=None, indent=None, levelnames=None, blanklines=None, colors=None, maxdepth=None)[source]

Return the current logger by this name if it already exists; otherwise, construct and return a new PdsLogger.

Parameters:

  • logname (str or Logger) – Name of the logger, to be appended to the given parent. If a Logger or PdsLogger is provided, its name is used and parent is ignored.

  • parent (str, logger, or PdsLogger, optional) – The parent name or parent logger for this new logger. By default, the logger defined by set_default_parent() is used. Use “” for no parent.

  • levels (dict, optional) – A dictionary of level names and their values. These override or augment the default level values.

  • limits (dict, optional) – A dictionary indicating the upper limit on the number of messages to log as a function of level name.

  • roots (str, Path, FCPath, or list[str, Path, or FCPath], optional) – Character strings to suppress if they appear at the beginning of file paths. Used to reduce the length of log entries when, for example, every file path is in a single subdirectory tree on the volume.

  • level (int or str, optional) – The minimum level or level name for a record to enter the log. By default, the value for an existing PdsLogger is preserved; if there is already a Logger of the same name, the default is False; for an entirely new PdsLogger, the default is the minimum logging level, HIDDEN + 1.

  • timestamps (bool, optional) – True to include timestamps in the log records. By default, the value for an existing PdsLogger is preserved; if there is already a Logger of the same name, the default is False; for an entirely new PdsLogger, the default is True.

  • digits (int, optional) – Number of fractional digits in the seconds field of the timestamp. By default, the value for an existing PdsLogger is preserved; otherwise, the default is 6.

  • lognames (bool, optional) – True to include the name of the logger in the log records. By default, the value for an existing PdsLogger is preserved; if there is already a Logger of the same name, the default is False; for an entirely new PdsLogger, the default is True.

  • pid (bool, optional) – True to include the process ID in each log record. By default, the value for an existing PdsLogger is preserved; otherwise, the default is False.

  • indent (bool, optional) – True to include a sequence of dashes in each log record to provide a visual indication of the depth in a logging hierarchy. By default, the value for an existing PdsLogger is preserved; if there is already a Logger of the same name, the default is False; for an entirely new PdsLogger, the default is True.

  • levelnames (bool, optional) – True to include the name of the log level, e.g., “ERROR”, in the log records. By default, the value for an existing PdsLogger is preserved; if there is already a Logger of the same name, the default is False; for an entirely new PdsLogger, the default is True.

  • blanklines (bool, optional) – True to include a blank line in log files when a tier in the hierarchy is closed; False otherwise. By default, the value for an existing PdsLogger is preserved; otherwise, the default is True.

  • colors (bool, optional) – True to color-code any log files generated, for Macintosh only. By default, the value for an existing PdsLogger is preserved; otherwise, the default is True.

  • maxdepth (int, optional) – Maximum depth of the logging hierarchy, needed to prevent unlimited recursion. By default, the value for an existing PdsLogger is preserved; otherwise, the default is 6.

static getLogger(*args, **kwargs)[source]

Alternative name for get_logger().

copy(logname, parent=None)[source]

A copy of this PdsLogger with a revised name.

All other attributes are retained except handlers.

Parameters:

  • logname (str) – Name of the logger, to be appended to the given parent.

  • parent (str, logger, or PdsLogger, optional) – The parent name or parent logger for this new logger. By default, the logger defined by set_default_parent() is used. Use “” for no parent.

Raises:

ValueError – If the log name is already in use of if the level name associated with a limit is unknown.

get_child(name, levels={}, limits={}, roots=[], level=None, timestamps=None, digits=None, lognames=None, pid=None, indent=None, levelnames=None, blanklines=None, colors=None, maxdepth=None)[source]

Construct if necessary and return the named child PdsLogger of this PdsLogger.

Parameters:

  • name (str) – Name of the child logger, to be appended to the name of this PdsLogger.

  • levels (dict, optional) – A dictionary of level names and their values. These values override or augment the level values of the parent logger.

  • limits (dict, optional) – A dictionary indicating the upper limit on the number of messages to log as a function of level name. These values override or augment the limits of the parent logger.

  • roots (str, Path, FCPath, or list[str, Path, or FCPath], optional) – Character strings to suppress if they appear at the beginning of file paths. Used to reduce the length of log entries when, for example, every file path is in a single subdirectory tree on the volume. These values augment the roots inherited from the parent logger.

  • level (int or str, optional) – The minimum level or level name for a record to enter the log. If not specified, the child logger inherits its value from the parent.

  • timestamps (bool, optional) – True to include timestamps in the log records. If not specified, the child logger inherits this value from the parent.

  • digits (int, optional) – Number of fractional digits in the seconds field of the timestamp. If not specified, the child logger inherits this value from the parent.

  • lognames (bool, optional) – True to include the name of the logger in the log records. If not specified, the child logger inherits this value from the parent.

  • pid (bool, optional) – True to include the process ID in each log record. If not specified, the child logger inherits this value from the parent.

  • indent (bool, optional) – True to include a sequence of dashes in each log record to provide a visual indication of the depth in a logging hierarchy. If not specified, the child logger inherits this value from the parent.

  • levelnames (bool, optional) – True to include the name of the log level, e.g., “ERROR”, in the log records. If not specified, the child logger inherits this value from the parent.

  • blanklines (bool, optional) – True to include a blank line in log files when a tier in the hierarchy is closed; False otherwise. If not specified, the child logger inherits this value from the parent.

  • colors (bool, optional) – True to color-code any log files generated, for Macintosh only. If not specified, the child logger inherits this value from the parent.

  • maxdepth (int, optional) – Maximum depth of the logging hierarchy, needed to prevent unlimited recursion. If not specified, the child logger inherits this value from the parent.

getChild(name, **kwargs)[source]

Alternative name for get_child().

static as_pdslogger(logger)[source]

Convert the given Logger to a PdsLogger.

Parameters:

logger (logging.Logger or PdsLogger) – logger to convert to PdsLogger.

Returns:

converted logger. A PdsLogger is returned as is. If a PdsLogger has already been defined for the given logger, that PdsLogger is returned. Otherwise, a new PdsLogger is constructed using properties that will match the Logger’s current format.

Return type:

PdsLogger

__str__()[source]

Return str(self).

__repr__()[source]

Return repr(self).

set_format(*, level=None, timestamps=None, digits=None, lognames=None, pid=None, indent=None, levelnames=None, blanklines=None, colors=None, maxdepth=None)[source]

Set or modify the formatting and other properties of this PdsLogger.

Parameters:

  • level (int or str, optional) – The minimum level of level name for a record to enter the log.

  • timestamps (bool, optional) – True or False, defining whether to include a timestamp in each log record.

  • digits (int, optional) – Number of fractional digits in the seconds field of the timestamp.

  • lognames (bool, optional) – True or False, defining whether to include the name of the logger in each log record.

  • pid (bool, optional) – True or False, defining whether to include the process ID in each log record.

  • indent (bool, optional) – True or False, defining whether to include a sequence of dashes in each log record to provide a visual indication of the tier in a logging hierarchy.

  • levelnames (bool, optional) – True to include the name of the log level, e.g., “ERROR”, in the log records.

  • blanklines (bool, optional) – True or False, defining whether to include a blank line in log files when a tier in the hierarchy is closed.

  • colors (bool, optional) – True or False, defining whether to color-code the log files generated, for Macintosh only.

  • maxdepth (int, optional) – Maximum depth of the logging hierarchy, needed to prevent unlimited recursion.

property name

The name of this PdsLogger.

property parent

The parent of this PdsLogger.

static set_default_parent(parent)[source]

Define the name of the default prefix, which will be used for each new logger unless overridden in the constructor or in the call to get_logger().

Parameters:

parent (str, logger, or PdsLogger) – Name or logger to serve as the default parent.

get_children()[source]

The set of child PdsLoggers of this PdsLogger.

getChildren()[source]

Alternative name for get_children().

property level

The minimum logging level of this PdsLogger.

set_level(level)[source]

Set the level of messages for the current tier in the logger’s hierarchy.

Parameters;
level (int or str, optional):

The minimum level or level name for a record to enter the log.

setLevel(level)[source]

Alternative name for set_level().

set_limit(name, limit)[source]

Set the upper limit on the number of messages with this level name.

Parameters:

  • name (int or str) – A logging level or level name.

  • limit (int) – The maximum number of messages to be logged at this level. A limit of -1 implies no limit.

get_limit(name)[source]

Get the current upper limit on the number of messages with this level name.

Parameters:

name (int or str) – A logging level or level name.

Raises:

KeyError – If name is not a known level name.

get_limits()[source]

A dictionary of the current default upper limit on the number of messages with each level name.

add_root(*roots)[source]

Add one or more paths to the set of root paths.

When a root path appears at the beginning of a logged file path, only the portion following the root is shown.

Parameters:

*roots (str, Path, or FCPath) – One or more root paths to suppress.

property roots

This current list of root paths as strings.

replace_root(*roots)[source]

Replace the existing root(s) with one or more new paths.

property handlers

The list of handlers of this PdsLogger.

has_handlers()[source]

True if this PdsLogger has handlers.

hasHandlers()[source]

Alternative name for has_handlers.

add_handler(*handlers, local=None)[source]

Add one or more handlers to this PdsLogger at the current location in the hierarchy.

If a handler is already in use, or if it refers to a log file that is already in use, the input is ignored silently.

Parameters:

  • *handlers (logging.Handler, str, path, or FCPath) – One or more handlers. If a file path is provided, it is used by file_handler() to construct a new FileHandler.

  • local (bool, optional) – True to add this as a local handler, which will be removed when close() is called; False to treat it as a global handler, which is preserved until explicitly removed. Outside any call to open(), all handlers are global.

addHandler(*handlers, local=False)[source]

Alternative name for add_handler().

remove_handler(*handlers)[source]

Remove one or more handlers from this PdsLogger.

Parameters:

*handlers (logging.Handler, str, path, FCPath) – One or more handlers. If a file path is provided, the FileHandler using that log path is removed.

removeHandler(*handlers)[source]

Alternative name for remove_handler().

remove_all_handlers()[source]

Remove all the handlers from this PdsLogger.

replace_handler(*handlers)[source]

Replace the existing local handlers with one or more new handlers at the current tier in the logging hierarchy.

Parameters:

*handlers (str, path, FCPath, or logging.Handler) – One or more handlers. If a file path is provided, it is used in a new FileHandler.

property propagate
property disabled
isEnabledFor(level)[source]

Is this logger enabled for level ‘level’?

getEffectiveLevel()[source]

Get the effective level for this logger.

Loop through this logger and its parents in the logger hierarchy, looking for a non-zero logging level. Return the first one found.

addFilter(filter)[source]

Add the specified filter to this handler.

removeFilter(filter)[source]

Remove the specified filter from this handler.

filter(record)[source]

Determine if a record is loggable by consulting all the filters.

The default is to allow the record to be logged; any filter can veto this by returning a false value. If a filter attached to a handler returns a log record instance, then that instance is used in place of the original log record in any further processing of the event by that handler. If a filter returns any other true value, the original log record is used in any further processing of the event by that handler.

If none of the filters return false values, this method returns a log record. If any of the filters return a false value, this method returns a false value.

Changed in version 3.2: Allow filters to be just callables.

Changed in version 3.12: Allow filters to return a LogRecord instead of modifying it in place.

findCaller(stack_info=False, stacklevel=1)[source]

Find the stack frame of the caller so that we can note the source file name, line number and function name.

handle(record)[source]

Call the handlers for the specified record.

This method is used for unpickled records received from a socket, as well as those created locally. Logger-level filtering is applied.

makeRecord(*args, **kwargs)[source]

A factory method which can be overridden in subclasses to create specialized LogRecords.

is_enabled_for(level)

Is this logger enabled for level ‘level’?

get_effective_level()

Get the effective level for this logger.

Loop through this logger and its parents in the logger hierarchy, looking for a non-zero logging level. Return the first one found.

add_filter(filter)

Add the specified filter to this handler.

remove_filter(filter)

Remove the specified filter from this handler.

make_record(*args, **kwargs)

A factory method which can be overridden in subclasses to create specialized LogRecords.

open(title, *args, filepath='', level=None, limits={}, handler=[], force=False, blankline=False, **kwargs)[source]

Begin a new tier in the logging hierarchy.

Parameters:

  • title (str) – Title of the new section of the log.

  • *args – Zero or more items to be substituted into the message string using the string formatting operator. If there are no substitution patterns inside the message string (indicated by “%” of “{”) that use these args, a single argument is interpreted as the filepath.

  • filepath (str, Path, or FCPath, optional) – Optional file path to include in the title.

  • level (int, or str, optional) – The level or level name for the minimum logging level to use within this tier. The default is to preserve the current logging level.

  • limits (dict, optional) – A dictionary mapping level name to the maximum number of messages of that level to include. Subsequent messages are suppressed. Use a limit of -1 to show all messages.

  • handler (Handler or list[Handler], optional) – Optional handler(s) to use only until this part of the logger is closed.

  • force (bool, optional) – True to force the logging of the “open” messages, even if the current logging level is above that specified by level.

  • blankline (bool, optional) – True to insert a blank line before the logger.

  • **kwargs – Zero or more keyword=value attributes to be substituted into the title string using the string formatted operator.

Returns:

A context manager enabling “open logger.open():” syntax. If open() is not being used as a context manager, this object can be ignored.

Return type:

context manager

summarize(local=True)[source]

Return a tuple describing the number of logged messages by category in the current tier of the hierarchy.

Parameters:

local (bool, optional) – True for the totals at this depth in the hierarchy; False for the global totals since this PdsLogger was created.

Returns:

(number of critical errors, number of errors, number of warnings, total number of messages). These counts include messages that were suppressed because a limit was reached.

Return type:

tuple

close(*, force=False, blankline=False)[source]

Close the log at its current depth in the hierarchy.

The closure is logged, plus a summary of the time elapsed and levels identified while this sub-logger was open.

Parameters:

  • force (bool, int, or str, optional) – True to force the logging of all summary messages. Alternatively use a level or level name to force the summary messages only about logged messages at this level and higher.

  • blankline (bool, optional) – True to insert a blank line in the log before closing if it would not otherwise be inserted.

Returns:

(number of critical errors, number of errors, number of warnings, total number of messages). These counts include messages that were suppressed because a limit was reached.

Return type:

tuple

message_count(name)[source]

The number of messages generated at this named level since this last open().

Parameters:

name (str) – Name of a level.

Returns:

The number of messages logged, including any suppressed if a limit was reached.

Return type:

int

log(level, message, *args, filepath='', force=False, suppress=False, **kwargs)[source]

Log one record.

Parameters:

  • level (int or str) – Logging level or level name.

  • message (str) – Message to log.

  • *args – Zero or more items to be substituted into the message string using the string formatting operator. If there are no substitution patterns inside the message string (indicated by “%” of “{”) that use these args, a single argument is interpreted as the filepath.

  • filepath (str, Path, or FCPath, optional) – Path of the relevant file, if any.

  • force (bool, int, or str, optional) – True to log this message even if the relevant limit has been reached; False otherwise. Alternatively, use a level or level name to log the given message to handlers at or below a particular level.

  • suppress (bool, optional) – True to suppress message reporting even if the relevant limit has not been reached. The message is still included in the count. The force option takes precedence over this option.

  • **kwargs – Zero or more keyword=value attributes to be substituted into the message string using the string formatted operator.

debug(message, *args, filepath='', force=False, suppress=False, **kwargs)[source]

Log a message with level == “debug”.

Parameters:

  • message (str) – Message to log.

  • *args – Zero or more items to be substituted into the message string using the string formatting operator. If there are no substitution patterns (indicated by “%” of “{”) inside the message string, a single argument is interpreted as the filepath.

  • filepath (str, Path, or FCPath, optional) – Path of the relevant file, if any.

  • force (bool, int, or str, optional) – True to log this message even if the relevant limit has been reached; False otherwise. Alternatively, use a level or level name to log the given message to handlers at or below a particular level.

  • suppress (bool, optional) – True to suppress message reporting even if the relevant limit has not been reached. The message is still included in the count. The force option takes precedence over this option.

  • **kwargs – Zero or more keyword=value attributes to be substituted into the message string using the string formatted operator.

info(message, *args, filepath='', force=False, suppress=False, **kwargs)[source]

Log a message with level == “info”.

Parameters:

  • message (str) – Message to log.

  • *args – Zero or more items to be substituted into the message string using the string formatting operator. If there are no substitution patterns (indicated by “%” of “{”) inside the message string, a single argument is interpreted as the filepath.

  • filepath (str, Path, or FCPath, optional) – Path of the relevant file, if any.

  • force (bool, int, or str, optional) – True to log this message even if the relevant limit has been reached; False otherwise. Alternatively, use a level or level name to log the given message to handlers at or below a particular level.

  • suppress (bool, optional) – True to suppress message reporting even if the relevant limit has not been reached. The message is still included in the count. The force option takes precedence over this option.

  • **kwargs – Zero or more keyword=value attributes to be substituted into the message string using the string formatted operator.

warning(message, *args, filepath='', force=False, suppress=False, **kwargs)[source]

Log a message with level == “warning”.

Parameters:

  • message (str) – Message to log.

  • *args – Zero or more items to be substituted into the message string using the string formatting operator. If there are no substitution patterns (indicated by “%” of “{”) inside the message string, a single argument is interpreted as the filepath.

  • filepath (str, Path, or FCPath, optional) – Path of the relevant file, if any.

  • force (bool, int, or str, optional) – True to log this message even if the relevant limit has been reached; False otherwise. Alternatively, use a level or level name to log the given message to handlers at or below a particular level.

  • suppress (bool, optional) – True to suppress message reporting even if the relevant limit has not been reached. The message is still included in the count. The force option takes precedence over this option.

  • **kwargs – Zero or more keyword=value attributes to be substituted into the message string using the string formatted operator.

warn(message, *args, filepath='', force=False, suppress=False, **kwargs)[source]

Log a message with level == “warning”.

Parameters:

  • message (str) – Message to log.

  • *args – Zero or more items to be substituted into the message string using the string formatting operator. If there are no substitution patterns (indicated by “%” of “{”) inside the message string, a single argument is interpreted as the filepath.

  • filepath (str, Path, or FCPath, optional) – Path of the relevant file, if any.

  • force (bool, int, or str, optional) – True to log this message even if the relevant limit has been reached; False otherwise. Alternatively, use a level or level name to log the given message to handlers at or below a particular level.

  • suppress (bool, optional) – True to suppress message reporting even if the relevant limit has not been reached. The message is still included in the count. The force option takes precedence over this option.

  • **kwargs – Zero or more keyword=value attributes to be substituted into the message string using the string formatted operator.

error(message, *args, filepath='', force=False, suppress=False, **kwargs)[source]

Log a message with level == “error”.

Parameters:

  • message (str) – Message to log.

  • *args – Zero or more items to be substituted into the message string using the string formatting operator. If there are no substitution patterns (indicated by “%” of “{”) inside the message string, a single argument is interpreted as the filepath.

  • filepath (str, Path, or FCPath, optional) – Path of the relevant file, if any.

  • force (bool, int, or str, optional) – True to log this message even if the relevant limit has been reached; False otherwise. Alternatively, use a level or level name to log the given message to handlers at or below a particular level.

  • suppress (bool, optional) – True to suppress message reporting even if the relevant limit has not been reached. The message is still included in the count. The force option takes precedence over this option.

  • **kwargs – Zero or more keyword=value attributes to be substituted into the message string using the string formatted operator.

critical(message, *args, filepath='', force=False, suppress=False, **kwargs)[source]

Log a message with level == “critical”.

Parameters:

  • message (str) – Message to log.

  • *args – Zero or more items to be substituted into the message string using the string formatting operator. If there are no substitution patterns (indicated by “%” of “{”) inside the message string, a single argument is interpreted as the filepath.

  • filepath (str, Path, or FCPath, optional) – Path of the relevant file, if any.

  • force (bool, int, or str, optional) – True to log this message even if the relevant limit has been reached; False otherwise. Alternatively, use a level or level name to log the given message to handlers at or below a particular level.

  • suppress (bool, optional) – True to suppress message reporting even if the relevant limit has not been reached. The message is still included in the count. The force option takes precedence over this option.

  • **kwargs – Zero or more keyword=value attributes to be substituted into the message string using the string formatted operator.

fatal(message, *args, filepath='', force=False, suppress=False, **kwargs)[source]

Log a message with level == “fatal”, equivalent to “critical”.

Parameters:

  • message (str) – Message to log.

  • *args – Zero or more items to be substituted into the message string using the string formatting operator. If there are no substitution patterns (indicated by “%” of “{”) inside the message string, a single argument is interpreted as the filepath.

  • filepath (str, Path, or FCPath, optional) – Path of the relevant file, if any.

  • force (bool, int, or str, optional) – True to log this message even if the relevant limit has been reached; False otherwise. Alternatively, use a level or level name to log the given message to handlers at or below a particular level.

  • suppress (bool, optional) – True to suppress message reporting even if the relevant limit has not been reached. The message is still included in the count. The force option takes precedence over this option.

  • **kwargs – Zero or more keyword=value attributes to be substituted into the message string using the string formatted operator.

normal(message, *args, filepath='', force=False, suppress=False, **kwargs)[source]

Log a message with level == “normal”, equivalent to “info”.

Parameters:

  • message (str) – Message to log.

  • *args – Zero or more items to be substituted into the message string using the string formatting operator. If there are no substitution patterns (indicated by “%” of “{”) inside the message string, a single argument is interpreted as the filepath.

  • filepath (str, Path, or FCPath, optional) – Path of the relevant file, if any.

  • force (bool, int, or str, optional) – True to log this message even if the relevant limit has been reached; False otherwise. Alternatively, use a level or level name to log the given message to handlers at or below a particular level.

  • suppress (bool, optional) – True to suppress message reporting even if the relevant limit has not been reached. The message is still included in the count. The force option takes precedence over this option.

  • **kwargs – Zero or more keyword=value attributes to be substituted into the message string using the string formatted operator.

ds_store(message, *args, filepath='', force=False, suppress=False, **kwargs)[source]

Log a message with level == “ds_store”, indicating that a file named “.DS_Store” was found.

These files are sometimes created on a Mac.

Parameters:

  • message (str) – Message to log.

  • *args – Zero or more items to be substituted into the message string using the string formatting operator. If there are no substitution patterns (indicated by “%” of “{”) inside the message string, a single argument is interpreted as the filepath.

  • filepath (str, Path, or FCPath, optional) – Path of the relevant file, if any.

  • force (bool, int, or str, optional) – True to log this message even if the relevant limit has been reached; False otherwise. Alternatively, use a level or level name to log the given message to handlers at or below a particular level.

  • suppress (bool, optional) – True to suppress message reporting even if the relevant limit has not been reached. The message is still included in the count. The force option takes precedence over this option.

  • **kwargs – Zero or more keyword=value attributes to be substituted into the message string using the string formatted operator.

dot_underscore(message, *args, filepath='', force=False, suppress=False, **kwargs)[source]

Log a message with level == “dot_”, indicating that a file with a name beginning with “._” was found.

These files are sometimes created during file transfers from a Mac.

Parameters:

  • message (str) – Message to log.

  • *args – Zero or more items to be substituted into the message string using the string formatting operator. If there are no substitution patterns (indicated by “%” of “{”) inside the message string, a single argument is interpreted as the filepath.

  • filepath (str, Path, or FCPath, optional) – Path of the relevant file, if any.

  • force (bool, int, or str, optional) – True to log this message even if the relevant limit has been reached; False otherwise. Alternatively, use a level or level name to log the given message to handlers at or below a particular level.

  • suppress (bool, optional) – True to suppress message reporting even if the relevant limit has not been reached. The message is still included in the count. The force option takes precedence over this option.

  • **kwargs – Zero or more keyword=value attributes to be substituted into the message string using the string formatted operator.

invisible(message, *args, filepath='', force=False, suppress=False, **kwargs)[source]

Log a message with level == “invisible”, indicating that an invisible file was found.

Parameters:

  • message (str) – Message to log.

  • *args – Zero or more items to be substituted into the message string using the string formatting operator. If there are no substitution patterns (indicated by “%” of “{”) inside the message string, a single argument is interpreted as the filepath.

  • filepath (str, Path, or FCPath, optional) – Path of the relevant file, if any.

  • force (bool, int, or str, optional) – True to log this message even if the relevant limit has been reached; False otherwise. Alternatively, use a level or level name to log the given message to handlers at or below a particular level.

  • suppress (bool, optional) – True to suppress message reporting even if the relevant limit has not been reached. The message is still included in the count. The force option takes precedence over this option.

  • **kwargs – Zero or more keyword=value attributes to be substituted into the message string using the string formatted operator.

hidden(message, *args, filepath='', force=False, suppress=False, **kwargs)[source]

Log a message with level == “hidden”.

Parameters:

  • message (str) – Message to log.

  • *args – Zero or more items to be substituted into the message string using the string formatting operator. If there are no substitution patterns (indicated by “%” of “{”) inside the message string, a single argument is interpreted as the filepath.

  • filepath (str, Path, or FCPath, optional) – Path of the relevant file, if any.

  • force (bool, int, or str, optional) – True to log this message even if the relevant limit has been reached; False otherwise. Alternatively, use a level or level name to log the given message to handlers at or below a particular level.

  • suppress (bool, optional) – True to suppress message reporting even if the relevant limit has not been reached. The message is still included in the count. The force option takes precedence over this option.

  • **kwargs – Zero or more keyword=value attributes to be substituted into the message string using the string formatted operator.

exception(error, *args, filepath='', stacktrace=None, exc_info=None, more='', **kwargs)[source]

Log an Exception or KeyboardInterrupt.

This method is only to be used inside an except clause.

Parameters:

  • error (Exception or str) – The error raised or a text message.

  • *args – Zero or more items to be substituted into the message string using the string formatting operator. If there are no substitution patterns (indicated by “%” of “{”) inside the message string, a single argument is interpreted as the filepath.

  • filepath (str, Path, or FCPath, optional) – File path to include in the message.

  • stacktrace (bool, optional) – True to include the stacktrace of the exception.

  • exc_info (bool, optional) – Alternative name for stacktrace. If both are unspecified, True is assumed.

  • more (str, optional) – Additional information to write into the log following the error message.

  • **kwargs – Zero or more keyword=value attributes to be substituted into the message string using the string formatted operator.

Notes

The LoggerError constructor provides additional contol over how an exception will appear in the log, so use it or a subclass if you need this extra control.

A KeyboardInterrupt is not handled by this method. A brief note is added to the log and then this exception is re-raised.

blankline(level=20, force=False)[source]

Write a blank line into the log.

Parameters:

  • level (int or str) – Logging level or level name.

  • force (bool, optional) – True to force the message to be logged even if the logging level is above the specified level.

class pdslogger.EasyLogger(logname='easylog', **kwargs)[source]

Simple subclass of PdsLogger that prints messages to the terminal.

__init__(logname='easylog', **kwargs)[source]

Constructor for a PdsLogger.

Parameters:

  • logname (str or Logger) – Name of the logger, to be appended to the given parent. Each logger name must be globally unique. If a Logger is given, its name is used and the given Logger is wrapped by the returned PdsLogger.

  • parent (str, logger, or PdsLogger, optional) – The parent name or parent logger for this new logger. By default, the logger defined by set_default_parent() is used. Use “” for no parent.

  • levels (dict, optional) – A dictionary of level names and their values. These override or augment the default level values. Use a negative level value to replace the default name for a level; for example, {‘VERY_BAD’: -CRITICAL} will cause “CRITICAL” errors to appear in the log as “VERY_BAD” errors instead. The case of level names is ignored.

  • limits (dict, optional) – A dictionary indicating the upper limit on the number of messages to log as a function of level name.

  • roots (str, Path, FCPath, or list[str, Path, or FCPath], optional) – Character strings to suppress if they appear at the beginning of file paths. Used to reduce the length of log entries when, for example, every file path is in a single subdirectory tree on the volume.

  • level (int or str, optional) – The minimum level or level name for a record to enter the log. By default, this is the minimum logging level, HIDDEN + 1, unless this PdsLogger is being derived from an existing Logger of the same name, in which case it will match the existing Logger’s level.

  • timestamps (bool, optional) – True to include timestamps in the log records. By default, this is True unless this PdsLogger is being derived from an existing Logger of the same name, in which case it is False.

  • digits (int, optional) – Number of fractional digits in the seconds field of the timestamp.

  • lognames (bool, optional) – True to include the name of the logger in the log records. By default, this is True unless this PdsLogger is being derived from an existing Logger of the same name, in which case it is False.

  • pid (bool, optional) – True to include the process ID in each log record.

  • indent (bool, optional) – True to include a sequence of dashes in each log record to provide a visual indication of the depth in a logging hierarchy. By default, this is True unless this PdsLogger is being derived from an existing Logger of the same name, in which case it is False.

  • levelnames (bool, optional) – True to include the name of the log level, e.g., “ERROR”, in the log records. By default, this is True unless this PdsLogger is being derived from an existing Logger of the same name, in which case it is False.

  • blanklines (bool, optional) – True to include a blank line in log files after a sub-logger is closed.

  • colors (bool, optional) – True to color-code any log files generated, for Macintosh only.

  • maxdepth (int, optional) – Maximum depth of the logging hierarchy, needed to prevent unlimited recursion.

Raises:

ValueError – If the log name is already in use of if the level name associated with a limit is unknown.

class pdslogger.ErrorLogger(logname='errorlog', **kwargs)[source]

Simple subclass of PdsLogger that suppresses all messages except ERROR messages and those that have been forced.

__init__(logname='errorlog', **kwargs)[source]

Constructor for a PdsLogger.

Parameters:

  • logname (str or Logger) – Name of the logger, to be appended to the given parent. Each logger name must be globally unique. If a Logger is given, its name is used and the given Logger is wrapped by the returned PdsLogger.

  • parent (str, logger, or PdsLogger, optional) – The parent name or parent logger for this new logger. By default, the logger defined by set_default_parent() is used. Use “” for no parent.

  • levels (dict, optional) – A dictionary of level names and their values. These override or augment the default level values. Use a negative level value to replace the default name for a level; for example, {‘VERY_BAD’: -CRITICAL} will cause “CRITICAL” errors to appear in the log as “VERY_BAD” errors instead. The case of level names is ignored.

  • limits (dict, optional) – A dictionary indicating the upper limit on the number of messages to log as a function of level name.

  • roots (str, Path, FCPath, or list[str, Path, or FCPath], optional) – Character strings to suppress if they appear at the beginning of file paths. Used to reduce the length of log entries when, for example, every file path is in a single subdirectory tree on the volume.

  • level (int or str, optional) – The minimum level or level name for a record to enter the log. By default, this is the minimum logging level, HIDDEN + 1, unless this PdsLogger is being derived from an existing Logger of the same name, in which case it will match the existing Logger’s level.

  • timestamps (bool, optional) – True to include timestamps in the log records. By default, this is True unless this PdsLogger is being derived from an existing Logger of the same name, in which case it is False.

  • digits (int, optional) – Number of fractional digits in the seconds field of the timestamp.

  • lognames (bool, optional) – True to include the name of the logger in the log records. By default, this is True unless this PdsLogger is being derived from an existing Logger of the same name, in which case it is False.

  • pid (bool, optional) – True to include the process ID in each log record.

  • indent (bool, optional) – True to include a sequence of dashes in each log record to provide a visual indication of the depth in a logging hierarchy. By default, this is True unless this PdsLogger is being derived from an existing Logger of the same name, in which case it is False.

  • levelnames (bool, optional) – True to include the name of the log level, e.g., “ERROR”, in the log records. By default, this is True unless this PdsLogger is being derived from an existing Logger of the same name, in which case it is False.

  • blanklines (bool, optional) – True to include a blank line in log files after a sub-logger is closed.

  • colors (bool, optional) – True to color-code any log files generated, for Macintosh only.

  • maxdepth (int, optional) – Maximum depth of the logging hierarchy, needed to prevent unlimited recursion.

Raises:

ValueError – If the log name is already in use of if the level name associated with a limit is unknown.

class pdslogger.CriticalLogger(logname='criticallog', **kwargs)[source]

Simple subclass of PdsLogger that suppresses all messages except CRITICAL messages and those that have been forced.

__init__(logname='criticallog', **kwargs)[source]

Constructor for a PdsLogger.

Parameters:

  • logname (str or Logger) – Name of the logger, to be appended to the given parent. Each logger name must be globally unique. If a Logger is given, its name is used and the given Logger is wrapped by the returned PdsLogger.

  • parent (str, logger, or PdsLogger, optional) – The parent name or parent logger for this new logger. By default, the logger defined by set_default_parent() is used. Use “” for no parent.

  • levels (dict, optional) – A dictionary of level names and their values. These override or augment the default level values. Use a negative level value to replace the default name for a level; for example, {‘VERY_BAD’: -CRITICAL} will cause “CRITICAL” errors to appear in the log as “VERY_BAD” errors instead. The case of level names is ignored.

  • limits (dict, optional) – A dictionary indicating the upper limit on the number of messages to log as a function of level name.

  • roots (str, Path, FCPath, or list[str, Path, or FCPath], optional) – Character strings to suppress if they appear at the beginning of file paths. Used to reduce the length of log entries when, for example, every file path is in a single subdirectory tree on the volume.

  • level (int or str, optional) – The minimum level or level name for a record to enter the log. By default, this is the minimum logging level, HIDDEN + 1, unless this PdsLogger is being derived from an existing Logger of the same name, in which case it will match the existing Logger’s level.

  • timestamps (bool, optional) – True to include timestamps in the log records. By default, this is True unless this PdsLogger is being derived from an existing Logger of the same name, in which case it is False.

  • digits (int, optional) – Number of fractional digits in the seconds field of the timestamp.

  • lognames (bool, optional) – True to include the name of the logger in the log records. By default, this is True unless this PdsLogger is being derived from an existing Logger of the same name, in which case it is False.

  • pid (bool, optional) – True to include the process ID in each log record.

  • indent (bool, optional) – True to include a sequence of dashes in each log record to provide a visual indication of the depth in a logging hierarchy. By default, this is True unless this PdsLogger is being derived from an existing Logger of the same name, in which case it is False.

  • levelnames (bool, optional) – True to include the name of the log level, e.g., “ERROR”, in the log records. By default, this is True unless this PdsLogger is being derived from an existing Logger of the same name, in which case it is False.

  • blanklines (bool, optional) – True to include a blank line in log files after a sub-logger is closed.

  • colors (bool, optional) – True to color-code any log files generated, for Macintosh only.

  • maxdepth (int, optional) – Maximum depth of the logging hierarchy, needed to prevent unlimited recursion.

Raises:

ValueError – If the log name is already in use of if the level name associated with a limit is unknown.

class pdslogger.NullLogger(logname='nulllog', **kwargs)[source]

Simple subclass of PdsLogger that suppresses all messages.

__init__(logname='nulllog', **kwargs)[source]

Constructor for a PdsLogger.

Parameters:

  • logname (str or Logger) – Name of the logger, to be appended to the given parent. Each logger name must be globally unique. If a Logger is given, its name is used and the given Logger is wrapped by the returned PdsLogger.

  • parent (str, logger, or PdsLogger, optional) – The parent name or parent logger for this new logger. By default, the logger defined by set_default_parent() is used. Use “” for no parent.

  • levels (dict, optional) – A dictionary of level names and their values. These override or augment the default level values. Use a negative level value to replace the default name for a level; for example, {‘VERY_BAD’: -CRITICAL} will cause “CRITICAL” errors to appear in the log as “VERY_BAD” errors instead. The case of level names is ignored.

  • limits (dict, optional) – A dictionary indicating the upper limit on the number of messages to log as a function of level name.

  • roots (str, Path, FCPath, or list[str, Path, or FCPath], optional) – Character strings to suppress if they appear at the beginning of file paths. Used to reduce the length of log entries when, for example, every file path is in a single subdirectory tree on the volume.

  • level (int or str, optional) – The minimum level or level name for a record to enter the log. By default, this is the minimum logging level, HIDDEN + 1, unless this PdsLogger is being derived from an existing Logger of the same name, in which case it will match the existing Logger’s level.

  • timestamps (bool, optional) – True to include timestamps in the log records. By default, this is True unless this PdsLogger is being derived from an existing Logger of the same name, in which case it is False.

  • digits (int, optional) – Number of fractional digits in the seconds field of the timestamp.

  • lognames (bool, optional) – True to include the name of the logger in the log records. By default, this is True unless this PdsLogger is being derived from an existing Logger of the same name, in which case it is False.

  • pid (bool, optional) – True to include the process ID in each log record.

  • indent (bool, optional) – True to include a sequence of dashes in each log record to provide a visual indication of the depth in a logging hierarchy. By default, this is True unless this PdsLogger is being derived from an existing Logger of the same name, in which case it is False.

  • levelnames (bool, optional) – True to include the name of the log level, e.g., “ERROR”, in the log records. By default, this is True unless this PdsLogger is being derived from an existing Logger of the same name, in which case it is False.

  • blanklines (bool, optional) – True to include a blank line in log files after a sub-logger is closed.

  • colors (bool, optional) – True to color-code any log files generated, for Macintosh only.

  • maxdepth (int, optional) – Maximum depth of the logging hierarchy, needed to prevent unlimited recursion.

Raises:

ValueError – If the log name is already in use of if the level name associated with a limit is unknown.

exception pdslogger.LoggerError(message, filepath='', *, force=False, level='error', stacktrace=False)[source]

For an exception of this class, logger.exception() will write a message into the log with the user-specified level.

Unless requested, no stacktrace will be included in the log.

__init__(message, filepath='', *, force=False, level='error', stacktrace=False)[source]

Constructor.

Parameters:

  • message (str or Exception) – Text of the message as a string. If an Exception object is provided, the message is derived from this error.

  • filepath (str, Path, or FCPath, optional) – File path to include in the message. If not specified, the filepath appearing in the call to exception() will be used.

  • force (bool, optional) – True to force the message to be logged even if the logging level is above the level of “warning”.

  • level (int or str, optional) – The level or level name for a record to enter the log.

  • stacktrace (bool, optional) – True to include a stacktrace in the log.

__str__()[source]

Return str(self).

pdslogger.file_handler(logpath, level=2, rotation='none', suffix='')[source]

File handler for a PdsLogger.

Parameters:

  • logath (str, Path, or FCPath) – The path to the log file.

  • level (int or str) – The minimum logging level at which to log messages; either an int or one of “critical”, “error”, “warning”, “info”, “debug”, or “hidden”.

  • rotation (str, optional) –

    Log file rotation method, one of:

    • ”none”: No rotation; append to an existing log of the same name.

    • ”number”: Move an existing log file to one of the same name with a version number (“_v” followed by an integer suffix of at least three digits) before the extension.

    • ”midnight”: Each night at midnight, append the date to the log file name and start a new log.

    • ”ymd”: Append the current date in the form “_yyyy-mm-dd” to each log file name (before the “.log” extension).

    • ”ymdhms”: Append the current date and time in the form “_yyyy-mm-ddThh-mm-ss” to each log file name (before the “.log” extension).

    • ”replace”: Replace this new log with any pre-existing log of the same name.

  • suffix (str, optional) – Append this suffix string to the log file name after any date and before the extension.

Returns:

FileHandler with the specified properties.

Return type:

logging.FileHandler

Raises:

  • ValueError – Invalid rotation.

  • KeyError – Invalid level string.

pdslogger.info_handler(parent, name='INFO.log', *, rotation='none')[source]

Quick creation of an “info”-level file handler.

Parameters:

  • parent (str, Path, or FCPath) – Path to the parent directory.

  • name (str, optional) – Basename of the file handler.

  • rotation (str, optional) –

    Log file rotation method, one of:

    • ”none”: No rotation; append to an existing log of the same name.

    • ”number”: Move an existing log file to one of the same name with a version number (“_v” followed by an integer suffix of at least three digits) before the extension.

    • ”midnight”: Each night at midnight, append the date to the log file name and start a new log.

    • ”ymd”: Append the current date in the form “_yyyy-mm-dd” to each log file name (before the “.log” extension).

    • ”ymdhms”: Append the current date and time in the form “_yyyy-mm-ddThh-mm-ss” to each log file name (before the “.log” extension).

    • ”replace”: Replace this new log with any pre-existing log of the same name.

Returns:

FileHandler with the specified properties.

Return type:

logging.FileHandler

Raises:

ValueError – Invalid rotation.

pdslogger.warning_handler(parent, name='WARNINGS.log', *, rotation='none')[source]

Quick creation of a “warning”-level file handler.

Parameters:

  • parent (str, Path, or FCPath) – Path to the parent directory.

  • name (str, optional) – Basename of the file handler.

  • rotation (str, optional) –

    Log file rotation method, one of:

    • ”none”: No rotation; append to an existing log of the same name.

    • ”number”: Move an existing log file to one of the same name with a version number (“_v” followed by an integer suffix of at least three digits) before the extension.

    • ”midnight”: Each night at midnight, append the date to the log file name and start a new log.

    • ”ymd”: Append the current date in the form “_yyyy-mm-dd” to each log file name (before the “.log” extension).

    • ”ymdhms”: Append the current date and time in the form “_yyyy-mm-ddThh-mm-ss” to each log file name (before the “.log” extension).

    • ”replace”: Replace this new log with any pre-existing log of the same name.

Returns:

FileHandler with the specified properties.

Return type:

logging.FileHandler

Raises:

ValueError – Invalid rotation.

pdslogger.error_handler(parent, name='ERRORS.log', *, rotation='none')[source]

Quick creation of an “error”-level file handler.

Parameters:

  • parent (str, Path, or FCPath) – Path to the parent directory.

  • name (str, optional) – Basename of the file handler.

  • rotation (str, optional) –

    Log file rotation method, one of:

    • ”none”: No rotation; append to an existing log of the same name.

    • ”number”: Move an existing log file to one of the same name with a version number (“_v” followed by an integer suffix of at least three digits) before the extension.

    • ”midnight”: Each night at midnight, append the date to the log file name and start a new log.

    • ”ymd”: Append the current date in the form “_yyyy-mm-dd” to each log file name (before the “.log” extension).

    • ”ymdhms”: Append the current date and time in the form “_yyyy-mm-ddThh-mm-ss” to each log file name (before the “.log” extension).

    • ”replace”: Replace this new log with any pre-existing log of the same name.

Returns:

FileHandler with the specified properties.

Return type:

logging.FileHandler

Raises:

ValueError – Invalid rotation.

pdslogger.stream_handler(level=2, stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)[source]

Stream handler, e.g., for directing logged messages to the terminal.

Parameters:

  • level (int or str, optional) – The minimum logging level at which to log messages; either an int or one of “critical”, “error”, “warning”, “info”, “debug”, or “hidden”.

  • stream (stream, optional) – An output stream, defaulting to the terminal via sys.stdout.