osbot-utils 1.7.7__py3-none-any.whl

osbot_utils/helpers/sqlite/Sqlite__Table.py

@@ -0,0 +1,293 @@
+import re
+
+from osbot_utils.base_classes.Kwargs_To_Self                import Kwargs_To_Self
+from osbot_utils.decorators.lists.filter_list               import filter_list
+from osbot_utils.decorators.lists.index_by                  import index_by
+from osbot_utils.decorators.methods.cache_on_self           import cache_on_self
+from osbot_utils.helpers.Print_Table                        import Print_Table
+from osbot_utils.helpers.sqlite.Sqlite__Database            import Sqlite__Database
+from osbot_utils.helpers.sqlite.Sqlite__Globals             import DEFAULT_FIELD_NAME__ID, ROW_BASE_CLASS, SQL_TABLE__MODULE_NAME__ROW_SCHEMA
+from osbot_utils.helpers.sqlite.models.Sqlite__Field__Type  import Sqlite__Field__Type
+from osbot_utils.utils.Dev import pprint
+from osbot_utils.utils.Json                                 import json_load
+from osbot_utils.utils.Misc                                 import list_set
+from osbot_utils.utils.Objects import base_types, default_value, bytes_to_obj, obj_to_bytes
+from osbot_utils.utils.Str                                  import str_cap_snake_case
+
+class Sqlite__Table(Kwargs_To_Self):
+    database        : Sqlite__Database
+    table_name      : str
+    row_schema      : type
+    auto_pickle_blob: bool = False
+
+    def __setattr__(self, key, value):
+        if key =='table_name':                                                              # SQL injection protection
+            if re.search(r'[^a-zA-Z0-9_-]',value):                                  # make sure table name cannot be used to inject SQL, str_safe uses r'[^a-zA-Z0-9_-]' regex, i.e. only allows letter, numbers and the chars - _
+                raise ValueError( "Invalid table name. Table names can only contain alphanumeric characters, numbers, underscores, and hyphens.")
+
+        super().__setattr__(key, value)
+
+    def _table_create(self):                                                                         # todo: Sqlite__Table__Create needs to be refactored (since that was created before we had support for table_class )
+        from osbot_utils.helpers.sqlite.Sqlite__Table__Create import Sqlite__Table__Create
+        table_create       = Sqlite__Table__Create(self.table_name)                                  # todo: fix this workflow
+        table_create.table = self
+        return table_create                                                                            #       since it is weird to have to overwrite the table vale of Sqlite__Table__Create
+
+    def add_row(self, **row_data):
+        new_row  = self.new_row_obj(row_data)
+        return self.row_add(new_row)
+
+    def add_row_and_commit(self, **row_data):
+        new_row  = self.new_row_obj(row_data)
+        return self.row_add_and_commit(new_row)
+
+    def clear(self):
+        sql_query = self.sql_builder().command__delete_table()
+        return self.cursor().execute_and_commit(sql_query)
+
+    def create(self):
+        table_create = self._table_create()
+        return table_create.create_table__from_row_schema(self.row_schema)
+
+    def commit(self):
+        return self.cursor().commit()
+
+    def connection(self):
+        return self.database.connection()
+
+    def cursor(self):
+        return self.database.cursor()
+
+    def delete(self):
+        if self.exists() is False:                                  # if table doesn't exist
+            return False                                            # return False
+        self.cursor().table_delete(self.table_name)                 # delete table
+        return self.exists() is False                               # confirm table does not exist
+
+    def exists(self):
+        return self.cursor().table_exists(self.table_name)
+
+    def fields(self):
+        return self.schema(index_by='name')
+
+    @cache_on_self
+    def fields__cached(self):
+        return self.fields()
+
+    def fields_data__from_raw_json(self, target_field):                     # todo: see if this should be refactored into a Select/Data filtering class
+        fields_data = []
+        for raw_field_data in self.select_field_values(target_field):
+            fields_data.append(json_load(raw_field_data))
+        return fields_data
+
+    def fields_types__cached(self, exclude_id=False):
+        fields_types = {}
+        for field_name, field_data in self.fields__cached().items():
+            if exclude_id and field_name == DEFAULT_FIELD_NAME__ID:
+                continue
+            sqlite_field_type = field_data['type']
+            field_type = Sqlite__Field__Type.enum_map().get(sqlite_field_type)
+            fields_types[field_name] = field_type
+        return fields_types
+
+    def fields_names__cached(self, exclude_id=False, include_star_field=False):
+        field_names = list_set(self.fields__cached())
+        if exclude_id:
+            field_names.remove(DEFAULT_FIELD_NAME__ID)
+        if include_star_field:
+            field_names.append('*')
+        return field_names
+
+    def index_create(self, index_field):
+        if index_field not in self.fields_names__cached():
+            raise ValueError(f"in index_create, invalid target_field: {index_field}")
+
+        index_name = self.index_name(index_field)
+        sql_query = f'CREATE INDEX IF NOT EXISTS {index_name} ON {self.table_name}({index_field});'
+        return self.cursor().execute_and_commit(sql_query)
+
+    def index_delete(self, index_name):
+        sql_query = f'DROP INDEX IF EXISTS {index_name};'
+        return self.cursor().execute_and_commit(sql_query)
+
+    def index_exists(self, index_field):
+        index_name = self.index_name(index_field)
+        return index_name in self.indexes()
+
+    def index_name(self, index_field):
+        return f'idx__{self.table_name}__{index_field}'
+
+    def list_of_field_name_from_rows(self, rows, field_name):
+        return [row[field_name] for row in rows]
+
+    def indexes(self):
+        field_name        = 'name'
+        return_fields     = [field_name]
+        table_sqlite_master = self.database.table__sqlite_master()
+        table_type        = 'index'
+        query_conditions  = {'type': table_type, 'tbl_name': self.table_name}
+        sql_query, params = table_sqlite_master.sql_builder().query_select_fields_with_conditions(return_fields, query_conditions)
+        rows              = table_sqlite_master.cursor().execute__fetch_all(sql_query, params)
+        return table_sqlite_master.list_of_field_name_from_rows(rows, field_name)
+
+    def new_row_obj(self, row_data=None):
+        if self.row_schema:
+            new_obj = self.row_schema()
+            if row_data and ROW_BASE_CLASS in base_types(new_obj):
+                row_data = self.parse_new_row_data(row_data)
+                new_obj.update_from_kwargs(**row_data)
+            return new_obj
+
+    def not_exists(self):
+        return self.exists() is False
+
+    def parse_new_row_data(self, row_data):
+        if row_data:
+            if self.auto_pickle_blob:
+                fields = self.fields__cached()
+                picked_row_data = {}
+                for field_name, field_value in row_data.items():
+                    field_type = fields.get(field_name, {}).get('type')
+                    if field_type == 'BLOB':
+                        picked_row_data[field_name] = obj_to_bytes(field_value)
+                    else:
+                        picked_row_data[field_name] = field_value
+                return picked_row_data
+        return row_data
+    def parse_row(self, row):
+        if row and self.auto_pickle_blob:
+            fields = self.fields__cached()
+            for field_name, field_value in row.items():
+                field_type = fields.get(field_name, {}).get('type')
+                if field_type == 'BLOB':
+                    row[field_name] = bytes_to_obj(field_value)
+        return row
+
+    def parse_rows(self, rows):
+        return [self.parse_row(row) for row in rows]
+
+    def print(self, **kwargs):
+        return Print_Table(**kwargs).print(self.rows())
+
+    def row_add(self, row_obj=None):
+        invalid_reason = self.sql_builder().validate_row_obj(row_obj)
+        if invalid_reason:
+            raise Exception(f"in row_add the provided row_obj is not valid: {invalid_reason}")
+        return self.row_add_record(row_obj.__dict__)
+
+    def row_add_and_commit(self, row_obj=None):
+        if self.row_add(row_obj).get('status') == 'ok':
+            self.commit()
+            return row_obj                                      # this allows the original callers to see the actual object that was added to the table
+
+    def row_add_record(self, record):
+        validation_result = self.validate_record_with_schema(record)
+        if validation_result:
+            raise ValueError(f"row_add_record, validation_result for provided record failed with {validation_result}")
+
+        sql_command,params = self.sql_builder().command_for_insert(record)
+        return self.cursor().execute(sql_command, params)                    # Execute the SQL statement with the filtered data values
+
+    def row_schema__create_from_current_field_types(self):
+        exclude_field_id                 = True                                                                 # don't include the id field since in most cases the row_schema doesn't include it
+        field_types                      = self.fields_types__cached(exclude_id=exclude_field_id)               # mapping with field name to field type (in python)
+        caps_table_name                  = str_cap_snake_case(self.table_name)
+        dynamic_class_name               = f'Row_Schema__{caps_table_name}'                                    # name that we will give to the dynamic class generated
+        dynamic_class_dict               = { k: default_value(v) for k, v in field_types.items()}              # assign the field values its default value (for that type)
+        dynamic_class_dict['__module__'] = SQL_TABLE__MODULE_NAME__ROW_SCHEMA                                            # set the module name
+        Dynamic_Class                    = type(dynamic_class_name, (ROW_BASE_CLASS,), dynamic_class_dict)     # Create the dynamic class
+        Dynamic_Class.__annotations__    = field_types                                                         # Set annotations of the new Dynamic_Class to be the mappings we have from field_types
+        return Dynamic_Class                                                                                   # return the Dynamic class (whose fields should match the field_types)
+
+    def row_schema__set_from_field_types(self):
+        self.row_schema = self.row_schema__create_from_current_field_types()
+        return self
+
+    def row_update(self, update_fields, query_conditions ):
+        sql_query, params = self.sql_builder().sql_query_update_with_conditions(update_fields, query_conditions)
+        return self.cursor().execute_and_commit(sql_query, params)
+
+    def rows(self, fields_names=None, limit=None):
+        sql_query = self.sql_builder(limit=limit).query_for_fields(fields_names)
+        rows = self.cursor().execute__fetch_all(sql_query)
+        return self.parse_rows(rows)
+
+    def rows_add(self, records, commit=True):           # todo: refactor to use row_add
+        for record in records:
+            if type(record) is dict:
+                self.row_add_record(record)
+            else:
+                self.row_add(row_obj=record)
+        if commit:
+            self.cursor().commit()
+        return self
+
+    def rows_delete_where(self, **query_conditions):
+        sql_query,params = self.sql_builder().command__delete_where(query_conditions)
+        return self.cursor().execute_and_commit(sql_query,params)
+
+    def select_row_where(self, **kwargs):
+        rows = self.select_rows_where(**kwargs)                     # execute the query
+        if len(rows) == 1:                                          # only return a result if there is one row
+            return rows[0]
+        return None                                                 # return None if there no match or more than one match
+
+    def select_rows_where(self, **kwargs):
+        sql_query, params = self.sql_builder().query_for_select_rows_where(**kwargs)
+        rows = self.cursor().execute__fetch_all(sql_query, params)                      # Execute the query and return the results
+        return self.parse_rows(rows)
+
+    def select_rows_where_one(self, **kwargs):
+        sql_query, params = self.sql_builder().query_for_select_rows_where(**kwargs)
+        row = self.cursor().execute__fetch_one(sql_query, params)                      # Execute the query and return the results
+        return self.parse_row(row)
+
+    def select_field_values(self, field_name):
+        if field_name not in self.fields__cached():
+            raise ValueError(f'in select_all_vales_from_field, the provide field_name "{field_name}" does not exist in the current table "{self.table_name}"')
+
+        sql_query  = self.sql_builder().query_for_fields([field_name])
+        rows       = self.cursor().execute__fetch_all(sql_query)        # Execute the SQL query and get all rows
+        all_rows   = self.parse_rows(rows)
+        all_values = [row[field_name] for row in all_rows]              # Extract the desired field from each row in the result set
+        return all_values
+
+    @index_by
+    def schema(self):
+        return self.cursor().table_schema(self.table_name)
+
+    @filter_list
+    def schema__by_name_type(self):
+        return {item.get('name'): item.get('type') for item in self.schema()}
+
+    def size(self):
+        sql_query = self.sql_builder().query_for_size()
+        result = self.cursor().execute__fetch_one(sql_query)
+        return result.get('size')
+
+    @cache_on_self
+    def sql_builder(self, limit=None):
+        from osbot_utils.helpers.sqlite.sql_builder.SQL_Builder import SQL_Builder
+        return SQL_Builder(table=self, limit=limit)
+
+    def validate_record_with_schema(self, record):                                          # todo: refactor out to a validator class
+        schema = self.fields__cached()
+
+        extra_keys = [key for key in record if key not in schema]                           # Check for keys in record that are not in the schema
+        if extra_keys:
+            return f'Validation error: Unrecognized keys {extra_keys} in record.'
+        return ''                                                                           # If we reach here, the record is valid
+
+    # query helpers
+    def contains(self, **kwargs):
+        result = self.where_one(**kwargs)
+        return result is not None
+
+    def not_contains(self, **kwargs):
+        return self.contains(**kwargs) is False
+
+    def where(self, **kwargs):
+        return self.select_rows_where(**kwargs)
+
+    def where_one(self, **kwargs):
+        return self.select_rows_where_one(**kwargs)

