iker-python-common 1.0.48__tar.gz → 1.0.50__tar.gz

{iker_python_common-1.0.48 → iker_python_common-1.0.50}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iker-python-common
-Version: 1.0.48
+Version: 1.0.50
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12

{iker_python_common-1.0.48 → iker_python_common-1.0.50}/src/iker/common/utils/dbutils.py

@@ -1,7 +1,6 @@
 import contextlib
 import dataclasses
-import urllib.parse
-from typing import Any
+from typing import Any, Sequence
 
 import packaging.version
 import psycopg
@@ -10,12 +9,13 @@ import sqlalchemy
 import sqlalchemy.ext.compiler
 import sqlalchemy.orm
 
-from iker.common.utils.sequtils import head_or_none
-from iker.common.utils.strutils import is_blank
+from iker.common.utils.jsonutils import JsonType
 
 __all__ = [
+    "Dialects",
+    "Drivers",
+    "make_scheme",
     "ConnectionMaker",
-    "DBAdapter",
     "orm_to_dict",
     "orm_clone",
     "mysql_insert_ignore",
@@ -23,87 +23,73 @@ __all__ = [
 ]
 
 
+class Dialects:
+    mysql = "mysql"
+    postgresql = "postgresql"
+
+
+class Drivers:
+    pymysql = pymysql.__name__
+    psycopg = psycopg.__name__
+
+
+def make_scheme(dialect: str, driver: str | None = None) -> str:
+    """
+    Constructs a SQLAlchemy scheme string based on the provided dialect and driver.
+
+    :param dialect: The database dialect (e.g., 'mysql', 'postgresql').
+    :param driver: Optional database driver (e.g., 'pymysql', 'psycopg').
+    :return: A SQLAlchemy scheme string.
+    """
+    return dialect if driver is None else f"{dialect}+{driver}"
+
+
 class ConnectionMaker(object):
     """
     Provides utilities to simplify establishing database connections and sessions, including connection string
     construction, engine and session creation, and model management.
 
-    :param driver: The database driver string (e.g., ``mysql+pymysql``).
-    :param host: The database host.
-    :param port: The database port.
-    :param user: The database user.
-    :param password: The database password.
-    :param database: The database name.
+    :param url: A SQLAlchemy URL string or ``URL`` object representing the database connection.
     :param engine_opts: Optional dictionary of SQLAlchemy engine options.
     :param session_opts: Optional dictionary of SQLAlchemy session options.
     """
 
-    class Drivers:
-        Mysql = f"mysql+{pymysql.__name__}"
-        Postgresql = f"postgresql+{psycopg.__name__}"
-
     def __init__(
         self,
-        driver: str,
-        host: str,
-        port: int,
-        user: str,
-        password: str,
-        database: str,
-        engine_opts: dict[str, Any] | None = None,
-        session_opts: dict[str, Any] | None = None,
+        url: sqlalchemy.URL,
+        *,
+        engine_opts: dict[str, JsonType] | None = None,
+        session_opts: dict[str, JsonType] | None = None,
     ):
-        self.driver = driver
-        self.host = host
-        self.port = port
-        self.user = user
-        self.password = password
-        self.database = database
+        self.url = url
         self.engine_opts = engine_opts or {}
         self.session_opts = session_opts or {}
 
     @staticmethod
     def from_url(
-        driver: str,
-        url: str | urllib.parse.ParseResult,
-        engine_opts: dict[str, Any] | None = None,
-        session_opts: dict[str, Any] | None = None,
+        url: str | sqlalchemy.URL,
+        *,
+        engine_opts: dict[str, JsonType] | None = None,
+        session_opts: dict[str, JsonType] | None = None,
     ) -> "ConnectionMaker":
         """
-        Creates a ``ConnectionMaker`` instance from a URL string or ``ParseResult``, extracting connection parameters.
+        Creates a new instance of ``ConnectionMaker`` from a SQLAlchemy URL string or object.
 
-        :param driver: The database driver string.
-        :param url: The database URL as a string or ``ParseResult``.
+        :param url: A SQLAlchemy URL string or ``URL`` object representing the database connection.
         :param engine_opts: Optional dictionary of SQLAlchemy engine options.
         :param session_opts: Optional dictionary of SQLAlchemy session options.
-        :return: A ``ConnectionMaker`` instance.
+        :return: A new instance of ``ConnectionMaker`` configured with the provided URL and options.
         """
-        if isinstance(url, str):
-            return ConnectionMaker.from_url(driver, urllib.parse.urlparse(url), engine_opts, session_opts)
-        if isinstance(url, urllib.parse.ParseResult):
-            return ConnectionMaker(driver,
-                                   url.hostname,
-                                   url.port,
-                                   url.username,
-                                   url.password,
-                                   url.path.strip("/"),
-                                   engine_opts,
-                                   session_opts)
-        raise ValueError("malformed parameter 'url'")
+        return ConnectionMaker(sqlalchemy.make_url(url), engine_opts=engine_opts, session_opts=session_opts)
 
     @property
     def connection_string(self) -> str:
         """
-        Constructs the SQLAlchemy connection string for the database using the provided parameters.
+        Constructs a SQLAlchemy connection string for the database using the provided parameters.
 
-        :return: The connection string as a string.
+        :return: A string representing the database connection.
         """
-        port_part = "" if self.port is None else (":%d" % self.port)
-        user_part = urllib.parse.quote(self.user, safe="")
-        password_part = "" if is_blank(self.password) else (":%s" % urllib.parse.quote(self.password, safe=""))
-        database_part = urllib.parse.quote(self.database, safe="")
-
-        return f"{self.driver}://{user_part}{password_part}@{self.host}{port_part}/{database_part}"
+        return self.url.render_as_string(hide_password=False)
 
     @property
     def engine(self) -> sqlalchemy.Engine:
@@ -114,7 +100,7 @@ class ConnectionMaker(object):
         """
         return sqlalchemy.create_engine(self.connection_string, **self.engine_opts)
 
-    def make_connection(self):
+    def make_connection(self) -> sqlalchemy.Connection:
         """
         Establishes and returns a new database connection using the SQLAlchemy engine.
 
@@ -165,11 +151,11 @@ class ConnectionMaker(object):
         :param params: The parameters dictionary for the SQL statement.
         :return: None.
         """
-        with self.make_connection() as connection:
-            connection.execute(sqlalchemy.text(sql), params)
-            connection.commit()
+        with self.make_session() as session:
+            session.execute(sqlalchemy.text(sql), params)
+            session.commit()
 
-    def query_all(self, sql: str, **params) -> list[tuple]:
+    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.
 
@@ -177,23 +163,22 @@ class ConnectionMaker(object):
         :param params: The parameters dictionary for the SQL query.
         :return: A list of result tuples.
         """
-        with self.make_connection() as connection:
-            with contextlib.closing(connection.execute(sqlalchemy.text(sql), params)) as proxy:
-                return [item for item in proxy.fetchall()]
+        with self.make_session() as session:
+            result = session.execute(sqlalchemy.text(sql), params)
+            return result.all()
 
-    def query_first(self, sql: str, **params) -> tuple | None:
+    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.
+        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.
         """
-        return head_or_none(self.query_all(sql, **params))
-
-
-DBAdapter = ConnectionMaker
+        with self.make_session() as session:
+            result = session.execute(sqlalchemy.text(sql), params)
+            return result.first()
 
 
 def orm_to_dict(orm, exclude: set[str] = None) -> dict[str, Any]:
@@ -241,40 +226,49 @@ def orm_clone(orm, exclude: set[str] = None, no_autoincrement: bool = False):
     return new_orm
 
 
-def mysql_insert_ignore(enabled: bool = True):
+@contextlib.contextmanager
+def mysql_insert_ignore():
     """
-    Registers a SQLAlchemy compiler extension to add ``IGNORE`` to MySQL ``INSERT`` statements if ``enabled``.
-
-    :param enabled: Whether to enable the ``IGNORE`` prefix for MySQL ``INSERT`` statements.
-    :return: None.
+    Registers a SQLAlchemy compiler extension to add ``IGNORE`` to MySQL ``INSERT`` statements.
     """
 
-    @sqlalchemy.ext.compiler.compiles(sqlalchemy.sql.Insert, "mysql")
-    def dispatch(insert: sqlalchemy.sql.Insert, compiler: sqlalchemy.sql.compiler.SQLCompiler, **kwargs) -> str:
-        if not enabled:
-            return compiler.visit_insert(insert, **kwargs)
+    def context(enabled: bool):
+        @sqlalchemy.ext.compiler.compiles(sqlalchemy.sql.Insert, Dialects.mysql)
+        def dispatch(insert: sqlalchemy.sql.Insert, compiler: sqlalchemy.sql.compiler.SQLCompiler, **kwargs) -> str:
+            if not enabled:
+                return compiler.visit_insert(insert, **kwargs)
 
-        return compiler.visit_insert(insert.prefix_with("IGNORE"), **kwargs)
+            return compiler.visit_insert(insert.prefix_with("IGNORE"), **kwargs)
 
+    context(True)
+    try:
+        yield
+    finally:
+        context(False)
 
-def postgresql_insert_on_conflict_do_nothing(enabled: bool = True):
-    """
-    Registers a SQLAlchemy compiler extension to add ``ON CONFLICT DO NOTHING`` to PostgreSQL ``INSERT`` statements if
-    ``enabled``.
 
-    :param enabled: Whether to enable the ``ON CONFLICT DO NOTHING`` clause for PostgreSQL ``INSERT`` statements.
-    :return: None.
+@contextlib.contextmanager
+def postgresql_insert_on_conflict_do_nothing():
+    """
+    Registers a SQLAlchemy compiler extension to add ``ON CONFLICT DO NOTHING`` to Postgresql ``INSERT`` statements.
     """
 
-    @sqlalchemy.ext.compiler.compiles(sqlalchemy.sql.Insert, "postgresql")
-    def dispatch(insert: sqlalchemy.sql.Insert, compiler: sqlalchemy.sql.compiler.SQLCompiler, **kwargs) -> str:
-        if not enabled:
-            return compiler.visit_insert(insert, **kwargs)
-
-        statement = compiler.visit_insert(insert, **kwargs)
-        # If we have a ``RETURNING`` clause, we must insert before it
-        returning_position = statement.find("RETURNING")
-        if returning_position >= 0:
-            return statement[:returning_position] + " ON CONFLICT DO NOTHING " + statement[returning_position:]
-        else:
-            return statement + " ON CONFLICT DO NOTHING"
+    def context(enabled: bool):
+        @sqlalchemy.ext.compiler.compiles(sqlalchemy.sql.Insert, Dialects.postgresql)
+        def dispatch(insert: sqlalchemy.sql.Insert, compiler: sqlalchemy.sql.compiler.SQLCompiler, **kwargs) -> str:
+            if not enabled:
+                return compiler.visit_insert(insert, **kwargs)
+
+            statement = compiler.visit_insert(insert, **kwargs)
+            # If we have a ``RETURNING`` clause, we must insert before it
+            returning_position = statement.find("RETURNING")
+            if returning_position >= 0:
+                return statement[:returning_position] + " ON CONFLICT DO NOTHING " + statement[returning_position:]
+            else:
+                return statement + " ON CONFLICT DO NOTHING"
+
+    context(True)
+    try:
+        yield
+    finally:
+        context(False)

{iker_python_common-1.0.48 → iker_python_common-1.0.50}/src/iker/common/utils/dtutils.py

@@ -24,6 +24,8 @@ __all__ = [
     "dt_utc",
     "td_to_us",
     "td_from_us",
+    "td_to_time",
+    "td_from_time",
     "dt_to_ts",
     "dt_to_ts_us",
     "dt_from_ts",
@@ -46,16 +48,16 @@ def basic_date_format() -> str:
 
 
 @memorized
-def basic_time_format(with_ms: bool = False, with_tz: bool = False) -> str:
+def basic_time_format(with_us: bool = False, with_tz: bool = False) -> str:
     """
-    Returns the basic time format string, with optional milliseconds and timezone.
+    Returns the basic time format string, with optional microseconds and timezone.
 
-    :param with_ms: If ``True``, include milliseconds in the format.
+    :param with_us: If ``True``, include microseconds in the format.
     :param with_tz: If ``True``, include timezone in the format.
     :return: The basic time format string.
     """
     fmt_str = "T%H%M%S"
-    if with_ms:
+    if with_us:
         fmt_str = fmt_str + ".%f"
     if with_tz:
         fmt_str = fmt_str + "%z"
@@ -63,15 +65,15 @@ def basic_time_format(with_ms: bool = False, with_tz: bool = False) -> str:
 
 
 @memorized
-def basic_format(with_ms: bool = False, with_tz: bool = False) -> str:
+def basic_format(with_us: bool = False, with_tz: bool = False) -> str:
     """
-    Returns the basic combined date and time format string, with optional milliseconds and timezone.
+    Returns the basic combined date and time format string, with optional microseconds and timezone.
 
-    :param with_ms: If ``True``, include milliseconds in the time format.
+    :param with_us: If ``True``, include microseconds in the time format.
     :param with_tz: If ``True``, include timezone in the time format.
     :return: The basic combined date and time format string.
     """
-    return basic_date_format() + basic_time_format(with_ms, with_tz)
+    return basic_date_format() + basic_time_format(with_us, with_tz)
 
 
 @singleton
@@ -85,16 +87,16 @@ def extended_date_format() -> str:
 
 
 @memorized
-def extended_time_format(with_ms: bool = False, with_tz: bool = False) -> str:
+def extended_time_format(with_us: bool = False, with_tz: bool = False) -> str:
     """
-    Returns the extended time format string, with optional milliseconds and timezone.
+    Returns the extended time format string, with optional microseconds and timezone.
 
-    :param with_ms: If ``True``, include milliseconds in the format.
+    :param with_us: If ``True``, include microseconds in the format.
     :param with_tz: If ``True``, include timezone in the format.
     :return: The extended time format string.
     """
     fmt_str = "T%H:%M:%S"
-    if with_ms:
+    if with_us:
         fmt_str = fmt_str + ".%f"
     if with_tz:
         fmt_str = fmt_str + "%:z"
@@ -102,15 +104,15 @@ def extended_time_format(with_ms: bool = False, with_tz: bool = False) -> str:
 
 
 @memorized
-def extended_format(with_ms: bool = False, with_tz: bool = False) -> str:
+def extended_format(with_us: bool = False, with_tz: bool = False) -> str:
     """
-    Returns the extended combined date and time format string, with optional milliseconds and timezone.
+    Returns the extended combined date and time format string, with optional microseconds and timezone.
 
-    :param with_ms: If ``True``, include milliseconds in the time format.
+    :param with_us: If ``True``, include microseconds in the time format.
     :param with_tz: If ``True``, include timezone in the time format.
     :return: The extended combined date and time format string.
     """
-    return extended_date_format() + extended_time_format(with_ms, with_tz)
+    return extended_date_format() + extended_time_format(with_us, with_tz)
 
 
 iso_date_format = extended_date_format
@@ -122,7 +124,7 @@ iso_format = extended_format
 def iso_formats() -> list[str]:
     """
     Returns a list of supported ISO 8601 date and time format strings, including both basic and extended forms, with
-    optional milliseconds and timezone.
+    optional microseconds and timezone.
 
     :return: A list of ISO 8601 format strings.
     """
@@ -229,6 +231,26 @@ def td_from_us(us: int) -> datetime.timedelta:
     return datetime.timedelta(microseconds=us)
 
 
+def td_to_time(td: datetime.timedelta) -> datetime.time:
+    """
+    Returns a ``time`` object representing the given ``timedelta``.
+
+    :param td: The ``timedelta`` to convert.
+    :return: The corresponding ``time`` object.
+    """
+    return (dt_utc_min() + td).timetz()
+
+
+def td_from_time(t: datetime.time) -> datetime.timedelta:
+    """
+    Returns a ``timedelta`` representing the given ``time``.
+
+    :param t: The ``time`` to convert.
+    :return: The corresponding ``timedelta``.
+    """
+    return datetime.timedelta(hours=t.hour, minutes=t.minute, seconds=t.second, microseconds=t.microsecond)
+
+
 def dt_to_td(dt: datetime.datetime) -> datetime.timedelta:
     """
     Returns the ``timedelta`` between the given ``datetime`` and the POSIX epoch.

{iker_python_common-1.0.48 → iker_python_common-1.0.50}/src/iker/common/utils/testutils.py

@@ -69,7 +69,7 @@ class ApproxNestedMapping(ApproxNestedMixin, ApproxMapping):
                 yield from mapping._yield_comparisons(actual[k])
 
 
-def nested_approx(expected, rel: float = None, abs: float = None, nan_ok: bool = False):
+def nested_approx(expected, rel: float = None, abs: float = None, nan_ok: bool = False) -> ApproxBase:
     if isinstance(expected, dict):
         return ApproxNestedMapping(expected, rel, abs, nan_ok)
     if isinstance(expected, (tuple, list)):

{iker_python_common-1.0.48 → iker_python_common-1.0.50}/src/iker_python_common.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iker-python-common
-Version: 1.0.48
+Version: 1.0.50
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12