Logging¶

Has Log¶

class HasLog¶

Bases: HasModIdentity

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

property 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

property 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

property 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.

property 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

property 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: HasClassModIdentity, 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.

classmethod get_verbose_log()¶

Retrieve a verbose log for the class.

Note

This function uses the get_mod_identity() and get_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

property 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

property 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

property 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.

property 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

property 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

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:

A 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:

A 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()¶

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:

A 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:

A file path to the Old Messages file.

Return type:

str

static get_sims_4_game_version()¶

Retrieve the current game version of Sims 4.

Returns:: The current game version of Sims 4.
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, 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

Return type:: None

disable_logging_extra_sim_details()¶

Disable the logging of extra Sim details when logging a Sim, such as Sim Type and Sim Current Type.

Return type:: None

enable(message_types=(2, 3, 4), enable_logging_extra_sim_details=False)¶

Enable the log or specific types of logs.

Parameters:

message_types (Iterator[CommonMessageType]) – 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

Return type:

None

enable_logging_extra_sim_details()¶

Enable the logging of extra Sim details, when logging a Sim, such as Sim Type and Sim Current Type.

Return type:: None

property 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=1, 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.

property 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=3, 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=3, 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 :rtype: None

Note

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

property messages_file_path¶

The file path messages are logged to.

Returns:: The file path messages are logged to.
Return type:: str

property mod_name¶

The name of the mod that owns the log.

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

property 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: 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(mod_identifier=None)¶

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=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:

CommonLog

Message Type¶

class CommonMessageType(*args, **kwargs)¶

Bases: CommonInt

Message types for use when logging.

DEBUG = 3¶

ERROR = 1¶

INFO = 4¶

INVALID = 0¶

WARN = 2¶