SQLPyHelper 0.1.3__tar.gz → 0.1.4__tar.gz

{sqlpyhelper-0.1.3 → sqlpyhelper-0.1.4}/PKG-INFO

@@ -1,11 +1,21 @@
 Metadata-Version: 2.4
 Name: SQLPyHelper
-Version: 0.1.3
+Version: 0.1.4
 Summary: A simple SQL database helper package for Python.
+Home-page: https://github.com/adebayopeter/sqlpyhelper
 Author: Adebayo Olaonipekun
 Author-email: pekunmi@live.com
+Project-URL: Source, https://github.com/adebayopeter/sqlpyhelper
+Project-URL: Bug Tracker, https://github.com/adebayopeter/sqlpyhelper/issues
+Project-URL: Changelog, https://github.com/adebayopeter/sqlpyhelper/blob/main/CHANGELOG.md
+Keywords: database,sql,sqlite,postgresql,mysql,sqlserver,oracle,db,query,helper
 Classifier: Programming Language :: Python :: 3
-Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Database :: Database Engines/Servers
 Classifier: Operating System :: OS Independent
@@ -13,32 +23,44 @@ Classifier: License :: OSI Approved :: MIT License
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: psycopg2
-Requires-Dist: mysql-connector-python
-Requires-Dist: pyodbc
-Requires-Dist: cx_Oracle
 Requires-Dist: python-dotenv
-Provides-Extra: mysql
-Requires-Dist: mysql-connector-python; extra == "mysql"
+Requires-Dist: click
 Provides-Extra: postgres
 Requires-Dist: psycopg2; extra == "postgres"
-Provides-Extra: oracle
-Requires-Dist: cx_Oracle; extra == "oracle"
+Provides-Extra: mysql
+Requires-Dist: mysql-connector-python; extra == "mysql"
 Provides-Extra: sqlserver
 Requires-Dist: pyodbc; extra == "sqlserver"
-Provides-Extra: sqlite
+Provides-Extra: oracle
+Requires-Dist: cx_Oracle; extra == "oracle"
+Provides-Extra: all
+Requires-Dist: psycopg2; extra == "all"
+Requires-Dist: mysql-connector-python; extra == "all"
+Requires-Dist: pyodbc; extra == "all"
+Requires-Dist: cx_Oracle; extra == "all"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
 Dynamic: license-file
+Dynamic: project-url
 Dynamic: provides-extra
 Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
