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()
DEFAULT_SQL_PARAMS = {'journal_mode': 'WAL', 'synchronous': 'NORMAL', 'cache_size': '100000'}
INIT_TABLES = ['CREATE TABLE IF NOT EXISTS numerics( \n uuid TEXT NOT NULL,\n type TEXT NOT NULL,\n name TEXT NOT NULL,\n data NUMERIC NOT NULL,\n PRIMARY KEY (uuid, name)\n )\n ', 'CREATE TABLE IF NOT EXISTS text( \n uuid TEXT NOT NULL,\n type TEXT NOT NULL,\n name TEXT NOT NULL,\n data TEXT NOT NULL,\n PRIMARY KEY (uuid, name)\n )\n ', 'CREATE TABLE IF NOT EXISTS blobs( \n uuid TEXT NOT NULL,\n type TEXT NOT NULL,\n name TEXT NOT NULL,\n data BLOB NOT NULL,\n PRIMARY KEY (uuid, name)\n )\n ']
TABLE_NAMES = ('numerics', 'text', 'blobs')
class ECS_Register:
 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

ECS_Register(register_dir='/ecs/register', sql_params=None, dispatcher=None)
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.

register_dir
db_file_path
db_configs
dispatcher
ecs_db
@staticmethod
def get_table_from_type(v_type):
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

@staticmethod
def generate_id():
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

@staticmethod
def is_uuid(uuid_val):
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

@staticmethod
def get_data_type_string(value: <built-in function any>):
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

@staticmethod
def get_semantic_name(comp_name: str, var_name: str = None):
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

def open(self):
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)

def close(self):
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)

def load_components(self, table: str, comp_name: str, uuids: tuple = ()):
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

def update_components( self, comp_name: str, update_tuples: tuple[typing.Any, str], pack=True):
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

def register_entity(self, components: dict):
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

def add_component(self, uuid: str, comp_name: str, value: Any):
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.

def delete_entity(self, uuid: str):
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.

def remove_component(self, uuid: str, comp_name: str):
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.