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.
-
classmethod
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.
-
classmethod
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]
-
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]
-
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]
-
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]
-
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
-
clear_data
()¶ Clear all data managers in the registry.
-
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.
-
clear
()¶ Clear all data from the data manager.
-
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 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.
-
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 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 – 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.
-
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
() → str¶ The identifier of the data store.
-
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.
-
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:
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, per_save_slot=False, folder_name=None, custom_file_name=None, data_folder_path=None)¶ Bases:
sims4communitylib.persistence.persistence_services.common_persistence_service.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 – 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.
:type custom_file_name; str, optional :param data_folder_path: Use to specify a custom folder path at the top level for which to save/load data to/from. Default is “Mods/mod_data”. :type data_folder_path: str, optional
-
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
Individual Folder¶
-
class
CommonIndividualFolderPersistenceService
(main_file_name='main.json', combined_file_name='combined.json', allow_duplicates_in_collections=False, data_folder_path=None)¶ Bases:
sims4communitylib.persistence.persistence_services.common_persistence_service.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”.
-
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]
-
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)¶ 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