-# 📌 SQLPyHelper v.0.1.3 🚀
+# SQLPyHelper
+
+[![PyPI version](https://img.shields.io/pypi/v/sqlpyhelper.svg)](https://pypi.org/project/sqlpyhelper/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/sqlpyhelper.svg)](https://pypi.org/project/sqlpyhelper/)
+[![Python versions](https://img.shields.io/pypi/pyversions/sqlpyhelper.svg)](https://pypi.org/project/sqlpyhelper/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/adebayopeter/sqlpyhelper/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/adebayopeter/sqlpyhelper?style=social)](https://github.com/adebayopeter/sqlpyhelper)
+
+# 📌 SQLPyHelper v.0.1.4 🚀
 
 A Python library for simplified database interactions across **SQLite, PostgreSQL, MySQL, SQL Server, and Oracle**. SQLPyHelper provides an intuitive API for handling queries, connection pooling, transactions, logging, and backups efficiently.
 
@@ -60,13 +82,13 @@ A Python library for simplified database interactions across **SQLite, PostgreSQ
 ---
 
 ## 🚀 Features in v0.1.3
-✅ Unified connection pooling for multiple databases. 
-✅ Automatic reconnection for lost connections. 
-✅ Transaction support (BEGIN, ROLLBACK, COMMIT). 
-✅ Secure parameterized queries to prevent SQL injection. 
-✅ Bulk insertion & dynamic table creation. 
-✅ Logging & error handling for better debugging. 
-✅ CSV export & database backups.
+- Unified connection pooling for multiple databases. 
+- Automatic reconnection for lost connections. 
+- Transaction support (BEGIN, ROLLBACK, COMMIT). 
+- Secure parameterized queries to prevent SQL injection. 
+- Bulk insertion & dynamic table creation. 
+- Logging & error handling for better debugging. 
+- CSV export & database backups.
 
 ---
 ## 📦 Installation

{sqlpyhelper-0.1.3 → sqlpyhelper-0.1.4}/README.md

@@ -1,4 +1,12 @@
-# 📌 SQLPyHelper v.0.1.3 🚀
+# SQLPyHelper
+
+[![PyPI version](https://img.shields.io/pypi/v/sqlpyhelper.svg)](https://pypi.org/project/sqlpyhelper/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/sqlpyhelper.svg)](https://pypi.org/project/sqlpyhelper/)
+[![Python versions](https://img.shields.io/pypi/pyversions/sqlpyhelper.svg)](https://pypi.org/project/sqlpyhelper/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/adebayopeter/sqlpyhelper/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/adebayopeter/sqlpyhelper?style=social)](https://github.com/adebayopeter/sqlpyhelper)
+
+# 📌 SQLPyHelper v.0.1.4 🚀
 
 A Python library for simplified database interactions across **SQLite, PostgreSQL, MySQL, SQL Server, and Oracle**. SQLPyHelper provides an intuitive API for handling queries, connection pooling, transactions, logging, and backups efficiently.
 
@@ -20,13 +28,13 @@ A Python library for simplified database interactions across **SQLite, PostgreSQ
 ---
 
 ## 🚀 Features in v0.1.3
-✅ Unified connection pooling for multiple databases. 
-✅ Automatic reconnection for lost connections. 
-✅ Transaction support (BEGIN, ROLLBACK, COMMIT). 
-✅ Secure parameterized queries to prevent SQL injection. 
-✅ Bulk insertion & dynamic table creation. 
-✅ Logging & error handling for better debugging. 
-✅ CSV export & database backups.
+- Unified connection pooling for multiple databases. 
+- Automatic reconnection for lost connections. 
+- Transaction support (BEGIN, ROLLBACK, COMMIT). 
+- Secure parameterized queries to prevent SQL injection. 
+- Bulk insertion & dynamic table creation. 
+- Logging & error handling for better debugging. 
+- CSV export & database backups.
 
 ---
 ## 📦 Installation

{sqlpyhelper-0.1.3 → sqlpyhelper-0.1.4}/SQLPyHelper.egg-info/PKG-INFO

@@ -1,11 +1,21 @@
 Metadata-Version: 2.4
 Name: SQLPyHelper
-Version: 0.1.3
+Version: 0.1.4
 Summary: A simple SQL database helper package for Python.
+Home-page: https://github.com/adebayopeter/sqlpyhelper
 Author: Adebayo Olaonipekun
 Author-email: pekunmi@live.com
+Project-URL: Source, https://github.com/adebayopeter/sqlpyhelper
+Project-URL: Bug Tracker, https://github.com/adebayopeter/sqlpyhelper/issues
+Project-URL: Changelog, https://github.com/adebayopeter/sqlpyhelper/blob/main/CHANGELOG.md
+Keywords: database,sql,sqlite,postgresql,mysql,sqlserver,oracle,db,query,helper
 Classifier: Programming Language :: Python :: 3
-Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Database :: Database Engines/Servers
 Classifier: Operating System :: OS Independent
@@ -13,32 +23,44 @@ Classifier: License :: OSI Approved :: MIT License
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: psycopg2
-Requires-Dist: mysql-connector-python
-Requires-Dist: pyodbc
-Requires-Dist: cx_Oracle
 Requires-Dist: python-dotenv
-Provides-Extra: mysql
-Requires-Dist: mysql-connector-python; extra == "mysql"
+Requires-Dist: click
 Provides-Extra: postgres
 Requires-Dist: psycopg2; extra == "postgres"
-Provides-Extra: oracle
-Requires-Dist: cx_Oracle; extra == "oracle"
+Provides-Extra: mysql
+Requires-Dist: mysql-connector-python; extra == "mysql"
 Provides-Extra: sqlserver
 Requires-Dist: pyodbc; extra == "sqlserver"
-Provides-Extra: sqlite
+Provides-Extra: oracle
+Requires-Dist: cx_Oracle; extra == "oracle"
+Provides-Extra: all
+Requires-Dist: psycopg2; extra == "all"
+Requires-Dist: mysql-connector-python; extra == "all"
+Requires-Dist: pyodbc; extra == "all"
+Requires-Dist: cx_Oracle; extra == "all"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
 Dynamic: license-file
+Dynamic: project-url
 Dynamic: provides-extra
 Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
-# 📌 SQLPyHelper v.0.1.3 🚀
+# SQLPyHelper
+
+[![PyPI version](https://img.shields.io/pypi/v/sqlpyhelper.svg)](https://pypi.org/project/sqlpyhelper/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/sqlpyhelper.svg)](https://pypi.org/project/sqlpyhelper/)
+[![Python versions](https://img.shields.io/pypi/pyversions/sqlpyhelper.svg)](https://pypi.org/project/sqlpyhelper/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/adebayopeter/sqlpyhelper/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/adebayopeter/sqlpyhelper?style=social)](https://github.com/adebayopeter/sqlpyhelper)
+
+# 📌 SQLPyHelper v.0.1.4 🚀
 
 A Python library for simplified database interactions across **SQLite, PostgreSQL, MySQL, SQL Server, and Oracle**. SQLPyHelper provides an intuitive API for handling queries, connection pooling, transactions, logging, and backups efficiently.
 
@@ -60,13 +82,13 @@ A Python library for simplified database interactions across **SQLite, PostgreSQ
 ---
 
 ## 🚀 Features in v0.1.3
-✅ Unified connection pooling for multiple databases. 
-✅ Automatic reconnection for lost connections. 
-✅ Transaction support (BEGIN, ROLLBACK, COMMIT). 
-✅ Secure parameterized queries to prevent SQL injection. 
-✅ Bulk insertion & dynamic table creation. 
-✅ Logging & error handling for better debugging. 
-✅ CSV export & database backups.
+- Unified connection pooling for multiple databases. 
+- Automatic reconnection for lost connections. 
+- Transaction support (BEGIN, ROLLBACK, COMMIT). 
+- Secure parameterized queries to prevent SQL injection. 
+- Bulk insertion & dynamic table creation. 
+- Logging & error handling for better debugging. 
+- CSV export & database backups.
 
 ---
 ## 📦 Installation

{sqlpyhelper-0.1.3 → sqlpyhelper-0.1.4}/SQLPyHelper.egg-info/SOURCES.txt

@@ -4,8 +4,13 @@ setup.py
 SQLPyHelper.egg-info/PKG-INFO
 SQLPyHelper.egg-info/SOURCES.txt
 SQLPyHelper.egg-info/dependency_links.txt
+SQLPyHelper.egg-info/entry_points.txt
 SQLPyHelper.egg-info/requires.txt
 SQLPyHelper.egg-info/top_level.txt
 sqlpyhelper/__init__.py
+sqlpyhelper/automation_utils.py
+sqlpyhelper/cli.py
 sqlpyhelper/db_helper.py
+sqlpyhelper/py.typed
+test/test_automation.py
 test/test_sqlpyhelper.py

sqlpyhelper-0.1.4/SQLPyHelper.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sqlpyhelper = sqlpyhelper.cli:cli

{sqlpyhelper-0.1.3 → sqlpyhelper-0.1.4}/SQLPyHelper.egg-info/requires.txt

@@ -1,8 +1,11 @@
+python-dotenv
+click
+
+[all]
 psycopg2
 mysql-connector-python
 pyodbc
 cx_Oracle
-python-dotenv
 
 [mysql]
 mysql-connector-python
@@ -13,7 +16,5 @@ cx_Oracle
 [postgres]
 psycopg2
 
-[sqlite]
-
 [sqlserver]
 pyodbc

sqlpyhelper-0.1.4/setup.py

@@ -0,0 +1,63 @@
+from setuptools import setup, find_packages
+
+with open("README.md", "r", encoding="utf-8") as f:
+    long_description = f.read()
+
+setup(
+    name='SQLPyHelper',
+    version='0.1.4',
+    description='A simple SQL database helper package for Python.',
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    author='Adebayo Olaonipekun',
+    author_email='pekunmi@live.com',
+    url='https://github.com/adebayopeter/sqlpyhelper',
+    packages=find_packages(),
+    package_data={
+        "sqlpyhelper": ["py.typed"],
+    },
+    python_requires=">=3.8",
+    install_requires=[
+        'python-dotenv',
+        'click'
+    ],
+    extras_require={
+        "postgres": ["psycopg2"],
+        "mysql": ["mysql-connector-python"],
+        "sqlserver": ["pyodbc"],
+        "oracle": ["cx_Oracle"],
+        "all": [
+            "psycopg2",
+            "mysql-connector-python",
+            "pyodbc",
+            "cx_Oracle",
+        ],
+    },
+    keywords=[
+        "database", "sql", "sqlite", "postgresql", "mysql",
+        "sqlserver", "oracle", "db", "query", "helper",
+    ],
+    project_urls={
+        "Source": "https://github.com/adebayopeter/sqlpyhelper",
+        "Bug Tracker": "https://github.com/adebayopeter/sqlpyhelper/issues",
+        "Changelog": "https://github.com/adebayopeter/sqlpyhelper/blob/main/CHANGELOG.md",
+    },
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "Topic :: Database :: Database Engines/Servers",
+        "Operating System :: OS Independent",
+        "License :: OSI Approved :: MIT License",
+    ],
+    entry_points={
+        'console_scripts': [
+            'sqlpyhelper=sqlpyhelper.cli:cli',
+        ],
+    },
+)

sqlpyhelper-0.1.4/sqlpyhelper/__init__.py

@@ -0,0 +1,9 @@
+# Match the version in setup.py
+__version__ = "0.1.4"
+
+from sqlpyhelper.db_helper import (
+    SQLPyHelperError,
+    ConnectionError,
+    QueryError,
+    BackupError,
+)

sqlpyhelper-0.1.4/sqlpyhelper/automation_utils.py

@@ -0,0 +1,145 @@
+import pandas as pd
+from sqlpyhelper.db_helper import SQLPyHelper
+import subprocess
+from datetime import datetime
+import os
+import shutil
+
+
+class AutomationUtils:
+    def __init__(self, db=None, **db_kwargs):
+        """
+        Optionally accepts db instance or connection parameters like:
+        db_type, host, user, password, database, port, driver.
+        """
+        self.db = db or SQLPyHelper(**db_kwargs)
+
+    def backup_database(self, target="local", tag="autobackup"):
+        """
+        Backs up the active PostgreSQL database using pg_dump.
+
+        Args:
+            target (str): Backup destination ("local" only for now).
+            tag (str): Custom tag for backup file naming.
+        """
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M")
+        filename = f"{tag}_{timestamp}.sql"
+        backup_dir = "backups"
+        os.makedirs(backup_dir, exist_ok=True)
+        filepath = os.path.join(backup_dir, filename)
+
+        db_name = self.db.database
+        user = self.db.user
+        host = self.db.host or "localhost"
+        port = str(self.db.port or "5432")
+
+        try:
+            if self.db.db_type == "sqlite":
+                filename2 = f"{tag}_{timestamp}.db"
+                sqlite_filepath = os.path.join(backup_dir, filename2)
+                shutil.copy2(self.db.database, sqlite_filepath)
+            else:
+                print(f"📦 Backing up database to {filepath}")
+                subprocess.run(
+                    [
+                        "pg_dump",
+                        "-h", host,
+                        "-p", port,
+                        "-U", user,
+                        db_name,
+                        "-F", "c",
+                        "-f", filepath,
+                    ],
+                    check=True,
+                    shell=False,
+                )
+        except subprocess.CalledProcessError as e:
+            print("❌ Backup failed:", e)
+
+    def load_data_from_csv(self, file_path, table_name, if_exists="append"):
+        """
+        Loads a CSV file into the specified database table.
+
+        Args:
+            file_path (str): Path to the CSV file.
+            table_name (str): Destination table name in the database.
+            if_exists (str): 'append' or 'replace'. Default is 'append'.
+        """
+        df = pd.read_csv(file_path)
+
+        if if_exists == "replace":
+            self.db.execute_query(f"DROP TABLE IF EXISTS {table_name}")
+
+        for _, row in df.iterrows():
+            self.db.insert_dynamic(table_name, row.to_dict())
+
+    def detect_missing_periods(self, table, entity_column, date_column):
+        """
+        Flags rows where recurring time periods (e.g. monthly) are missing per entity.
+
+        Args:
+            table (str): Table name to query.
+            entity_column (str): Column representing entity ID.
+            date_column (str): Column representing timestamp/date.
+        """
+        if self.db.db_type == 'sqlite':
+            month_expr = f"strftime('%Y-%m', {date_column})"
+        else:
+            month_expr = f"DATE_TRUNC('month', {date_column})"
+        query = f"""
+        SELECT {entity_column}, COUNT(DISTINCT {month_expr}) AS recorded_months
+        FROM {table}
+        GROUP BY {entity_column}
+        HAVING COUNT(DISTINCT {month_expr}) < 12
+        """
+        self.db.execute_query(query)
+        return self.db.fetch_all()
+
+    def aggregate_column(self, table, value_column, group_column=None, time_column=None):
+        """
+        Computes sum of any value column grouped by entity or month.
+
+        Args:
+            table (str): Table name.
+            value_column (str): Numeric column to aggregate.
+            group_column (str, optional): Entity or category to group by.
+            time_column (str, optional): Timestamp to extract month grouping.
+        """
+        if self.db.db_type == 'sqlite':
+            month_expr = f"strftime('%Y-%m', {time_column})"
+        else:
+            month_expr = f"DATE_TRUNC('month', {time_column})"
+
+        if group_column and time_column:
+            query = f"""
+            SELECT {group_column}, {month_expr} AS month, SUM({value_column}) AS total
+            FROM {table}
+            GROUP BY {group_column}, month
+            ORDER BY month
+            """
+        else:
+            query = f"SELECT SUM({value_column}) FROM {table}"
+
+        self.db.execute_query(query)
+        return self.db.fetch_all()
+
+    def detect_outliers(self, table, numeric_column, threshold=2):
+        """
+        Detects statistical outliers based on deviation from mean.
+
+        Args:
+            table (str): Table name.
+            numeric_column (str): Column to analyze.
+            threshold (int): Number of standard deviations from mean to flag as outlier.
+        """
+        query = f"""
+            SELECT *, {numeric_column} 
+            AS value FROM {table}
+        """
+        self.db.execute_query(query)
+        data = pd.DataFrame(self.db.fetch_all(), columns=[desc[0] for desc in self.db.cursor.description])
+
+        mean_val = data["value"].mean()
+        std_val = data["value"].std()
+        outliers = data[abs(data["value"] - mean_val) > threshold * std_val]
+        return outliers.values.tolist()

sqlpyhelper-0.1.4/sqlpyhelper/cli.py

@@ -0,0 +1,146 @@
+import click
+from sqlpyhelper.db_helper import SQLPyHelper
+from sqlpyhelper.automation_utils import AutomationUtils
+
+
+@click.group()
+def cli():
+    """SQLPyHelper Command Line Interface"""
+    pass
+
+
+@cli.command()
+@click.option('--db_type', help='Type of database (e.g., sqlite, postgres, mysql)')
+@click.option('--host', help='Database host')
+@click.option('--user', help='Username')
+@click.option('--password', help='Password')
+@click.option('--database', help='Database name or file')
+@click.option('--query', required=True, help='SQL query to run')
+def run_query(db_type, host, user, password, database, query):
+    """Run a single SQL query and print results"""
+    db = SQLPyHelper(db_type=db_type, host=host, user=user, password=password, database=database)
+    results = db.execute_query(query)
+    for row in results:
+        click.echo(row)
+    db.close()
+
+
+@cli.command()
+@click.option('--db_type', required=True)
+@click.option('--host')
+@click.option('--user')
+@click.option('--password')
+@click.option('--database', required=True)
+def interactive_shell(db_type, host, user, password, database):
+    """Launch an interactive SQL shell"""
+    db = SQLPyHelper(db_type=db_type, host=host, user=user, password=password, database=database)
+    click.echo("Interactive shell started. Type your SQL query or 'exit'")
+    while True:
+        query = input("sqlpy> ")
+        if query.lower() in ("exit", "quit"):
+            break
+        try:
+            db.execute_query(query)
+            results = db.fetch_all()
+            for row in results:
+                click.echo(row)
+        except Exception as e:
+            click.echo(f"Error: {e}")
+    db.close()
+
+
+@cli.command()
+@click.option('--target', default="local", help="Backup destination")
+@click.option('--tag', default="autobackup", help="Tag for backup file naming")
+@click.option('--db-type')
+@click.option('--host')
+@click.option('--user')
+@click.option('--password')
+@click.option('--database')
+@click.option('--port')
+def backup(target, tag, db_type, host, user, password, database, port):
+    """Create a timestamped backup of the connected database."""
+    utils = AutomationUtils(
+        db_type=db_type,
+        host=host,
+        user=user,
+        password=password,
+        database=database,
+        port=port
+    )
+    utils.backup_database(target=target, tag=tag)
+
+
+@cli.command()
+@click.option('--file', required=True, help="Path to CSV file")
+@click.option('--table', required=True, help="Destination table")
+@click.option('--if-exists', default="append", type=click.Choice(["append", "replace"]), help="What to do if table exists")
+@click.option('--db-type')
+@click.option('--host')
+@click.option('--user')
+@click.option('--password')
+@click.option('--database')
+@click.option('--port')
+def load_data(file, table, if_exists, db_type, host, user, password, database, port):
+    """Load data from CSV into database table."""
+    utils = AutomationUtils(db_type=db_type, host=host, user=user, password=password, database=database, port=port)
+    utils.load_data_from_csv(file, table, if_exists=if_exists)
+
+
+@cli.command()
+@click.option('--table', required=True)
+@click.option('--entity-column', required=True)
+@click.option('--date-column', required=True)
+@click.option('--db-type')
+@click.option('--host')
+@click.option('--user')
+@click.option('--password')
+@click.option('--database')
+@click.option('--port')
+def detect_missing_periods(table, entity_column, date_column, db_type, host, user, password, database, port):
+    """Flag entities with fewer than 12 months of activity."""
+    utils = AutomationUtils(db_type=db_type, host=host, user=user, password=password, database=database, port=port)
+    results = utils.detect_missing_periods(table, entity_column, date_column)
+    for row in results:
+        click.echo(row)
+
+
+@cli.command()
+@click.option('--table', required=True)
+@click.option('--value-column', required=True)
+@click.option('--group-column')
+@click.option('--time-column')
+@click.option('--db-type')
+@click.option('--host')
+@click.option('--user')
+@click.option('--password')
+@click.option('--database')
+@click.option('--port')
+def aggregate(table, value_column, group_column, time_column, db_type, host, user, password, database, port):
+    """Aggregate numeric column optionally grouped by entity and time."""
+    utils = AutomationUtils(db_type=db_type, host=host, user=user, password=password, database=database, port=port)
+    results = utils.aggregate_column(table, value_column, group_column, time_column)
+    for row in results:
+        click.echo(row)
+
+
+@cli.command()
+@click.option('--table', required=True)
+@click.option('--numeric-column', required=True)
+@click.option('--threshold', default=2, type=int)
+@click.option('--db-type')
+@click.option('--host')
+@click.option('--user')
+@click.option('--password')
+@click.option('--database')
+@click.option('--port')
+def detect_outliers(table, numeric_column, threshold, db_type, host, user, password, database, port):
+    """Flag rows where values deviate statistically from average."""
+    utils = AutomationUtils(db_type=db_type, host=host, user=user, password=password, database=database, port=port)
+    results = utils.detect_outliers(table, numeric_column, threshold)
+    for row in results:
+        click.echo(row)
+
+
+if __name__ == "__main__":
+    cli()

{sqlpyhelper-0.1.3 → sqlpyhelper-0.1.4}/sqlpyhelper/db_helper.py

@@ -1,27 +1,70 @@
 import csv
 from dotenv import load_dotenv
 import os
+import re
 
 load_dotenv()  # Load environment variables from .env file
 
 
-def log_query(query):
-    """Logs queries for debugging purposes."""
-    with open("query_log.txt", "a") as f:
-        f.write(query + "\n")
+def _validate_identifier(name: str) -> str:
+    """
+    Validate a SQL identifier (table or column name).
+    Allows only alphanumeric characters and underscores.
+    Raises ValueError for anything else, preventing SQL injection via identifiers.
+    """
+    if not re.match(r'^[A-Za-z_][A-Za-z0-9_]*$', name):
+        raise ValueError(
+            f"Invalid SQL identifier: {name!r}. "
+            "Only letters, digits, and underscores are allowed."
+        )
+    return name
+
+
+class SQLPyHelperError(Exception):
+    """Base exception for SQLPyHelper errors."""
+
+
+class ConnectionError(SQLPyHelperError):
+    """Raised when a database connection fails."""
+
+
+class QueryError(SQLPyHelperError):
+    """Raised when a query fails to execute."""
+
+
+class BackupError(SQLPyHelperError):
+    """Raised when a backup operation fails."""
 
 
 class SQLPyHelper:
-    def __init__(self):
-        self.db_type = os.getenv("DB_TYPE").lower()
-        self.host = os.getenv("DB_HOST")
-        self.user = os.getenv("DB_USER")
-        self.password = os.getenv("DB_PASSWORD")
-        self.database = os.getenv("DB_NAME")
-        self.driver = os.getenv("DB_DRIVER")
-        self.oracle_sid = os.getenv("ORACLE_SID")
+    def __init__(self, db_type=None, host=None, user=None, password=None,
+                 database=None, driver=None, port=None, oracle_sid=None):
+
+        # Store original params so reconnect() can replay them
+        self._init_kwargs = {
+            "db_type": db_type,
+            "host": host,
+            "user": user,
+            "password": password,
+            "database": database,
+            "driver": driver,
+            "port": port,
+            "oracle_sid": oracle_sid,
+        }
+
+        self.db_type = db_type or os.getenv("DB_TYPE").lower()
+        self.host = host or os.getenv("DB_HOST")
+        self.user = user or os.getenv("DB_USER")
+        self.password = password or os.getenv("DB_PASSWORD")
+        self.database = database or os.getenv("DB_NAME")
+        self.driver = driver or os.getenv("DB_DRIVER")
+        self.port = port or os.getenv("DB_PORT")
+        self.oracle_sid = oracle_sid or os.getenv("ORACLE_SID")
         self.pool = None
 
+        if not self.db_type or not self.database:
+            raise ValueError("Missing required database configuration.")
+
         if self.db_type == "sqlite":
             import sqlite3
             self.connection = sqlite3.connect(self.database)
@@ -47,6 +90,13 @@ class SQLPyHelper:
 
         self.cursor = self.connection.cursor()
 
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        return False
+
     def execute_query(self, query, params=None):
         """Executes a query with optional parameters"""
         try:
@@ -61,32 +111,32 @@ class SQLPyHelper:
                 self.cursor.execute(query, params)
                 self.connection.commit()
             else:
-                print(f"Error executing query: {e}")
+                raise QueryError(f"Query failed: {e}") from e
 
     def fetch_one(self):
         """Fetches a single row"""
         try:
             return self.cursor.fetchone()
         except Exception as e:
-            print(f"Error fetching row: {e}")
-            return None
+            raise QueryError(f"Failed to fetch row: {e}") from e
 
     def fetch_all(self):
         """Fetches all rows from the last executed query"""
         try:
             return self.cursor.fetchall()
         except Exception as e:
-            print(f"Error fetching rows: {e}")
-            return None
+            raise QueryError(f"Failed to fetch rows: {e}") from e
 
     def fetch_by_param(self, table_name, column_name, value):
         try:
-            query = f"SELECT * FROM {table_name} WHERE {column_name} = %s"
+            table_name = _validate_identifier(table_name)
+            column_name = _validate_identifier(column_name)
+            placeholder = "?" if self.db_type == "sqlite" else "%s"
+            query = f"SELECT * FROM {table_name} WHERE {column_name} = {placeholder}"
             self.cursor.execute(query, (value,))
             return self.cursor.fetchall()
         except Exception as e:
-            print(f"Error fetching row(s): {e}")
-            return None
+            raise QueryError(f"Failed to fetch by param: {e}") from e
 
     def close(self):
         """Closes the connection"""
@@ -94,8 +144,7 @@ class SQLPyHelper:
             self.cursor.close()
             self.connection.close()
         except Exception as e:
-            print(f"Error closing connection: {e}")
-            return None
+            raise ConnectionError(f"Failed to close connection: {e}") from e
 
     def create_table(self, table_name, columns):
         """
@@ -104,12 +153,13 @@ class SQLPyHelper:
         columns = {'id': 'INTEGER PRIMARY KEY', 'name': 'TEXT', 'age': 'INTEGER'}
         """
         try:
-            column_defs = ", ".join(f"{col} {dtype}" for col, dtype in columns.items())
-            query = f"CREATE TABLE {table_name} ({column_defs})"
+            table_name = _validate_identifier(table_name)
+            validated_cols = {_validate_identifier(col): dtype for col, dtype in columns.items()}
+            columns_def = ", ".join([f"{col} {dtype}" for col, dtype in validated_cols.items()])
+            query = f"CREATE TABLE IF NOT EXISTS {table_name} ({columns_def})"
             self.execute_query(query)
         except Exception as e:
-            print(f"Error creating table: {e}")
-            return None
+            raise QueryError(f"Failed to create table: {e}") from e
 
     def insert_bulk(self, table_name, data):
         """
@@ -118,16 +168,18 @@ class SQLPyHelper:
         data = [{'id': 1, 'name': 'Alice'}, {'id': 2, 'name': 'Bob'}]
         """
         try:
-            columns = ", ".join(data[0].keys())  # Extract column names
-            placeholders = ", ".join(["%s" for _ in data[0].keys()])  # Generate placeholders
+            table_name = _validate_identifier(table_name)
+            col_names = [_validate_identifier(col) for col in data[0].keys()]
+            columns = ", ".join(col_names)
+            placeholder = "?" if self.db_type == "sqlite" else "%s"
+            placeholders = ", ".join([placeholder] * len(data[0]))
             query = f"INSERT INTO {table_name} ({columns}) VALUES ({placeholders})"
             values = [tuple(row.values()) for row in data]
             self.cursor.executemany(query, values)
             self.connection.commit()
 
         except Exception as e:
-            print(f"Error inserting bulk rows: {e}")
-            return None
+            raise QueryError(f"Failed to insert bulk rows: {e}") from e
 
     def backup_table(self, table_name, backup_file):
         """
@@ -136,6 +188,7 @@ class SQLPyHelper:
         backup_table('users', 'users_backup.csv')
         """
         try:
+            table_name = _validate_identifier(table_name)
             query = f"SELECT * FROM {table_name}"
             self.execute_query(query)
             rows = self.fetch_all()
@@ -145,8 +198,7 @@ class SQLPyHelper:
                 writer.writerow([desc[0] for desc in self.cursor.description])  # Column headers
                 writer.writerows(rows)
         except Exception as e:
-            print(f"Error backing up table: {e}")
-            return None
+            raise BackupError(f"Failed to backup table: {e}") from e
 
     def setup_connection_pool(self, min_conn=1, max_conn=5, pool_size=5):
         """Sets up connection pooling based on the database type"""
@@ -182,28 +234,51 @@ class SQLPyHelper:
             else:
                 raise ValueError(f"Connection pooling not supported for {self.db_type}")
         except Exception as e:
-            print(f"⚠️ Error setting up connection pool: {e}")
-            self.pool = None  # Prevent broken pool usage
+            raise ConnectionError(f"Failed to set up connection pool: {e}") from e
 
     def get_connection_from_pool(self):
         """Fetches a connection from the pool."""
         return self.pool.get_connection()
 
-    def return_connection_to_pool(self):
+    def return_connection_to_pool(self, connection=None) -> None:
         """Returns a connection back to the pool."""
-        self.connection.close()
+        conn = connection or self.connection
+        if self.pool is None:
+            raise RuntimeError("No connection pool initialised. Call setup_connection_pool() first.")
+
+        if self.db_type == "postgres":
+            self.pool.putconn(conn)
+        elif self.db_type == "mysql":
+            conn.close()
+        elif self.db_type == "oracle":
+            self.pool.release(conn)
+        else:
+            conn.close()
 
     def reconnect(self):
         """Reconnects to the database if connection is lost"""
         try:
-            self.connection.close()  # Close existing connection
-            self.__init__()  # Reinitialize the connection
+            self.connection.close()
+            self.__init__(**self._init_kwargs)
             print("Database reconnected successfully.")
         except Exception as e:
-            print(f"Error during reconnection: {e}")
+            raise ConnectionError(f"Reconnection failed: {e}") from e
 
     def begin_transaction(self):
         self.execute_query("START TRANSACTION")
 
     def rollback_transaction(self):
         self.execute_query("ROLLBACK")
+
+    def insert_dynamic(self, table, data: dict):
+        """
+        Dynamically constructs and executes an INSERT query with database-specific placeholders.
+        """
+        table = _validate_identifier(table)
+        columns = ", ".join(_validate_identifier(col) for col in data.keys())
+        placeholders_style = "?" if self.db_type == "sqlite" else "%s"
+        placeholders = ", ".join([placeholders_style] * len(data))
+        values = tuple(data.values())
+
+        sql = f"INSERT INTO {table} ({columns}) VALUES ({placeholders})"
+        self.execute_query(sql, values)

sqlpyhelper-0.1.4/test/test_automation.py

@@ -0,0 +1,15 @@
+from sqlpyhelper.automation_utils import AutomationUtils
+
+utils = AutomationUtils()
+
+print("✅ Loading test data...")
+utils.load_data_from_csv("sample_data.csv", "contributors")
+
+print("\n📊 Contribution breakdown:")
+print(utils.aggregate_column("contributors", "contribution", "name", "timestamp"))
+
+print("\n⚠️ Missing months:")
+print(utils.detect_missing_periods("contributors", "name", "timestamp"))
+
+print("\n🚨 Outliers:")
+print(utils.detect_outliers("contributors", "contribution"))

sqlpyhelper-0.1.3/setup.py

@@ -1,38 +0,0 @@
-from setuptools import setup, find_packages
-
-with open("README.md", "r", encoding="utf-8") as f:
-    long_description = f.read()
-
-setup(
-    name='SQLPyHelper',
-    version='0.1.3',
-    description='A simple SQL database helper package for Python.',
-    long_description=long_description,
-    long_description_content_type="text/markdown",
-    author='Adebayo Olaonipekun',
-    author_email='pekunmi@live.com',
-    packages=find_packages(),
-    install_requires=[
-        'psycopg2',
-        'mysql-connector-python',
-        'pyodbc',
-        'cx_Oracle',
-        'python-dotenv'
-    ],
-    extras_require={
-        "mysql": ["mysql-connector-python"],
-        "postgres": ["psycopg2"],
-        "oracle": ["cx_Oracle"],
-        "sqlserver": ["pyodbc"],
-        "sqlite": []
-    },
-    python_requires=">=3.8",
-    classifiers=[
-        "Programming Language :: Python :: 3",
-        "Development Status :: 5 - Production/Stable",
-        "Intended Audience :: Developers",
-        "Topic :: Database :: Database Engines/Servers",
-        "Operating System :: OS Independent",
-        "License :: OSI Approved :: MIT License"
-    ],
-)

sqlpyhelper-0.1.3/sqlpyhelper/__init__.py

@@ -1,2 +0,0 @@
-# Match the version in setup.py
-__version__ = "0.1.3"