osbot_utils/helpers/sqlite/Sqlite__Table__Create.py

@@ -0,0 +1,96 @@
+import inspect
+from osbot_utils.base_classes.Kwargs_To_Self                import Kwargs_To_Self
+from osbot_utils.decorators.lists.filter_list               import filter_list
+from osbot_utils.helpers.sqlite.Sqlite__Field               import Sqlite__Field
+from osbot_utils.helpers.sqlite.Sqlite__Table               import Sqlite__Table, DEFAULT_FIELD_NAME__ID
+from osbot_utils.helpers.sqlite.models.Sqlite__Field__Type  import Sqlite__Field__Type
+
+class Sqlite__Table__Create(Kwargs_To_Self):
+    fields  : list[Sqlite__Field]
+    table   : Sqlite__Table
+
+    def __init__(self, table_name):
+        super().__init__()
+        self.table.table_name = table_name
+        self.set_default_fields()
+
+    def add_field(self, field_data: dict):
+        sqlite_field = Sqlite__Field.from_json(field_data)
+        if sqlite_field:
+            self.fields.append(sqlite_field)
+            return True
+        return False
+
+    def add_fields(self, fields_data:list[dict]):
+        results = []
+        if fields_data:
+            for field_data in fields_data:
+                results.append(self.add_field(field_data))
+        return results
+
+    def add_fields_from_class(self, table_class):
+        if inspect.isclass(table_class):
+            for field_name, field_type in table_class.__annotations__.items():
+                self.add_field_with_type(field_name, field_type)
+        return self
+
+    def add_field_with_type(self, field_name, field_type):
+        if inspect.isclass(field_type):
+            field_type = Sqlite__Field__Type.type_map().get(field_type)
+
+        return self.add_field(dict(name=field_name, type=field_type))
+
+    def add_field__text(self, field_name):
+        return self.add_field_with_type(field_name=field_name, field_type=str)
+
+    def add_fields__text(self, *fields_name):
+        for field_name in fields_name:
+            self.add_field__text(field_name=field_name)
+        return self
+
+    def create_table(self):
+        sql_query = self.sql_for__create_table()
+        if self.table.not_exists():
+            self.table.cursor().execute(sql_query)
+            return self.table.exists()
+        return False
+
+    def create_table__from_row_schema(self, row_schema):  # todo add check if there is an index field (which is now supported since it clashes with the one that is added by default)
+        self.add_fields_from_class(row_schema)
+        self.table.row_schema = row_schema
+        return self.create_table()
+
+    @filter_list
+    def fields_json(self):
+        return [field.json() for field in self.fields]
+
+    def fields__by_name_type(self):
+        return { item.get('name'): item.get('type') for item in self.fields_json() }
+
+    def fields_reset(self):
+        self.fields = []
+        return self
+
+    def database(self):
+        return self.table.database
+
+    def set_default_fields(self):
+        self.add_field(dict(name=DEFAULT_FIELD_NAME__ID, type="INTEGER", pk=True))        # by default every table has an id field
+        return self
+
+    def sql_for__create_table(self):
+        field_definitions = [field.text_for_create_table() for field in self.fields]
+        primary_keys = [field.name for field in self.fields if field.pk]
+        foreign_keys_constraints = [field.text_for_create_table() for field in self.fields if field.is_foreign_key]
+
+        # Handling composite primary keys if necessary
+        if len(primary_keys) > 1:
+            pk_constraint = f"PRIMARY KEY ({', '.join(primary_keys)})"
+            field_definitions.append(pk_constraint)
+
+        # Adding foreign key constraints separately if there are any
+        if foreign_keys_constraints:
+            field_definitions.extend(foreign_keys_constraints)
+
+        table_definition = f"CREATE TABLE {self.table.table_name} ({', '.join(field_definitions)});"
+        return table_definition

