Persistence

Local Persistence

Sim Data

class CommonSimDataStorage(sim_info)

Bases: sims4communitylib.persistence.common_sim_data_storage._CommonSimDataStorage

A wrapper for Sim instances that allows storing of data.

Warning

Data stored within is not persisted when closing and reopening the game!

Warning

DO NOT CREATE THIS CLASS DIRECTLY, IT IS ONLY MEANT TO INHERIT FROM!

Example usage:
# Inherit from CommonSimDataStorage
class _ExampleSimDataStorage(CommonSimDataStorage):
    @classmethod
    def get_mod_identity(cls) -> CommonModIdentity:
        # !!!Override with the CommonModIdentity of your own mod!!!
        from sims4communitylib.modinfo import ModInfo
        return ModInfo.get_identity()

    @property
    def example_property_one(self) -> bool:
        # Could also be written self.get_data(default=False, key='example_property_one') and it would do the same thing.
        return self.get_data(default=False)

    @example_property_one.setter
    def example_property_one(self, value: bool):
        # Could also be written self.set_data(value, key='example_property_one') and it would do the same thing.
        self.set_data(value)
Parameters:sim_info (SimInfo) – The SimInfo of a Sim.
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.

Game Object Data

class CommonGameObjectDataStorage(game_object)

Bases: sims4communitylib.persistence.common_game_object_data_storage._CommonGameObjectDataStorage

A wrapper for Object instances that allows storing of data.

Warning

Data stored within is not persisted when closing and reopening the game!

Warning

DO NOT CREATE THIS CLASS DIRECTLY, IT IS ONLY MEANT TO INHERIT FROM!

Example usage:
# Inherit from CommonGameObjectDataStorage
class _ExampleGameObjectDataStorage(CommonGameObjectDataStorage):
    # noinspection PyMissingOrEmptyDocstring
    @classmethod
    def get_mod_identity(cls) -> CommonModIdentity:
        # !!!Override with the CommonModIdentity of your own mod!!!
        from sims4communitylib.modinfo import ModInfo
        return ModInfo.get_identity()

    @property
    def example_property_one(self) -> bool:
        # Could also be written self.get_data(default=False, key='example_property_one') and it would do the same thing.
        return self.get_data(default=False)

    @example_property_one.setter
    def example_property_one(self, value: bool):
        # Could also be written self.set_data(value, key='example_property_one') and it would do the same thing.
        self.set_data(value)
Parameters:game_object (GameObject) – An instance of an Object.
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.

Saved Persistence

Sim Data

class CommonPersistedSimDataStorage(sim_info)

Bases: sims4communitylib.persistence.common_sim_data_storage.CommonSimDataStorage

A wrapper for Sim instances that allows storing of data and persisting it between saves.

Warning

Data stored within will be persisted for a Save even when closing and reopening the game!

Warning

DO NOT CREATE THIS CLASS DIRECTLY, IT IS ONLY MEANT TO INHERIT FROM!

Example usage:
# Inherit from CommonPersistedSimDataStorage
class ExamplePersistedSimDataStorage(CommonPersistedSimDataStorage):
    @classmethod
    def get_mod_identity(cls) -> CommonModIdentity:
        # !!!Override with the CommonModIdentity of your own mod!!!
        from sims4communitylib.modinfo import ModInfo
        return ModInfo.get_identity()

    @property
    def example_property_one(self) -> bool:
        # Could also be written self.get_data(default=False, key='example_property_one') and it would do the same thing.
        return self.get_data(default=False)

    @example_property_one.setter
    def example_property_one(self, value: bool):
        # Could also be written self.set_data(value, key='example_property_one') and it would do the same thing.
        self.set_data(value)
Parameters:sim_info (SimInfo) – The SimInfo of a Sim.
blacklist_property_names

If a property is within this list, it will not be persisted when saving. By default no properties are blacklisted.

Returns:A collection of property names.
Return type:Tuple[str]
data_store_type

The type of data store used for saving and loading data.

Returns:The type of the data store to use when saving and loading data.
Return type:Type[CommonDataStore]
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.
whitelist_property_names

If a property is within this list, it will be persisted when saving. By default all properties are whitelisted.

Returns:A collection of property names.
Return type:Tuple[str]

Game Object Data

class CommonPersistedGameObjectDataStorage(game_object)

Bases: sims4communitylib.persistence.common_game_object_data_storage.CommonGameObjectDataStorage

A wrapper for Game Object instances that allows storing of data and persisting it between saves.

Warning

Data stored within will be persisted for a Save even when closing and reopening the game!

Warning

DO NOT CREATE THIS CLASS DIRECTLY, IT IS ONLY MEANT TO INHERIT FROM!

