4. Advanced Programmatic Interface

4.1. Logging

class poptus.AbstractLogger(level)

It is intended that all tools in the POptUS universe use objects instantiated from concrete logger classes derived from this class to communicate to users all general, debug, warning, and error messages. In this way, this package helps implement and enforce a common, uniform logging interface across the universe.

Parameters:

level – Verbosity level of the logger

property level
Returns:

Logger’s verbosity level

abstractmethod log(caller, msg, level)

Log the given message if the logger’s verbosity level is greater than or equal to the given message’s level. The actual, final logged message, which includes the message provided by the caller, should not given any indication that the message indicates a warning or an error.

It is a logical error for the given message level to be LOG_LEVEL_NONE. Concrete loggers derived from this class are responsible for enforcing this.

Parameters:

  • caller – Name of calling code so that concrete logger can include this in actual logged message if so desired

  • msg – Message to potentially log

  • level – Message’s log level

abstractmethod warn(caller, msg)

Log given message in such a way that it is clear that it is transmitting a warning message to users. This is printed regardless of the logger’s verbosity level.

Parameters:

  • caller – Name of calling code so that concrete logger can include this in actual logged message if so desired

  • msg – Warning message to log

abstractmethod error(caller, msg)

Log given message in such a way that it is clear that it is transmitting an error message to users. This is printed regardless of the logger’s verbosity level.

Parameters:

  • caller – Name of calling code so that concrete logger can include this in actual logged message if so desired

  • msg – Error message to log

class poptus.StandardLogger(level=1)

A concrete POptUS logger class that is “standard” in the sense that many POptUS applications and users might choose to use this directly and because logging is done using standard output and error.

Parameters:

level – Verbosity level of the logger

log(caller, msg, level)

Print the given message to stdout if the logger’s verbosity level is greater than or equal to the given message’s level.

Parameters:

  • caller – Name of calling code for inclusion in actual logged message

  • msg – Message to potentially log

  • level – Message’s log level

warn(caller, msg)

Print the given message to stdout in such a way that it is clear that it is transmitting a warning message to users. This is printed regardless of the logger’s verbosity level.

Parameters:

  • caller – Name of calling code for inclusion in actual logged warning

  • msg – Warning message to log

error(caller, msg)

Print the given message to stderr in such a way that it is clear that it is transmitting an error message to users. This is printed regardless of the logger’s verbosity level.

Parameters:

  • caller – Name of calling code for inclusion in actual logged error

  • msg – Error message to log

property level
Returns:

Logger’s verbosity level

class poptus.FileLogger(filename, overwrite, level=1)

A concrete POptUS logger class that writes all log, warning, and error messages to the given file. Error messages are also written to standard error.

Parameters:

  • level – Verbosity level of the logger

  • filename – Name and path of file to write to

  • overwrite – If a file with the given name already exists, then it is overwritten if True or an error is raised if False.

property filename
Returns:

Name including path of file to which log information is written

log(caller, msg, level)

Write the given message to file if the logger’s verbosity level is greater than or equal to the given message’s level.

Parameters:

  • caller – Name of calling code for inclusion in actual logged message

  • msg – Message to potentially log

  • level – Message’s log level

warn(caller, msg)

Write the given message to file in such a way that it is clear that it is transmitting a warning message to users. This is printed regardless of the logger’s verbosity level.

Parameters:

  • caller – Name of calling code for inclusion in actual logged warning

  • msg – Warning message to log

error(caller, msg)

Print the given message to stderr and write to file in such a way that it is clear that it is transmitting an error message to users. This is printed regardless of the logger’s verbosity level.

Parameters:

  • caller – Name of calling code for inclusion in actual logged error

  • msg – Error message to log

property level
Returns:

Logger’s verbosity level