core-db 3.2.0__tar.gz → 3.2.1__tar.gz

{core_db-3.2.0 → core_db-3.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-db
-Version: 3.2.0
+Version: 3.2.1
 Summary: This project/library contains common elements and clients related to database engines...
 Author-email: Alejandro Cora González <alek.cora.glez@gmail.com>
 Maintainer: Alejandro Cora González
@@ -23,6 +23,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Description-Content-Type: text/x-rst
 License-File: LICENSE
@@ -38,8 +39,8 @@ Requires-Dist: pymongo>=4.6.0; extra == "all"
 Requires-Dist: ibm-db>=3.2.3; extra == "all"
 Requires-Dist: snowflake-connector-python>=3.13.1; extra == "all"
 Provides-Extra: dev
-Requires-Dist: core-dev-tools>=2.0.0; extra == "dev"
-Requires-Dist: core-tests>=2.1.0; extra == "dev"
+Requires-Dist: core-dev-tools>=2.1.0; extra == "dev"
+Requires-Dist: core-tests>=2.3.0; extra == "dev"
 Requires-Dist: types-ibm-db>=3.2.3.20241212; extra == "dev"
 Provides-Extra: mysql
 Requires-Dist: PyMySQL>=1.1.1; extra == "mysql"
@@ -66,12 +67,16 @@ provides clients to simplify the connections...
 
 ===============================================================================
 
+.. image:: https://static.pepy.tech/personalized-badge/core-db?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads
+    :target: https://pepy.tech/projects/core-db
+    :alt: PyPI Downloads
+
 .. image:: https://img.shields.io/pypi/pyversions/core-db.svg
     :target: https://pypi.org/project/core-db/
     :alt: Python Versions
 
 .. image:: https://img.shields.io/badge/license-MIT-blue.svg
-    :target: https://gitlab.com/bytecode-solutions/core/core-db/-/blob/main/LICENSE
+    :target: https://gitlab.com/bytecode-solutions/core/core-db/-/blob/master/LICENSE
     :alt: License
 
 .. image:: https://gitlab.com/bytecode-solutions/core/core-db/badges/release/pipeline.svg

{core_db-3.2.0 → core_db-3.2.1}/README.rst

@@ -6,12 +6,16 @@ provides clients to simplify the connections...
 
 ===============================================================================
 
+.. image:: https://static.pepy.tech/personalized-badge/core-db?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads
+    :target: https://pepy.tech/projects/core-db
+    :alt: PyPI Downloads
+
 .. image:: https://img.shields.io/pypi/pyversions/core-db.svg
     :target: https://pypi.org/project/core-db/
     :alt: Python Versions
 
 .. image:: https://img.shields.io/badge/license-MIT-blue.svg
-    :target: https://gitlab.com/bytecode-solutions/core/core-db/-/blob/main/LICENSE
+    :target: https://gitlab.com/bytecode-solutions/core/core-db/-/blob/master/LICENSE
     :alt: License
 
 .. image:: https://gitlab.com/bytecode-solutions/core/core-db/badges/release/pipeline.svg

{core_db-3.2.0 → core_db-3.2.1}/core_db/__init__.py

@@ -1,12 +1,8 @@
-# -*- coding: utf-8 -*-
-
 """
 Provides common elements and clients related to database engines.
 """
 
-from importlib.metadata import PackageNotFoundError
-from importlib.metadata import version
-
+from importlib.metadata import PackageNotFoundError, version
 
 try:
     __version__ = version("core-db")

{core_db-3.2.0 → core_db-3.2.1}/core_db/engines/__init__.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """
 Database Engine Clients Module
 ================================

{core_db-3.2.0 → core_db-3.2.1}/core_db/engines/db2.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """
 IBM DB2 Database Client Module
 ================================
@@ -8,13 +6,10 @@ This module provides the Db2Client class for connecting to and interacting
 with IBM DB2 databases using the ibm_db library.
 """
 
-import json
+from __future__ import annotations
+
+from collections.abc import Iterator
 from typing import Any
-from typing import Dict
-from typing import Iterator
-from typing import List
-from typing import Optional
-from typing import Tuple
 
 import ibm_db
 
@@ -73,12 +68,16 @@ class Db2Client(ISqlDatabaseClient):
         Returns a wrapper object that mimics cursor behavior.
         """
 
-        class StatementWrapper:
+        class StatementWrapper:  # pylint: disable=too-few-public-methods
+            """Adapts an ibm_db statement handle to expose a cursor-like `rowcount`."""
+
             def __init__(self, statement):
                 self._statement = statement
 
             @property
             def rowcount(self):
+                """Number of rows affected by the last statement, or 0 if none was run."""
+
                 if self._statement:
                     return ibm_db.num_rows(self._statement)
                 return 0
@@ -114,7 +113,7 @@ class Db2Client(ISqlDatabaseClient):
         except Exception as error:
             raise DatabaseClientException(error) from error
 
-    def test_connection(self, query: Optional[str] = None) -> Any:
+    def test_connection(self, query: str | None = None) -> Any:
         """
         Test the database connection by executing a simple query.
 
@@ -145,8 +144,14 @@ class Db2Client(ISqlDatabaseClient):
         if params:
             # Use prepared statement with parameter binding
             self.statement = ibm_db.prepare(self.cxn, query)
+            if isinstance(self.statement, bool):
+                error = ibm_db.conn_error(self.cxn)
+                raise DatabaseClientException(f"Failed to prepare query: {error}")
+
             if not ibm_db.execute(self.statement, params):
-                raise DatabaseClientException(f"Failed to execute query: {ibm_db.stmt_error()}")
+                raise DatabaseClientException(
+                    f"Failed to execute query: {ibm_db.stmt_error()}"
+                )
 
         else:
             # Use immediate execution for non-parameterized queries
@@ -163,23 +168,23 @@ class Db2Client(ISqlDatabaseClient):
 
         ibm_db.commit(self.cxn)
 
-    def fetch_record(self) -> Dict[str, Any]:
+    def fetch_record(self) -> dict[str, Any]:
         """
         Fetch the next row as a dictionary with column names as keys.
         :return: Dictionary representing a single row, or empty dict if no more rows.
         """
 
         result = ibm_db.fetch_assoc(self.statement)
-        return result if result else {}  # type: ignore[return-value]
+        return result if isinstance(result, dict) else {}
 
-    def fetch_one(self) -> Tuple:
+    def fetch_one(self) -> tuple:
         """
         Fetch the next row as a tuple.
         :return: Tuple representing a single row.
         """
         return ibm_db.fetch_tuple(self.statement)
 
-    def fetch_records(self) -> Iterator[Dict[str, Any]]:
+    def fetch_records(self) -> Iterator[dict[str, Any]]:
         """
         Fetch all remaining rows as an iterator of dictionaries.
         :return: Iterator yielding dictionaries with column names as keys.
@@ -189,7 +194,7 @@ class Db2Client(ISqlDatabaseClient):
             if isinstance(row_, dict):  # Type guard to ensure row_ is dict, not bool
                 yield row_
 
-    def fetch_all(self) -> Iterator[Tuple]:
+    def fetch_all(self) -> Iterator[tuple]:
         """
         Fetch all remaining rows as an iterator of tuples.
         :return: Iterator yielding tuples representing rows.
@@ -199,13 +204,13 @@ class Db2Client(ISqlDatabaseClient):
             yield row_
 
     @classmethod
-    def get_merge_dml(
+    def get_merge_dml(  # pylint: disable=arguments-differ,too-many-locals,duplicate-code
         cls,
         table_fqn: str,
-        pk_ids: List[str],
-        columns: List[str],
-        records: List[Dict],
-    ) -> Tuple[str, Tuple]:
+        pk_ids: list[str],
+        columns: list[str],
+        records: list[dict],
+    ) -> tuple[str, tuple]:
         """
         Generate parameterized MERGE statement for IBM DB2. Uses parameter
         binding to prevent SQL injection attacks.
@@ -220,7 +225,7 @@ class Db2Client(ISqlDatabaseClient):
         """
 
         if not records:
-            return "", tuple()
+            return "", ()
 
         cls.validate_identifier(columns + pk_ids)
 
@@ -231,16 +236,9 @@ class Db2Client(ISqlDatabaseClient):
         # Create source columns list
         source_columns = ", ".join(columns)
 
-        # Building the ON clause for matching
-        on_conditions = " AND ".join([f"target.{pk} = source.{pk}" for pk in pk_ids])
-
-        # Building UPDATE SET statement
-        update_columns = [col for col in columns if col not in pk_ids]
-        set_statement = ", ".join([f"target.{col} = source.{col}" for col in update_columns])
-
-        # Building INSERT statement
-        insert_columns = ", ".join(columns)
-        insert_values = ", ".join([f"source.{col}" for col in columns])
+        on_conditions, set_statement, insert_columns, insert_values = (
+            cls._build_merge_clauses(pk_ids, columns)
+        )
 
         # SQL construction is safe: columns are validated, values use placeholders...
         query = f"""
@@ -253,15 +251,7 @@ class Db2Client(ISqlDatabaseClient):
                 INSERT ({insert_columns})
                 VALUES ({insert_values})"""  # nosec B608
 
-        # Extracting parameters in the correct order for each record
-        params: List = []
-        for record in records:
-            params.extend([
-                json.dumps(record[col]) if type(record[col]) in [dict, list] else record[col]
-                for col in columns
-            ])
-
-        return query, tuple(params)
+        return query, cls._flatten_params(records, columns)
 
     def close(self):
         """

{core_db-3.2.0 → core_db-3.2.1}/core_db/engines/mongo.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """
 MongoDB Database Client Module
 ================================
@@ -8,22 +6,17 @@ This module provides the MongoClient class for connecting to and interacting
 with MongoDB databases using the pymongo library.
 """
 
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
 from typing import Any
-from typing import Dict
-from typing import Iterator
-from typing import List
-from typing import Mapping
-from typing import Optional
 
 from pymongo import MongoClient as PyMongoClient
 from pymongo.client_session import ClientSession
 from pymongo.collation import Collation
-from pymongo.results import DeleteResult
-from pymongo.results import InsertManyResult
-from pymongo.results import InsertOneResult
+from pymongo.results import DeleteResult, InsertManyResult, InsertOneResult
 
-from core_db.interfaces.base import DatabaseClientException
-from core_db.interfaces.base import IDatabaseClient
+from core_db.interfaces.base import DatabaseClientException, IDatabaseClient
 
 
 class MongoClient(IDatabaseClient):
@@ -83,8 +76,8 @@ class MongoClient(IDatabaseClient):
 
     def test_connection(
         self,
-        query: Optional[str] = None,
-        session: Optional[ClientSession] = None,
+        query: str | None = None,
+        session: ClientSession | None = None,
     ):
         """
         Test the database connection by retrieving server
@@ -102,14 +95,14 @@ class MongoClient(IDatabaseClient):
             raise DatabaseClientException("No active connection")
         return self.cxn.server_info(session=session)
 
-    def find_one(
+    def find_one(  # pylint: disable=keyword-arg-before-vararg
         self,
         collection_name: str,
-        filters: Optional[Dict] = None,
-        projection: Optional[Dict] = None,
+        filters: dict | None = None,
+        projection: dict | None = None,
         *args,
         **kwargs,
-    ) -> Dict:
+    ) -> dict:
         """
         Get a single document from the database. All arguments to find() are also
         valid arguments for find_one(), although any limit argument will be ignored. Returns
@@ -137,13 +130,15 @@ class MongoClient(IDatabaseClient):
         if not projection:
             projection = {}
 
-        return getattr(self.db, collection_name).find_one(filters, projection, *args, **kwargs)
+        return getattr(self.db, collection_name).find_one(
+            filters, projection, *args, **kwargs
+        )
 
-    def find(
+    def find(  # pylint: disable=keyword-arg-before-vararg
         self,
         collection_name: str,
-        filters: Optional[Dict] = None,
-        projection: Optional[Dict] = None,
+        filters: dict | None = None,
+        projection: dict | None = None,
         *args,
         **kwargs,
     ) -> Iterator:
@@ -174,17 +169,18 @@ class MongoClient(IDatabaseClient):
         if not projection:
             projection = {}
 
-        cursor = getattr(self.db, collection_name).find(filters, projection, *args, **kwargs)
-        for record in cursor:
-            yield record
+        cursor = getattr(self.db, collection_name).find(
+            filters, projection, *args, **kwargs
+        )
+        yield from cursor
 
     def insert_one(
         self,
         collection_name: str,
-        document: Dict,
+        document: dict,
         bypass_document_validation: bool = False,
-        session: Optional[ClientSession] = None,
-        comment: Optional[str] = None,
+        session: ClientSession | None = None,
+        comment: str | None = None,
     ) -> InsertOneResult:
         """
         This is a method by which we can insert a single entry within
@@ -222,10 +218,10 @@ class MongoClient(IDatabaseClient):
     def insert_many(
         self,
         collection_name: str,
-        documents: List[Dict],
+        documents: list[dict],
         ordered: bool = True,
         bypass_document_validation: bool = False,
-        session: Optional[ClientSession] = None,
+        session: ClientSession | None = None,
     ) -> InsertManyResult:
         """
         This method is used to insert multiple entries in a collection or the
@@ -264,15 +260,15 @@ class MongoClient(IDatabaseClient):
             session=session,
         )
 
-    def delete_one(
+    def delete_one(  # pylint: disable=too-many-arguments,too-many-positional-arguments
         self,
         collection_name: str,
-        filter_query: Dict,
-        collation: Optional[Collation] = None,
+        filter_query: dict,
+        collation: Collation | None = None,
         hint=None,
-        session: Optional[ClientSession] = None,
-        let: Optional[Mapping[str, Any]] = None,
-        comment: Optional[Any] = None,
+        session: ClientSession | None = None,
+        let: Mapping[str, Any] | None = None,
+        comment: Any | None = None,
     ) -> DeleteResult:
         """
         To remove one document from the collection...
@@ -310,15 +306,15 @@ class MongoClient(IDatabaseClient):
             comment=comment,
         )
 
-    def delete_many(
+    def delete_many(  # pylint: disable=too-many-arguments,too-many-positional-arguments
         self,
         collection_name: str,
-        filter_query: Dict,
-        collation: Optional[Collation] = None,
+        filter_query: dict,
+        collation: Collation | None = None,
         hint=None,
-        session: Optional[ClientSession] = None,
-        let: Optional[Mapping[str, Any]] = None,
-        comment: Optional[Any] = None,
+        session: ClientSession | None = None,
+        let: Mapping[str, Any] | None = None,
+        comment: Any | None = None,
     ) -> DeleteResult:
         """
         It is used when one needs to delete more than one document. A query

{core_db-3.2.0 → core_db-3.2.1}/core_db/engines/mssql.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """
 Microsoft SQL Server Database Client Module
 ============================================
@@ -8,13 +6,13 @@ This module provides the MsSqlClient class for connecting to and interacting
 with Microsoft SQL Server databases using the pyodbc library.
 """
 
-import json
-from typing import Dict
-from typing import List
-from typing import Optional
-from typing import Tuple
+from __future__ import annotations
 
-import pyodbc  # type: ignore
+# pyodbc is a C extension that dynamically links against the system unixODBC
+# library (libodbc.so.2). The CI linters job runs on a bare python:latest
+# image that doesn't have it installed, so pylint's astroid can't import the
+# module to introspect it and reports a false import-error there.
+import pyodbc  # type: ignore[import-not-found]  # pylint: disable=import-error
 
 from core_db.interfaces.base import DatabaseClientException
 from core_db.interfaces.sql_based import ISqlDatabaseClient
@@ -32,10 +30,12 @@ class MsSqlClient(ISqlDatabaseClient):
 
         from core_db.engines.mssql import MsSqlClient
 
-        with MsSqlClient(
-                dsn="DRIVER={ODBC Driver 18 for SQL Server};SERVER=localhost;DATABASE=master;UID=SA;PWD=sOm3str0ngP@33w0rd;Encrypt=no",
-                autocommit=True, timeout=5) as client:
+        dsn = (
+            "DRIVER={ODBC Driver 18 for SQL Server};SERVER=localhost;"
+            "DATABASE=master;UID=SA;PWD=sOm3str0ngP@33w0rd;Encrypt=no"
+        )
 
+        with MsSqlClient(dsn=dsn, autocommit=True, timeout=5) as client:
             client.execute("SELECT @@VERSION AS 'version';")
             print(list(client.fetch_records()))
     ..
@@ -43,6 +43,7 @@ class MsSqlClient(ISqlDatabaseClient):
 
     PLACEHOLDER = "?"
 
+    # pylint: disable=line-too-long
     def __init__(self, **kwargs) -> None:
         """
         Expected -> dsn, autocommit, timeout
@@ -51,6 +52,7 @@ class MsSqlClient(ISqlDatabaseClient):
           - https://learn.microsoft.com/en-us/sql/connect/python/python-driver-for-sql-server?view=sql-server-ver16
           - https://learn.microsoft.com/en-us/sql/relational-databases/native-client/applications/using-connection-string-keywords-with-sql-server-native-client?view=sql-server-ver15&viewFallbackFrom=sql-server-ver16
         """
+        # pylint: enable=line-too-long
 
         super().__init__(**kwargs)
         self.connect_fcn = pyodbc.connect
@@ -68,13 +70,13 @@ class MsSqlClient(ISqlDatabaseClient):
 
         try:
             self.cxn = self.connect_fcn(
-                self.cxn_parameters.pop("dsn", ""),
-                **self.cxn_parameters)
+                self.cxn_parameters.pop("dsn", ""), **self.cxn_parameters
+            )
 
         except Exception as error:
             raise DatabaseClientException(error) from error
 
-    def test_connection(self, query: Optional[str] = None):
+    def test_connection(self, query: str | None = None):
         """
         Test the database connection by executing a simple query.
 
@@ -96,19 +98,22 @@ class MsSqlClient(ISqlDatabaseClient):
         :return: Cursor object after execution.
         """
 
+        if not self.cursor:
+            raise DatabaseClientException("No active cursor!")
+
         params = kwargs.get("params", None)
         if params:
             return self.cursor.execute(query, params)
         return self.cursor.execute(query)
 
     @classmethod
-    def get_merge_dml(
+    def get_merge_dml(  # pylint: disable=arguments-differ,too-many-locals,duplicate-code
         cls,
         table_fqn: str,
-        pk_ids: List[str],
-        columns: List[str],
-        records: List[Dict],
-    ) -> Tuple[str, Tuple]:
+        pk_ids: list[str],
+        columns: list[str],
+        records: list[dict],
+    ) -> tuple[str, tuple]:
         """
         Generate parameterized MERGE statement for Microsoft SQL Server. Uses
         parameter binding to prevent SQL injection attacks.
@@ -123,7 +128,7 @@ class MsSqlClient(ISqlDatabaseClient):
         """
 
         if not records:
-            return "", tuple()
+            return "", ()
 
         cls.validate_identifier(columns + pk_ids)
 
@@ -134,22 +139,17 @@ class MsSqlClient(ISqlDatabaseClient):
             # Remaining rows
             union_rows = []
             for _ in range(1, len(records)):
-                union_rows.append(f"SELECT {', '.join([cls.PLACEHOLDER for _ in columns])}")
+                union_rows.append(
+                    f"SELECT {', '.join([cls.PLACEHOLDER for _ in columns])}"
+                )
             using_clause = f"({first_row} UNION ALL {' UNION ALL '.join(union_rows)})"
         else:
             # Single record
             using_clause = f"(SELECT {', '.join([f'{cls.PLACEHOLDER} AS {col}' for col in columns])})"
 
-        # Building the ON clause for matching
-        on_conditions = " AND ".join([f"target.{pk} = source.{pk}" for pk in pk_ids])
-
-        # Building UPDATE SET statement
-        update_columns = [col for col in columns if col not in pk_ids]
-        set_statement = ", ".join([f"target.{col} = source.{col}" for col in update_columns])
-
-        # Building INSERT statement
-        insert_columns = ", ".join(columns)
-        insert_values = ", ".join([f"source.{col}" for col in columns])
+        on_conditions, set_statement, insert_columns, insert_values = (
+            cls._build_merge_clauses(pk_ids, columns)
+        )
 
         # SQL construction is safe: columns are validated, values use placeholders...
         query = f"""
@@ -162,12 +162,4 @@ class MsSqlClient(ISqlDatabaseClient):
                 INSERT ({insert_columns})
                 VALUES ({insert_values});"""  # nosec B608
 
-        # Extracting parameters in the correct order for each record
-        params: List = []
-        for record in records:
-            params.extend([
-                json.dumps(record[col]) if type(record[col]) in [dict, list] else record[col]
-                for col in columns
-            ])
-
-        return query, tuple(params)
+        return query, cls._flatten_params(records, columns)

{core_db-3.2.0 → core_db-3.2.1}/core_db/engines/mysql.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """
 MySQL Database Client Module
 ==============================
@@ -8,14 +6,11 @@ This module provides the MySQLClient class for connecting to and interacting
 with MySQL databases using the pymysql library.
 """
 
-import json
+from __future__ import annotations
+
 from typing import Any
-from typing import Dict
-from typing import List
-from typing import Optional
-from typing import Tuple
 
-import pymysql  # type: ignore
+import pymysql  # type: ignore[import-untyped]
 
 from core_db.interfaces import DatabaseClientException
 from core_db.interfaces.sql_based import ISqlDatabaseClient
@@ -177,13 +172,13 @@ class MySQLClient(ISqlDatabaseClient):
         return self.cursor.execute(query, **args)
 
     @classmethod
-    def get_merge_dml(
+    def get_merge_dml(  # pylint: disable=arguments-differ
         cls,
         table_fqn: str,
-        columns: List[str],
-        records: List[Dict],
-        epoch_column: Optional[str] = None,
-    ) -> Tuple[str, Tuple]:
+        columns: list[str],
+        records: list[dict],
+        epoch_column: str | None = None,
+    ) -> tuple[str, tuple]:
         """
         Generate parameterized MERGE/UPSERT statement for MySQL using
         INSERT ... ON DUPLICATE KEY UPDATE. Uses parameter binding to
@@ -198,7 +193,7 @@ class MySQLClient(ISqlDatabaseClient):
         """
 
         if not records:
-            return "", tuple()
+            return "", ()
 
         cls.validate_identifier(columns)
 
@@ -213,7 +208,8 @@ class MySQLClient(ISqlDatabaseClient):
         if epoch_column:
             # Only update if the new epoch value is greater
             on_duplicate = [
-                f"`{col}` = IF(VALUES(`{epoch_column}`) > `{epoch_column}`, VALUES(`{col}`), `{col}`)"
+                f"`{col}` = IF(VALUES(`{epoch_column}`) > `{epoch_column}`, "
+                f"VALUES(`{col}`), `{col}`)"
                 for col in columns
             ]
 
@@ -223,17 +219,9 @@ class MySQLClient(ISqlDatabaseClient):
         # SQL construction is safe: columns are validated, values use placeholders...
         query = f"""
             INSERT INTO {table_fqn}
-            ({', '.join([f'`{col}`' for col in columns])})
+            ({", ".join([f"`{col}`" for col in columns])})
             VALUES {values_rows}
             ON DUPLICATE KEY UPDATE
-            {', '.join(on_duplicate)}"""  # nosec B608
-
-        # Extract and flatten parameters in the correct order
-        params = []
-        for record in records:
-            params.extend([
-                json.dumps(record[col]) if type(record[col]) in [dict, list] else record[col]
-                for col in columns
-            ])
+            {", ".join(on_duplicate)}"""  # nosec B608
 
-        return query, tuple(params)
+        return query, cls._flatten_params(records, columns)