SQLPyHelper 0.1.7__tar.gz → 0.1.8__tar.gz

{sqlpyhelper-0.1.7 → sqlpyhelper-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SQLPyHelper
-Version: 0.1.7
+Version: 0.1.8
 Summary: A simple SQL database helper package for Python.
 Home-page: https://github.com/adebayopeter/sqlpyhelper
 Author: Adebayo Olaonipekun
@@ -34,11 +34,28 @@ Provides-Extra: sqlserver
 Requires-Dist: pyodbc; extra == "sqlserver"
 Provides-Extra: oracle
 Requires-Dist: oracledb; extra == "oracle"
+Provides-Extra: async-postgres
+Requires-Dist: asyncpg; extra == "async-postgres"
+Provides-Extra: async-mysql
+Requires-Dist: aiomysql; extra == "async-mysql"
+Provides-Extra: async-sqlite
+Requires-Dist: aiosqlite; extra == "async-sqlite"
+Provides-Extra: async-sqlserver
+Requires-Dist: aioodbc; extra == "async-sqlserver"
+Provides-Extra: async-all
+Requires-Dist: asyncpg; extra == "async-all"
+Requires-Dist: aiomysql; extra == "async-all"
+Requires-Dist: aiosqlite; extra == "async-all"
+Requires-Dist: aioodbc; extra == "async-all"
 Provides-Extra: all
 Requires-Dist: psycopg2; extra == "all"
 Requires-Dist: mysql-connector-python; extra == "all"
 Requires-Dist: pyodbc; extra == "all"
 Requires-Dist: oracledb; extra == "all"
+Requires-Dist: asyncpg; extra == "all"
+Requires-Dist: aiomysql; extra == "all"
+Requires-Dist: aiosqlite; extra == "all"
+Requires-Dist: aioodbc; extra == "all"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier

{sqlpyhelper-0.1.7 → sqlpyhelper-0.1.8}/SQLPyHelper.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SQLPyHelper
-Version: 0.1.7
+Version: 0.1.8
 Summary: A simple SQL database helper package for Python.
 Home-page: https://github.com/adebayopeter/sqlpyhelper
 Author: Adebayo Olaonipekun
@@ -34,11 +34,28 @@ Provides-Extra: sqlserver
 Requires-Dist: pyodbc; extra == "sqlserver"
 Provides-Extra: oracle
 Requires-Dist: oracledb; extra == "oracle"
+Provides-Extra: async-postgres
+Requires-Dist: asyncpg; extra == "async-postgres"
+Provides-Extra: async-mysql
+Requires-Dist: aiomysql; extra == "async-mysql"
+Provides-Extra: async-sqlite
+Requires-Dist: aiosqlite; extra == "async-sqlite"
+Provides-Extra: async-sqlserver
+Requires-Dist: aioodbc; extra == "async-sqlserver"
+Provides-Extra: async-all
+Requires-Dist: asyncpg; extra == "async-all"
+Requires-Dist: aiomysql; extra == "async-all"
+Requires-Dist: aiosqlite; extra == "async-all"
+Requires-Dist: aioodbc; extra == "async-all"
 Provides-Extra: all
 Requires-Dist: psycopg2; extra == "all"
 Requires-Dist: mysql-connector-python; extra == "all"
 Requires-Dist: pyodbc; extra == "all"
 Requires-Dist: oracledb; extra == "all"
+Requires-Dist: asyncpg; extra == "all"
+Requires-Dist: aiomysql; extra == "all"
+Requires-Dist: aiosqlite; extra == "all"
+Requires-Dist: aioodbc; extra == "all"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier

{sqlpyhelper-0.1.7 → sqlpyhelper-0.1.8}/SQLPyHelper.egg-info/SOURCES.txt

@@ -10,10 +10,12 @@ SQLPyHelper.egg-info/entry_points.txt
 SQLPyHelper.egg-info/requires.txt
 SQLPyHelper.egg-info/top_level.txt
 sqlpyhelper/__init__.py
+sqlpyhelper/async_helper.py
 sqlpyhelper/automation_utils.py
 sqlpyhelper/cli.py
 sqlpyhelper/db_helper.py
 sqlpyhelper/migration.py
 sqlpyhelper/py.typed
+test/test_async_helper.py
 test/test_migration.py
 test/test_sqlpyhelper.py

sqlpyhelper-0.1.8/SQLPyHelper.egg-info/requires.txt

@@ -0,0 +1,42 @@
+python-dotenv
+click
+
+[all]
+psycopg2
+mysql-connector-python
+pyodbc
+oracledb
+asyncpg
+aiomysql
+aiosqlite
+aioodbc
+
+[async-all]
+asyncpg
+aiomysql
+aiosqlite
+aioodbc
+
+[async-mysql]
+aiomysql
+
+[async-postgres]
+asyncpg
+
+[async-sqlite]
+aiosqlite
+
+[async-sqlserver]
+aioodbc
+
+[mysql]
+mysql-connector-python
+
+[oracle]
+oracledb
+
+[postgres]
+psycopg2
+
+[sqlserver]
+pyodbc

{sqlpyhelper-0.1.7 → sqlpyhelper-0.1.8}/pyproject.toml

@@ -4,3 +4,6 @@ line-length = 88
 [tool.isort]
 profile = "black"
 line_length = 88
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

{sqlpyhelper-0.1.7 → sqlpyhelper-0.1.8}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as f:
 
 setup(
     name='SQLPyHelper',
-    version='0.1.7',
+    version='0.1.8',
     description='A simple SQL database helper package for Python.',
     long_description=long_description,
     long_description_content_type="text/markdown",
@@ -26,11 +26,14 @@ setup(
         "mysql": ["mysql-connector-python"],
         "sqlserver": ["pyodbc"],
         "oracle": ["oracledb"],
+        "async-postgres": ["asyncpg"],
+        "async-mysql": ["aiomysql"],
+        "async-sqlite": ["aiosqlite"],
+        "async-sqlserver": ["aioodbc"],
+        "async-all": ["asyncpg", "aiomysql", "aiosqlite", "aioodbc"],
         "all": [
-            "psycopg2",
-            "mysql-connector-python",
-            "pyodbc",
-            "oracledb",
+            "psycopg2", "mysql-connector-python", "pyodbc", "oracledb",
+            "asyncpg", "aiomysql", "aiosqlite", "aioodbc",
         ],
     },
     keywords=[

{sqlpyhelper-0.1.7 → sqlpyhelper-0.1.8}/sqlpyhelper/__init__.py

@@ -1,6 +1,11 @@
 # Match the version in setup.py
-__version__ = "0.1.7"
+__version__ = "0.1.8"
 
+from sqlpyhelper.async_helper import (  # noqa: F401
+    AsyncConnectionError,
+    AsyncQueryError,
+    AsyncSQLPyHelper,
+)
 from sqlpyhelper.db_helper import (  # noqa: F401
     BackupError,
     ConnectionError,

sqlpyhelper-0.1.8/sqlpyhelper/async_helper.py

@@ -0,0 +1,599 @@
+"""
+sqlpyhelper.async_helper
+~~~~~~~~~~~~~~~~~~~~~~~~
+Async-native database helper supporting SQLite, PostgreSQL, MySQL,
+SQL Server, and Oracle.
+
+Uses async-native drivers:
+- SQLite:     aiosqlite
+- PostgreSQL: asyncpg
+- MySQL:      aiomysql
+- SQL Server: aioodbc
+- Oracle:     python-oracledb (async mode)
+
+Example usage::
+
+    import asyncio
+    from sqlpyhelper.async_helper import AsyncSQLPyHelper
+
+    async def main():
+        async with AsyncSQLPyHelper(db_type="sqlite", database="my.db") as db:
+            await db.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER, name TEXT)")
+            await db.execute("INSERT INTO users VALUES ($1, $2)", 1, "Alice")
+            rows = await db.fetch_all("SELECT * FROM users")
+            print(rows)
+
+    asyncio.run(main())
+"""
+
+import logging
+import os
+from typing import Any, Optional
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+logger = logging.getLogger("sqlpyhelper.async")
+
+
+class AsyncConnectionError(Exception):
+    """Raised when an async database connection fails."""
+
+
+class AsyncQueryError(Exception):
+    """Raised when an async query fails."""
+
+
+class AsyncSQLPyHelper:
+    """
+    Async-native database helper with a unified API across
+    SQLite, PostgreSQL, MySQL, SQL Server, and Oracle.
+
+    Use as an async context manager::
+
+        async with AsyncSQLPyHelper(db_type="postgres", ...) as db:
+            rows = await db.fetch_all("SELECT * FROM users")
+
+    Or manage the connection lifecycle manually::
+
+        db = AsyncSQLPyHelper(db_type="sqlite", database="my.db")
+        await db.connect()
+        try:
+            rows = await db.fetch_all("SELECT * FROM users")
+        finally:
+            await db.close()
+    """
+
+    def __init__(
+        self,
+        db_type: Optional[str] = None,
+        host: Optional[str] = None,
+        user: Optional[str] = None,
+        password: Optional[str] = None,
+        database: Optional[str] = None,
+        driver: Optional[str] = None,
+        port: Optional[str] = None,
+        oracle_sid: Optional[str] = None,
+    ) -> None:
+        self.db_type: str = (db_type or os.getenv("DB_TYPE") or "").lower()
+        self.host: Optional[str] = host or os.getenv("DB_HOST")
+        self.user: Optional[str] = user or os.getenv("DB_USER")
+        self.password: Optional[str] = password or os.getenv("DB_PASSWORD")
+        self.database: Optional[str] = database or os.getenv("DB_NAME")
+        self.driver: Optional[str] = driver or os.getenv("DB_DRIVER")
+        self.port: Optional[str] = port or os.getenv("DB_PORT")
+        self.oracle_sid: Optional[str] = oracle_sid or os.getenv("ORACLE_SID")
+
+        self._connection: Any = None
+        self._pool: Any = None
+
+        if not self.db_type or not self.database:
+            raise ValueError("Missing required database configuration.")
+
+        if self.db_type not in ("sqlite", "postgres", "mysql", "sqlserver", "oracle"):
+            raise ValueError(f"Unsupported database type: {self.db_type!r}")
+
+    # -----------------------------------------------------------------------
+    # Connection lifecycle
+    # -----------------------------------------------------------------------
+
+    async def connect(self) -> None:
+        """Open the database connection."""
+        try:
+            if self.db_type == "sqlite":
+                import aiosqlite
+
+                self._connection = await aiosqlite.connect(self.database or "")  # type: ignore[arg-type]
+                self._connection.row_factory = aiosqlite.Row
+                logger.info("Connected to SQLite database: %s", self.database)
+
+            elif self.db_type == "postgres":
+                import asyncpg
+
+                self._connection = await asyncpg.connect(
+                    host=self.host,
+                    port=int(self.port or 5432),
+                    user=self.user,
+                    password=self.password,
+                    database=self.database,
+                )
+                logger.info("Connected to PostgreSQL database: %s", self.database)
+
+            elif self.db_type == "mysql":
+                import aiomysql
+
+                self._connection = await aiomysql.connect(
+                    host=self.host or "localhost",
+                    port=int(self.port or 3306),
+                    user=self.user,
+                    password=self.password or "",
+                    db=self.database,
+                    autocommit=False,
+                )
+                logger.info("Connected to MySQL database: %s", self.database)
+
+            elif self.db_type == "sqlserver":
+                import aioodbc
+
+                dsn = (
+                    f"DRIVER={self.driver};"
+                    f"SERVER={self.host};"
+                    f"DATABASE={self.database};"
+                    f"UID={self.user};"
+                    f"PWD={self.password}"
+                )
+                self._connection = await aioodbc.connect(dsn=dsn)
+                logger.info("Connected to SQL Server database: %s", self.database)
+
+            elif self.db_type == "oracle":
+                import oracledb
+
+                oracle_port = int(os.getenv("ORACLE_DB_PORT", "1521"))
+                dsn = oracledb.makedsn(
+                    self.host, oracle_port, sid=self.oracle_sid  # type: ignore[arg-type]
+                )
+                self._connection = await oracledb.connect_async(
+                    user=self.user, password=self.password, dsn=dsn
+                )
+                logger.info("Connected to Oracle database: %s", self.oracle_sid)
+
+        except Exception as e:
+            raise AsyncConnectionError(
+                f"Failed to connect to {self.db_type}: {e}"
+            ) from e
+
+    async def close(self) -> None:
+        """Close the database connection."""
+        try:
+            if self._connection is not None:
+                await self._connection.close()
+                self._connection = None
+                logger.info("Closed %s connection", self.db_type)
+        except Exception as e:
+            raise AsyncConnectionError(f"Failed to close connection: {e}") from e
+
+    async def __aenter__(self) -> "AsyncSQLPyHelper":
+        await self.connect()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> bool:
+        await self.close()
+        return False
+
+    # -----------------------------------------------------------------------
+    # Internal helpers
+    # -----------------------------------------------------------------------
+
+    def _check_connection(self) -> None:
+        if self._connection is None:
+            raise AsyncConnectionError(
+                "No active connection. Call connect() or use async with."
+            )
+
+    def _adapt_query(self, query: str, args: tuple) -> tuple[str, tuple]:
+        """
+        Adapt a query and its arguments for the active database driver.
+
+        asyncpg uses $1, $2, ... positional placeholders.
+        aiosqlite and aiomysql use ? and %s respectively.
+        Callers should write queries using $1, $2, ... style and this
+        method will translate as needed.
+        """
+        if not args:
+            return query, args
+
+        if self.db_type == "postgres":
+            # asyncpg natively uses $1, $2 — pass through unchanged
+            return query, args
+
+        elif self.db_type == "sqlite":
+            # Replace $1, $2 with ?
+            import re
+
+            adapted = re.sub(r"\$\d+", "?", query)
+            return adapted, args
+
+        elif self.db_type in ("mysql", "sqlserver"):
+            # Replace $1, $2 with %s
+            import re
+
+            adapted = re.sub(r"\$\d+", "%s", query)
+            return adapted, args
+
+        elif self.db_type == "oracle":
+            # Replace $1, $2 with :1, :2
+            import re
+
+            def replace_placeholder(m: Any) -> str:
+                return f":{m.group(0)[1:]}"
+
+            adapted = re.sub(r"\$(\d+)", replace_placeholder, query)
+            return adapted, args
+
+        return query, args
+
+    # -----------------------------------------------------------------------
+    # Query execution
+    # -----------------------------------------------------------------------
+
+    async def execute(self, query: str, *args: Any) -> None:
+        """
+        Execute a SQL statement (INSERT, UPDATE, DELETE, DDL).
+
+        Use $1, $2, ... for parameterised values::
+
+            await db.execute(
+                "INSERT INTO users (id, name) VALUES ($1, $2)",
+                1, "Alice"
+            )
+
+        Args:
+            query: SQL query string using $1, $2 placeholders.
+            *args: Query parameters.
+
+        Raises:
+            AsyncQueryError: If the query fails.
+        """
+        self._check_connection()
+        adapted_query, adapted_args = self._adapt_query(query, args)
+        try:
+            if self.db_type == "postgres":
+                await self._connection.execute(adapted_query, *adapted_args)
+
+            elif self.db_type == "sqlite":
+                await self._connection.execute(adapted_query, adapted_args)
+                await self._connection.commit()
+
+            elif self.db_type in ("mysql", "sqlserver"):
+                async with self._connection.cursor() as cursor:
+                    await cursor.execute(adapted_query, adapted_args)
+                await self._connection.commit()
+
+            elif self.db_type == "oracle":
+                cursor = self._connection.cursor()
+                await cursor.execute(adapted_query, adapted_args)
+                await self._connection.commit()
+
+            logger.debug("Executed: %s", query)
+
+        except Exception as e:
+            raise AsyncQueryError(f"Query failed: {e}") from e
+
+    async def fetch_one(self, query: str, *args: Any) -> Optional[Any]:
+        """
+        Execute a SELECT query and return a single row, or None.
+
+        Args:
+            query: SQL query string using $1, $2 placeholders.
+            *args: Query parameters.
+
+        Returns:
+            A single row, or None if no rows matched.
+
+        Raises:
+            AsyncQueryError: If the query fails.
+        """
+        self._check_connection()
+        adapted_query, adapted_args = self._adapt_query(query, args)
+        try:
+            if self.db_type == "postgres":
+                return await self._connection.fetchrow(adapted_query, *adapted_args)
+
+            elif self.db_type == "sqlite":
+                async with self._connection.execute(
+                    adapted_query, adapted_args
+                ) as cursor:
+                    return await cursor.fetchone()
+
+            elif self.db_type in ("mysql", "sqlserver"):
+                async with self._connection.cursor() as cursor:
+                    await cursor.execute(adapted_query, adapted_args)
+                    return await cursor.fetchone()
+
+            elif self.db_type == "oracle":
+                cursor = self._connection.cursor()
+                await cursor.execute(adapted_query, adapted_args)
+                return await cursor.fetchone()
+
+            return None
+
+        except Exception as e:
+            raise AsyncQueryError(f"fetch_one failed: {e}") from e
+
+    async def fetch_all(self, query: str, *args: Any) -> list[Any]:
+        """
+        Execute a SELECT query and return all rows.
+
+        Args:
+            query: SQL query string using $1, $2 placeholders.
+            *args: Query parameters.
+
+        Returns:
+            A list of rows (empty list if no rows matched).
+
+        Raises:
+            AsyncQueryError: If the query fails.
+        """
+        self._check_connection()
+        adapted_query, adapted_args = self._adapt_query(query, args)
+        try:
+            if self.db_type == "postgres":
+                return await self._connection.fetch(adapted_query, *adapted_args)
+
+            elif self.db_type == "sqlite":
+                async with self._connection.execute(
+                    adapted_query, adapted_args
+                ) as cursor:
+                    return await cursor.fetchall()
+
+            elif self.db_type in ("mysql", "sqlserver"):
+                async with self._connection.cursor() as cursor:
+                    await cursor.execute(adapted_query, adapted_args)
+                    return await cursor.fetchall()
+
+            elif self.db_type == "oracle":
+                cursor = self._connection.cursor()
+                await cursor.execute(adapted_query, adapted_args)
+                return await cursor.fetchall()
+
+            return []
+
+        except Exception as e:
+            raise AsyncQueryError(f"fetch_all failed: {e}") from e
+
+    async def fetch_val(self, query: str, *args: Any) -> Optional[Any]:
+        """
+        Execute a SELECT query and return a single scalar value.
+
+        Useful for COUNT, SUM, or any query returning one value::
+
+            count = await db.fetch_val("SELECT COUNT(*) FROM users")
+
+        Args:
+            query: SQL query string using $1, $2 placeholders.
+            *args: Query parameters.
+
+        Returns:
+            A single scalar value, or None.
+
+        Raises:
+            AsyncQueryError: If the query fails.
+        """
+        self._check_connection()
+        adapted_query, adapted_args = self._adapt_query(query, args)
+        try:
+            if self.db_type == "postgres":
+                return await self._connection.fetchval(adapted_query, *adapted_args)
+
+            elif self.db_type == "sqlite":
+                async with self._connection.execute(
+                    adapted_query, adapted_args
+                ) as cursor:
+                    row = await cursor.fetchone()
+                    return row[0] if row else None
+
+            elif self.db_type in ("mysql", "sqlserver"):
+                async with self._connection.cursor() as cursor:
+                    await cursor.execute(adapted_query, adapted_args)
+                    row = await cursor.fetchone()
+                    return row[0] if row else None
+
+            elif self.db_type == "oracle":
+                cursor = self._connection.cursor()
+                await cursor.execute(adapted_query, adapted_args)
+                row = await cursor.fetchone()
+                return row[0] if row else None
+
+            return None
+
+        except Exception as e:
+            raise AsyncQueryError(f"fetch_val failed: {e}") from e
+
+    async def execute_many(self, query: str, args_list: list[tuple]) -> None:
+        """
+        Execute a SQL statement multiple times with different parameters.
+        Efficient for bulk inserts::
+
+            await db.execute_many(
+                "INSERT INTO users (id, name) VALUES ($1, $2)",
+                [(1, "Alice"), (2, "Bob"), (3, "Charlie")]
+            )
+
+        Args:
+            query:     SQL query string using $1, $2 placeholders.
+            args_list: List of parameter tuples.
+
+        Raises:
+            AsyncQueryError: If the operation fails.
+        """
+        self._check_connection()
+        if not args_list:
+            return
+        try:
+            if self.db_type == "postgres":
+                await self._connection.executemany(query, args_list)
+
+            elif self.db_type == "sqlite":
+                import re
+
+                adapted = re.sub(r"\$\d+", "?", query)
+                await self._connection.executemany(adapted, args_list)
+                await self._connection.commit()
+
+            elif self.db_type in ("mysql", "sqlserver"):
+                import re
+
+                adapted = re.sub(r"\$\d+", "%s", query)
+                async with self._connection.cursor() as cursor:
+                    await cursor.executemany(adapted, args_list)
+                await self._connection.commit()
+
+            elif self.db_type == "oracle":
+                import re
+
+                def replace_placeholder(m: Any) -> str:
+                    return f":{m.group(1)}"
+
+                adapted = re.sub(r"\$(\d+)", replace_placeholder, query)
+                cursor = self._connection.cursor()
+                await cursor.executemany(adapted, args_list)
+                await self._connection.commit()
+
+            logger.debug("execute_many: %d rows", len(args_list))
+
+        except Exception as e:
+            raise AsyncQueryError(f"execute_many failed: {e}") from e
+
+    # -----------------------------------------------------------------------
+    # Transaction management
+    # -----------------------------------------------------------------------
+
+    async def begin_transaction(self) -> None:
+        """
+        Begin an explicit transaction.
+
+        For PostgreSQL, use the transaction() context manager instead,
+        which is the idiomatic asyncpg approach.
+
+        Raises:
+            AsyncQueryError: If the transaction cannot be started.
+        """
+        self._check_connection()
+        try:
+            if self.db_type == "sqlite":
+                await self._connection.execute("BEGIN")
+            elif self.db_type == "mysql":
+                await self._connection.begin()
+            elif self.db_type == "sqlserver":
+                async with self._connection.cursor() as cursor:
+                    await cursor.execute("BEGIN TRANSACTION")
+            elif self.db_type == "oracle":
+                pass  # Oracle starts transactions implicitly
+            elif self.db_type == "postgres":
+                # asyncpg transactions are managed via connection.transaction()
+                # Calling begin() manually is supported but the context manager
+                # is preferred — see transaction() below
+                self._pg_transaction = self._connection.transaction()
+                await self._pg_transaction.start()
+            logger.info("Transaction started on %s", self.db_type)
+        except Exception as e:
+            raise AsyncQueryError(f"Failed to begin transaction: {e}") from e
+
+    async def commit_transaction(self) -> None:
+        """Commit the current transaction."""
+        self._check_connection()
+        try:
+            if self.db_type == "postgres":
+                await self._pg_transaction.commit()
+            else:
+                await self._connection.commit()
+            logger.info("Transaction committed on %s", self.db_type)
+        except Exception as e:
+            raise AsyncQueryError(f"Failed to commit transaction: {e}") from e
+
+    async def rollback_transaction(self) -> None:
+        """Roll back the current transaction."""
+        self._check_connection()
+        try:
+            if self.db_type == "postgres":
+                await self._pg_transaction.rollback()
+            else:
+                await self._connection.rollback()
+            logger.info("Transaction rolled back on %s", self.db_type)
+        except Exception as e:
+            raise AsyncQueryError(f"Failed to rollback transaction: {e}") from e
+
+    # -----------------------------------------------------------------------
+    # Connection pooling
+    # -----------------------------------------------------------------------
+
+    async def setup_pool(self, min_size: int = 1, max_size: int = 10) -> None:
+        """
+        Set up an async connection pool.
+
+        Supported for PostgreSQL and MySQL only.
+        After calling this, use get_connection_from_pool() to acquire
+        connections.
+
+        Args:
+            min_size: Minimum number of connections in the pool.
+            max_size: Maximum number of connections in the pool.
+
+        Raises:
+            AsyncConnectionError: If pool setup fails or db_type
+                                  does not support pooling.
+        """
+        try:
+            if self.db_type == "postgres":
+                import asyncpg
+
+                self._pool = await asyncpg.create_pool(
+                    host=self.host,
+                    port=int(self.port or 5432),
+                    user=self.user,
+                    password=self.password,
+                    database=self.database,
+                    min_size=min_size,
+                    max_size=max_size,
+                )
+                logger.info(
+                    "PostgreSQL async pool created (min=%d, max=%d)", min_size, max_size
+                )
+
+            elif self.db_type == "mysql":
+                import aiomysql
+
+                self._pool = await aiomysql.create_pool(
+                    host=self.host or "localhost",
+                    port=int(self.port or 3306),
+                    user=self.user,
+                    password=self.password or "",
+                    db=self.database,
+                    minsize=min_size,
+                    maxsize=max_size,
+                )
+                logger.info(
+                    "MySQL async pool created (min=%d, max=%d)", min_size, max_size
+                )
+
+            else:
+                raise AsyncConnectionError(
+                    f"Async connection pooling not supported for {self.db_type!r}. "
+                    "Supported: postgres, mysql."
+                )
+        except AsyncConnectionError:
+            raise
+        except Exception as e:
+            raise AsyncConnectionError(f"Failed to create async pool: {e}") from e
+
+    async def close_pool(self) -> None:
+        """Close the async connection pool."""
+        if self._pool is not None:
+            if self.db_type == "mysql":
+                self._pool.close()
+                await self._pool.wait_closed()
+            else:
+                await self._pool.close()
+            self._pool = None
+            logger.info("Async pool closed for %s", self.db_type)

sqlpyhelper-0.1.8/test/test_async_helper.py

@@ -0,0 +1,478 @@
+"""
+Tests for sqlpyhelper.async_helper
+All tests use mocking — no live database required.
+Uses pytest-asyncio for async test support.
+"""
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from sqlpyhelper.async_helper import (
+    AsyncConnectionError,
+    AsyncQueryError,
+    AsyncSQLPyHelper,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def make_async_db(db_type: str = "sqlite") -> AsyncSQLPyHelper:
+    """Create an AsyncSQLPyHelper instance without connecting."""
+    kwargs = {"db_type": db_type, "database": "test.db"}
+    if db_type != "sqlite":
+        kwargs.update(
+            {
+                "host": "localhost",
+                "user": "user",
+                "password": "pass",
+                "database": "testdb",
+            }
+        )
+    if db_type == "oracle":
+        kwargs["oracle_sid"] = "XE"
+    if db_type == "sqlserver":
+        kwargs["driver"] = "ODBC Driver 17 for SQL Server"
+    return AsyncSQLPyHelper(**kwargs)
+
+
+def attach_mock_connection(db: AsyncSQLPyHelper) -> MagicMock:
+    """Attach a mock connection to an AsyncSQLPyHelper instance."""
+    mock_conn = MagicMock()
+    mock_conn.close = AsyncMock()
+    mock_conn.commit = AsyncMock()
+    mock_conn.rollback = AsyncMock()
+    mock_conn.execute = AsyncMock()
+    mock_conn.executemany = AsyncMock()
+    mock_conn.fetch = AsyncMock(return_value=[])
+    mock_conn.fetchrow = AsyncMock(return_value=None)
+    mock_conn.fetchval = AsyncMock(return_value=None)
+    db._connection = mock_conn
+    return mock_conn
+
+
+# ---------------------------------------------------------------------------
+# __init__ validation
+# ---------------------------------------------------------------------------
+
+
+class TestInit:
+    def test_missing_database_raises(self):
+        with patch.dict("os.environ", {}, clear=True):
+            with pytest.raises(
+                ValueError, match="Missing required database configuration"
+            ):
+                AsyncSQLPyHelper(db_type="sqlite", database="")
+
+    def test_missing_db_type_raises(self):
+        with patch.dict("os.environ", {}, clear=True):
+            with pytest.raises(
+                ValueError, match="Missing required database configuration"
+            ):
+                AsyncSQLPyHelper(db_type="", database="test.db")
+
+    def test_unsupported_db_type_raises(self):
+        with pytest.raises(ValueError, match="Unsupported database type"):
+            AsyncSQLPyHelper(db_type="mongodb", database="test")
+
+    def test_valid_sqlite_init(self):
+        db = AsyncSQLPyHelper(db_type="sqlite", database="test.db")
+        assert db.db_type == "sqlite"
+        assert db.database == "test.db"
+        assert db._connection is None
+
+    def test_valid_postgres_init(self):
+        db = AsyncSQLPyHelper(
+            db_type="postgres",
+            host="localhost",
+            user="user",
+            password="pass",
+            database="testdb",
+        )
+        assert db.db_type == "postgres"
+
+
+# ---------------------------------------------------------------------------
+# connect / close
+# ---------------------------------------------------------------------------
+
+
+class TestConnect:
+    @pytest.mark.asyncio
+    async def test_sqlite_connect(self):
+        db = make_async_db("sqlite")
+        mock_conn = MagicMock()
+        mock_conn.close = AsyncMock()
+        with patch("aiosqlite.connect", new_callable=AsyncMock, return_value=mock_conn):
+            await db.connect()
+        assert db._connection is mock_conn
+
+    @pytest.mark.asyncio
+    async def test_postgres_connect(self):
+        db = make_async_db("postgres")
+        mock_conn = MagicMock()
+        mock_conn.close = AsyncMock()
+        with patch("asyncpg.connect", new_callable=AsyncMock, return_value=mock_conn):
+            await db.connect()
+        assert db._connection is mock_conn
+
+    @pytest.mark.asyncio
+    async def test_mysql_connect(self):
+        db = make_async_db("mysql")
+        mock_conn = MagicMock()
+        mock_conn.close = AsyncMock()
+        with patch("aiomysql.connect", new_callable=AsyncMock, return_value=mock_conn):
+            await db.connect()
+        assert db._connection is mock_conn
+
+    @pytest.mark.asyncio
+    async def test_connect_failure_raises_async_connection_error(self):
+        db = make_async_db("sqlite")
+        with patch("aiosqlite.connect", side_effect=Exception("disk full")):
+            with pytest.raises(AsyncConnectionError, match="Failed to connect"):
+                await db.connect()
+
+    @pytest.mark.asyncio
+    async def test_close(self):
+        db = make_async_db("sqlite")
+        mock_conn = attach_mock_connection(db)
+        await db.close()
+        mock_conn.close.assert_called_once()
+        assert db._connection is None
+
+    @pytest.mark.asyncio
+    async def test_close_raises_on_failure(self):
+        db = make_async_db("sqlite")
+        mock_conn = attach_mock_connection(db)
+        mock_conn.close.side_effect = Exception("already closed")
+        with pytest.raises(AsyncConnectionError, match="Failed to close"):
+            await db.close()
+
+
+# ---------------------------------------------------------------------------
+# Context manager
+# ---------------------------------------------------------------------------
+
+
+class TestContextManager:
+    @pytest.mark.asyncio
+    async def test_aenter_returns_self(self):
+        db = make_async_db("sqlite")
+        mock_conn = MagicMock()
+        mock_conn.close = AsyncMock()
+        with patch("aiosqlite.connect", new_callable=AsyncMock, return_value=mock_conn):
+            result = await db.__aenter__()
+        assert result is db
+
+    @pytest.mark.asyncio
+    async def test_aexit_closes_connection(self):
+        db = make_async_db("sqlite")
+        mock_conn = attach_mock_connection(db)
+        await db.__aexit__(None, None, None)
+        mock_conn.close.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_aexit_returns_false(self):
+        db = make_async_db("sqlite")
+        attach_mock_connection(db)
+        result = await db.__aexit__(None, None, None)
+        assert result is False
+
+    @pytest.mark.asyncio
+    async def test_async_with_statement(self):
+        mock_conn = MagicMock()
+        mock_conn.close = AsyncMock()
+        with patch("aiosqlite.connect", new_callable=AsyncMock, return_value=mock_conn):
+            async with AsyncSQLPyHelper(db_type="sqlite", database="test.db") as db:
+                assert db._connection is mock_conn
+        mock_conn.close.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# _check_connection
+# ---------------------------------------------------------------------------
+
+
+class TestCheckConnection:
+    def test_raises_when_no_connection(self):
+        db = make_async_db("sqlite")
+        with pytest.raises(AsyncConnectionError, match="No active connection"):
+            db._check_connection()
+
+    def test_passes_when_connected(self):
+        db = make_async_db("sqlite")
+        attach_mock_connection(db)
+        db._check_connection()  # should not raise
+
+
+# ---------------------------------------------------------------------------
+# _adapt_query
+# ---------------------------------------------------------------------------
+
+
+class TestAdaptQuery:
+    def test_postgres_passes_through(self):
+        db = make_async_db("postgres")
+        q, args = db._adapt_query("SELECT $1", (1,))
+        assert q == "SELECT $1"
+
+    def test_sqlite_replaces_with_question_mark(self):
+        db = make_async_db("sqlite")
+        q, args = db._adapt_query("SELECT $1, $2", (1, 2))
+        assert q == "SELECT ?, ?"
+
+    def test_mysql_replaces_with_percent_s(self):
+        db = make_async_db("mysql")
+        q, args = db._adapt_query("SELECT $1, $2", (1, 2))
+        assert q == "SELECT %s, %s"
+
+    def test_oracle_replaces_with_colon(self):
+        db = AsyncSQLPyHelper(
+            db_type="oracle",
+            host="localhost",
+            user="u",
+            password="p",
+            database="d",
+            oracle_sid="XE",
+        )
+        q, args = db._adapt_query("SELECT $1, $2", (1, 2))
+        assert q == "SELECT :1, :2"
+
+    def test_empty_args_returns_unchanged(self):
+        db = make_async_db("sqlite")
+        q, args = db._adapt_query("SELECT 1", ())
+        assert q == "SELECT 1"
+        assert args == ()
+
+
+# ---------------------------------------------------------------------------
+# execute
+# ---------------------------------------------------------------------------
+
+
+class TestExecute:
+    @pytest.mark.asyncio
+    async def test_sqlite_execute(self):
+        db = make_async_db("sqlite")
+        mock_conn = attach_mock_connection(db)
+        await db.execute("CREATE TABLE users (id INTEGER)")
+        mock_conn.execute.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_postgres_execute(self):
+        db = make_async_db("postgres")
+        mock_conn = attach_mock_connection(db)
+        await db.execute("INSERT INTO users VALUES ($1)", 1)
+        mock_conn.execute.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_raises_async_query_error_on_failure(self):
+        db = make_async_db("sqlite")
+        mock_conn = attach_mock_connection(db)
+        mock_conn.execute.side_effect = Exception("disk full")
+        with pytest.raises(AsyncQueryError, match="Query failed"):
+            await db.execute("INSERT INTO users VALUES ($1)", 1)
+
+    @pytest.mark.asyncio
+    async def test_raises_when_not_connected(self):
+        db = make_async_db("sqlite")
+        with pytest.raises(AsyncConnectionError, match="No active connection"):
+            await db.execute("SELECT 1")
+
+
+# ---------------------------------------------------------------------------
+# fetch_one
+# ---------------------------------------------------------------------------
+
+
+class TestFetchOne:
+    @pytest.mark.asyncio
+    async def test_postgres_fetch_one(self):
+        db = make_async_db("postgres")
+        mock_conn = attach_mock_connection(db)
+        mock_conn.fetchrow.return_value = {"id": 1, "name": "Alice"}
+        result = await db.fetch_one("SELECT * FROM users WHERE id = $1", 1)
+        assert result == {"id": 1, "name": "Alice"}
+
+    @pytest.mark.asyncio
+    async def test_raises_on_failure(self):
+        db = make_async_db("postgres")
+        mock_conn = attach_mock_connection(db)
+        mock_conn.fetchrow.side_effect = Exception("connection lost")
+        with pytest.raises(AsyncQueryError, match="fetch_one failed"):
+            await db.fetch_one("SELECT * FROM users")
+
+    @pytest.mark.asyncio
+    async def test_raises_when_not_connected(self):
+        db = make_async_db("sqlite")
+        with pytest.raises(AsyncConnectionError):
+            await db.fetch_one("SELECT 1")
+
+
+# ---------------------------------------------------------------------------
+# fetch_all
+# ---------------------------------------------------------------------------
+
+
+class TestFetchAll:
+    @pytest.mark.asyncio
+    async def test_postgres_fetch_all(self):
+        db = make_async_db("postgres")
+        mock_conn = attach_mock_connection(db)
+        mock_conn.fetch.return_value = [{"id": 1}, {"id": 2}]
+        result = await db.fetch_all("SELECT * FROM users")
+        assert len(result) == 2
+
+    @pytest.mark.asyncio
+    async def test_raises_on_failure(self):
+        db = make_async_db("postgres")
+        mock_conn = attach_mock_connection(db)
+        mock_conn.fetch.side_effect = Exception("timeout")
+        with pytest.raises(AsyncQueryError, match="fetch_all failed"):
+            await db.fetch_all("SELECT * FROM users")
+
+    @pytest.mark.asyncio
+    async def test_raises_when_not_connected(self):
+        db = make_async_db("sqlite")
+        with pytest.raises(AsyncConnectionError):
+            await db.fetch_all("SELECT 1")
+
+
+# ---------------------------------------------------------------------------
+# fetch_val
+# ---------------------------------------------------------------------------
+
+
+class TestFetchVal:
+    @pytest.mark.asyncio
+    async def test_postgres_fetch_val(self):
+        db = make_async_db("postgres")
+        mock_conn = attach_mock_connection(db)
+        mock_conn.fetchval.return_value = 42
+        result = await db.fetch_val("SELECT COUNT(*) FROM users")
+        assert result == 42
+
+    @pytest.mark.asyncio
+    async def test_raises_on_failure(self):
+        db = make_async_db("postgres")
+        mock_conn = attach_mock_connection(db)
+        mock_conn.fetchval.side_effect = Exception("error")
+        with pytest.raises(AsyncQueryError, match="fetch_val failed"):
+            await db.fetch_val("SELECT COUNT(*) FROM users")
+
+
+# ---------------------------------------------------------------------------
+# execute_many
+# ---------------------------------------------------------------------------
+
+
+class TestExecuteMany:
+    @pytest.mark.asyncio
+    async def test_postgres_execute_many(self):
+        db = make_async_db("postgres")
+        mock_conn = attach_mock_connection(db)
+        mock_conn.executemany = AsyncMock()
+        await db.execute_many(
+            "INSERT INTO users VALUES ($1, $2)", [(1, "Alice"), (2, "Bob")]
+        )
+        mock_conn.executemany.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_empty_list_does_nothing(self):
+        db = make_async_db("postgres")
+        mock_conn = attach_mock_connection(db)
+        await db.execute_many("INSERT INTO users VALUES ($1)", [])
+        mock_conn.executemany.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_raises_on_failure(self):
+        db = make_async_db("postgres")
+        mock_conn = attach_mock_connection(db)
+        mock_conn.executemany.side_effect = Exception("error")
+        with pytest.raises(AsyncQueryError, match="execute_many failed"):
+            await db.execute_many("INSERT INTO users VALUES ($1)", [(1,)])
+
+
+# ---------------------------------------------------------------------------
+# Transactions
+# ---------------------------------------------------------------------------
+
+
+class TestTransactions:
+    @pytest.mark.asyncio
+    async def test_mysql_begin_calls_begin(self):
+        db = make_async_db("mysql")
+        mock_conn = attach_mock_connection(db)
+        mock_conn.begin = AsyncMock()
+        await db.begin_transaction()
+        mock_conn.begin.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_commit(self):
+        db = make_async_db("mysql")
+        mock_conn = attach_mock_connection(db)
+        await db.commit_transaction()
+        mock_conn.commit.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_rollback(self):
+        db = make_async_db("mysql")
+        mock_conn = attach_mock_connection(db)
+        await db.rollback_transaction()
+        mock_conn.rollback.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_rollback_raises_on_failure(self):
+        db = make_async_db("mysql")
+        mock_conn = attach_mock_connection(db)
+        mock_conn.rollback.side_effect = Exception("rollback error")
+        with pytest.raises(AsyncQueryError, match="Failed to rollback"):
+            await db.rollback_transaction()
+
+
+# ---------------------------------------------------------------------------
+# Connection pool
+# ---------------------------------------------------------------------------
+
+
+class TestPool:
+    @pytest.mark.asyncio
+    async def test_postgres_pool_setup(self):
+        db = make_async_db("postgres")
+        mock_pool = MagicMock()
+        mock_pool.close = AsyncMock()
+        with patch(
+            "asyncpg.create_pool", new_callable=AsyncMock, return_value=mock_pool
+        ):
+            await db.setup_pool(min_size=1, max_size=5)
+        assert db._pool is mock_pool
+
+    @pytest.mark.asyncio
+    async def test_mysql_pool_setup(self):
+        db = make_async_db("mysql")
+        mock_pool = MagicMock()
+        mock_pool.close = MagicMock()
+        mock_pool.wait_closed = AsyncMock()
+        with patch(
+            "aiomysql.create_pool", new_callable=AsyncMock, return_value=mock_pool
+        ):
+            await db.setup_pool(min_size=1, max_size=5)
+        assert db._pool is mock_pool
+
+    @pytest.mark.asyncio
+    async def test_unsupported_db_raises(self):
+        db = make_async_db("sqlite")
+        with pytest.raises(AsyncConnectionError, match="not supported"):
+            await db.setup_pool()
+
+    @pytest.mark.asyncio
+    async def test_close_pool_postgres(self):
+        db = make_async_db("postgres")
+        mock_pool = MagicMock()
+        mock_pool.close = AsyncMock()
+        db._pool = mock_pool
+        await db.close_pool()
+        mock_pool.close.assert_called_once()
+        assert db._pool is None

sqlpyhelper-0.1.7/SQLPyHelper.egg-info/requires.txt

@@ -1,20 +0,0 @@
-python-dotenv
-click
-
-[all]
-psycopg2
-mysql-connector-python
-pyodbc
-oracledb
-
-[mysql]
-mysql-connector-python
-
-[oracle]
-oracledb
-
-[postgres]
-psycopg2
-
-[sqlserver]
-pyodbc