iker-python-common 1.0.60__py3-none-any.whl → 1.0.62__py3-none-any.whl

iker/common/utils/dbutils.py

@@ -1,11 +1,13 @@
 import contextlib
 import dataclasses
-from typing import Any, Sequence
+from typing import Any, Self, Sequence
 
+import asyncpg
 import packaging.version
 import psycopg
 import pymysql
 import sqlalchemy
+import sqlalchemy.ext.asyncio
 import sqlalchemy.ext.compiler
 import sqlalchemy.orm
 
@@ -16,6 +18,7 @@ __all__ = [
     "Drivers",
     "make_scheme",
     "ConnectionMaker",
+    "AsyncConnectionMaker",
     "orm_to_dict",
     "orm_clone",
     "mysql_insert_ignore",
@@ -31,6 +34,7 @@ class Dialects:
 class Drivers:
     pymysql = pymysql.__name__
     psycopg = psycopg.__name__
+    asyncpg = asyncpg.__name__
 
 
 def make_scheme(dialect: str, driver: str | None = None) -> str:
@@ -65,9 +69,10 @@ class ConnectionMaker(object):
         self.engine_opts = engine_opts or {}
         self.session_opts = session_opts or {}
 
-    @staticmethod
+    @classmethod
     def create(
-        driver: str | None = None,
+        cls,
+        scheme: str | None = None,
         host: str | None = None,
         port: int | None = None,
         username: str | None = None,
@@ -76,11 +81,11 @@ class ConnectionMaker(object):
         *,
         engine_opts: dict[str, JsonType] | None = None,
         session_opts: dict[str, JsonType] | None = None,
-    ):
+    ) -> Self:
         """
         Creates a new instance of ``ConnectionMaker`` using the provided parameters to construct a SQLAlchemy URL.
 
-        :param driver: Optional database driver.
+        :param scheme: The database scheme (e.g., 'mysql+pymysql', 'postgresql+psycopg').
         :param host: The database host (e.g., 'localhost').
         :param port: The database port.
         :param username: The database username.
@@ -89,22 +94,23 @@ class ConnectionMaker(object):
         :param engine_opts: Optional dictionary of SQLAlchemy engine options.
         :param session_opts: Optional dictionary of SQLAlchemy session options.
         """
-        return ConnectionMaker(sqlalchemy.URL.create(drivername=driver,
-                                                     host=host,
-                                                     port=port,
-                                                     username=username,
-                                                     password=password,
-                                                     database=database),
-                               engine_opts=engine_opts,
-                               session_opts=session_opts)
-
-    @staticmethod
+        return cls(sqlalchemy.URL.create(drivername=scheme,
+                                         host=host,
+                                         port=port,
+                                         username=username,
+                                         password=password,
+                                         database=database),
+                   engine_opts=engine_opts,
+                   session_opts=session_opts)
+
+    @classmethod
     def from_url(
+        cls,
         url: str | sqlalchemy.URL,
         *,
         engine_opts: dict[str, JsonType] | None = None,
         session_opts: dict[str, JsonType] | None = None,
-    ) -> "ConnectionMaker":
+    ) -> Self:
         """
         Creates a new instance of ``ConnectionMaker`` from a SQLAlchemy URL string or object.
 
@@ -113,7 +119,7 @@ class ConnectionMaker(object):
         :param session_opts: Optional dictionary of SQLAlchemy session options.
         :return: A new instance of ``ConnectionMaker`` configured with the provided URL and options.
         """
-        return ConnectionMaker(sqlalchemy.make_url(url), engine_opts=engine_opts, session_opts=session_opts)
+        return cls(sqlalchemy.make_url(url), engine_opts=engine_opts, session_opts=session_opts)
 
     @property
     def connection_string(self) -> str:
@@ -155,7 +161,6 @@ class ConnectionMaker(object):
         Creates all tables defined in the given ORM base using the current engine.
 
         :param orm_base: The SQLAlchemy ORM base class.
-        :return: None.
         """
         if packaging.version.parse(sqlalchemy.__version__) >= packaging.version.parse("2"):
             if not isinstance(orm_base, type) or not issubclass(orm_base, sqlalchemy.orm.DeclarativeBase):
@@ -168,7 +173,6 @@ class ConnectionMaker(object):
         Drops all tables defined in the given ORM base using the current engine.
 
         :param orm_base: The SQLAlchemy ORM base class.
-        :return: None.
         """
         if packaging.version.parse(sqlalchemy.__version__) >= packaging.version.parse("2"):
             if not isinstance(orm_base, type) or not issubclass(orm_base, sqlalchemy.orm.DeclarativeBase):
