Systems

Caching

Serializable Object Cache

class CommonSerializableObjectCache(cached_objects: Tuple[CommonSerializableObjectCacheType], checksums: Dict[str, int])

Bases: sims4communitylib.classes.serialization.common_serializable.CommonSerializable, typing.Generic

A cache of serializable objects.

cached_checksums

Cached checksums, these are used to check if the cache needs updating.

cached_objects

Cached objects

classmethod deserialize(data)

Deserialize the object from a JSON Serializable form.

Returns:The deserialized form of the object or None if it fails to deserialize.
Return type:Union[CommonSerializableType, None]
serialize()

Serialize the object into a JSON Serializable form.

Returns:A serializable representation of the object.
Return type:Union[str, Dict[str, Any]]

Serializable Object Cache Service

class CommonSerializableObjectCacheService

Bases: sims4communitylib.services.common_service.CommonService, sims4communitylib.logging.has_log.HasLog, typing.Generic

A service that manages a cache of serializable objects.

cache_needs_update(new_checksum_data: Any) → bool

Determine if the cache needs to be updated or not.

clear_cache() → None

Clear the cached data

create_cache(objects: Tuple[sims4communitylib.classes.serialization.common_serializable.CommonSerializable], checksums: Tuple[Any]) → CommonSerializableObjectCacheType

Create a new cache.

load_from_cache() → Optional[CommonSerializableObjectCacheType]

Load the cached data.

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.
save_to_cache(cache: CommonSerializableObjectCacheType) → None

Save a cache of data.

Item Query

Loaded Item

class CommonLoadedItem(tags: Set[Any], is_original: bool = False)

Bases: sims4communitylib.classes.serialization.common_serializable.CommonSerializable, sims4communitylib.logging.has_class_log.HasClassLog

Contains information about an item that was loaded from a Snippet.

add_tag(tag: Any)

Add a tag to the item.

add_tags(tags: Iterator[Any])

Add tags to the item.

clear_cached_data() → None

Clear cached data.

clone() → sims4communitylib.systems.item_query.dtos.common_loaded_item.CommonLoadedItem

Clone the item.

classmethod deserialize(data)

Deserialize the object from a JSON Serializable form.

