Logging

Has Log

class HasLog

Bases: sims4communitylib.mod_support.has_mod_identity.HasModIdentity

An inheritable class that will add a log and mod identity to a class.

log

The log for instances of the class.

Note

It uses the mod_identity and log_identifier when logging.

Returns:An instance of CommonLog
Return type:CommonLog
log_identifier

A string identifier for the log used by instances of the class.

Note

This is the text that will appear when logging messages.

Returns:The identifier of the log
Return type:str
mod_identity

The identity of the mod that owns this property

Warning

Override this property with the CommonModIdentity of your mod.

This is a MUST override to allow for proper Exception Handling and Logging!

Returns:An instance of CommonModIdentity
Return type:CommonModIdentity
Raises:NotImplementedError – Thrown when the property is not implemented.

Has Class Log

class HasClassLog

Bases: sims4communitylib.mod_support.has_class_mod_identity.HasClassModIdentity, sims4communitylib.logging.has_log.HasLog

An inheritable class that will add a log and mod identity to a class.

Note

This class inherits from HasLog and may be used as an alternative to it.

classmethod get_log()

Retrieve a log for the class.

Note

This function uses the get_mod_identity() and get_log_identifier() functions when logging.

Returns:An instance of CommonLog
Return type:CommonLog
classmethod get_log_identifier()

A string identifier for the log of the class.

Note

This is the text that will appear when logging messages.

Returns:The identifier for the log
Return type:str
classmethod get_mod_identity()

Retrieve the identity of the mod that owns the class.

Warning

Override this function with the CommonModIdentity of your mod.

This is a MUST override to allow for proper Exception Handling and Logging!

Returns:An instance of CommonModIdentity
Return type:CommonModIdentity
Raises:NotImplementedError – Thrown when the function is not implemented.
log

The log for instances of the class.

Note

It uses the mod_identity and log_identifier when logging.

Returns:An instance of CommonLog
Return type:CommonLog
log_identifier

A string identifier for the log used by instances of the class.

Note

This is the text that will appear when logging messages.

Returns:The identifier of the log
Return type:str
mod_identity

The identity of the mod that owns this property

Warning

Override this property with the CommonModIdentity of your mod.

This is a MUST override to allow for proper Exception Handling and Logging!

Returns:An instance of CommonModIdentity
Return type:CommonModIdentity
Raises:NotImplementedError – Thrown when the property is not implemented.

Log Utils

class CommonLogUtils

Bases: object

Utilities for retrieving the paths used for logging.

static get_exceptions_file_path(mod_identifier)

Retrieve the file path to the Exceptions file used for logging error messages.

Parameters:mod_identifier (Union[str, CommonModIdentity]) – The name or identity of the mod requesting the file path.
Returns:An str file path to the Exceptions file.
Return type:str
static get_message_file_path(mod_identifier)

Retrieve the file path to the Messages file used for logging info/debug messages.

Parameters:mod_identifier (Union[str, CommonModIdentity]) – The name of the mod requesting the file path.
Returns:An str file path to the Messages file.
Return type:str
static get_old_exceptions_file_path(mod_identifier)

Retrieve the file path to the Old Exceptions file used as the overflow when the main Exception file becomes too large.

Parameters:mod_identifier (Union[str, CommonModIdentity]) – The name or identity of the mod requesting the file path.
Returns:An str file path to the Old Exceptions file.
Return type:str
static get_old_message_file_path(mod_identifier)

Retrieve the file path to the Old Messages file used as the overflow when the main Messages file becomes too large.

Parameters:mod_identifier (Union[str, CommonModIdentity]) – The name of the mod requesting the file path.
Returns:An str file path to the Old Messages file.
Return type:str
static get_sims_documents_location_path()

Retrieve the full path of the folder ‘DocumentsElectronic ArtsThe Sims 4’

Returns:The file path to ‘DocumentsElectronic ArtsThe Sims 4’ folder.
Return type:str

Common Log

class CommonLog(mod_identifier, log_name)

Bases: object

A class used to log messages.

Parameters:
  • mod_identifier (Union[str, CommonModIdentity]) – The name or identity of the Mod that owns the log.
  • log_name (str) – The name of the log, used when enabling/disabling logs via commands
