iker-python-common 1.0.61__py3-none-any.whl → 1.0.63__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.61.dist-info → iker_python_common-1.0.63.dist-info}/METADATA

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: iker-python-common
-Version: 1.0.61
+Version: 1.0.63
 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: docker>=7.1
+Requires-Dist: asyncpg>=0.30
 Requires-Dist: numpy>=2.3
 Requires-Dist: psycopg>=3.2
 Requires-Dist: pymysql>=1.1
@@ -15,6 +15,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.61.dist-info → iker_python_common-1.0.63.dist-info}/RECORD

@@ -3,8 +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/dockerutils.py,sha256=n2WuzXaZB6_WocSljvPOnfExSIjIHRUbuWp2oBbaPKQ,8004
+iker/common/utils/dbutils.py,sha256=09DgvfPVDCPXwOAO_FTynLXhSq--ZzRz2fCQ6vJ5qqk,16151
 iker/common/utils/dtutils.py,sha256=86vbaa4pgcBWERZvTfJ92PKB3IimxP6tf0O11ho2Ffk,12554
 iker/common/utils/funcutils.py,sha256=4AkkvK9_Z2tgk1-Sp6-vLLVhI15cIgN9xW58QqL5QL4,7780
 iker/common/utils/jsonutils.py,sha256=AkziMAYVQDODHRqZC-c1x7VqI2hHY3Kxrw7gmoss8mU,18527
@@ -18,7 +17,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.61.dist-info/METADATA,sha256=ljOFhe6VlK3XJSewSNpaYBZEOfQu5TCKVE47pvggop4,813
-iker_python_common-1.0.61.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-iker_python_common-1.0.61.dist-info/top_level.txt,sha256=4_B8Prfc_lxFafFYTQThIU1ZqOYQ4pHHHnJ_fQ_oHs8,5
-iker_python_common-1.0.61.dist-info/RECORD,,
+iker_python_common-1.0.63.dist-info/METADATA,sha256=QUw6lKzGDZRY3Aul1qTE4B_dxtO96Tw0Mvo_acp9Ilw,867
+iker_python_common-1.0.63.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+iker_python_common-1.0.63.dist-info/top_level.txt,sha256=4_B8Prfc_lxFafFYTQThIU1ZqOYQ4pHHHnJ_fQ_oHs8,5
+iker_python_common-1.0.63.dist-info/RECORD,,