osbot_utils/helpers/sqlite/Temp_Sqlite__Database__Disk.py

@@ -0,0 +1,17 @@
+from osbot_utils.base_classes.Kwargs_To_Self import Kwargs_To_Self
+from osbot_utils.helpers.sqlite.Sqlite__Database import Sqlite__Database, SQLITE_DATABASE_PATH__IN_MEMORY
+
+
+class Temp_Sqlite__Database__Disk(Kwargs_To_Self):
+    database : Sqlite__Database
+
+    def __init__(self):
+        super().__init__()
+        self.database.in_memory = False
+
+    def __enter__(self):
+        self.database.connect()
+        return self.database
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.database.delete()

osbot_utils/helpers/sqlite/Temp_Sqlite__Table.py

@@ -0,0 +1,23 @@
+from osbot_utils.base_classes.Kwargs_To_Self import Kwargs_To_Self
+from osbot_utils.helpers.sqlite.Sqlite__Database import Sqlite__Database
+from osbot_utils.helpers.sqlite.Sqlite__Table import Sqlite__Table
+from osbot_utils.utils.Dev import pprint
+from osbot_utils.utils.Misc import random_text
+
+
+class Temp_Sqlite__Table(Kwargs_To_Self):
+    table_name   : str           = random_text(prefix='random_table')
+    table_fields : list
+    table        : Sqlite__Table
+
+
+    def __init__(self):
+        super().__init__()
+        self.table.table_name   = self.table_name
+
+    def __enter__(self):
+        self.table.create()
+        return self.table
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.table.delete()

