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 message identifier 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.
-
verbose_log
¶ The verbose log for instances of the class.
Note
It uses the mod_identity and verbose_log_identifier when logging.
Note
This log can be used to log extra details that you don’t want to appear when using the non verbose log.
Returns: An instance of CommonLog Return type: CommonLog
-
verbose_log_identifier
¶ A string identifier for the verbose log used by instances of the class.
Note
This is the message identifier that will appear when logging messages.
Returns: The identifier of the verbose log Return type: str
-
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()
andget_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.
-
classmethod
get_verbose_log
()¶ Retrieve a verbose log for the class.
Note
This function uses the
get_mod_identity()
andget_verbose_log_identifier()
functions when logging.Note
This log can be used to log extra details that you don’t want to appear when using the non verbose log.
Returns: An instance of CommonLog Return type: CommonLog
-
classmethod
get_verbose_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
-
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 message identifier 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.
-
verbose_log
¶ The verbose log for instances of the class.
Note
It uses the mod_identity and verbose_log_identifier when logging.
Note
This log can be used to log extra details that you don’t want to appear when using the non verbose log.
Returns: An instance of CommonLog Return type: CommonLog
-
verbose_log_identifier
¶ A string identifier for the verbose log used by instances of the class.
Note
This is the message identifier that will appear when logging messages.
Returns: The identifier of the verbose log Return type: str
-
classmethod
Log Utils¶
-
class
CommonLogUtils
¶ Bases:
object
Utilities for retrieving the paths used for logging.
-
static
get_exceptions_file_path
(mod_identifier, custom_file_path=None)¶ 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.
- custom_file_path (str, optional) – A custom file path relative to The Sims 4 folder. Example: Value is ‘fake_path/to/directory’, the final path would be ‘The Sims 4/fake_path/to_directory’. Default is None.
Returns: An str file path to the Exceptions file.
Return type: str
-
static
get_message_file_path
(mod_identifier, custom_file_path=None)¶ 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.
- custom_file_path (str, optional) – A custom file path relative to The Sims 4 folder. Example: Value is ‘fake_path/to/directory’, the final path would be ‘The Sims 4/fake_path/to_directory’. Default is None.
Returns: An str file path to the Messages file.
Return type: str
-
static
get_mod_data_location_path
()¶ Retrieve the full path of the folder ‘DocumentsElectronic ArtsThe Sims 4Modsmod_data’
Returns: The file path to ‘DocumentsElectronic ArtsThe Sims 4Modsmod_data’ folder. Return type: str
-
static
get_mod_logs_location_path
()¶ Retrieve the full path of the folder ‘DocumentsElectronic ArtsThe Sims 4mod_logs’
Returns: The file path to ‘DocumentsElectronic ArtsThe Sims 4mod_logs’ folder. Return type: str
-
static
get_mods_location_path
() → str¶ get_sims_mods_location_path()
Retrieve the full path of the folder ‘DocumentsElectronic ArtsThe Sims 4Mods’
Returns: The file path to ‘DocumentsElectronic ArtsThe Sims 4Mods’ folder. Return type: str
-
static
get_old_exceptions_file_path
(mod_identifier, custom_file_path=None)¶ 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.
- custom_file_path (str, optional) – A custom file path relative to The Sims 4 folder. Example: Value is ‘fake_path/to/directory’, the final path would be ‘The Sims 4/fake_path/to_directory’. Default is None.
Returns: An str file path to the Old Exceptions file.
Return type: str
-
static
get_old_message_file_path
(mod_identifier, custom_file_path=None)¶ 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.
- custom_file_path (str, optional) – A custom file path relative to The Sims 4 folder. Example: Value is ‘fake_path/to/directory’, the final path would be ‘The Sims 4/fake_path/to_directory’. Default is None.
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
-
static
Common Log¶
-
class
CommonLog
(mod_identifier, log_name, custom_file_path=None)¶ 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
- custom_file_path (str, optional) – A custom file path relative to The Sims 4 folder. Example: Value is ‘fake_path/to/directory’, the final path would be ‘The Sims 4/fake_path/to_directory’. Default is None.
-
debug
(message)¶ Log a message with message type DEBUG.
Parameters: message (str) – The message to log.
-
disable
()¶ Disable the log
-
disable_logging_extra_sim_details
()¶ Disable the logging of extra Sim details when logging a Sim, such as Sim Type and Sim Current Type.
-
enable
(message_types=(CommonMessageType.WARN, CommonMessageType.DEBUG, CommonMessageType.INFO), enable_extra_sim_details=False)¶ Enable the log or specific types of logs.
Parameters: - message_types – The types of messages to enable for logging. Default message types are Info, Debug, and Warn.
- enable_logging_extra_sim_details (bool, optional) – If True, when a Sim is being logged, extra Sim details, such as Sim Type and Current Sim Type, will be logged in addition to their name and id. If False, only their name and id will be logged. Default is False.
Rtype message_types: Tuple[CommonMessageTypes], optional
-
enable_logging_extra_sim_details
()¶ Enable the logging of extra Sim details, when logging a Sim, such as Sim Type and Sim Current Type.
-
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, stack_trace=None)¶ 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 (Exception, optional) – The exception that occurred. Default is None.
- stack_trace (List[str], optional) – The stack trace leading to the exception, if not supplied, a stack trace will be gathered for you. Default is None.
- throw (bool, optional) – If set to True, the exception will be rethrown.
-
exceptions_file_path
¶ The file path exceptions are logged to.
Returns: The file path exceptions are logged to. Return type: str
-
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, stack_trace=None, **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.
- stack_trace (List[str], optional) – The stack trace leading to the exception, if not supplied, a stack trace will be gathered for you. Default is None.
- 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, stack_trace=None, **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.
- stack_trace (List[str], optional) – The stack trace leading to the exception, if not supplied, a stack trace will be gathered for you. Default is None.
- 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.
-
is_enabled
(message_type)¶ Determine if a message type is enabled for logging.
Parameters: message_type (CommonMessageType) – The type of messages to check for allowance. Returns: True, if the specified message type is enabled for logging. False, if not. Return type: bool
-
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.
-
messages_file_path
¶ The file path messages are logged to.
Returns: The file path messages are logged to. Return type: str
-
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_all_logs
(mod_identifier=None)¶ Enable all logs from logging
Parameters: mod_identifier (Union[str, CommonModIdentity], optional) – The name or identity of the mod to enable 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, custom_file_path: str=None)¶ 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.
- custom_file_path (str, optional) – A custom file path relative to The Sims 4 folder. Example: Value is ‘fake_path/to/directory’, the final path would be ‘The Sims 4/fake_path/to_directory’. Default is None.
Returns: An object of type CommonLog
Return type: