Persistence¶

Local Persistence¶

Sim Data¶

class CommonSimDataStorage(sim_info)¶

Bases: _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: _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: 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.

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

customize_data_pre_save(data)¶

A hook that allows customization of data before it is persisted/saved.

Parameters:: data (Dict[str, Any]) – The data intending to be saved, it is available for customization.
Returns:: The customized data.
Return type:: Dict[str, Any]

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

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

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

customize_data_pre_save(data)¶

A hook that allows customization of data before it is persisted/saved.

Parameters:: data (Dict[str, Any]) – The data intending to be saved, it is available for customization.
Returns:: The customized data.
Return type:: Dict[str, Any]

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

property 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: CommonService, 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_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

clear_data()¶

Clear all data managers in the registry.

Return type:: None

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.
Return type:: Callable[[Type[CommonDataManager]], Any]

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.

Return type:: None

Data Manager¶

class CommonDataManager(identifier=None)¶

Bases: HasLog

Manage a storage of data.

clear()¶

Clear all data from the data manager.

Return type:: None

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.

Return type:: None

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

Return type:: None

remove_all_data(prevent_save=False)¶

Reset the data store to default values and remove persisted files.

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 (str) – 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.

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

customize_data_pre_save(data)¶

A hook that allows customization of data before it is persisted/saved.

Parameters:: data (Dict[str, Any]) – The data intending to be saved, it is available for customization.
Returns:: The customized data.
Return type:: Dict[str, Any]

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

The identifier of the data store.

Return type:: str

get_store_data_for_persistence()¶

Returns:: The data of this data store, but in an easy to serialize format.
Return type:: Dict[str, Any]

get_value_by_key(key, encode=None, decode=None)¶

Get data from storage by its key.

Parameters:

key (str) – An identifier.
encode (Callable[[Any], Any], optional) – If specified, the data will be encoded using this function and the result will be the new data stored. Default is None.
decode (Callable[[Any], Any], optional) – If specified, the data will be decoded using this function and the result will be the new result of “get_data”. Default is None.

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, encode=None)¶

Set data in storage by its key.

Parameters:

key (str) – An identifier.
value (Any) – A value.
encode (Callable[[Any], Any], optional) – If specified, the data will be encoded using this function and the result will be the new data stored. Default is None.

update_data(data)¶

Replace the data contained within the data store.

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

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

Sim Data¶

class CommonSimDataStore¶

Bases: 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()¶

The identifier of the data store.

Return type:: str

Game Object¶

class CommonGameObjectDataStore¶

Bases: 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()¶

The identifier of the data store.

Return type:: str

Persistence Services¶

File¶

class CommonFilePersistenceService(per_save=True, per_save_slot=False, folder_name=None, custom_file_name=None, data_folder_path=None)¶

Bases: CommonPersistenceService

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

Parameters:

per_save (bool, optional) – If True, the data will persist for each Game Save file (Set “per_save_slot” to True to persist per save SLOT as well!). If False, the data will persist for all Game Save files. Default is True.
per_save_slot (bool, optional) – If True, the data will persist for each Save slot. If False, the data will persist for each Game file only. Default is False. (This argument requires “per_save” to be True as well!)
folder_name (str, optional) – Use to specify a custom file path after the normal file path, example: “The Sims 4/Mods/mod_data/<mod_name>/<folder_name>”. Default is None.
custom_file_name (str, optional) – Use to specify a custom name for the loaded and saved file. example: “The Sims 4/Mods/mod_data/<mod_name>/<custom_file_name>” and if “folder_name” is specified: “The Sims 4/Mods/mod_data/<mod_name>/<folder_name>/<custom_file_name>”. Default is None.
data_folder_path (str, optional) – Use to specify a custom folder path at the top level for which to save/load data to/from. Default is “Mods/mod_data”.

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, identifier=None)¶

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

Individual Folder¶

class CommonIndividualFolderPersistenceService(main_file_name='main.json', data_folder_path=None, skip_file_names=(), required_file_name_extension='.json')¶

Bases: CommonPersistenceService

A service that persists data to a file within a folder on the system. It also loads all data from a folder on the system while loading the main file last.

Parameters:

main_file_name (str, optional) – A file that will be loaded after the other files in the folder specified by folder_name. Default is ‘main.json’.
data_folder_path (str, optional) – Use to specify a custom folder path at the top level for which to save/load data to/from. Default is “Mods/mod_data”.
skip_file_names (Tuple[str], optional) – A collection of file names to ignore. Default is no items.
required_file_name_extension (str, optional) – An extension that is required to be at the end of a file name for the file to be loaded. Default is .json.

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]

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

remove(mod_identity, identifier=None)¶

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: 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, identifier=None)¶

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