lezargus.library.logging module#

Error, warning, and logging functionality pertinent to Lezargus.

Use the functions here when logging or issuing errors or other information.

exception lezargus.library.logging.AccuracyWarning[source]#

Bases: LezargusWarning

A warning for inaccurate results.

This warning is used when some elements of the simulation or data reduction would yield less than desireable results. In general, a brief description on how bad the accuracy issue is, is desired. We trust that, for the most part, a user will take the messages into account.

exception lezargus.library.logging.AlgorithmWarning[source]#

Bases: LezargusWarning

A warning for issues with algorithms or methods.

This warning should be used when something went wrong with an algorithm. Examples include when continuing would lead to inaccurate results, or when alternative methods must be used, or when predicted execution time would be slow. This warning should be used in conjunction with other warnings to give a full picture of the issue.

exception lezargus.library.logging.ArithmeticalError[source]#

Bases: LezargusError

An error to be used when undefined arithmetic operations are attempted.

This error is to be used when any arithmetic functions are being attempted which do not have a definition. The most common use case for this error is doing operations on incompatible Lezargus containers. Note, it is named ArithmeticalError to avoid a name conflict with the built-in ArithmeticError.

class lezargus.library.logging.ColoredLogFormatter(message_format: str, date_format: str, color_hex_dict: dict[slice(<class 'int'>, <class 'str'>, None)] | None = None)[source]#

Bases: Formatter

Use this formatter to have colors.

message_format#

The message format, passed directly to the logger formatter after the color keys are added.

Type:

str

date_format#

The date format, passed directly to the logger formatter.

Type:

str

color_formatting#

The formatting for the color.

Type:

dict

__convert_color_hex_to_ansi_escape() str#

Convert a hex code to a ANSI escape code.

Parameters:

color_hex (str) – The HEX code of the color, including the # symbol.

Returns:

color_ansi_escape – The ANSI escape code for the color.

Return type:

str

__init__(message_format: str, date_format: str, color_hex_dict: dict[slice(<class 'int'>, <class 'str'>, None)] | None = None) None[source]#

Initialize the color formatter.

Parameters:
  • message_format (str) – The message format, passed directly to the logger formatter after the color keys are added.

  • date_format (str) – The date format, passed directly to the logger formatter.

  • color_hex_dict (dict, default = None) – The dictionary containing the color pairings between logging levels and its actual color. It should be a {level_number:hex_color} dictionary.

Return type:

None

format(record: LogRecord) str[source]#

Format a log record.

The name of this function cannot be helped as it is required for the Python logging module.

Parameters:

record (LogRecord) – The record to format.

Returns:

formatted_record – The formatted string.

Return type:

str

exception lezargus.library.logging.CommandLineError[source]#

Bases: LezargusError

An error used for an error with the command-line.

This error is used when the entered command-line command or its options are not correct.

exception lezargus.library.logging.ConfigurationError[source]#

Bases: LezargusError

An error used for an error with the configuration file.

This error is to be used when the configuration file or parameters are wrong. There is a specific expectation for how configuration files and configuration parameters are structures are defined.

exception lezargus.library.logging.ConfigurationWarning[source]#

Bases: LezargusWarning

A warning for inappropriate configurations.

This warning is to be used when the configuration file is wrong. There is a specific expectation for how configuration files and configuration parameters are structures are defined.

exception lezargus.library.logging.DataLossWarning[source]#

Bases: LezargusWarning

A warning to caution on data loss.

This warning is used when something is being done which might result in a loss of important data, for example, because a file is not saved or only part of a data file is read. This also occurs when possibly external files are trying to be deleted or otherwise modified.

exception lezargus.library.logging.DevelopmentError[source]#

Bases: LezargusBaseError

An error used for a development error.

This is an error where the development of Lezargus is not correct and something is not coded based on the expectations of the software itself. This is not the fault of the user.

exception lezargus.library.logging.DirectoryError[source]#

Bases: LezargusError

An error used for directory issues.

If there are issues with directories, use this error.

exception lezargus.library.logging.ElevatedError[source]#

Bases: LezargusError

An error used when elevating warnings or errors to critical level.

Only to be used when elevating via the configuration property.

exception lezargus.library.logging.ExpectedCaughtError[source]#

Bases: LezargusBaseError

An error used when raising an error to be caught later is needed.

This error should only be used when an error is needed to be raised which will be caught later. The user should not see this error at all as any time it is used, it should be caught. This name also conveniently provides an obvious and unique error name.

exception lezargus.library.logging.FileError[source]#

Bases: LezargusError

An error used for file issues.

If there are issues with files, use this error. This error should not be used in cases where the problem is because of an incorrect format of the file (other than corruption).

exception lezargus.library.logging.FileWarning[source]#

Bases: LezargusWarning

A warning used for file and permission issues which are not fatal.

If there are issues with files, use this warning. However, unlike the error version FileError, this should be used when the file issue is a case considered and is recoverable. This warning should not be used in cases where the problem is because of an incorrect format of the file (other than corruption).

exception lezargus.library.logging.InputError[source]#

Bases: LezargusError

An error used for issues with input parameters or data.

This is the error to be used when the inputs to a function are not valid and do not match the expectations of that function.

exception lezargus.library.logging.InputWarning[source]#

Bases: LezargusWarning

A warning for a weird input.

This warning is used when the input of a function or a field is not expected, but may be able to be handled.

exception lezargus.library.logging.LezargusBaseError[source]#

Bases: BaseException

The base inheriting class which for all Lezargus errors.

This is for exceptions that should never be caught and should bring everything to a halt.

exception lezargus.library.logging.LezargusError[source]#

Bases: Exception

The main inheriting class which all Lezargus errors use as their base.

This is done for ease of error handling and is something that can and should be managed.