debug(message)

Log a message with message type DEBUG.

Parameters:message (str) – The message to log.
disable()

Disable the log

enable()

Enable the log

enabled

Determine whether the log is enabled or not.

Note

All logs are disabled by default.

Returns:True, if the log is enabled. False, if the log is disabled.
Return type:bool
error(message, message_type=CommonMessageType.ERROR, exception=None, throw=True)

Log an error message with the specified message type

Parameters:
  • message (str) – The message to log.
  • message_type (CommonMessageType, optional) – The message type of the error message. Default is CommonMessageType.ERROR.
  • exception – The exception that occurred.
  • throw (bool, optional) – If set to True, the exception will be rethrown.
format(*args, message_type=CommonMessageType.DEBUG, update_tokens=True, **kwargs)

Log a non-descriptive message containing pformatted arguments and keyword arguments with the specified message type.

Parameters:
  • message_type (CommonMessageType, optional) – The MessageType of the logged message. Default is CommonMessageType.DEBUG.
  • update_tokens (bool, optional) – If set to True, when an arg or kwarg value is a Sim or SimInfo, it will be converted to their name before format occurs. Default is True.
  • args (Any) – Arguments to format into the message.
  • kwargs (Any) – Keyword Arguments to format into the message.
format_error(*args, exception=None, throw=True, update_tokens=True, **kwargs)

Log a non-descriptive error message containing pformatted arguments and keyword arguments.

Parameters:
  • exception (Exception, optional) – The exception that occurred.
  • throw (bool, optional) – If set to True, the exception will be rethrown.
  • update_tokens (bool, optional) – If set to True, when an arg or kwarg value is a Sim or SimInfo, it will be converted to their name before format occurs. Default is True.
  • args (Any) – Arguments to format into the message.
  • kwargs (Any) – Keyword Arguments to format into the message.
format_error_with_message(message, *args, exception=None, throw=True, update_tokens=True, **kwargs)

Log an error message containing pformatted arguments and keyword arguments.

Parameters:
  • message (str) – The message to log.
  • exception (Exception, None) – The exception that occurred. Default is None.
  • throw (bool, optional) – If set to True, the exception will be rethrown. Default is True.
  • update_tokens (bool, optional) – If set to True, when an arg or kwarg value is a Sim or SimInfo, it will be converted to their name before format occurs. Default is True.
  • args (Any) – Arguments to format into the message.
  • kwargs (Any) – Keyword Arguments to format into the message.
format_info(*args, update_tokens=True, **kwargs)

Log a non-descriptive message containing pformatted arguments and keyword arguments with message type INFO.

Parameters:
  • update_tokens (bool, optional) – If set to True, when an arg or kwarg value is a Sim or SimInfo, it will be converted to their name before format occurs. Default is True.
  • args (Any) – Arguments to format into the message.
  • kwargs (Any) – Keyword Arguments to format into the message.
format_info_with_message(message, *args, update_tokens=True, **kwargs)

Log a message containing pformatted arguments and keyword arguments with message type INFO.

Parameters:
  • message (str) – The message to log.
  • update_tokens (bool, optional) – If set to True, when an arg or kwarg value is a Sim or SimInfo, it will be converted to their name before format occurs. Default is True.
  • args (Any) – Arguments to format into the message.
  • kwargs (Any) – Keyword Arguments to format into the message.
format_warn(*args, update_tokens=True, **kwargs)

Log a non-descriptive message containing pformatted arguments and keyword arguments with message type WARN.

Parameters:
  • update_tokens (bool, optional) – If set to True, when an arg or kwarg value is a Sim or SimInfo, it will be converted to their name before format occurs. Default is True.
  • args (Any) – Arguments to format into the message.
  • kwargs (Any) – Keyword Arguments to format into the message.
format_warn_with_message(message, *args, update_tokens=True, **kwargs)

Log a message containing pformatted arguments and keyword arguments with message type WARN.

Parameters:
  • message (str) – The message to log.
  • update_tokens (bool, optional) – If set to True, when an arg or kwarg value is a Sim or SimInfo, it will be converted to their name before format occurs. Default is True.
  • args (Any) – Arguments to format into the message.
  • kwargs (Any) – Keyword Arguments to format into the message.