osbot_utils/helpers/sqlite/domains/Sqlite__Cache__Requests.py

@@ -0,0 +1,214 @@
+import types
+from osbot_utils.base_classes.Kwargs_To_Self                    import Kwargs_To_Self
+from osbot_utils.helpers.sqlite.domains.Sqlite__DB__Requests    import Sqlite__DB__Requests
+from osbot_utils.utils.Json                                     import json_dumps, json_loads
+from osbot_utils.utils.Misc                                     import str_sha256, timestamp_utc_now
+from osbot_utils.utils.Objects                                  import pickle_save_to_bytes, pickle_load_from_bytes
+
+
+class Sqlite__Cache__Requests(Kwargs_To_Self):
+    add_timestamp     : bool                 = True
+    enabled           : bool                 = True
+    update_mode       : bool                 = False
+    cache_only_mode   : bool                 = False
+    sqlite_requests   : Sqlite__DB__Requests = None
+    pickle_response   : bool                 = False
+    capture_exceptions: bool                 = False                # once this is working, it might be more useful to have this set to true
+    exception_classes : list
+    on_invoke_target  : types.FunctionType
+
+    def __init__(self, db_path=None, db_name=None, table_name=None):
+        self.sqlite_requests = Sqlite__DB__Requests(db_path=db_path, db_name=db_name, table_name=table_name)
+        super().__init__()
+
+    def cache_add(self, request_data, response_data):
+        new_row_obj = self.create_new_cache_obj(request_data, response_data)
+        return self.cache_table().row_add_and_commit(new_row_obj)
+
+    def cache_delete(self, request_data):
+        request_data        = json_dumps(request_data)
+        request_data_sha256 = str_sha256(request_data)
+        return self.cache_table().rows_delete_where(request_hash=request_data_sha256)
+
+    def cache_entries(self):
+        return self.cache_table().rows()
+
+    def cache_entry(self, request_data):
+        request_data        = json_dumps(request_data)
+        request_data_sha256 = str_sha256(request_data)
+        data                = self.cache_table().select_rows_where(request_hash=request_data_sha256)
+        if len(data) > 0:                       # todo: add logic to handle (or log), where there are multiple entries with the same hash
+            return data[0]
+        return {}
+
+    def cache_entry_comments(self, model_id, body):
+        cache_entry = self.cache_entry_for_request_params(model_id=model_id, body=body)
+        return cache_entry.get('comments')
+
+    def cache_entry_comments_update(self, model_id, body, new_comments):
+        cache_entry      = self.cache_entry_for_request_params(model_id=model_id, body=body)
+        request_hash     = cache_entry.get('request_hash')
+        update_fields    = dict(comments=new_comments)
+        query_conditions = dict(request_hash=request_hash)
+        result           = self.cache_table().row_update(update_fields, query_conditions)
+        return result
+
+    def cache_entry_for_request_params(self, *args, **target_kwargs):
+        request_data = self.cache_request_data(*args, **target_kwargs)
+        return self.cache_entry(request_data)
+
+    def create_new_cache_data(self, request_data, response_data):
+        request_data_json  = json_dumps(request_data)
+        request_data_hash  = str_sha256(request_data_json)
+        if self.add_timestamp:
+            timestamp = timestamp_utc_now()
+        else:
+            timestamp = 0
+        cache_cata = dict(request_data   = request_data_json   ,
+                          request_hash   = request_data_hash   ,
+                          response_bytes = b''                 ,
+                          response_data  = ''                  ,
+                          response_hash  = ''                  ,
+                          timestamp      = timestamp           )
+        if self.pickle_response:
+            cache_cata['response_bytes'] = response_data
+        else:
+            response_data_json = json_dumps(response_data)
+            response_data_hash = str_sha256(response_data_json)
+            cache_cata['response_data'] = response_data_json
+            cache_cata['response_hash'] = response_data_hash
+        return cache_cata
+
+    def create_new_cache_obj(self, request_data, response_data):
+        new_row_data = self.create_new_cache_data(request_data, response_data)
+        new_row_obj = self.cache_table().new_row_obj(new_row_data)
+        return new_row_obj
+
+    def cache_table(self):
+        return self.sqlite_requests.table_requests()
+
+    def cache_table__clear(self):
+        return self.cache_table().clear()
+
+    def cache_request_data(self, *args, **target_kwargs):
+        return {'args': list(args), 'kwargs': target_kwargs}                                # convert the args tuple to a list since that is what it will be once it is serialised
+
+
+    def delete_where_request_data(self, request_data):                                      # todo: check if it is ok to use the request_data as a query target, or if we should use the request_hash variable
+        if type(request_data) is dict:                                                      # if we get an request_data obj
+            request_data = json_dumps(request_data)                                         # convert it to the json dump
+        if type(request_data) is str:                                                       # make sure we have a string
+            if len(self.rows_where__request_data(request_data)) > 0:                        # make sure there is at least one entry to delete
+                self.cache_table().rows_delete_where(request_data=request_data)             # delete it
+                return len(self.rows_where__request_data(request_data)) == 0                # confirm it was deleted
+        return False                                                                        # if anything was not right, return False
+
+    def disable(self):
+        self.enabled = False
+        return self
+
+    def enable(self):
+        self.enabled = True
+        return self
+
+    def invoke(self, target, target_args, target_kwargs):
+        return self.invoke_with_cache(target, target_args, target_kwargs)
+
+    def invoke_target(self, target, target_args, target_kwargs):
+        if self.on_invoke_target:
+            raw_response = self.on_invoke_target(target, target_args, target_kwargs)
+        else:
+            raw_response = target(*target_args, **target_kwargs)
+        return self.transform_raw_response(raw_response)
+
+    def invoke_with_cache(self, target, target_args, target_kwargs, request_data=None):
+        if self.enabled is False:
+            if self.cache_only_mode:
+                return None
+            return self.invoke_target(target, target_args, target_kwargs)
+        if request_data is None:
+            request_data  = self.cache_request_data(*target_args, **target_kwargs)
+        cache_entry   = self.cache_entry(request_data)
+        if cache_entry:
+            if self.update_mode is True:
+                self.cache_delete(request_data)
+            else:
+                return self.response_data_deserialize(cache_entry)
+        if self.cache_only_mode is False:
+            return self.invoke_target__and_add_to_cache(request_data, target, target_args, target_kwargs)
+
+
+    def invoke_target__and_add_to_cache(self,request_data, target, target_args, target_kwargs):
+        try:
+            response_data_obj = self.invoke_target(target, target_args, target_kwargs)
+            response_data     = self.response_data_serialize(response_data_obj)
+            self.cache_add(request_data=request_data, response_data=response_data)
+            return response_data_obj
+        except Exception as exception:
+            if self.capture_exceptions:
+                response_data     = self.response_data_serialize(exception)
+                self.cache_add(request_data=request_data, response_data=response_data)
+            raise exception
+
+    def only_from_cache(self, value=True):
+        self.cache_only_mode = value
+        return self
+
+    def response_data_deserialize(self, cache_entry):
+        if self.pickle_response:
+            response_bytes = cache_entry.get('response_bytes')
+            response_data_obj =  pickle_load_from_bytes(response_bytes)
+        else:
+            response_data = cache_entry.get('response_data')
+            response_data_obj = json_loads(response_data)
+        if self.capture_exceptions:
+            if (type(response_data_obj) is Exception or                     # raise if it is an exception
+                type(response_data_obj) in self.exception_classes):         # or if one of the types that have been set as being exception classes
+                    raise response_data_obj
+            # else:
+            #     pprint(type(response_data_obj))
+        return response_data_obj
+
+    def response_data_serialize(self, response_data):
+        if self.pickle_response:
+            return pickle_save_to_bytes(response_data)
+        return response_data
+
+    def response_data_for__request_hash(self, request_hash):
+        rows = self.rows_where__request_hash(request_hash)
+        if len(rows) > 0:
+            cache_entry       = rows[0]
+            response_data_obj = self.response_data_deserialize(cache_entry)
+            return response_data_obj
+        return {}
+
+    def requests_data__all(self):
+        requests_data = []
+        for row in self.cache_table().rows():
+            req_id           = row.get('id')
+            request_data     = row.get('request_data')
+            request_hash     = row.get('request_hash')
+            request_comments = row.get('comments')
+            request_data_obj = json_loads(request_data)
+            request_data_obj['_id'      ] = req_id
+            request_data_obj['_hash'    ] = request_hash
+            request_data_obj['_comments'] = request_comments
+
+            requests_data.append(request_data_obj)
+        return requests_data
+
+    def rows_where(self, **kwargs):
+        return self.cache_table().select_rows_where(**kwargs)
+
+    def rows_where__request_data(self, request_data):
+        return self.rows_where(request_data=request_data)
+
+    def rows_where__request_hash(self, request_hash):
+        return self.rows_where(request_hash=request_hash)
+
+    def transform_raw_response(self, raw_response):
+        return raw_response
+
+    def update(self, value=True):
+        self.update_mode = value
+        return self