Returns:The deserialized form of the object or None if it fails to deserialize.
Return type:Union[CommonSerializableType, 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.
has_all_tags(tags: Iterator[Any]) → sims4communitylib.classes.testing.common_test_result.CommonTestResult

Determine if the item has all the specified tags.

has_any_tags(tags: Iterator[Any]) → sims4communitylib.classes.testing.common_test_result.CommonTestResult

Determine if the item has any of the specified tags.

has_tag(tag: Any) → bool

Determine if the item has a tag.

identifier

The identifier of the item.

identifiers_backwards_compatible

The backwards compatible identifier of the item.

is_available

Determine if the item is available.

classmethod load_from_package(package_item, tuning_name, log)

Load an item from a package.

Parameters:
  • package_item (Any) – A package item.
  • tuning_name (str) – The name of the tuning being read from.
  • log (CommonLog) – A log for warnings.
Returns:

An item or None if an error occurs.

Return type:

Union[CommonLoadedItem, None]

original

The original unmodified item.

remove_tag(tag: Any)

Remove a tag from the item.

remove_tags(tags: Iterator[Any])

Remove tags from the item.

replace_tag(tag_to_remove: Any, tag_to_add: Any)

Replace one tag with another on the item.

serialize()

Serialize the object into a JSON Serializable form.

Returns:A serializable representation of the object.
Return type:Union[str, Dict[str, Any]]
short_name

A short name for the item.

tags

A collection of tags that apply to the item.

verify() → sims4communitylib.classes.testing.common_test_result.CommonTestResult

Verify the item.

Query Method Type

class CommonQueryMethodType

Bases: sims4communitylib.enums.enumtypes.common_int.CommonInt

Various methods to query for items.

ALL_INTERSECT_ANY = Ellipsis
ALL_INTERSECT_ANY_MUST_HAVE_ONE = Ellipsis
ALL_PLUS_ANY = Ellipsis
ALL_PLUS_ANY_MUST_HAVE_ONE = Ellipsis

Base Item Loader

class CommonBaseItemLoader

Bases: sims4communitylib.services.common_service.CommonService, sims4communitylib.logging.has_log.HasLog, typing.Generic

Loads items.

get_checksum_data_gen() → Iterator[Tuple[str, int, int]]

Generate checksums.

load()

Loads all items.

Returns:An iterator of the valid items.
Return type:Iterator[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
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.
snippet_names

The names of snippets containing items.

total

The total number of items that were looked at

total_invalid

The total number of items that were invalid.

total_valid

The total number of items that were valid.

Loaded Item Test

class CommonLoadedItemTest

Bases: sims4communitylib.logging.has_class_log.HasClassLog, typing.Generic

A test that is run to test a loaded item.

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.
test_item(item: CommonLoadedItemType) → sims4communitylib.classes.testing.common_test_result.CommonTestResult

Test an item for a match.

Loaded Item Tests - Item Is Available

class CommonLoadedItemIsAvailableTest

Bases: sims4communitylib.systems.item_query.item_tests.common_loaded_item_test.CommonLoadedItemTest

Test for an item is available.

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.
test_item(item: sims4communitylib.systems.item_query.dtos.common_loaded_item.CommonLoadedItem) → sims4communitylib.classes.testing.common_test_result.CommonTestResult

Test an item for a match.

Loaded Item Tests - Item Is Not Available

class CommonLoadedItemIsNotAvailableTest

Bases: sims4communitylib.systems.item_query.item_tests.common_loaded_item_test.CommonLoadedItemTest

Test for an item to not be available.

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.
test_item(item: sims4communitylib.systems.item_query.dtos.common_loaded_item.CommonLoadedItem) → sims4communitylib.classes.testing.common_test_result.CommonTestResult

Test an item for a match.

Loaded Item Cache

class CommonLoadedItemCache(cached_objects: Tuple[CommonSerializableObjectCacheType], checksums: Dict[str, int])

Bases: sims4communitylib.systems.caching.common_serializable_object_cache.CommonSerializableObjectCache, typing.Generic

A cache of Loaded Items.

Loaded Item Cache Service

class CommonLoadedItemCacheService

Bases: sims4communitylib.systems.caching.common_serializable_object_cache_service.CommonSerializableObjectCacheService, typing.Generic

A service that manages a cache of Loaded Items.

create_cache(objects: Tuple[sims4communitylib.systems.item_query.dtos.common_loaded_item.CommonLoadedItem], checksums: Tuple[Any]) → CommonLoadedItemCacheType

Create a new cache.

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.

Loaded Item Filter

class CommonLoadedItemFilter(match_all: bool, match_at_least_one: bool = False, exclude: bool = False, key_type: ItemKeyType = None)

Bases: sims4communitylib.logging.has_log.HasLog, typing.Generic

A filter for use when querying loaded items.

exclude

Determine if we should not have any of the keys.

get_keys() → Tuple[sims4communitylib.systems.item_query.query.common_loaded_item_key.CommonLoadedItemKey]

Retrieve the keys of this filter.

key_type

The type of keys produced by this filter.

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
match_all

Determine if we should match all (True) the keys or any (False) of them.

match_at_least_one

Determine if we should match at least one key.

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.

Loaded Item Filter Request

class CommonLoadedItemFilterRequest(item_filters: Iterator[CommonLoadedItemFilterType], item_tests: Iterator[CommonLoadedItemTestType], query_type: sims4communitylib.systems.item_query.enums.common_query_method_type.CommonQueryMethodType = Ellipsis)

Bases: typing.Generic

A request used to locate things.

exclude_keys

Must NOT have any of these keys to match.

include_all_keys

Must have all these keys to match.

include_any_keys

Must have any of these keys to match.

item_filters

Filters used to filter items.

item_tests

Tests to run on items.

must_match_at_least_one_key_sets

Must match at least one of these keys.

query_type

The method used to query items.

Loaded Item Key

class CommonLoadedItemKey(key_type: ItemKeyType, value: Any)

Bases: typing.Generic

A key for a loaded item.

key

The combination of the type and value.

key_type

The type of key.

value

The value.

Loaded Item Organizer

class CommonLoadedItemOrganizer(key_type: CommonLoadedItemKeyType)

Bases: typing.Generic

An organizer of items.

applies(item: CommonLoadedItemType) → bool

Determine if this organizer applies to an item.

get_key_values(item: CommonLoadedItemType) → Tuple[Any]

Retrieve key values for this organizer.

key_type

The type of keys this organizer produces.

Loaded Item Query Utils

class CommonLoadedItemQueryUtils

Bases: sims4communitylib.logging.has_log.HasLog, typing.Generic

Query for items using various filter configurations.

create_filter_request(item_filters: Tuple[sims4communitylib.systems.item_query.query.common_loaded_item_filter.CommonLoadedItemFilter], item_tests: Iterator[sims4communitylib.systems.item_query.item_tests.common_loaded_item_test.CommonLoadedItemTest], query_type: sims4communitylib.systems.item_query.enums.common_query_method_type.CommonQueryMethodType = Ellipsis) → sims4communitylib.systems.item_query.query.common_loaded_item_filter_request.CommonLoadedItemFilterRequest

Create a filter request for items.

get_all() → Tuple[CommonLoadedItemType]

Get all items.

get_available_for_filters_gen(item_filters: Tuple[sims4communitylib.systems.item_query.query.common_loaded_item_filter.CommonLoadedItemFilter], item_tests: Tuple[sims4communitylib.systems.item_query.item_tests.common_loaded_item_test.CommonLoadedItemTest], query_type: sims4communitylib.systems.item_query.enums.common_query_method_type.CommonQueryMethodType = Ellipsis) → Iterator[CommonLoadedItemType]

Get all items matching filters that are marked as being available.

get_for_filters_gen(item_filters: Tuple[sims4communitylib.systems.item_query.query.common_loaded_item_filter.CommonLoadedItemFilter], item_tests: Iterator[sims4communitylib.systems.item_query.item_tests.common_loaded_item_test.CommonLoadedItemTest], query_type: sims4communitylib.systems.item_query.enums.common_query_method_type.CommonQueryMethodType = Ellipsis) → Iterator[CommonLoadedItemType]

Get all items matching filters.

get_random_for_filters(item_filters: Tuple[sims4communitylib.systems.item_query.query.common_loaded_item_filter.CommonLoadedItemFilter], item_tests: Tuple[sims4communitylib.systems.item_query.item_tests.common_loaded_item_test.CommonLoadedItemTest], query_type: sims4communitylib.systems.item_query.enums.common_query_method_type.CommonQueryMethodType = Ellipsis) → Optional[CommonLoadedItemType]

Get a random item that matches filters.

get_random_from_available_for_filters(item_filters: Tuple[sims4communitylib.systems.item_query.query.common_loaded_item_filter.CommonLoadedItemFilter], item_tests: Tuple[sims4communitylib.systems.item_query.item_tests.common_loaded_item_test.CommonLoadedItemTest], query_type: sims4communitylib.systems.item_query.enums.common_query_method_type.CommonQueryMethodType = Ellipsis) → Optional[CommonLoadedItemType]

Get a random item that matches filters and is marked as being available.

has_available_for_filters(item_filters: Tuple[sims4communitylib.systems.item_query.query.common_loaded_item_filter.CommonLoadedItemFilter], item_tests: Iterator[sims4communitylib.systems.item_query.item_tests.common_loaded_item_test.CommonLoadedItemTest], query_type: sims4communitylib.systems.item_query.enums.common_query_method_type.CommonQueryMethodType = Ellipsis) → bool

Determine if any items are available that match filters and are marked as being available.

has_for_filters(item_filters: Tuple[sims4communitylib.systems.item_query.query.common_loaded_item_filter.CommonLoadedItemFilter], item_tests: Iterator[sims4communitylib.systems.item_query.item_tests.common_loaded_item_test.CommonLoadedItemTest], query_type: sims4communitylib.systems.item_query.enums.common_query_method_type.CommonQueryMethodType = Ellipsis) → bool

Determine if any items are available that match filters.

locate_by_identifier(identifier: str) → Optional[CommonLoadedItemType]

Locate a CAS Part by its identifier.

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.

Loaded Item Query Registry

class CommonLoadedItemQueryRegistry

Bases: sims4communitylib.services.common_service.CommonService, sims4communitylib.logging.has_log.HasLog, typing.Generic

Registry handling item queries.

add_item_organizer(item_organizer_init: Callable[[Any], sims4communitylib.systems.item_query.query.common_loaded_item_organizer.CommonLoadedItemOrganizer], key_type: Any)

Add an item organizer.

collecting

Determine if items are being collected.

duplicates

The total number of items that were valid.

get_all() → Tuple[CommonLoadedItemType]

Get all items.

get_items_gen(requests: Tuple[sims4communitylib.systems.item_query.query.common_loaded_item_filter_request.CommonLoadedItemFilterRequest]) → Iterator[CommonLoadedItemType]

Retrieve items matching the requests.

has_items(requests: Tuple[sims4communitylib.systems.item_query.query.common_loaded_item_filter_request.CommonLoadedItemFilterRequest]) → bool

Determine if items exist for queries.

item_library

A library of items organized by filter keys.

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.
classmethod register_item_organizer(key_type: Any) → Callable[[Any], Any]

Register an item organizer.

total

The total number of items that were looked at

total_invalid

The total number of items that were invalid.

total_valid

The total number of items that were valid.

trigger_collection(show_loading_notification=True)

Trigger the action code to collect all items and organize them by a number of keys.

Parameters:show_loading_notification (bool, optional) – If set to True, the Loading Item’s notification will be shown. If set to False, the Loading Item’s notification will not be shown. Default is True.

Loaded Item Registry

class CommonLoadedItemRegistry

Bases: sims4communitylib.services.common_service.CommonService, sims4communitylib.logging.has_log.HasLog, typing.Generic

A registry that contains loaded items.

add_item(item)

Add an Item to the registry.

Parameters:item (CommonLoadedItemType) – An instance of an Item
Returns:True, if the item was successfully added. False, if not.
Return type:bool
add_item_loader(item_loader: sims4communitylib.systems.item_query.item_loaders.common_base_item_loader.CommonBaseItemLoader) → bool

Add a loader of items.

duplicates

The total number of duplicate items that were found.

item_loaders

Loaders that load items.

load() → None

Load data.

loaded

True, if the registry has finished loading.

loaded_items

A library of items organized by their identifiers.

loading

True, if the registry is currently loading.

locate_by_identifier(identifier: str) → Optional[CommonLoadedItemType]

Locate an item by an identifier.

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.
register_on_finished_loading_callback(callback) → None

Finished loading callback.

total

The total number of items that were found

total_invalid

The total number of items that were invalid.

total_time

The total time the registry took to load in milliseconds.

total_valid

The total number of items that were valid.

Settings

Setting Utils

class CommonSettingUtils

Bases: typing.Generic

Utilities for settings.

classmethod get_enum_tuple_setting(key: str, enum_type: Type[SettingEnumType], invalid_enum_value: SettingEnumType) → Tuple[SettingEnumType]

Retrieve a setting that is a collection of enum values.

classmethod get_enum_value_collection_setting(key: str, enum_value_collection_type: Type[SettingEnumValueCollectionType]) → SettingEnumValueCollectionType

Retrieve an enum value collection setting.

classmethod get_value(key: str, encode: Callable[[Any], Any] = None, decode: Callable[[Any], Any] = None) → Any

Get a value using an encoding and decoding.

classmethod set_enum_tuple_setting(key: str, value: Tuple[SettingEnumType])

Set a setting that is a collection of enum values.

classmethod set_enum_value_collection_setting(key: str, value: SettingEnumValueCollectionType)

Set an enum value collection setting.

classmethod set_value(key: str, value: Any, encode: Callable[[Any], Any] = None) → Any

Set a value using an encoding and decoding.

Settings Data Manager

class CommonSettingsDataManager(identifier: str = None)

Bases: sims4communitylib.persistence.data_management.common_data_manager.CommonDataManager

Manage a storage of settings data.

classmethod get_identifier() → str

Retrieve the identifier of the data manager. This identifier is used in the name of the settings file.

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]

Settings Data Manager Utils

class CommonSettingsDataManagerUtils

Bases: sims4communitylib.services.common_service.CommonService, sims4communitylib.logging.has_log.HasLog

Utilities to manage settings data.

get_all_data() → Dict[str, Dict[str, Any]]

Get all data.

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.
reset(prevent_save: bool = False) → bool

Reset data.

save() → bool

Save data.

Settings Data Store

class CommonSettingsDataStore

Bases: sims4communitylib.persistence.data_stores.common_data_store.CommonDataStore

Manages main settings for CM.

classmethod get_identifier() → str

The identifier of the data store.