Example usage:
# Inherit from CommonPersistedGameObjectDataStorage
class ExamplePersistedGameObjectDataStorage(CommonPersistedGameObjectDataStorage):
    @classmethod
    def get_mod_identity(cls) -> CommonModIdentity:
        # !!!Override with the CommonModIdentity of your own mod!!!
        from sims4communitylib.modinfo import ModInfo
        return ModInfo.get_identity()

    @property
    def example_property_one(self) -> bool:
        # Could also be written self.get_data(default=False, key='example_property_one') and it would do the same thing.
        return self.get_data(default=False)

    @example_property_one.setter
    def example_property_one(self, value: bool):
        # Could also be written self.set_data(value, key='example_property_one') and it would do the same thing.
        self.set_data(value)
Parameters:game_object (GameObject) – An instance of a GameObject
blacklist_property_names

If a property is within this list, it will not be persisted when saving. By default no properties are blacklisted.

Returns:A collection of property names.
Return type:Tuple[str]
data_store_type

The type of data store used for saving and loading data.

Returns:The type of the data store to use when saving and loading data.
Return type:Type[CommonDataStore]
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.
whitelist_property_names

If a property is within this list, it will be persisted when saving. By default all properties are whitelisted.

Returns:A collection of property names.
Return type:Tuple[str]

Data Management

Data Manager Registry

class CommonDataManagerRegistry

Bases: sims4communitylib.services.common_service.CommonService, sims4communitylib.logging.has_class_log.HasClassLog

A registry that maintains data managers for saving and loading of data.

Example usage:
from typing import Tuple
from sims4communitylib.mod_support.mod_identity import CommonModIdentity
from sims4communitylib.persistence.data_management.common_data_manager import CommonDataManager
from sims4communitylib.persistence.data_management.common_data_manager_registry import CommonDataManagerRegistry
from sims4communitylib.persistence.persistence_services.common_persistence_service import CommonPersistenceService


# This attribute will register the data manager to the registry.
# @CommonDataManagerRegistry.common_data_manager()
# Passing an identifier argument will give a unique identifier to the data manager, but it isn't required unless you have multiple managers for your mod.
@CommonDataManagerRegistry.common_data_manager(identifier='I_am_unique')
class ExampleDataManager(CommonDataManager):
    # noinspection PyMissingOrEmptyDocstring
    @property
    def mod_identity(self) -> CommonModIdentity:
        # !!! Override this property using your own CommonModIdentity !!!
        return ModInfo.get_identity()

    # noinspection PyMissingOrEmptyDocstring
    @property
    def log_identifier(self) -> str:
        return 'the_example_data_manager'

    # noinspection PyMissingOrEmptyDocstring
    @property
    def persistence_services(self) -> Tuple[CommonPersistenceService]:
        from sims4communitylib.persistence.persistence_services.common_hidden_household_persistence_service import                     CommonHiddenHouseholdPersistenceService
        from sims4communitylib.persistence.persistence_services.common_file_persistence_service import                     CommonFilePersistenceService
        # The order matters. The later services will override data loaded from the earlier services. In the follow, any data loaded from the file will override any matching data that was loaded from the hidden household.
        result: Tuple[CommonPersistenceService] = (
            # Having this will result in the data being saved to a hidden household.
            CommonHiddenHouseholdPersistenceService(),
            # Having this will result in the data also being saved to a file at saves\mod_name\do_not_remove_mod_name_author_I_am_unique_id_1234_guid_5435.json (Notice that "I_am_unique" becomes a part of the file name because it was specified as the identifier)
            CommonFilePersistenceService()
        )
        return result
static common_data_manager(identifier=None)

An attribute that will register the decorated data manager to the registry.

Parameters:identifier (str, optional) – If you need to distinguish two different data managers for your mod, this will be the unique identifier. Default is None.
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.
locate_data_manager(mod_identity, identifier=None)

Locate a data manager for a mod.

Parameters:
  • mod_identity (CommonModIdentity) – The identity of the Mod.
  • identifier (str, optional) – If you distinguished your data manager with an identifier when registering it, provide it here to locate the correct data manager, otherwise leave it as None. Default is None.
Returns:

The data manager for the specified mod with the specified identifier (if specified) or None if not found.

Return type:

Union[CommonDataManager, None]

save_data()

Save the data of all data managers.

Data Manager

class CommonDataManager

Bases: sims4communitylib.logging.has_log.HasLog

Manage a storage of data.

get_data_store_by_type(data_store_type)

Retrieve a data store by its type.

Note

This will also add the data store using the type if it does not exist already.

Parameters:data_store_type (Type[CommonDataStore]) – The type of data store.
Returns:The data store.
Return type:CommonDataStore
load()

Load data into the data manager.

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

A collection of services that save and load data for the manager using the Mod Identity of the manager.

Note

The precedence of data being loaded/saved is in the order you return them in. For example, with (CommonHiddenHouseholdPersistenceService, CommonFilePersistenceService), data loaded via the file will override data loaded via the hidden household

Returns:A collection of persistence services.
Return type:Tuple[CommonPersistenceService]
reload()

Reloads data into the data manager.

remove_all_data(prevent_save=False)

Reset the data store to default values.

Parameters:prevent_save (bool) – If True, when the game is saved, the data will not be persisted.
Returns:True, if all data was successfully removed. False, if not.
Return type:bool
remove_data_store_by_name(name)

