Logging

A class to handle logging messages with different verbosity levels.

__init__(logger_settings)

Initializes the logger with configuration settings.

The structure of logger_settings is as follows: { "logfile_name": Optional[str], # The name of the log file. If None, no file logging will be done. "file_verbosity": Optional[str], # Verbosity level for file logging "console_verbosity": Optional[str], # Verbosity level for console logging "max_lines": Optional[int], # Maximum number of lines to keep in the log file "log_process_id": Optional[bool], # If True, include the process ID in log messages. Defaults to False. "log_thread_id": Optional[bool], # If True, include the thread ID in log messages. Defaults to False. }

Parameters:

Name	Type	Description	Default
logger_settings	Optional[dict]	A dictionary containing logger settings	required

clear_fatal_error()

Clear a previously logged fatal error.

Returns:

Name	Type	Description
result	bool	True if the file was deleted, False if it did not exist.

clear_notifiable_issue(entity, issue_type)

Clear a notifiable issue.

Parameters:

Name	Type	Description	Default
entity	str	The entity reporting the issue (e.g., "Device 123", "Module", etc.)	required
issue_type	str	A brief description of the issue (e.g. "Offline").	required

Returns:

Name	Type	Description
result	bool	True if the issue was found and cleared, False otherwise.

get_fatal_error()

Returns True if a fatal error was previously reported, false otherwise.

initialise_settings(logger_settings)

Set / reset the logger configuration settings. See the init() method for the structure of logger_settings.

Parameters:

Name	Type	Description	Default
logger_settings	Optional[dict]	A dictionary containing logger settings.	required

log_fatal_error(message, report_stack=False, calling_function=None)

Log a fatal error, send an email if configured to so and then exit the program.

Parameters:

Name	Type	Description	Default
message	str	The error message to log.	required
report_stack	Optional[bool]	If True, include the stack trace in the log message.	False
calling_function	Optional[str]	The name of the function that called this method, if known. If None, the calling function will be determined automatically.	None

Raises:

Type	Description
SystemExit	Exits the program with a status code of 1 after logging the fatal error.

log_message(message, verbosity='summary')

Writes a log message to the console and/or a file based on verbosity settings.

Parameters:

Name	Type	Description	Default
message	str	The message to log.	required
verbosity	str	The verbosity level for the message. Must be one of "none", "error", "warning", "summary", "detailed", "debug", or "all".	'summary'

Raises:

Type	Description
ValueError	If an invalid verbosity level is provided.

register_email_settings(email_settings)

Registers email settings for sending emails.

Use the SCConfigManager.get_email_settings() method to get a dictionary containing the email settings. Otherwise, you can pass a dictionary directly to this method with these keys: SendEmailsTo: str, the email address to send emails to SMTPServer: str, the SMTP server address SMTPPort: int, the SMTP server port (optional, defaults to 587) SMTPUsername: str, the username for the SMTP server SMTPPassword: str, the password for the SMTP server (preferably an App Password) SubjectPrefix: str, a prefix for email subjects (optional, default to None)

Parameters:

Name	Type	Description	Default
email_settings	Optional[dict]	A dictionary containing email settings. If empty or None, no email settings will be registered.	required

Raises:

Type	Description
TypeError	If email_settings is not a dictionary.
ValueError	If any required keys are missing from the email_settings dictionary.

report_notifiable_issue(entity, issue_type, send_delay, message)

Log a notifiable issue and send an email if configured to do so.

When a new combination of entity and issue_type is reported, it will be noted including the current timestamp. If one or more issues of the same type are reported for the same entity at least send_delay seconds after the last notification, an email will be sent including the first time this issue was reported. Subsequent issues of the same type for the same entity will be ignored until the issue is cleared.

Parameters:

Name	Type	Description	Default
entity	str	The entity reporting the issue (e.g., "Device 123", "Module", etc.)	required
issue_type	str	A brief description of the issue (e.g. "Offline").	required
send_delay	int	The delay in seconds before sending the email	required
message	str	The issue message to log and email.	required

Returns:

Name	Type	Description
result	bool	True if the email was sent, False otherwise.

send_email(subject, body, test_mode=False)

Sends an email using the SMTP server previously specified in register_email_settings().

Parameters:

Name	Type	Description	Default
subject	str	The subject of the email.	required
body	str	The body of the email. This argument can be one of 4 things: 1. A string containing the HTML body of the email 2. A string or Path containing the path to an HTML file to read the body from 3. A string containing the text body of the email 4. A string or Path containing the path to an text file to read the body from	required
test_mode	bool	If True, the email will not be sent, but a message will be logged indicating that the email would have been sent. Defaults to False.	False

Returns:

Name	Type	Description
result	bool	True if the email was sent successfully, False otherwise.

set_fatal_error(message)

Create a fatal error tracking file and write the message to it.

Parameters:

Name	Type	Description	Default
message	str	The error message to write to the fatal error file.	required

trim_logfile()

Trims the log file to the maximum number of lines specified.