Systems¶

Command Services

Caching¶

Serializable Object Cache¶

class CommonSerializableObjectCache(cached_objects, checksums)¶

Bases: CommonSerializable, Generic[CommonSerializableObjectCacheType]

A cache of serializable objects.

property cached_checksums¶: Cached checksums, these are used to check if the cache needs updating.

property 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: CommonService, HasLog, Generic[CommonSerializableObjectCacheType]

A service that manages a cache of serializable objects.

cache_needs_update(new_checksum_data)¶

Determine if the cache needs to be updated or not.

Return type:: bool

clear_cache()¶

Clear the cached data

Return type:: None

create_cache(objects, checksums)¶

Create a new cache.

Return type:: TypeVar(CommonSerializableObjectCacheType, bound= CommonSerializableObjectCache[CommonSerializable])

load_from_cache()¶

Load the cached data.

Return type:: Optional[TypeVar(CommonSerializableObjectCacheType, bound= CommonSerializableObjectCache[CommonSerializable])]

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.

save_to_cache(cache)¶

Save a cache of data.

Return type:: None

Item Query¶

Loaded Item¶

class CommonLoadedItem(tags, is_original=False)¶

Bases: CommonSerializable, HasClassLog

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

add_tag(tag)¶: Add a tag to the item.

add_tags(tags)¶: Add tags to the item.

clear_cached_data()¶

Clear cached data.

Return type:: None

clone()¶

Clone the item.

Return type:: CommonLoadedItem

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

Determine if the item has all the specified tags.

Return type:: bool

has_any_tags(tags)¶

Determine if the item has any of the specified tags.

Return type:: bool

has_tag(tag)¶

Determine if the item has a tag.

Return type:: bool

property identifier¶: The identifier of the item.

property identifiers_backwards_compatible¶: The backwards compatible identifier of the item.

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

property original¶: The original unmodified item.

remove_tag(tag)¶: Remove a tag from the item.

remove_tags(tags)¶: Remove tags from the item.

replace_tag(tag_to_remove, tag_to_add)¶: 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]]

property short_name¶: A short name for the item.

property tags¶: A collection of tags that apply to the item.

verify()¶

Verify the item.

Return type:: CommonTestResult

Query Method Type¶

class CommonQueryMethodType¶

Bases: 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: CommonService, HasLog, Generic[CommonLoadedItemType]

Loads items.

get_checksum_data_gen()¶

Generate checksums.

Return type:: Iterator[Tuple[str, int, int]]

load()¶

Loads all items.

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

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 snippet_names¶: The names of snippets containing items.

property total¶: The total number of items that were looked at

property total_invalid¶: The total number of items that were invalid.

property total_valid¶: The total number of items that were valid.

Loaded Item Test¶

class CommonLoadedItemTest¶

Bases: HasClassLog, Generic[CommonLoadedItemType]

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

Test an item for a match.

Return type:: CommonTestResult

Loaded Item Tests - Item Is Available¶

class CommonLoadedItemIsAvailableTest¶

Bases: CommonLoadedItemTest[CommonLoadedItem]

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

Test an item for a match.

Return type:: CommonTestResult

Loaded Item Tests - Item Is Not Available¶

class CommonLoadedItemIsNotAvailableTest¶

Bases: CommonLoadedItemTest[CommonLoadedItem]

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

Test an item for a match.

Return type:: CommonTestResult

Loaded Item Cache¶

class CommonLoadedItemCache(cached_objects, checksums)¶

Bases: CommonSerializableObjectCache[CommonLoadedItemCacheType], Generic[CommonLoadedItemCacheType]

A cache of Loaded Items.

Loaded Item Cache Service¶

class CommonLoadedItemCacheService¶

Bases: CommonSerializableObjectCacheService[CommonLoadedItemCacheType], Generic[CommonLoadedItemCacheType]

A service that manages a cache of Loaded Items.

create_cache(objects, checksums)¶

Create a new cache.

Return type:: TypeVar(CommonLoadedItemCacheType, bound= CommonLoadedItemCache[CommonLoadedItem])

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.

Loaded Item Filter¶

class CommonLoadedItemFilter(match_all, match_at_least_one=False, exclude=False, key_type=None)¶

Bases: HasLog, Generic[ItemKeyType]

A filter for use when querying loaded items.

property exclude¶: Determine if we should not have any of the keys.

get_keys()¶

Retrieve the keys of this filter.

Return type:: Tuple[CommonLoadedItemKey]

property key_type¶: The type of keys produced by this filter.

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 match_all¶: Determine if we should match all (True) the keys or any (False) of them.

property match_at_least_one¶: Determine if we should match at least one key.

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.

Loaded Item Filter Request¶

class CommonLoadedItemFilterRequest(item_filters, item_tests, query_type=Ellipsis)¶

Bases: Generic[CommonLoadedItemFilterType, CommonLoadedItemTestType, CommonLoadedItemKeyType]

A request used to locate things.

property exclude_keys¶: Must NOT have any of these keys to match.

property include_all_keys¶: Must have all these keys to match.

property include_any_keys¶: Must have any of these keys to match.

property item_filters¶: Filters used to filter items.

property item_tests¶: Tests to run on items.

property must_match_at_least_one_key_sets¶: Must match at least one of these keys.

property query_type¶: The method used to query items.

Loaded Item Key¶

class CommonLoadedItemKey(key_type, value)¶

Bases: Generic[ItemKeyType]

A key for a loaded item.

property key¶: The combination of the type and value.

property key_type¶: The type of key.

property value¶: The value.

Loaded Item Organizer¶

class CommonLoadedItemOrganizer(key_type)¶

Bases: Generic[CommonLoadedItemKeyType, CommonLoadedItemType]

An organizer of items.

applies(item)¶