@@ -182,7 +186,6 @@ class ConnectionMaker(object):
 
         :param sql: The SQL statement to execute.
         :param params: The parameters dictionary for the SQL statement.
-        :return: None.
         """
         with self.make_session() as session:
             session.execute(sqlalchemy.text(sql), params)
@@ -214,6 +217,104 @@ class ConnectionMaker(object):
             return result.first()
 
 
+class AsyncConnectionMaker(ConnectionMaker):
+    """
+    Provides utilities to simplify establishing asynchronous database connections and sessions, including connection
+    string construction, async engine and session creation, and model management.
+    """
+
+    @property
+    def engine(self) -> sqlalchemy.ext.asyncio.AsyncEngine:
+        """
+        Returns a SQLAlchemy ``AsyncEngine`` instance for the configured connection string and engine options.
+
+        :return: The SQLAlchemy ``AsyncEngine``.
+        """
+        return sqlalchemy.ext.asyncio.create_async_engine(self.connection_string, **self.engine_opts)
+
+    async def make_connection(self) -> sqlalchemy.ext.asyncio.AsyncConnection:
+        """
+        Asynchronously establishes and returns a new database connection using the SQLAlchemy async engine.
+
+        :return: A database connection object.
+        """
+        return await self.engine.connect()
+
+    def make_session(self, **kwargs) -> contextlib.AbstractAsyncContextManager[
+        sqlalchemy.ext.asyncio.AsyncSession
+    ]:
+        """
+        Creates a context-managed asynchronous SQLAlchemy session with the configured async engine and session options.
+
+        :param kwargs: Additional keyword arguments for session creation.
+        :return: A context manager yielding a SQLAlchemy ``AsyncSession``.
+        """
+        return contextlib.aclosing(
+            sqlalchemy.ext.asyncio.async_sessionmaker(self.engine, **{**self.session_opts, **kwargs})())
+
+    async def create_model(self, orm_base):
+        """
+        Asynchronously creates all tables defined in the given ORM base using the current async engine.
+
+        :param orm_base: The SQLAlchemy ORM base class.
+        """
+        if packaging.version.parse(sqlalchemy.__version__) >= packaging.version.parse("2"):
+            if not isinstance(orm_base, type) or not issubclass(orm_base, sqlalchemy.orm.DeclarativeBase):
+                raise TypeError("not a subclass of 'sqlalchemy.orm.DeclarativeBase'")
+
+        async with self.engine.begin() as conn:
+            await conn.run_sync(orm_base.metadata.create_all)
+
+    async def drop_model(self, orm_base):
+        """
+        Asynchronously drops all tables defined in the given ORM base using the current async engine.
+
+        :param orm_base: The SQLAlchemy ORM base class.
+        """
+        if packaging.version.parse(sqlalchemy.__version__) >= packaging.version.parse("2"):
+            if not isinstance(orm_base, type) or not issubclass(orm_base, sqlalchemy.orm.DeclarativeBase):
+                raise TypeError("not a subclass of 'sqlalchemy.orm.DeclarativeBase'")
+
+        async with self.engine.begin() as conn:
+            await conn.run_sync(orm_base.metadata.drop_all)
+
+    async def execute(self, sql: str, **params):
+        """
+        Executes the given SQL statement with the specified parameters.
+
+        :param sql: The SQL statement to execute.
+        :param params: The parameters dictionary for the SQL statement.
+        """
+        async with self.make_session() as session:
+            await session.execute(sqlalchemy.text(sql), params)
+            await session.commit()
+
+    async def query_all(self, sql: str, **params) -> Sequence[sqlalchemy.Row[tuple[Any, ...]]]:
+        """
+        Executes the given SQL query with the specified parameters and returns all result tuples.
+
+        :param sql: The SQL query to execute.
+        :param params: The parameters dictionary for the SQL query.
+        :return: A list of result tuples.
+        """
+        async with self.make_session() as session:
+            query = await session.execute(sqlalchemy.text(sql), params)
+            return query.all()
+
+    async def query_first(self, sql: str, **params) -> sqlalchemy.Row[tuple[Any, ...]] | None:
+        """
+        Executes the given SQL query with the specified parameters and returns the first result tuple, or ``None``
+        if no results are found.
+
+        :param sql: The SQL query to execute.
+        :param params: The parameters dictionary for the SQL query.
+        :return: The first result tuple, or ``None`` if no results are found.
+        """
+        async with self.make_session() as session:
+            query = await session.execute(sqlalchemy.text(sql), params)
+            return query.first()
+
+
 def orm_to_dict(orm, exclude: set[str] = None) -> dict[str, Any]:
     """
     Converts an ORM object to a dictionary, optionally excluding specified fields.