Remove a data store by its name.

Parameters:
  • name – The name of a data store.
  • name – str
Returns:

True, if successfully removed. False, if not.

Return type:

bool

save()

Save data from the data manager.

Returns:True, if save was successful. False, if not.
Return type:bool

Data Stores

Data Store

class CommonDataStore

Bases: object

Manage a subset of data.

get_default_value_by_key(key)

Get the default value

Parameters:key (str) – An identifier.
Returns:The default value associated with the specified key or None if no default value has been provided for the specified key.
Return type:Any
classmethod get_identifier() → str

The identifier of the data store.

get_value_by_key(key)

Get data from storage by its key.

Parameters:key (str) – An identifier.
Returns:The value assigned to the key or the default value if not found.
Return type:Any
remove_data_by_key(key)

Remove data from storage.

Parameters:key (str) – An identifier.
Returns:True, if the data with the specified identifier is removed successfully. False, if not.
Return type:bool
set_value_by_key(key, value)

Set data in storage by its key.

Parameters:
  • key (str) – An identifier.
  • value (Any) – A value.
update_data(data)

Replace the data contained within the data store.

Parameters:data (Dict[str, Any]) – A library of data.

Sim Data

class CommonSimDataStore

Bases: sims4communitylib.persistence.data_stores.common_data_store.CommonDataStore

A store of Sim Data.

get_default_value_by_key(key)

Get the default value

Parameters:key (str) – An identifier.
Returns:The default value associated with the specified key or None if no default value has been provided for the specified key.
Return type:Any
classmethod get_identifier() → str

The identifier of the data store.

Game Object

class CommonGameObjectDataStore

Bases: sims4communitylib.persistence.data_stores.common_data_store.CommonDataStore

A store of Game Object Data.

get_default_value_by_key(key)

Get the default value

Parameters:key (str) – An identifier.
Returns:The default value associated with the specified key or None if no default value has been provided for the specified key.
Return type:Any
classmethod get_identifier() → str

The identifier of the data store.

Persistence Services

File

class CommonFilePersistenceService(per_save=True)

Bases: sims4communitylib.persistence.persistence_services.common_persistence_service.CommonPersistenceService

A service that persists data into a file on the system.

Parameters:per_save (bool, optional) – If True, the data will persist for each Save file individually. If False, the data will persist for all Save files. Default is True.
load(mod_identity, identifier=None)

Load persisted data for the specified Mod Identity.

Parameters:
  • mod_identity (CommonModIdentity) – The identity of the mod that data is being loaded for.
  • identifier (str, optional) – If set, the identifier will be used to make the data name even more unique. Don’t set it if you don’t need to! Default is None.
Returns:

A library of data.

Return type:

Dict[str, Any]

remove(mod_identity)

Removed persisted data for the specified Mod Identity.

Parameters:
  • mod_identity (CommonModIdentity) – The identity of the mod that data is being removed for.
  • identifier (str, optional) – If set, the identifier will be used to make the data name even more unique. Don’t set it if you don’t need to! Default is None.
Returns:

True, if the data was removed successfully. False, if not.

Return type:

bool

save(mod_identity, data, identifier=None)

Save persisted data for the specified Mod Identity.

Parameters:
  • mod_identity (CommonModIdentity) – The identity of the mod that data is being saved for.
  • data (Dict[str, Any]) – The data being persisted.
  • identifier (str, optional) – If set, the identifier will be used to make the data name even more unique. Don’t set it if you don’t need to! Default is None.
Returns:

True, if the data was persisted successfully. False, if not.

Return type:

bool

Hidden Household

class CommonHiddenHouseholdPersistenceService

Bases: sims4communitylib.persistence.persistence_services.common_persistence_service.CommonPersistenceService

A service that persists data into a hidden household. (This data is per save file, it won’t carry to other Saves)

load(mod_identity, identifier=None)

Load persisted data for the specified Mod Identity.

Parameters:
  • mod_identity (CommonModIdentity) – The identity of the mod that data is being loaded for.
  • identifier (str, optional) – If set, the identifier will be used to make the data name even more unique. Don’t set it if you don’t need to! Default is None.
Returns:

A library of data.

Return type:

Dict[str, Any]

remove(mod_identity)

Removed persisted data for the specified Mod Identity.

Parameters:
  • mod_identity (CommonModIdentity) – The identity of the mod that data is being removed for.
  • identifier (str, optional) – If set, the identifier will be used to make the data name even more unique. Don’t set it if you don’t need to! Default is None.
Returns:

True, if the data was removed successfully. False, if not.

Return type:

bool

save(mod_identity, data, identifier=None)

Save persisted data for the specified Mod Identity.

Parameters:
  • mod_identity (CommonModIdentity) – The identity of the mod that data is being saved for.
  • data (Dict[str, Any]) – The data being persisted.
  • identifier (str, optional) – If set, the identifier will be used to make the data name even more unique. Don’t set it if you don’t need to! Default is None.
Returns:

True, if the data was persisted successfully. False, if not.

Return type:

bool