Merge pull request #5 from Pymetheus/update-main

Add full CRUD support and query operator utilities

Author: Pymetheus

README.md

@@ -3,7 +3,7 @@
 **A modular toolkit for building, configuring, and managing databases using SQLAlchemy**
 
 The SQLAlchemy Database Toolkit simplifies the setup and management across different relational databases.  
-Currently, it handles configuration loading, engine creation, ORM base registration, and session management.  
+Currently, it handles configuration loading, engine creation, ORM base registration, session management and CRUD operations.  
 It provides an extensible foundation for rapid database development, prototyping, and integration into data pipelines or applications.  
 
 Supported DBMS under current version:
@@ -81,7 +81,7 @@ Engine Factory Example:
 ```python
 from sqlalchemy_dbtoolkit.engine.factory import AlchemyEngineFactory  
 
-engine = AlchemyEngineFactory(dbms="mysql", db_name="analytics_db", config_path='../.config/config.ini').engine
+engine = AlchemyEngineFactory(dbms='mysql', db_name='analytics_db', config_path='../.config/config.ini').engine
 ```
 
 ORM Table Management Example:
@@ -106,14 +106,29 @@ ORM Session Insert Example:
 from sqlalchemy_dbtoolkit.query.create import InsertManager
 
 inserter = InsertManager(engine)
-inserter.add_row(YourTable, {"column_1": "value", "column_2": 42})
+inserter.add_row(YourTable, {'column_1': 'value', 'column_2': 42})
 ```
 
 ORM Session Select Example:
 ```python
 from sqlalchemy_dbtoolkit.query.read import SelectManager
 selector = SelectManager(engine)