{iker_python_common-1.0.60.dist-info → iker_python_common-1.0.62.dist-info}/METADATA

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: iker-python-common
-Version: 1.0.60
+Version: 1.0.62
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: <3.15,>=3.12
+Requires-Dist: asyncpg>=0.30
 Requires-Dist: docker>=7.1
 Requires-Dist: numpy>=2.3
 Requires-Dist: psycopg>=3.2
@@ -15,6 +16,7 @@ Provides-Extra: all
 Requires-Dist: iker-python-common; extra == "all"
 Provides-Extra: test
 Requires-Dist: ddt>=1.7; extra == "test"
+Requires-Dist: pytest-asyncio>=1.2; extra == "test"
 Requires-Dist: pytest-cov>=5.0; extra == "test"
 Requires-Dist: pytest-mysql>=3.0; extra == "test"
 Requires-Dist: pytest-order>=1.3; extra == "test"

{iker_python_common-1.0.60.dist-info → iker_python_common-1.0.62.dist-info}/RECORD

@@ -3,7 +3,7 @@ iker/common/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU
 iker/common/utils/argutils.py,sha256=hMLNqdZs_Kjc2hw4Npm6N47RivP6JRNzCKIbJr1jYy8,9274
 iker/common/utils/config.py,sha256=z8rLqli961A-qAV9EaELp-pKuhNUNaq1Btdv-uwG7_I,4690
 iker/common/utils/csv.py,sha256=_V9OUrKcojec2L-hWagEIVnL2uvGjyJAFTrD7tHNr48,7573
-iker/common/utils/dbutils.py,sha256=zXZVJCz7HZPityFRF7sHRRMpMraegV_hyYnzApUUPhY,11852
+iker/common/utils/dbutils.py,sha256=09DgvfPVDCPXwOAO_FTynLXhSq--ZzRz2fCQ6vJ5qqk,16151
 iker/common/utils/dockerutils.py,sha256=n2WuzXaZB6_WocSljvPOnfExSIjIHRUbuWp2oBbaPKQ,8004
 iker/common/utils/dtutils.py,sha256=86vbaa4pgcBWERZvTfJ92PKB3IimxP6tf0O11ho2Ffk,12554
 iker/common/utils/funcutils.py,sha256=4AkkvK9_Z2tgk1-Sp6-vLLVhI15cIgN9xW58QqL5QL4,7780
@@ -18,7 +18,7 @@ iker/common/utils/span.py,sha256=u_KuWi2U7QDMUotl4AeW2_57ItL3YhVDSeCwaOiFDvs,596
 iker/common/utils/strutils.py,sha256=Tu_qFeH3K-SfwvMxdrZAc9iLPV8ZmtX4ntyyFGNslf8,5094
 iker/common/utils/testutils.py,sha256=2VieV5yeCDntSKQSpIeyqRT8BZmZYE_ArMeQz3g7fXY,5568
 iker/common/utils/typeutils.py,sha256=RVkYkFRgDrx77OHFH7PavMV0AIB0S8ly40rs4g7JWE4,8220
-iker_python_common-1.0.60.dist-info/METADATA,sha256=2B3f-_-H83ceea3JraxM602M47-BcdClWBtZIZLF_I0,813
-iker_python_common-1.0.60.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-iker_python_common-1.0.60.dist-info/top_level.txt,sha256=4_B8Prfc_lxFafFYTQThIU1ZqOYQ4pHHHnJ_fQ_oHs8,5
-iker_python_common-1.0.60.dist-info/RECORD,,
+iker_python_common-1.0.62.dist-info/METADATA,sha256=0xFB0M0zbyGoFcUy9Y-lfZGzNDbAhtW0574bl8XS7XU,894
+iker_python_common-1.0.62.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+iker_python_common-1.0.62.dist-info/top_level.txt,sha256=4_B8Prfc_lxFafFYTQThIU1ZqOYQ4pHHHnJ_fQ_oHs8,5
+iker_python_common-1.0.62.dist-info/RECORD,,