m_strat.api.ecs.ecs_register
1import numbers 2import os 3import sqlite3 4from typing import Any 5 6from .component_dispatcher import ComponentDispatcher 7from .entity import generate_id, is_uuid 8 9DEFAULT_SQL_PARAMS = { 10 "journal_mode": "WAL", 11 "synchronous": "NORMAL", 12 "cache_size": "100000", 13} 14 15INIT_TABLES = [ 16 """CREATE TABLE IF NOT EXISTS numerics( 17 uuid TEXT NOT NULL, 18 type TEXT NOT NULL, 19 name TEXT NOT NULL, 20 data NUMERIC NOT NULL, 21 PRIMARY KEY (uuid, name) 22 ) 23 """, 24 """CREATE TABLE IF NOT EXISTS text( 25 uuid TEXT NOT NULL, 26 type TEXT NOT NULL, 27 name TEXT NOT NULL, 28 data TEXT NOT NULL, 29 PRIMARY KEY (uuid, name) 30 ) 31 """, 32 """CREATE TABLE IF NOT EXISTS blobs( 33 uuid TEXT NOT NULL, 34 type TEXT NOT NULL, 35 name TEXT NOT NULL, 36 data BLOB NOT NULL, 37 PRIMARY KEY (uuid, name) 38 ) 39 """, 40] 41 42TABLE_NAMES = ("numerics", "text", "blobs") 43 44 45class ECS_Register: 46 """SQLite based interface for storing Entities for Entity Component System, defaults to use db file""" 47 48 def __init__(self, register_dir="/ecs/register", sql_params=None, dispatcher=None): 49 """Instansiates an ECS_Register object 50 Args: 51 register_dir (str, optional): The path (or address) of where the database is. Defaults to "/ecs/register". 52 sql_params (_type_, optional): overrides default sql parameters (completely) if supplied. Defaults to None. 53 dispatcher (_type_, optional): Component Dispatcher to be used (if none supplied). Defaults to None. 54 """ 55 self.register_dir = register_dir 56 self.db_file_path = os.path.join(register_dir, "proj_ents.db") 57 self.db_configs = dict(sql_params) if sql_params else DEFAULT_SQL_PARAMS 58 self.dispatcher = dispatcher if dispatcher else ComponentDispatcher() 59 60 if not os.path.exists(register_dir): 61 os.makedirs(register_dir) 62 63 self.ecs_db = sqlite3.connect(self.db_file_path) 64 65 for param_name, param_val in self.db_configs.items(): 66 self.ecs_db.execute(f"PRAGMA {param_name}={param_val};") 67 68 with self.ecs_db: 69 for init_string in INIT_TABLES: 70 self.ecs_db.execute(init_string) 71 self.ecs_db.execute( 72 "CREATE INDEX IF NOT EXISTS idx_numerics_name ON numerics(name, uuid);" 73 ) 74 self.ecs_db.execute( 75 "CREATE INDEX IF NOT EXISTS idx_text_name ON text(name, uuid);" 76 ) 77 self.ecs_db.execute( 78 "CREATE INDEX IF NOT EXISTS idx_blobs_name ON blobs(name, uuid);" 79 ) 80 81 def __del__(self): 82 """To close the database in case of unprompt exit""" 83 self.ecs_db.close() 84 85 @staticmethod 86 def get_table_from_type(v_type): 87 """Simple method to determine which table a type will exist on 88 Args: 89 v_type (type): The type to determine the table 90 Returns: 91 string: Strin of the table name that will be used for the given type 92 """ 93 if issubclass(v_type, numbers.Number): 94 return "numerics" 95 elif issubclass(v_type, str): 96 return "text" 97 else: 98 return "blobs" 99 100 @staticmethod 101 def generate_id(): 102 """Exact metod of entity generat_id, generateds UUID""" 103 return generate_id() 104 105 @staticmethod 106 def is_uuid(uuid_val): 107 """Wrapper of is_uuid method from entity file, determines if the given value is a uuid""" 108 return is_uuid(uuid_val) 109 110 @staticmethod 111 def get_data_type_string(value: any): 112 """From a value, gets the type string used by component dispatcher 113 Args: 114 value (any): target of determined type 115 Returns: 116 string: the type string as determined by ComponentDispatcher 117 """ 118 v_type = type(value) 119 return ComponentDispatcher.get_type_string(v_type) 120 121 @staticmethod 122 def get_semantic_name(comp_name: str, var_name: str = None): 123 """Helper to get name of an entity""" 124 return f"{comp_name}.{var_name}" if var_name else comp_name 125 126 def open(self): 127 """Opens the db connection if it has not started (ensuring the previous one is closed)""" 128 if self.ecs_db is not None: 129 self.ecs_db.close() 130 self.ecs_db = sqlite3.connect(self.db_file_path) 131 132 def close(self): 133 """closes the active ecs db connection (May cause errors if requests are made when closed)""" 134 self.ecs_db.close() 135 self.ecs_db = None 136 137 def load_components(self, table: str, comp_name: str, uuids: tuple = ()): 138 """Loads a list of componenets by name (with optional uuid whitelisting) 139 Args: 140 table (str): _description_ 141 comp_name (str): _description_ 142 uuids (tuple, optional): _description_. Defaults to (). 143 Returns: 144 tuple [uuid, Any]: the target components loaded 145 NB: uuids may be required for updating if needed 146 """ 147 assert table in TABLE_NAMES, f"Invalid table reference string {table}" 148 assert isinstance(comp_name, str), "Registry reads require a string name" 149 150 query = f"SELECT uuid, data, type FROM {table} WHERE name=?" 151 params = [comp_name] 152 153 if uuids: 154 query += f" AND uuid IN ({','.join('?' for _ in uuids)})" 155 params.extend(uuids) 156 157 query += " ORDER BY uuid DESC" 158 cursor = self.ecs_db.execute(query, params) 159 160 uuid_lst = [] 161 data_lst = [] 162 163 for uuid, data, d_type in cursor: 164 uuid_lst.append(uuid) 165 unpacked_data = self.dispatcher.unpack(d_type, data) 166 data_lst.append(unpacked_data) 167 168 return uuid_lst, data_lst 169 170 def _save_register(self): 171 """Saves the register as is""" 172 self.ecs_db.commit() 173 174 # FIXME? Should update_tuples be 2 lists so it is easier to manage 175 def update_components( 176 self, comp_name: str, update_tuples: tuple[Any, str], pack=True 177 ): 178 """Updates componenets by name in the db 179 Args: 180 comp_name (str): name of the components to be targetted 181 update_tuples (Any, str): tuples of (Data, uuid) to be updated 182 pack (bool, optional): _description_. Defaults to True. 183 Raises: 184 sqlite.Error: on error it rollsback and raises the exception 185 """ 186 if not update_tuples: 187 return 188 189 if pack: 190 packed_tuples = [] 191 for data, uuid in update_tuples: 192 type_str = self.get_data_type_string(data) 193 packed_val = self.dispatcher.pack(type_str, data) 194 packed_tuples.append((packed_val, uuid, comp_name)) 195 update_tuples = packed_tuples 196 else: 197 update_tuples = [(data, uuid, comp_name) for data, uuid in update_tuples] 198 199 table = self.get_table_from_type(type(update_tuples[0][0])) 200 query = f"UPDATE {table} SET data = ? WHERE uuid = ? AND name = ?" 201 cursor = self.ecs_db.cursor() 202 203 try: 204 cursor.executemany(query, update_tuples) 205 self.ecs_db.commit() 206 except sqlite3.Error as e: 207 self.ecs_db.rollback() 208 raise e 209 finally: 210 if cursor: 211 cursor.close() 212 213 def _register_components(self, table_name: str, updates, cursor=None): 214 """Inserts a componet into the ECS register (private as this is typically done publically by entity. 215 Args: 216 table_name (str): target name of the table 217 updates (list[str|numbers|blobs]): list for updates 218 cursor (_type_, optional): Active cursor (if one is in use). Defaults to None. 219 Raises: 220 e (sqlite3.Error): rollsback changes on cursor, only closing it if none is supplied, then raises the error 221 """ 222 assert table_name in TABLE_NAMES, f"target table not valid {table_name}" 223 update_query = ( 224 f"INSERT INTO {table_name} (uuid, name, type, data) VALUES (?,?,?,?)" 225 ) 226 close_cursor = False 227 228 try: 229 if not cursor: 230 close_cursor = True 231 cursor = self.ecs_db.cursor() 232 cursor.executemany(update_query, updates) 233 except sqlite3.Error as e: 234 self.ecs_db.rollback() 235 raise e 236 finally: 237 if close_cursor and cursor: 238 cursor.close() 239 240 def register_entity(self, components: dict): 241 """Using a dict to represent an entity, registers any components contained within that dictionary. 242 Args: 243 components (dict): dictionary of values to be stored 244 Raises: 245 e (Sqlite3.Error): rollsback changes and raises any db errors 246 Returns: 247 str: the uuid of the entity that was just created 248 """ 249 uuid = self.generate_id() 250 inserts = {"text": [], "blobs": [], "numerics": []} 251 252 for comp_name, comp_data in components.items(): 253 items = ( 254 vars(comp_data).items() 255 if not isinstance(comp_data, dict) 256 else comp_data.items() 257 ) 258 259 for var_name, value in items: 260 type_str = self.get_data_type_string(value) 261 ent_name = self.get_semantic_name(comp_name, var_name) 262 263 packed_data = self.dispatcher.pack(type_str, value) 264 table_name = self.get_table_from_type(type(packed_data)) 265 266 inserts[table_name].append((uuid, ent_name, type_str, packed_data)) 267 268 try: 269 cursor = self.ecs_db.cursor() 270 for table_name, update_vals in inserts.items(): 271 if update_vals: 272 self._register_components(table_name, update_vals, cursor=cursor) 273 self.ecs_db.commit() 274 except sqlite3.Error as e: 275 self.ecs_db.rollback() 276 raise e 277 finally: 278 cursor.close() 279 280 return uuid 281 282 def add_component(self, uuid: str, comp_name: str, value: Any): 283 """Adds a component to an entity by associating a value to the given uuid 284 Args: 285 uuid (str): uuid of entity to be targetted 286 comp_name (str): name of the component to be added 287 value (Any): the value to be stored 288 289 Raises: 290 ValueError: if uuid does not exist, use register entity! 291 ValueError: if exact component name already exists on entity, give it a different one! 292 e(Sqlite3.Error): Raises when db update failed, all changes are rolled back. 293 """ 294 assert self.is_uuid(uuid), f"Invalid uuid: {uuid}" 295 cursor = self.ecs_db.cursor() 296 297 entity_exists = False 298 for table in TABLE_NAMES: 299 cursor.execute(f"SELECT 1 FROM {table} WHERE uuid = ? LIMIT 1", (uuid,)) 300 if cursor.fetchone(): 301 entity_exists = True 302 break 303 304 if not entity_exists: 305 cursor.close() 306 raise ValueError(f"Entity {uuid} does not exist in registry.") 307 308 semantic_name = self.get_semantic_name(comp_name) 309 for table in TABLE_NAMES: 310 cursor.execute( 311 f"SELECT 1 FROM {table} WHERE uuid = ? AND name = ?", 312 (uuid, semantic_name), 313 ) 314 if cursor.fetchone(): 315 cursor.close() 316 raise ValueError( 317 f"Component {semantic_name} already exists on entity {uuid}." 318 ) 319 320 type_str = self.get_data_type_string(value) 321 packed_data = self.dispatcher.pack(type_str, value) 322 table_name = self.get_table_from_type(type(packed_data)) 323 324 try: 325 self._register_components( 326 table_name=table_name, 327 updates=[(uuid, semantic_name, type_str, packed_data)], 328 cursor=cursor, 329 ) 330 self.ecs_db.commit() 331 except sqlite3.Error as e: 332 self.ecs_db.rollback() 333 raise e 334 finally: 335 cursor.close() 336 337 def delete_entity(self, uuid: str): 338 """Deletes an entity given the uuide (all component within the db associated with it will be removed) 339 Args: 340 uuid (str): unique identifier of entity 341 342 Returns: 343 bool: True if succeeded, otherwise false. 344 """ 345 assert self.is_uuid(uuid), f"Invalid uuid: {uuid}" 346 cursor = self.ecs_db.cursor() 347 try: 348 for table in TABLE_NAMES: 349 cursor.execute(f"DELETE FROM {table} WHERE uuid = ?", [uuid]) 350 self.ecs_db.commit() 351 except sqlite3.Error: 352 self.ecs_db.rollback() 353 return False 354 finally: 355 cursor.close() 356 357 return True 358 359 def remove_component(self, uuid: str, comp_name: str): 360 """Removes a single value by name from an entity 361 Args: 362 uuid (str): entity to be targetted 363 comp_name (str): name of the component to be removed 364 365 Raises: 366 e (sqlite3.Error): Raises when something failed within the db, rollsback any changes before raising. 367 """ 368 assert self.is_uuid(uuid), f"Invalid uuid: {uuid}" 369 cursor = self.ecs_db.cursor() 370 target_name_pattern = f"{comp_name}.%" 371 try: 372 for table in TABLE_NAMES: 373 cursor.execute( 374 f"DELETE FROM {table} WHERE uuid = ? AND (name = ? OR name LIKE ?)", 375 (uuid, comp_name, target_name_pattern), 376 ) 377 self.ecs_db.commit() 378 except sqlite3.Error as e: 379 self.ecs_db.rollback() 380 raise e 381 finally: 382 cursor.close()
46class ECS_Register: 47 """SQLite based interface for storing Entities for Entity Component System, defaults to use db file""" 48 49 def __init__(self, register_dir="/ecs/register", sql_params=None, dispatcher=None): 50 """Instansiates an ECS_Register object 51 Args: 52 register_dir (str, optional): The path (or address) of where the database is. Defaults to "/ecs/register". 53 sql_params (_type_, optional): overrides default sql parameters (completely) if supplied. Defaults to None. 54 dispatcher (_type_, optional): Component Dispatcher to be used (if none supplied). Defaults to None. 55 """ 56 self.register_dir = register_dir 57 self.db_file_path = os.path.join(register_dir, "proj_ents.db") 58 self.db_configs = dict(sql_params) if sql_params else DEFAULT_SQL_PARAMS 59 self.dispatcher = dispatcher if dispatcher else ComponentDispatcher() 60 61 if not os.path.exists(register_dir): 62 os.makedirs(register_dir) 63 64 self.ecs_db = sqlite3.connect(self.db_file_path) 65 66 for param_name, param_val in self.db_configs.items(): 67 self.ecs_db.execute(f"PRAGMA {param_name}={param_val};") 68 69 with self.ecs_db: 70 for init_string in INIT_TABLES: 71 self.ecs_db.execute(init_string) 72 self.ecs_db.execute( 73 "CREATE INDEX IF NOT EXISTS idx_numerics_name ON numerics(name, uuid);" 74 ) 75 self.ecs_db.execute( 76 "CREATE INDEX IF NOT EXISTS idx_text_name ON text(name, uuid);" 77 ) 78 self.ecs_db.execute( 79 "CREATE INDEX IF NOT EXISTS idx_blobs_name ON blobs(name, uuid);" 80 ) 81 82 def __del__(self): 83 """To close the database in case of unprompt exit""" 84 self.ecs_db.close() 85 86 @staticmethod 87 def get_table_from_type(v_type): 88 """Simple method to determine which table a type will exist on 89 Args: 90 v_type (type): The type to determine the table 91 Returns: 92 string: Strin of the table name that will be used for the given type 93 """ 94 if issubclass(v_type, numbers.Number): 95 return "numerics" 96 elif issubclass(v_type, str): 97 return "text" 98 else: 99 return "blobs" 100 101 @staticmethod 102 def generate_id(): 103 """Exact metod of entity generat_id, generateds UUID""" 104 return generate_id() 105 106 @staticmethod 107 def is_uuid(uuid_val): 108 """Wrapper of is_uuid method from entity file, determines if the given value is a uuid""" 109 return is_uuid(uuid_val) 110 111 @staticmethod 112 def get_data_type_string(value: any): 113 """From a value, gets the type string used by component dispatcher 114 Args: 115 value (any): target of determined type 116 Returns: 117 string: the type string as determined by ComponentDispatcher 118 """ 119 v_type = type(value) 120 return ComponentDispatcher.get_type_string(v_type) 121 122 @staticmethod 123 def get_semantic_name(comp_name: str, var_name: str = None): 124 """Helper to get name of an entity""" 125 return f"{comp_name}.{var_name}" if var_name else comp_name 126 127 def open(self): 128 """Opens the db connection if it has not started (ensuring the previous one is closed)""" 129 if self.ecs_db is not None: 130 self.ecs_db.close() 131 self.ecs_db = sqlite3.connect(self.db_file_path) 132 133 def close(self): 134 """closes the active ecs db connection (May cause errors if requests are made when closed)""" 135 self.ecs_db.close() 136 self.ecs_db = None 137 138 def load_components(self, table: str, comp_name: str, uuids: tuple = ()): 139 """Loads a list of componenets by name (with optional uuid whitelisting) 140 Args: 141 table (str): _description_ 142 comp_name (str): _description_ 143 uuids (tuple, optional): _description_. Defaults to (). 144 Returns: 145 tuple [uuid, Any]: the target components loaded 146 NB: uuids may be required for updating if needed 147 """ 148 assert table in TABLE_NAMES, f"Invalid table reference string {table}" 149 assert isinstance(comp_name, str), "Registry reads require a string name" 150 151 query = f"SELECT uuid, data, type FROM {table} WHERE name=?" 152 params = [comp_name] 153 154 if uuids: 155 query += f" AND uuid IN ({','.join('?' for _ in uuids)})" 156 params.extend(uuids) 157 158 query += " ORDER BY uuid DESC" 159 cursor = self.ecs_db.execute(query, params) 160 161 uuid_lst = [] 162 data_lst = [] 163 164 for uuid, data, d_type in cursor: 165 uuid_lst.append(uuid) 166 unpacked_data = self.dispatcher.unpack(d_type, data) 167 data_lst.append(unpacked_data) 168 169 return uuid_lst, data_lst 170 171 def _save_register(self): 172 """Saves the register as is""" 173 self.ecs_db.commit() 174 175 # FIXME? Should update_tuples be 2 lists so it is easier to manage 176 def update_components( 177 self, comp_name: str, update_tuples: tuple[Any, str], pack=True 178 ): 179 """Updates componenets by name in the db 180 Args: 181 comp_name (str): name of the components to be targetted 182 update_tuples (Any, str): tuples of (Data, uuid) to be updated 183 pack (bool, optional): _description_. Defaults to True. 184 Raises: 185 sqlite.Error: on error it rollsback and raises the exception 186 """ 187 if not update_tuples: 188 return 189 190 if pack: 191 packed_tuples = [] 192 for data, uuid in update_tuples: 193 type_str = self.get_data_type_string(data) 194 packed_val = self.dispatcher.pack(type_str, data) 195 packed_tuples.append((packed_val, uuid, comp_name)) 196 update_tuples = packed_tuples 197 else: 198 update_tuples = [(data, uuid, comp_name) for data, uuid in update_tuples] 199 200 table = self.get_table_from_type(type(update_tuples[0][0])) 201 query = f"UPDATE {table} SET data = ? WHERE uuid = ? AND name = ?" 202 cursor = self.ecs_db.cursor() 203 204 try: 205 cursor.executemany(query, update_tuples) 206 self.ecs_db.commit() 207 except sqlite3.Error as e: 208 self.ecs_db.rollback() 209 raise e 210 finally: 211 if cursor: 212 cursor.close() 213 214 def _register_components(self, table_name: str, updates, cursor=None): 215 """Inserts a componet into the ECS register (private as this is typically done publically by entity. 216 Args: 217 table_name (str): target name of the table 218 updates (list[str|numbers|blobs]): list for updates 219 cursor (_type_, optional): Active cursor (if one is in use). Defaults to None. 220 Raises: 221 e (sqlite3.Error): rollsback changes on cursor, only closing it if none is supplied, then raises the error 222 """ 223 assert table_name in TABLE_NAMES, f"target table not valid {table_name}" 224 update_query = ( 225 f"INSERT INTO {table_name} (uuid, name, type, data) VALUES (?,?,?,?)" 226 ) 227 close_cursor = False 228 229 try: 230 if not cursor: 231 close_cursor = True 232 cursor = self.ecs_db.cursor() 233 cursor.executemany(update_query, updates) 234 except sqlite3.Error as e: 235 self.ecs_db.rollback() 236 raise e 237 finally: 238 if close_cursor and cursor: 239 cursor.close() 240 241 def register_entity(self, components: dict): 242 """Using a dict to represent an entity, registers any components contained within that dictionary. 243 Args: 244 components (dict): dictionary of values to be stored 245 Raises: 246 e (Sqlite3.Error): rollsback changes and raises any db errors 247 Returns: 248 str: the uuid of the entity that was just created 249 """ 250 uuid = self.generate_id() 251 inserts = {"text": [], "blobs": [], "numerics": []} 252 253 for comp_name, comp_data in components.items(): 254 items = ( 255 vars(comp_data).items() 256 if not isinstance(comp_data, dict) 257 else comp_data.items() 258 ) 259 260 for var_name, value in items: 261 type_str = self.get_data_type_string(value) 262 ent_name = self.get_semantic_name(comp_name, var_name) 263 264 packed_data = self.dispatcher.pack(type_str, value) 265 table_name = self.get_table_from_type(type(packed_data)) 266 267 inserts[table_name].append((uuid, ent_name, type_str, packed_data)) 268 269 try: 270 cursor = self.ecs_db.cursor() 271 for table_name, update_vals in inserts.items(): 272 if update_vals: 273 self._register_components(table_name, update_vals, cursor=cursor) 274 self.ecs_db.commit() 275 except sqlite3.Error as e: 276 self.ecs_db.rollback() 277 raise e 278 finally: 279 cursor.close() 280 281 return uuid 282 283 def add_component(self, uuid: str, comp_name: str, value: Any): 284 """Adds a component to an entity by associating a value to the given uuid 285 Args: 286 uuid (str): uuid of entity to be targetted 287 comp_name (str): name of the component to be added 288 value (Any): the value to be stored 289 290 Raises: 291 ValueError: if uuid does not exist, use register entity! 292 ValueError: if exact component name already exists on entity, give it a different one! 293 e(Sqlite3.Error): Raises when db update failed, all changes are rolled back. 294 """ 295 assert self.is_uuid(uuid), f"Invalid uuid: {uuid}" 296 cursor = self.ecs_db.cursor() 297 298 entity_exists = False 299 for table in TABLE_NAMES: 300 cursor.execute(f"SELECT 1 FROM {table} WHERE uuid = ? LIMIT 1", (uuid,)) 301 if cursor.fetchone(): 302 entity_exists = True 303 break 304 305 if not entity_exists: 306 cursor.close() 307 raise ValueError(f"Entity {uuid} does not exist in registry.") 308 309 semantic_name = self.get_semantic_name(comp_name) 310 for table in TABLE_NAMES: 311 cursor.execute( 312 f"SELECT 1 FROM {table} WHERE uuid = ? AND name = ?", 313 (uuid, semantic_name), 314 ) 315 if cursor.fetchone(): 316 cursor.close() 317 raise ValueError( 318 f"Component {semantic_name} already exists on entity {uuid}." 319 ) 320 321 type_str = self.get_data_type_string(value) 322 packed_data = self.dispatcher.pack(type_str, value) 323 table_name = self.get_table_from_type(type(packed_data)) 324 325 try: 326 self._register_components( 327 table_name=table_name, 328 updates=[(uuid, semantic_name, type_str, packed_data)], 329 cursor=cursor, 330 ) 331 self.ecs_db.commit() 332 except sqlite3.Error as e: 333 self.ecs_db.rollback() 334 raise e 335 finally: 336 cursor.close() 337 338 def delete_entity(self, uuid: str): 339 """Deletes an entity given the uuide (all component within the db associated with it will be removed) 340 Args: 341 uuid (str): unique identifier of entity 342 343 Returns: 344 bool: True if succeeded, otherwise false. 345 """ 346 assert self.is_uuid(uuid), f"Invalid uuid: {uuid}" 347 cursor = self.ecs_db.cursor() 348 try: 349 for table in TABLE_NAMES: 350 cursor.execute(f"DELETE FROM {table} WHERE uuid = ?", [uuid]) 351 self.ecs_db.commit() 352 except sqlite3.Error: 353 self.ecs_db.rollback() 354 return False 355 finally: 356 cursor.close() 357 358 return True 359 360 def remove_component(self, uuid: str, comp_name: str): 361 """Removes a single value by name from an entity 362 Args: 363 uuid (str): entity to be targetted 364 comp_name (str): name of the component to be removed 365 366 Raises: 367 e (sqlite3.Error): Raises when something failed within the db, rollsback any changes before raising. 368 """ 369 assert self.is_uuid(uuid), f"Invalid uuid: {uuid}" 370 cursor = self.ecs_db.cursor() 371 target_name_pattern = f"{comp_name}.%" 372 try: 373 for table in TABLE_NAMES: 374 cursor.execute( 375 f"DELETE FROM {table} WHERE uuid = ? AND (name = ? OR name LIKE ?)", 376 (uuid, comp_name, target_name_pattern), 377 ) 378 self.ecs_db.commit() 379 except sqlite3.Error as e: 380 self.ecs_db.rollback() 381 raise e 382 finally: 383 cursor.close()
SQLite based interface for storing Entities for Entity Component System, defaults to use db file
49 def __init__(self, register_dir="/ecs/register", sql_params=None, dispatcher=None): 50 """Instansiates an ECS_Register object 51 Args: 52 register_dir (str, optional): The path (or address) of where the database is. Defaults to "/ecs/register". 53 sql_params (_type_, optional): overrides default sql parameters (completely) if supplied. Defaults to None. 54 dispatcher (_type_, optional): Component Dispatcher to be used (if none supplied). Defaults to None. 55 """ 56 self.register_dir = register_dir 57 self.db_file_path = os.path.join(register_dir, "proj_ents.db") 58 self.db_configs = dict(sql_params) if sql_params else DEFAULT_SQL_PARAMS 59 self.dispatcher = dispatcher if dispatcher else ComponentDispatcher() 60 61 if not os.path.exists(register_dir): 62 os.makedirs(register_dir) 63 64 self.ecs_db = sqlite3.connect(self.db_file_path) 65 66 for param_name, param_val in self.db_configs.items(): 67 self.ecs_db.execute(f"PRAGMA {param_name}={param_val};") 68 69 with self.ecs_db: 70 for init_string in INIT_TABLES: 71 self.ecs_db.execute(init_string) 72 self.ecs_db.execute( 73 "CREATE INDEX IF NOT EXISTS idx_numerics_name ON numerics(name, uuid);" 74 ) 75 self.ecs_db.execute( 76 "CREATE INDEX IF NOT EXISTS idx_text_name ON text(name, uuid);" 77 ) 78 self.ecs_db.execute( 79 "CREATE INDEX IF NOT EXISTS idx_blobs_name ON blobs(name, uuid);" 80 )
Instansiates an ECS_Register object Args: register_dir (str, optional): The path (or address) of where the database is. Defaults to "/ecs/register". sql_params (_type_, optional): overrides default sql parameters (completely) if supplied. Defaults to None. dispatcher (_type_, optional): Component Dispatcher to be used (if none supplied). Defaults to None.
86 @staticmethod 87 def get_table_from_type(v_type): 88 """Simple method to determine which table a type will exist on 89 Args: 90 v_type (type): The type to determine the table 91 Returns: 92 string: Strin of the table name that will be used for the given type 93 """ 94 if issubclass(v_type, numbers.Number): 95 return "numerics" 96 elif issubclass(v_type, str): 97 return "text" 98 else: 99 return "blobs"
Simple method to determine which table a type will exist on Args: v_type (type): The type to determine the table Returns: string: Strin of the table name that will be used for the given type
101 @staticmethod 102 def generate_id(): 103 """Exact metod of entity generat_id, generateds UUID""" 104 return generate_id()
Exact metod of entity generat_id, generateds UUID
106 @staticmethod 107 def is_uuid(uuid_val): 108 """Wrapper of is_uuid method from entity file, determines if the given value is a uuid""" 109 return is_uuid(uuid_val)
Wrapper of is_uuid method from entity file, determines if the given value is a uuid
111 @staticmethod 112 def get_data_type_string(value: any): 113 """From a value, gets the type string used by component dispatcher 114 Args: 115 value (any): target of determined type 116 Returns: 117 string: the type string as determined by ComponentDispatcher 118 """ 119 v_type = type(value) 120 return ComponentDispatcher.get_type_string(v_type)
From a value, gets the type string used by component dispatcher Args: value (any): target of determined type Returns: string: the type string as determined by ComponentDispatcher
122 @staticmethod 123 def get_semantic_name(comp_name: str, var_name: str = None): 124 """Helper to get name of an entity""" 125 return f"{comp_name}.{var_name}" if var_name else comp_name
Helper to get name of an entity
127 def open(self): 128 """Opens the db connection if it has not started (ensuring the previous one is closed)""" 129 if self.ecs_db is not None: 130 self.ecs_db.close() 131 self.ecs_db = sqlite3.connect(self.db_file_path)
Opens the db connection if it has not started (ensuring the previous one is closed)
133 def close(self): 134 """closes the active ecs db connection (May cause errors if requests are made when closed)""" 135 self.ecs_db.close() 136 self.ecs_db = None
closes the active ecs db connection (May cause errors if requests are made when closed)
138 def load_components(self, table: str, comp_name: str, uuids: tuple = ()): 139 """Loads a list of componenets by name (with optional uuid whitelisting) 140 Args: 141 table (str): _description_ 142 comp_name (str): _description_ 143 uuids (tuple, optional): _description_. Defaults to (). 144 Returns: 145 tuple [uuid, Any]: the target components loaded 146 NB: uuids may be required for updating if needed 147 """ 148 assert table in TABLE_NAMES, f"Invalid table reference string {table}" 149 assert isinstance(comp_name, str), "Registry reads require a string name" 150 151 query = f"SELECT uuid, data, type FROM {table} WHERE name=?" 152 params = [comp_name] 153 154 if uuids: 155 query += f" AND uuid IN ({','.join('?' for _ in uuids)})" 156 params.extend(uuids) 157 158 query += " ORDER BY uuid DESC" 159 cursor = self.ecs_db.execute(query, params) 160 161 uuid_lst = [] 162 data_lst = [] 163 164 for uuid, data, d_type in cursor: 165 uuid_lst.append(uuid) 166 unpacked_data = self.dispatcher.unpack(d_type, data) 167 data_lst.append(unpacked_data) 168 169 return uuid_lst, data_lst
Loads a list of componenets by name (with optional uuid whitelisting) Args: table (str): _description_ comp_name (str): _description_ uuids (tuple, optional): _description_. Defaults to (). Returns: tuple [uuid, Any]: the target components loaded NB: uuids may be required for updating if needed
176 def update_components( 177 self, comp_name: str, update_tuples: tuple[Any, str], pack=True 178 ): 179 """Updates componenets by name in the db 180 Args: 181 comp_name (str): name of the components to be targetted 182 update_tuples (Any, str): tuples of (Data, uuid) to be updated 183 pack (bool, optional): _description_. Defaults to True. 184 Raises: 185 sqlite.Error: on error it rollsback and raises the exception 186 """ 187 if not update_tuples: 188 return 189 190 if pack: 191 packed_tuples = [] 192 for data, uuid in update_tuples: 193 type_str = self.get_data_type_string(data) 194 packed_val = self.dispatcher.pack(type_str, data) 195 packed_tuples.append((packed_val, uuid, comp_name)) 196 update_tuples = packed_tuples 197 else: 198 update_tuples = [(data, uuid, comp_name) for data, uuid in update_tuples] 199 200 table = self.get_table_from_type(type(update_tuples[0][0])) 201 query = f"UPDATE {table} SET data = ? WHERE uuid = ? AND name = ?" 202 cursor = self.ecs_db.cursor() 203 204 try: 205 cursor.executemany(query, update_tuples) 206 self.ecs_db.commit() 207 except sqlite3.Error as e: 208 self.ecs_db.rollback() 209 raise e 210 finally: 211 if cursor: 212 cursor.close()
Updates componenets by name in the db Args: comp_name (str): name of the components to be targetted update_tuples (Any, str): tuples of (Data, uuid) to be updated pack (bool, optional): _description_. Defaults to True. Raises: sqlite.Error: on error it rollsback and raises the exception
241 def register_entity(self, components: dict): 242 """Using a dict to represent an entity, registers any components contained within that dictionary. 243 Args: 244 components (dict): dictionary of values to be stored 245 Raises: 246 e (Sqlite3.Error): rollsback changes and raises any db errors 247 Returns: 248 str: the uuid of the entity that was just created 249 """ 250 uuid = self.generate_id() 251 inserts = {"text": [], "blobs": [], "numerics": []} 252 253 for comp_name, comp_data in components.items(): 254 items = ( 255 vars(comp_data).items() 256 if not isinstance(comp_data, dict) 257 else comp_data.items() 258 ) 259 260 for var_name, value in items: 261 type_str = self.get_data_type_string(value) 262 ent_name = self.get_semantic_name(comp_name, var_name) 263 264 packed_data = self.dispatcher.pack(type_str, value) 265 table_name = self.get_table_from_type(type(packed_data)) 266 267 inserts[table_name].append((uuid, ent_name, type_str, packed_data)) 268 269 try: 270 cursor = self.ecs_db.cursor() 271 for table_name, update_vals in inserts.items(): 272 if update_vals: 273 self._register_components(table_name, update_vals, cursor=cursor) 274 self.ecs_db.commit() 275 except sqlite3.Error as e: 276 self.ecs_db.rollback() 277 raise e 278 finally: 279 cursor.close() 280 281 return uuid
Using a dict to represent an entity, registers any components contained within that dictionary. Args: components (dict): dictionary of values to be stored Raises: e (Sqlite3.Error): rollsback changes and raises any db errors Returns: str: the uuid of the entity that was just created
283 def add_component(self, uuid: str, comp_name: str, value: Any): 284 """Adds a component to an entity by associating a value to the given uuid 285 Args: 286 uuid (str): uuid of entity to be targetted 287 comp_name (str): name of the component to be added 288 value (Any): the value to be stored 289 290 Raises: 291 ValueError: if uuid does not exist, use register entity! 292 ValueError: if exact component name already exists on entity, give it a different one! 293 e(Sqlite3.Error): Raises when db update failed, all changes are rolled back. 294 """ 295 assert self.is_uuid(uuid), f"Invalid uuid: {uuid}" 296 cursor = self.ecs_db.cursor() 297 298 entity_exists = False 299 for table in TABLE_NAMES: 300 cursor.execute(f"SELECT 1 FROM {table} WHERE uuid = ? LIMIT 1", (uuid,)) 301 if cursor.fetchone(): 302 entity_exists = True 303 break 304 305 if not entity_exists: 306 cursor.close() 307 raise ValueError(f"Entity {uuid} does not exist in registry.") 308 309 semantic_name = self.get_semantic_name(comp_name) 310 for table in TABLE_NAMES: 311 cursor.execute( 312 f"SELECT 1 FROM {table} WHERE uuid = ? AND name = ?", 313 (uuid, semantic_name), 314 ) 315 if cursor.fetchone(): 316 cursor.close() 317 raise ValueError( 318 f"Component {semantic_name} already exists on entity {uuid}." 319 ) 320 321 type_str = self.get_data_type_string(value) 322 packed_data = self.dispatcher.pack(type_str, value) 323 table_name = self.get_table_from_type(type(packed_data)) 324 325 try: 326 self._register_components( 327 table_name=table_name, 328 updates=[(uuid, semantic_name, type_str, packed_data)], 329 cursor=cursor, 330 ) 331 self.ecs_db.commit() 332 except sqlite3.Error as e: 333 self.ecs_db.rollback() 334 raise e 335 finally: 336 cursor.close()
Adds a component to an entity by associating a value to the given uuid Args: uuid (str): uuid of entity to be targetted comp_name (str): name of the component to be added value (Any): the value to be stored
Raises: ValueError: if uuid does not exist, use register entity! ValueError: if exact component name already exists on entity, give it a different one! e(Sqlite3.Error): Raises when db update failed, all changes are rolled back.
338 def delete_entity(self, uuid: str): 339 """Deletes an entity given the uuide (all component within the db associated with it will be removed) 340 Args: 341 uuid (str): unique identifier of entity 342 343 Returns: 344 bool: True if succeeded, otherwise false. 345 """ 346 assert self.is_uuid(uuid), f"Invalid uuid: {uuid}" 347 cursor = self.ecs_db.cursor() 348 try: 349 for table in TABLE_NAMES: 350 cursor.execute(f"DELETE FROM {table} WHERE uuid = ?", [uuid]) 351 self.ecs_db.commit() 352 except sqlite3.Error: 353 self.ecs_db.rollback() 354 return False 355 finally: 356 cursor.close() 357 358 return True
Deletes an entity given the uuide (all component within the db associated with it will be removed) Args: uuid (str): unique identifier of entity
Returns: bool: True if succeeded, otherwise false.
360 def remove_component(self, uuid: str, comp_name: str): 361 """Removes a single value by name from an entity 362 Args: 363 uuid (str): entity to be targetted 364 comp_name (str): name of the component to be removed 365 366 Raises: 367 e (sqlite3.Error): Raises when something failed within the db, rollsback any changes before raising. 368 """ 369 assert self.is_uuid(uuid), f"Invalid uuid: {uuid}" 370 cursor = self.ecs_db.cursor() 371 target_name_pattern = f"{comp_name}.%" 372 try: 373 for table in TABLE_NAMES: 374 cursor.execute( 375 f"DELETE FROM {table} WHERE uuid = ? AND (name = ? OR name LIKE ?)", 376 (uuid, comp_name, target_name_pattern), 377 ) 378 self.ecs_db.commit() 379 except sqlite3.Error as e: 380 self.ecs_db.rollback() 381 raise e 382 finally: 383 cursor.close()
Removes a single value by name from an entity Args: uuid (str): entity to be targetted comp_name (str): name of the component to be removed
Raises: e (sqlite3.Error): Raises when something failed within the db, rollsback any changes before raising.