{iker_python_common-1.0.61.dist-info → iker_python_common-1.0.63.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

iker/common/utils/dockerutils.py

@@ -1,236 +0,0 @@
-import contextlib
-import dataclasses
-import re
-from collections.abc import Generator, Iterator
-from typing import Any
-
-import docker
-import docker.errors
-import docker.models.containers
-import docker.models.images
-import requests.exceptions
-
-from iker.common.utils import logger
-from iker.common.utils.strutils import parse_int_or, trim_to_empty
-
-__all__ = [
-    "ImageName",
-    "docker_create_client",
-    "docker_build_image",
-    "docker_get_image",
-    "docker_pull_image",
-    "docker_fetch_image",
-    "docker_run_detached",
-]
-
-
-@dataclasses.dataclass
-class ImageName(object):
-    registry_host: str | None
-    registry_port: int | None
-    components: list[str]
-    tag: str | None
-
-    @property
-    def registry(self) -> str:
-        if self.registry_host is None and self.registry_port is None:
-            return ""
-        if self.registry_port is None:
-            return self.registry_host
-        return f"{self.registry_host}:{self.registry_port}"
-
-    @property
-    def repository(self) -> str:
-        return "/".join(self.components)
-
-    @staticmethod
-    def parse(s: str):
-
-        # Registry absent version
-        matcher = re.compile(
-            r"^(?P<components>[a-z0-9]+((__?|-+)[a-z0-9]+)*(/[a-z0-9]+((__?|-+)[a-z0-9]+)*)*)(:(?P<tag>\w[\w.-]{0,127}))?$")
-        match = matcher.match(s)
-        if match:
-            return ImageName(registry_host=None,
-                             registry_port=None,
-                             components=trim_to_empty(match.group("components")).split("/"),
-                             tag=match.group("tag"))
-
-        # Registry present version
-        matcher = re.compile(
-            r"^((?P<host>[a-zA-Z0-9.-]+)(:(?P<port>\d+))?/)?(?P<components>[a-z0-9]+((__?|-+)[a-z0-9]+)*(/[a-z0-9]+((__?|-+)[a-z0-9]+)*)*)(:(?P<tag>\w[\w.-]{0,127}))?$")
-        match = matcher.match(s)
-        if match:
-            return ImageName(registry_host=match.group("host"),
-                             registry_port=parse_int_or(match.group("port"), None),
-                             components=trim_to_empty(match.group("components")).split("/"),
-                             tag=match.group("tag"))
-
-        return None
-
-
-def docker_create_client(
-    registry: str,
-    username: str,
-    password: str,
-) -> contextlib.AbstractContextManager[docker.DockerClient]:
-    try:
-        client = docker.DockerClient()
-        client.login(registry=registry, username=username, password=password, reauth=True)
-        return contextlib.closing(client)
-    except docker.errors.APIError:
-        logger.exception("Failed to login Docker server <%s>", registry)
-        raise
-
-
-def docker_build_image(
-    client: docker.DockerClient,
-    tag: str,
-    path: str,
-    dockerfile: str,
-    build_args: dict[str, str],
-) -> tuple[docker.models.images.Image, Iterator[dict[str, str]]]:
-    try:
-        return client.images.build(tag=tag,
-                                   path=path,
-                                   dockerfile=dockerfile,
-                                   buildargs=build_args,
-                                   rm=True,
-                                   forcerm=True,
-                                   nocache=True)
-
-    except docker.errors.BuildError:
-        logger.exception("Failed to build image <%s>", tag)
-        raise
-    except docker.errors.APIError:
-        logger.exception("Docker server returns an error while building image <%s>", tag)
-        raise
-    except Exception:
-        logger.exception("Unexpected error occurred while building image <%s>", tag)
-        raise
-
-
-def docker_get_image(
-    client: docker.DockerClient,
-    image: str,
-) -> docker.models.images.Image:
-    try:
-        return client.images.get(image)
-    except docker.errors.ImageNotFound:
-        logger.exception("Image <%s> is not found from local repository", image)
-        raise
-    except docker.errors.APIError:
-        logger.exception("Docker server returns an error while getting image <%s>", image)
-        raise
-    except Exception:
-        logger.exception("Unexpected error occurred while getting image <%s>", image)
-        raise
-
-
-def docker_pull_image(
-    client: docker.DockerClient,
-    image: str,
-    fallback_local: bool = False,
-) -> docker.models.images.Image:
-    try:
-        return client.images.pull(image)
-    except docker.errors.ImageNotFound:
-        if not fallback_local:
-            logger.exception("Image <%s> is not found from remote repository", image)
-            raise
-        logger.warning("Image <%s> is not found from remote repository, try local repository instead", image)
-    except docker.errors.APIError:
-        if not fallback_local:
-            logger.exception("Docker server returns an error while pulling image <%s>", image)
-            raise
-        logger.warning("Docker server returns an error while pulling image <%s>, try local repository instead", image)
-    except Exception:
-        logger.exception("Unexpected error occurred while pulling image <%s>", image)
-        raise
-
-    return docker_get_image(client, image)
-
-
-def docker_fetch_image(
-    client: docker.DockerClient,
-    image: str,
-    force_pull: bool = False,
-) -> docker.models.images.Image:
-    if force_pull:
-        return docker_pull_image(client, image, fallback_local=True)
-    else:
-        try:
-            return docker_get_image(client, image)
-        except Exception:
-            return docker_pull_image(client, image, fallback_local=False)
-
-
-def docker_run_detached(
-    client: docker.DockerClient,
-    image: str,
-    name: str,
-    command: str | list[str],
-    volumes: dict[str, dict[str, str]],
-    environment: dict[str, str],
-    extra_hosts: dict[str, str],
-    timeout: int,
-    **kwargs,
-) -> tuple[dict[str, Any], Any]:
-    @contextlib.contextmanager
-    def managed_docker_run(
-        client: docker.DockerClient,
-        **kwargs,
-    ) -> Generator[docker.models.containers.Container, None, None]:
-        container_model = None
-        try:
-            container_model = client.containers.run(**kwargs)
-            yield container_model
-        except docker.errors.DockerException:
-            raise
-        finally:
-            if container_model is not None:
-                try:
-                    if container_model.status != "exited":
-                        try:
-                            container_model.stop()
-                        except docker.errors.DockerException:
-                            pass
-                    container_model.wait()
-                    try:
-                        container_model.remove()
-                    except docker.errors.DockerException:
-                        pass
-                except Exception:
-                    raise
-
-    try:
-        run_args = kwargs.copy()
-        run_args.update(dict(image=image,
-                             name=name,
-                             command=command,
-                             volumes=volumes,
-                             environment=environment,
-                             extra_hosts=extra_hosts,
-                             detach=True))
-
-        with managed_docker_run(client, **run_args) as container_model:
-            result = container_model.wait(timeout=timeout)
-            logs = container_model.logs()
-
-            return result, logs
-
-    except requests.exceptions.ReadTimeout:
-        logger.exception("Running container <%s> of image <%s> exceed the timeout", name, image)
-        raise
-    except docker.errors.ImageNotFound:
-        logger.exception("Image <%s> is not found", image)
-        raise
-    except docker.errors.ContainerError:
-        logger.exception("Failed to run container <%s> of image <%s>", name, image)
-        raise
-    except docker.errors.APIError:
-        logger.exception("Docker server returns an error while running container <%s> of image <%s>", name, image)
-        raise
-    except Exception:
-        logger.exception("Unexpected error occurred while running container <%s> of image <%s>", image)
-        raise