-selection = selector.select_one_by_column(Table=YourTable, column_name="column_1", value="value")
+selection = selector.select_one_by_column(Table=YourTable, column_name='column_1', column_value='value', operator_name='eq')
+```
+
+ORM Session Update Example:
+```python
+from sqlalchemy_dbtoolkit.query.update import UpdateManager
+updater = UpdateManager(engine)
+updates = {'column_2': 43}
+updated_rows = updater.update_rows(Table=YourTable, column_name='column_1', column_value='value', update_dict=updates, operator_name='eq')
+```
+
+ORM Session Delete Example:
+```python
+from sqlalchemy_dbtoolkit.query.delete import DeleteManager
+deleter = DeleteManager(engine)
+deleted_rows = deleter.delete_rows_by_filter(Table=YourTable, column_name='column_1', column_value='value', operator_name='eq')
 ```
 
 Inspector Example:
@@ -129,7 +144,7 @@ for table in table_names:
 ## Roadmap
 
 - [ ] Pandas Integration: Enable conversion between database queries and pandas DataFrames for analysis and data manipulation  
-- [ ] Full CRUD Support: Expand the query layer to include read, update, and delete operations  
+- [X] Full CRUD Support: Expand the query layer to include read, update, and delete operations  
 - [ ] SQLAlchemy Core Support: Provide additional utilities to support low-level, fine-grained database interactions  
 - [ ] Integrated Logging: Add structured logging across all components to improve debugging  
 - [ ] Integrate DBMSs: Include support for additional DBMS like mariadb, mssql and oracle

docs/SECURITY.md

@@ -4,11 +4,11 @@ If you believe you have found a security vulnerability, please report it to us a
 
 ## Supported Versions
 
-Currently only the 0.1.7 version of the sqlalchemy-dbtoolkit is supported.
+Currently only the 0.1.8 version of the sqlalchemy-dbtoolkit is supported.
 
 | Version | Supported          |
 |---------| ------------------ |
-| 0.1.7   | :white_check_mark: |
+| 0.1.8   | :white_check_mark: |
 | others  | :x:                |
 
 ## Reporting a Vulnerability
@@ -17,4 +17,4 @@ Currently only the 0.1.7 version of the sqlalchemy-dbtoolkit is supported.
 
 Please report security vulnerabilities via [Email](mailto:github.senate902@passfwd.com).
 You will receive a response from us within 48 hours.
-If the issue is confirmed, we will release a patch as soon as possible depending on complexity
+If the issue is confirmed, we will release a patch as soon as possible depending on complexity.

setup.py

@@ -1,25 +1,25 @@
 from setuptools import setup, find_packages
 
-with open("README.md", "r", encoding="utf-8") as fh:
+with open('README.md', 'r', encoding='utf-8') as fh:
     long_description = fh.read()
 
 setup(
-    name="sqlalchemy-dbtoolkit",
-    version="0.1.7",
-    description="A toolkit for building SQLAlchemy database engines and utilities.",
+    name='sqlalchemy-dbtoolkit',
+    version='0.1.8',
+    description='A toolkit for building SQLAlchemy database engines and utilities.',
     long_description=long_description,
-    long_description_content_type="text/markdown",
-    author="Pymetheus",
-    author_email="github.senate902@passfwd.com",
-    url="https://github.com/Pymetheus/sqlalchemy-dbtoolkit",
-    license="MIT",
+    long_description_content_type='text/markdown',
+    author='Pymetheus',
+    author_email='github.senate902@passfwd.com',
+    url='https://github.com/Pymetheus/sqlalchemy-dbtoolkit',
+    license='MIT',
     packages=find_packages(),
     include_package_data=False,
     install_requires=[
-        "sqlalchemy>=2.0",
-        "mysql-connector-python>=9.3.0",
-        "psycopg2>=2.9.10",
-        "pandas>=2.2.0"
+        'sqlalchemy>=2.0',
+        'mysql-connector-python>=9.3.0',
+        'psycopg2>=2.9.10',
+        'pandas>=2.2.0'
     ],
-    python_requires=">=3.8"
+    python_requires='>=3.8'
 )

sqlalchemy_dbtoolkit/engine/builder.py

@@ -11,11 +11,11 @@ class BaseEngine(ABC):
     """
 
     DEFAULT_DB_PORTS = {
-        "mariadb": 3306,
-        "mssql": 1433,
-        "mysql": 3306,
-        "oracle": 1521,
-        "postgresql": 5432
+        'mariadb': 3306,
+        'mssql': 1433,
+        'mysql': 3306,
+        'oracle': 1521,
+        'postgresql': 5432
     }
 
     def __init__(self, db_name, config_path='../../.config/config.ini'):
@@ -74,7 +74,7 @@ def sanitize_db_name(self, name):
         if len(name) > 63:
             raise ValueError(f"Database name is too long: {len(name)} Max length is 63 characters.")
 
-        if not re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", name):
+        if not re.match(r'^[A-Za-z_][A-Za-z0-9_]*$', name):
             raise ValueError(f"{name} must start with letter/underscore. Only letters, numbers, underscores allowed.")
 
     def create_connection_url(self):
@@ -87,7 +87,7 @@ def create_connection_url(self):
         """
 
         connection_url = URL.create(
-            drivername=f"{self.dialect}+{self.driver}",
+            drivername=f'{self.dialect}+{self.driver}',
             username=self.username,
             password=self.password,
             host=self.host,

sqlalchemy_dbtoolkit/engine/factory.py

@@ -32,7 +32,7 @@ def validate_supported_dbms(self):
         """
         Validates that the provided DBMS is supported.
         """
-        supported_dbms = ["mysql", "postgresql", "sqlite"]
+        supported_dbms = ['mysql', 'postgresql', 'sqlite']
         if self.dbms not in supported_dbms:
             raise ValueError(f"{self.dbms} is not in supported DBMS: {supported_dbms}")
 
@@ -45,15 +45,15 @@ def initialize_engine(self):
             sqlalchemy.engine.Engine: Initialized SQLAlchemy engine.
         """
 
-        if self.dbms == "mysql":
+        if self.dbms == 'mysql':
             engine_instance = MysqlEngine(db_name=self.db_name, config_path=self.config_path)
             engine_instance.establish_db_connection()
             return engine_instance.engine
-        elif self.dbms == "postgresql":
+        elif self.dbms == 'postgresql':
             engine_instance = PostgreSQLEngine(db_name=self.db_name, config_path=self.config_path)
             engine_instance.establish_db_connection()
             return engine_instance.engine
-        elif self.dbms == "sqlite":
+        elif self.dbms == 'sqlite':
             engine_instance = SqliteEngine(db_name=self.db_name, config_path=self.config_path)
             engine_instance.establish_db_connection()
             return engine_instance.engine

sqlalchemy_dbtoolkit/engine/mysql_engine.py

@@ -20,7 +20,7 @@ def __init__(self, db_name, config_path='../../.config/config.ini'):
         """
 
         super().__init__(db_name, config_path)
-        self.driver = "mysqlconnector"
+        self.driver = 'mysqlconnector'
         self.load_config()
 
     @property
@@ -31,7 +31,7 @@ def dialect(self):
         Returns:
             str: Always returns 'mysql'.
         """
-        return "mysql"
+        return 'mysql'
 
     @property
     def fallback_database(self):
@@ -42,7 +42,7 @@ def fallback_database(self):
             str: The name of the fallback database, 'information_schema'.
         """
 
-        return "information_schema"
+        return 'information_schema'
 
     def load_config(self):
         """
@@ -82,7 +82,7 @@ def database_exists(self):
         try:
             temp_engine = self.connect_to_fallback_db()
             with temp_engine.begin() as temp_connection:
-                check_db_query = "SHOW DATABASES;"
+                check_db_query = 'SHOW DATABASES;'
                 result = temp_connection.execute(text(check_db_query))
 
             for item in result:
@@ -107,7 +107,7 @@ def create_new_database(self, new_db):
         try:
             temp_engine = self.connect_to_fallback_db()
             with temp_engine.connect() as temp_connection:
-                create_db_query = f"CREATE DATABASE IF NOT EXISTS {new_db}"
+                create_db_query = f'CREATE DATABASE IF NOT EXISTS {new_db}'
                 temp_connection.execute(text(create_db_query))
                 temp_connection.commit()
         except Exception as e:

sqlalchemy_dbtoolkit/engine/postgresql_engine.py

@@ -20,7 +20,7 @@ def __init__(self, db_name, config_path='../../.config/config.ini'):
         """
 
         super().__init__(db_name, config_path)
-        self.driver = "psycopg2"
+        self.driver = 'psycopg2'
         self.load_config()
 
     @property
@@ -31,7 +31,7 @@ def dialect(self):
         Returns:
             str: Always returns 'postgresql'.
         """
-        return "postgresql"
+        return 'postgresql'
 
     @property
     def fallback_database(self):
@@ -41,7 +41,7 @@ def fallback_database(self):
         Returns:
             str: The name of the fallback database, 'postgres'.
         """
-        return "postgres"
+        return 'postgres'
 
     def load_config(self):
         """
@@ -81,7 +81,7 @@ def database_exists(self):
         try:
             temp_engine = self.connect_to_fallback_db()
             with temp_engine.begin() as temp_connection:
-                check_db_query = "SELECT datname FROM pg_database WHERE datistemplate = false;"
+                check_db_query = 'SELECT datname FROM pg_database WHERE datistemplate = false;'
                 result = temp_connection.execute(text(check_db_query))
 
             for item in result:
@@ -104,8 +104,8 @@ def create_new_database(self, new_db):
         temp_engine = None
         try:
             temp_engine = self.connect_to_fallback_db()
-            with temp_engine.connect().execution_options(isolation_level="AUTOCOMMIT") as temp_connection:
-                create_db_query = f"CREATE DATABASE {new_db}"
+            with temp_engine.connect().execution_options(isolation_level='AUTOCOMMIT') as temp_connection:
+                create_db_query = f'CREATE DATABASE {new_db}'
                 temp_connection.execute(text(create_db_query))
                 temp_connection.commit()
         except Exception as e:

sqlalchemy_dbtoolkit/engine/sqlite_engine.py

@@ -33,7 +33,7 @@ def dialect(self):
             str: Always returns 'sqlite'.
         """
 
-        return "sqlite"
+        return 'sqlite'
 
     @property
     def fallback_database(self):
@@ -66,7 +66,7 @@ def create_connection_url(self):
             sqlalchemy.engine.URL: The SQLite connection URL.
         """
 
-        database_path = os.path.join(self.sqlite_dir_path, f"{self.db_name}.db")
+        database_path = os.path.join(self.sqlite_dir_path, f'{self.db_name}.db')
         connection_url = URL.create(
             drivername=self.dialect,
             database=database_path

sqlalchemy_dbtoolkit/query/delete.py

@@ -0,0 +1,83 @@
+from sqlalchemy_dbtoolkit.orm.session import ORMSessionManager
+from sqlalchemy_dbtoolkit.utils.query_operators import get_filter_operator
+
+
+class DeleteManager:
+    """
+    Handles database delete operations using SQLAlchemy ORM sessions.
+    """
+
+    def __init__(self, engine):
+        """
+        Initializes the DeleteManager with a SQLAlchemy engine.
+
+        Args:
+            engine (sqlalchemy.Engine): An initialized SQLAlchemy engine.
+        """
+
+        self.session_manager = ORMSessionManager(engine)
+
+    def delete_row(self, row_instance):
+        """
+        Deletes a single ORM object from the database.
+
+        Args:
+            row_instance (Base): An instance of a SQLAlchemy ORM model to delete.
+
+        Returns:
+            One
+        """
+
+        if row_instance is None:
+            raise ValueError("Cannot delete a None object")
+
+        with self.session_manager.session_scope() as session:
+            session.delete(row_instance)
+
+        return 1
+
+    def delete_rows(self, row_instances):
+        """
+        Deletes multiple ORM objects at once.
+
+        Args:
+            row_instances (list[Base]): A list of SQLAlchemy ORM model instances to delete.
+
+        Returns:
+            int: The number of rows deleted.
+        """
+
+        if row_instances is None:
+            raise ValueError("Must be a non-empty list of ORM objects")
+
+        with self.session_manager.session_scope() as session:
+            for instance in row_instances:
+                session.delete(instance)
+
+        return len(row_instances)
+
+    def delete_rows_by_filter(self, Table, column_name, column_value, operator_name='eq'):
+        """
+            Deletes rows from the specified table based on a filter condition.
+
+            Args:
+                Table (Base): A SQLAlchemy ORM model/table class.
+                column_name (str): The column name to filter by.
+                column_value (Any): The value to match in the specified column.
+                operator_name (str, optional): The filter operator to use (default 'eq').
+                    Supported operators: eq, ne, gt, lt, ge, le, like, in, etc.
+
+            Returns:
+                int: The number of rows deleted.
+            """
+
+        with self.session_manager.session_scope() as session:
+            column_attr = getattr(Table, column_name, None)
+            if column_attr is None:
+                raise AttributeError(f"{column_name} is not a valid column of {Table.__name__}")
+
+            operator_func = get_filter_operator(operator_name=operator_name)
+            deleted_rows = session.query(Table).filter(operator_func(column_attr, column_value)).delete(
+                synchronize_session=False)
+
+        return deleted_rows