Utilities
Public module members
Section titled “Public module members”plexosdb.utils
Section titled “plexosdb.utils”PreparedPropertiesResult
Section titled “PreparedPropertiesResult”Prepared inputs for bulk property insertion.
batched
Section titled “batched”Implement batched iterator.
https://docs.python.org/3/library/itertools.html#itertools.batched
batched(iterable: Iterable[Any], n: int) -> Iterator[tuple[Any, ...]]validate_string
Section titled “validate_string”Validate string and convert it to python object.
This function also tries to parse floats or ints. Numeric strings containing underscores and complex-looking strings are kept unchanged because they may be PLEXOS identifiers.
Parameters
value: AnyString value to be converted to Python Object
Note
The ast is slow due to the multiple cases. Use it only on simple for loops as this could become a bottleneck.
validate_string(value: str) -> Anyno_space
Section titled “no_space”Collate function for catching strings with spaces.
no_space(a: str, b: str) -> intnormalize_names
Section titled “normalize_names”Normalize a name or list of names into a unique list of strings.
Parameters
names : str or Iterable[str]A string or an iterable of strings to normalize
Returns
list[str]A deduplicated list of the provided names
Raises
ValueErrorIf the input is neither a string nor an iterable of strings
normalize_names(*args: str | Iterable[str]) -> list[str]prepare_sql_data_params
Section titled “prepare_sql_data_params”Create list of tuples for data ingestion.
Parameters
records : list[dict[str, float]]List of records where each record is a dictionary containing ‘name’ and property valuesmemberships : list[dict[str, int]]List of membership dictionaries with ‘name’ and ‘membership_id’ keysproperty_mapping : list[tuple[str, int]]List of tuples mapping property names to property IDs
Returns
list[tuple[int, int, Any]]List of tuples containing (membership_id, property_id, value) for database insertion
prepare_sql_data_params(records: list[dict[str, float]], memberships: list[dict[str, Any]], property_mapping: list[tuple[str, int]]) -> list[tuple[int, int, Any]]create_membership_record
Section titled “create_membership_record”Create membership records for database insertion.
Parameters
object_ids : Iterable[int]Iterable of child object IDs to create memberships forchild_object_class_id : intClass ID for the child objectsparent_object_id : intID of the parent objectparent_object_class_id : intClass ID for the parent objectcollection_id : intID of the collection to which the membership belongs
Returns
list[dict[str, int]]List of dictionaries representing membership records ready for database insertion
create_membership_record(object_ids: Iterable[int], child_object_class_id: int, parent_object_id: int, parent_object_class_id: int, collection_id: int) -> list[dict[str, int]]plan_property_inserts
Section titled “plan_property_inserts”Prepare SQL parameters for property insertion.
plan_property_inserts(db: PlexosDB, records: list[dict[str, Any]], *, object_class: ClassEnum, collection: CollectionEnum, parent_class: ClassEnum) -> PreparedPropertiesResultget_system_object_name
Section titled “get_system_object_name”Return the canonical System object name for this model.
Parameters
db : PlexosDBDatabase instance to query.
Returns
strThe name of the System object.
Raises
NotFoundErrorIf no System object exists in the model.ValueErrorIf multiple System objects exist and none is named “System”.
get_system_object_name(db: PlexosDB) -> strresolve_membership_id
Section titled “resolve_membership_id”Resolve a single membership ID for property operations.
Parameters
db : PlexosDBDatabase instance to query.object_name : strName of the child object.object_class : ClassEnumClass of the child object.collection : CollectionEnumCollection defining the membership relationship.parent_class : ClassEnumClass of the parent object.parent_object_name : str | None, optionalExplicit parent object name. If provided, uses direct lookup.
Returns
intThe membership ID.
Raises
NotFoundErrorIf no matching membership is found.ValueErrorIf multiple memberships exist (ambiguous).
resolve_membership_id(db: PlexosDB, object_name: str, *, object_class: ClassEnum, collection: CollectionEnum, parent_class: ClassEnum, parent_object_name: str | None=None) -> intinsert_property_values
Section titled “insert_property_values”Insert property data and return mapping of data IDs to object names.
Parameters
db : PlexosDBDatabase instanceparams : list[tuple]List of (membership_id, property_id, value) tuplesmetadata_map : dict | None, optionalMapping of params to metadata (band, date_from, date_to), by default None
Returns
dictMapping of (membership_id, property_id, value) to (data_id, obj_name)
insert_property_values(db: PlexosDB, params: list[tuple[int, int, Any]], *, metadata_map: dict[tuple[int, int, Any, int], dict[str, Any]] | None=None) -> dict[tuple[int, int, Any, int], tuple[int, str]]apply_scenario_tags
Section titled “apply_scenario_tags”Insert scenario tags for property data.
Parameters
db : PlexosDBDatabase instanceparams : list[tuple]List of (membership_id, property_id, value) tuplesscenario : strScenario namechunksize : intNumber of records to process in each batch
apply_scenario_tags(db: PlexosDB, params: list[tuple[int, int, Any]], /, *, scenario: str, chunksize: int, data_id_map: dict[tuple[int, int, Any, int], tuple[int, str]] | None=None) -> Noneinsert_property_texts
Section titled “insert_property_texts”Add text data for properties from specified field.
Parameters
db : PlexosDBDatabase instanceparams : list[tuple]List of (membership_id, property_id, value) tuplesdata_id_map : dictMapping of (membership_id, property_id, value) to (data_id, obj_name)records : list[dict]Original records containing the text fieldfield_name : strName of the field in records containing text datatext_class : ClassEnumClassEnum for the text datametadata_map : dict | None, optionalMetadata map keyed by param tuple to drive property-specific text mapping
insert_property_texts(db: PlexosDB, params: list[tuple[int, int, Any]], /, *, data_id_map: dict[tuple[int, int, Any, int], tuple[int, str]], records: list[dict[str, Any]], field_name: str, text_class: ClassEnum, metadata_map: dict[tuple[int, int, Any, int], dict[str, Any]] | None=None) -> Nonebuild_data_id_map
Section titled “build_data_id_map”Build mapping of (membership_id, property_id, value) to (data_id, obj_name).
Parameters
db_manager : DBManagerDatabase manager instance for executing queriesparams : list[tuple]List of (membership_id, property_id, value) tuples
Returns
dictMapping of (membership_id, property_id, value) to (data_id, obj_name)
build_data_id_map(db: SQLiteManager, params: list[tuple[int, int, Any]]) -> dict[tuple[int, int, Any], tuple[int, str]]get_scenario_id
Section titled “get_scenario_id”Get or create scenario ID.
Parameters
db_manager : DBManagerDatabase manager instancescenario : strScenario name
Returns
intScenario object ID
get_scenario_id(db: PlexosDB, scenario: str) -> int