format_with_message(message, *args, message_type=CommonMessageType.DEBUG, update_tokens=True, **kwargs)

Log a message containing pformatted arguments and keyword arguments with the specified message type.

Parameters:
  • message (str) – The message to log.
  • message_type (CommonMessageType, optional) – The type of message being logged. Default is CommonMessageType.DEBUG.
  • update_tokens (bool, optional) – If set to True, when an arg or kwarg value is a Sim or SimInfo, it will be converted to their name before format occurs. Default is True.
  • args (Any) – Arguments to format into the message.
  • kwargs (Any) – Keyword Arguments to format into the message.
info(message)

Log a message with message type INFO.

Parameters:message (str) – The message to log.
log_stack()

Log the current stack trace and the calling frames

Note

The best use for this is to find the path of invocation to the location this function is called at.

mod_name

The name of the mod that owns the log.

Returns:The name of the mod that owns the log
Return type:str
name

The identifier of this log.

Returns:A string identifier.
Return type:str
warn(message)

Log a message with message type WARN.

Parameters:message (str) – The message to log.

Log Registry

class CommonLogRegistry

Bases: sims4communitylib.services.common_service.CommonService

Used to register logs.

Note

To register your own logs, please use get() to create a CommonLogRegistry (CommonLogRegistry.get()).

Example Usage:
# Register the log, Logs will appear in a file titled "MOD_NAME_Messages.txt" and messages logged using this log will be prefixed with "s4cl_log_name"
log = CommonLogRegistry.get().register_log('MOD_NAME', 's4cl_log_name')
# Enable the log, if not enabled, messages will not be logged.
log.enable()
# Log a message
log.debug('Printing a message to the log.')
# Disable the log
log.disable()

# The MOD_NAME_Messages.txt file will contain the "Printing a message to the log." message.

Note

Available Commands:

  • s4clib.enable_log or s4clib.enablelog
  • s4clib.disable_log or s4clib.disablelog
  • s4clib.disable_all_logs or s4clib.disablealllogs
  • s4clib.logs
disable_all_logs(mod_identifier=None)

Disable all logs from logging

Parameters:mod_identifier (Union[str, CommonModIdentity], optional) – The name or identity of the mod to disable logs for. Default is None.
Returns:True, if successful. False, if not.
Return type:bool
disable_logs(log_name, mod_identifier=None)

Disable all logs with the specified name.

Parameters:
  • log_name (str) – The name of the logs to disable.
  • mod_identifier (Union[str, CommonModIdentity], optional) – The name or identity of the mod to disable logs for. Default is None.
Returns:

True, if successful. False, if not.

Return type:

bool

enable_logs(log_name, mod_identifier=None)

Enable all logs with the specified name.

Parameters:
  • log_name (str) – The name of the logs to enable.
  • mod_identifier (Union[str, CommonModIdentity], optional) – The name or identity of the mod the log belongs to. Default is None.
Returns:

True, if successful. False, if not.

Return type:

bool

get_registered_log_names()

Retrieve the names of all registered logs.

Parameters:mod_identifier (Union[str, CommonModIdentity], optional) – The name or identifier of the mod the log is registered for. Default is None.
Returns:A collection of registered logs.
Return type:List[str]
log_exists(log_name, mod_identifier=None)

Determine if logs exist with the specified name.

Parameters:
  • log_name (str) – The name of the log to locate.
  • mod_identifier (Union[str, CommonModIdentity], optional) – The name or identity of the mod the log belongs to. Default is None.
Returns:

True, if a handler exists with the specified name.

Return type:

bool

register_log(mod_identifier, log_name)

Create and register a log with the specified name.

Note

If log_name matches the name of a Log already registered, that log will be returned rather than creating a new Log.

Parameters:
  • mod_identifier (Union[str, CommonModIdentity]) – The name or identifier of the mod the log is registered for.
  • log_name (str) – The name of the log.
Returns:

An object of type CommonLog

Return type:

CommonLog

Message Type

class CommonMessageType

Bases: sims4communitylib.enums.enumtypes.common_int.CommonInt

Message types for use when logging.

DEBUG = 0
ERROR = 1
INFO = 2
WARN = 3