Logging Tutorial - ColonolNutty/Sims4CommunityLibrary GitHub Wiki

In this tutorial we will cover the basics of logging.

How Do I Log A Message?

Create Logger

  • Before you can log a message, you must register (create) a log.
from example_mod.mod_info import ModInfo
from sims4communitylib.utils.common_log_registry import CommonLogRegistry

# Use the Mod Info of your own Mod here!
example_log: CommonLog = CommonLogRegistry.get().register_log(ModInfo.get_identity(), 'example_logger_of_logs')

Let's break this down:

  • CommonLogRegistry is the class that holds all logs, you use it to register, enable, and disable logs.
  • example_log is your Logger, use it to log messages.
  • example_logger_of_logs is the name of your Logger. This is the unique identifier of this logger and is used in conjunction with the in-game command s4clib.enable_log example_logger_of_logs.
  • ModInfo.get_identity() is the identity of your Mod, it is also used to tell S4CL where to log any messages. <mod_name>_Messages.txt

Log Messages:

Once you've created a logger, you can then invoke various functions on it. (For more details, check out the docs)

  • debug(str) is likely the most common function you will use, it is a basic function you may use to log information.
  • enable() will enable your log in the code. Similar to the command s4clib.enable_log <log_name>
  • disable() will disable your log in the code. Similar to the command s4clib.disable_log <log_name>

Example:

from example_mod.mod_info import ModInfo
from sims4communitylib.utils.common_log_registry import CommonLogRegistry

example_log: CommonLog = CommonLogRegistry.get().register_log(ModInfo.get_identity(), 'example_logger_of_logs')
example_log.debug('I am a message, fear {}!'.format('me'))

If example_log has been enabled, either through the s4clib.enable_log command or example_log.enable(), then the message I am a message, fear me! will be logged in a file with the name MyModName_Messages.txt

An interesting thing you can do with enable and disable is to only enable it in certain cases.

from example_mod.mod_info import ModInfo
from sims4communitylib.utils.common_log_registry import CommonLogRegistry

example_log: CommonLog = CommonLogRegistry.get().register_log(ModInfo.get_identity(), 'example_logger_of_logs')
example_log.debug('I am a message, fear {}!'.format('me'))
example_log.enable()
example_log.debug('I am message number 2!')
example_log.disable()
example_log.debug('I am message number 3!')

In the above example, only the message I am message number 2! will be logged to MyModName, because example_log was only enabled at the time of hitting that line.

Other (and Preferred) Ways To Create a Log

HasLog

from example_mod.mod_info import ModInfo
from sims4communitylib.logging.has_log import HasLog

class ExampleClassWithLog(HasLog):
    @property
    def mod_identity(self) -> CommonModIdentity:
        return ModInfo.get_identity()

    @property
    def log_identifier(self) -> str:
        return 'example_logger_of_logs'

    def i_am_instance_method_thingy(self):
        self.log.debug('I am message number 2!')`
  • Inside your functions you may then do self.log to access the log and perform the exact same functions as you do in the above examples. self.log.debug('I am message number 2!') 
ExampleClassWithLog().log.debug('I am message number 6!`) # Will log "I am message number 6!"
ExampleClassWithLog().i_am_instance_method_thingy() # Will log "I am message number 2!"

HasClassLog

from example_mod.mod_info import ModInfo
from sims4communitylib.logging.has_class_log import HasClassLog

class ExampleClassWithClassLog(HasClassLog):
    @classmethod
    def get_mod_identity(cls) -> CommonModIdentity:
        return ModInfo.get_identity()

    @classmethod
    def get_log_identifier(cls) -> str:
        return 'example_logger_of_logs'

    @classmethod
    def i_am_class_method_thingy(cls):
        cls.get_log().debug('I am message number 2!')`

    def i_am_instance_method_thingy(self):
        self.log.debug('I am message number 4!')`
  • You will notice the "properties" you override now are slightly different get_mod_identity instead of mod_identity and get_log_identifier instead of log_identifier. You may also notice instead of @property they are using @classmethod.
  • The log within ExampleClassWithClassLog may still be accessed via self.log as done with HasLog only this time you gain access to a class level version of the log cls.get_log() which can be accessed without an instance of the class!
# These can still be done!
ExampleClassWithLog().log.debug('I am message number 6!`) # Will log "I am message number 6!"
ExampleClassWithLog().i_am_instance_method_thingy() # Will log "I am message number 4!"

# Using HasClassLog, now these are available to be done!
ExampleClassWithClassLog.get_log().debug('I am message number 8!`) # Will log "I am message number 8!"
ExampleClassWithClassLog.i_am_class_method_thingy() # Will also log "I am message number 2!"
⚠️ **GitHub.com Fallback** ⚠️