Determine if this organizer applies to an item.

Return type:: bool

get_key_values(item)¶

Retrieve key values for this organizer.

Return type:: Tuple[Any]

property key_type¶: The type of keys this organizer produces.

Loaded Item Query Utils¶

class CommonLoadedItemQueryUtils¶

Bases: HasLog, Generic[CommonLoadedItemType]

Query for items using various filter configurations.

create_filter_request(item_filters, item_tests, query_type=Ellipsis)¶

Create a filter request for items.

Return type:: CommonLoadedItemFilterRequest

get_all()¶

Get all items.

Return type:: Tuple[TypeVar(CommonLoadedItemType, bound= CommonLoadedItem)]

get_available_for_filters_gen(item_filters, item_tests, query_type=Ellipsis)¶

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

Return type:: Iterator[TypeVar(CommonLoadedItemType, bound= CommonLoadedItem)]

get_for_filters_gen(item_filters, item_tests, query_type=Ellipsis)¶

Get all items matching filters.

Return type:: Iterator[TypeVar(CommonLoadedItemType, bound= CommonLoadedItem)]

get_random_for_filters(item_filters, item_tests, query_type=Ellipsis)¶

Get a random item that matches filters.

Return type:: Optional[TypeVar(CommonLoadedItemType, bound= CommonLoadedItem)]

get_random_from_available_for_filters(item_filters, item_tests, query_type=Ellipsis)¶

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

Return type:: Optional[TypeVar(CommonLoadedItemType, bound= CommonLoadedItem)]

has_available_for_filters(item_filters, item_tests, query_type=Ellipsis)¶

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

Return type:: bool

has_for_filters(item_filters, item_tests, query_type=Ellipsis)¶

Determine if any items are available that match filters.

Return type:: bool

locate_by_identifier(identifier)¶

Locate a CAS Part by its identifier.

Return type:: Optional[TypeVar(CommonLoadedItemType, bound= CommonLoadedItem)]

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.

Loaded Item Query Registry¶

class CommonLoadedItemQueryRegistry¶

Bases: CommonService, HasLog, Generic[CommonLoadedItemType]

Registry handling item queries.

add_item_organizer(item_organizer_init, key_type)¶: Add an item organizer.

property collecting¶: Determine if items are being collected.

property duplicates¶: The total number of items that were valid.

get_all()¶

Get all items.

Return type:: Tuple[TypeVar(CommonLoadedItemType, bound= CommonLoadedItem)]

get_items_gen(requests)¶

Retrieve items matching the requests.

Return type:: Iterator[TypeVar(CommonLoadedItemType, bound= CommonLoadedItem)]

has_items(requests)¶

Determine if items exist for queries.

Return type:: bool

property item_library¶: A library of items organized by filter keys.

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.

classmethod register_item_organizer(key_type)¶

Register an item organizer.

Return type:: Callable[[Any], Any]

property total¶: The total number of items that were looked at

property total_invalid¶: The total number of items that were invalid.

property 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.
Return type:: None

Loaded Item Registry¶

class CommonLoadedItemRegistry¶

Bases: CommonService, HasLog, Generic[CommonLoadedItemType]

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

Add a loader of items.

Return type:: bool

property duplicates¶: The total number of duplicate items that were found.

property item_loaders¶: Loaders that load items.

load()¶

Load data.

Return type:: None

property loaded¶: True, if the registry has finished loading.

property loaded_items¶: A library of items organized by their identifiers.

property loading¶: True, if the registry is currently loading.

locate_by_identifier(identifier)¶

Locate an item by an identifier.

Return type:: Optional[TypeVar(CommonLoadedItemType, bound= CommonLoadedItem)]

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.

register_on_finished_loading_callback(callback)¶

Finished loading callback.

Return type:: None

property total¶: The total number of items that were found

property total_invalid¶: The total number of items that were invalid.

property total_time¶: The total time the registry took to load in milliseconds.

property total_valid¶: The total number of items that were valid.

Settings¶

Setting Utils¶

class CommonSettingUtils(*args, **kwds)¶

Bases: Generic[SettingDataStoreType]

Utilities for settings.

classmethod get_enum_tuple_setting(key, enum_type, invalid_enum_value)¶

Retrieve a setting that is a collection of enum values.

Return type:: Tuple[TypeVar(SettingEnumType, CommonInt, CommonIntFlags, CommonVersionedInt, CommonVersionedIntFlags), ...]

classmethod get_enum_value_collection_setting(key, enum_value_collection_type)¶

Retrieve an enum value collection setting.

Return type:: TypeVar(SettingEnumValueCollectionType, bound= CommonVersionedEnumValueCollection)

classmethod get_value(key, encode=None, decode=None)¶

Get a value using an encoding and decoding.

Return type:: Any

classmethod set_enum_tuple_setting(key, value)¶: Set a setting that is a collection of enum values.

classmethod set_enum_value_collection_setting(key, value)¶: Set an enum value collection setting.

classmethod set_value(key, value, encode=None)¶

Set a value using an encoding and decoding.

Return type:: Any

Settings Data Manager¶

class CommonSettingsDataManager(identifier=None)¶

Bases: CommonDataManager

Manage a storage of settings data.

classmethod get_identifier()¶

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

Return type:: str

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]

Settings Data Manager Utils¶

class CommonSettingsDataManagerUtils¶

Bases: CommonService, HasLog

Utilities to manage settings data.

get_all_data()¶

Get all data.

Return type:: Dict[str, 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

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.

reset(prevent_save=False)¶

Reset data.

Return type:: bool

save()¶

Save data.

Return type:: bool

Settings Data Store¶

class CommonSettingsDataStore¶

Bases: CommonDataStore

Manages main settings for CM.

classmethod get_identifier()¶

The identifier of the data store.

Return type:: str