exception lezargus.library.logging.LezargusWarning[source]#

Bases: UserWarning

The main inheriting class which all Lezargus warnings use as their base.

The base warning class which all of the other Lezargus warnings are derived from.

exception lezargus.library.logging.LogicFlowError[source]#

Bases: LezargusBaseError

An error used for an error in the flow of program logic.

This is an error to ensure that the logic does not flow to a point to a place where it is not supposed to. This is helpful in making sure changes to the code do not screw up the logical flow of the program.

exception lezargus.library.logging.MemoryFullWarning[source]#

Bases: LezargusWarning

A warning for when there is not enough volatile memory.

This warning is used when the program detects that the machine does not have enough memory to proceed with a given process and so it tries an alternative method to do a similar calculation. We use the name MemoryFullWarning to avoid a name collision with MemoryWarning and to be a little more specific about what the issue is.

exception lezargus.library.logging.NotSupportedError[source]#

Bases: LezargusBaseError

An error used for something which is beyond the scope of work.

This error is to be used when whatever procedure is expected will not be done for a variety of reasons. Exactly why should be explained by the error itself.

For all other cases, the usages of warnings and other errors are probably better.

exception lezargus.library.logging.ReadOnlyError[source]#

Bases: LezargusError

An error used for problems with read-only files and variables.

If the file is read-only and it needs to be read, use FileError. This error is to be used only when variables or files are assumed to be read only, this error should be used to enforce that notion.

exception lezargus.library.logging.ToDoError[source]#

Bases: LezargusBaseError

An error used for something which is not yet implemented.

This is an error to be used when what is trying to be done is not yet implemented, but it is supposed to be. This type of error is rare and is used as a placeholder for actual functionality. This is an error because not all cases can be bypassed like other levels of logging, and, fundamentally, code is missing.

exception lezargus.library.logging.UndiscoveredError[source]#

Bases: LezargusBaseError

An error used for an unknown error.

This is an error used in cases where the source of the error has not been determined and so a more helpful error message or mitigation strategy cannot be devised.

exception lezargus.library.logging.WrongOrderError[source]#

Bases: LezargusError

An error used when things are done in the wrong order.

This error is used when something is happening out of the expected required order. This order being in place for specific publicly communicated reasons.

lezargus.library.logging.add_console_logging_handler(console: object = <_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>, log_level: int = 10, use_color: bool = True) None[source]#

Add a console stream handler to the logging infrastructure.

This differs from the main stream implementation in that a specific check is done to see if there is a logging handler which is specific to this console or console output. If there is, this function does not make a new one. This is helpful for Jupyter Notebooks.

Parameters:
  • console (Any) – The stream where the logs will write to.

  • log_level (int) – The logging level for this handler.

  • use_color (bool) – If True, use colored log messaged based on the configuration file parameters.

Return type:

None

lezargus.library.logging.add_file_logging_handler(filename: str, log_level: int = 10) None[source]#

Add a stream handler to the logging infrastructure.

Parameters:
  • filename (str) – The filename path where the log file will be saved to.

  • log_level (int) – The logging level for this handler.

Return type:

None

lezargus.library.logging.add_stream_logging_handler(stream: object, log_level: int = 10, use_color: bool = True) None[source]#

Add a stream handler to the logging infrastructure.

This function may not be used for most cases.

Parameters:
  • stream (Any) – The stream where the logs will write to.

  • log_level (int) – The logging level for this handler.

  • use_color (bool) – If True, use colored log messaged based on the configuration file parameters.

Return type:

None

lezargus.library.logging.critical(critical_type: LezargusError, message: str) None[source]#

Log a critical error and raise.

Use this for issues which are more serious than warnings and should raise/throw an exception. The main difference between critical and error for logging is that critical will also raise the exception as error will not and the program will attempt to continue.

This is a wrapper around the critical function to standardize it for Lezargus.

Parameters:
  • critical_type (LezargusError) – The class of the critical exception error which will be used and raised.

  • message (str) – The critical error message.

Return type:

None

lezargus.library.logging.debug(message: str) None[source]#

Log a debug message.

This is a wrapper around the debug function to standardize it for Lezargus.

Parameters:

message (str) – The debugging message.

Return type:

None

lezargus.library.logging.error(error_type: LezargusError, message: str, elevate: bool | None = None) None[source]#

Log an error message, do not raise.

Use this for issues which are more serious than warnings but do not result in a raised exception.

This is a wrapper around the error function to standardize it for Lezargus.

Parameters:
  • error_type (LezargusError) – The class of the error which will be used.

  • message (str) – The error message.

  • elevate (bool, default = None) – If True, always elevate the error to a critical issue. By default, use the configuration value.

Return type:

None

lezargus.library.logging.info(message: str) None[source]#

Log an informational message.

This is a wrapper around the info function to standardize it for Lezargus.

Parameters:

message (str) – The informational message.

Return type:

None

lezargus.library.logging.terminal() None[source]#

Terminal error function which is used to stop everything.

Parameters:

None

Return type:

None

lezargus.library.logging.update_global_minimum_logging_level(log_level: int = 10) None[source]#

Update the logging level of this module.

This function updates the minimum logging level which is required for a log record to be recorded. Handling each single logger handler is really unnecessary.

Parameters:

log_level (int, default = logging.DEBUG) – The log level which will be set as the minimum level.

Return type:

None

lezargus.library.logging.warning(warning_type: LezargusWarning, message: str, elevate: bool | None = None) None[source]#

Log a warning message.

This is a wrapper around the warning function to standardize it for Lezargus.

Parameters:
  • warning_type (LezargusWarning) – The class of the warning which will be used.

  • message (str) – The warning message.

  • elevate (bool, default = None) – If True, always elevate the warning to a critical issue. By default, use the configuration value.

Return type:

None