mysqlclient-client 1.0.0__py3-none-any.whl

mysqlclient_client/client.py

@@ -0,0 +1,594 @@
+"""database client"""
+
+import atexit
+import csv
+import io
+import queue
+import threading
+import time
+from collections.abc import AsyncGenerator, Generator
+from datetime import UTC, datetime
+
+import MySQLdb
+import MySQLdb.cursors
+
+from .query_by_key.query import Query
+from .query_by_key.query_util import (
+    get_query_with_value,
+)
+from .query_by_key.settings import Settings as QrySettings
+from .settings import Settings
+
+connection = MySQLdb.Connection
+
+
+class ClientPool:
+    """database connection pool"""
+
+    def __init__(self, db_settings_pool: Settings):
+        self.db_settings_pool = db_settings_pool
+        self._lock = threading.Lock()
+        self._pool: queue.Queue[MySQLdb.Connection] = queue.Queue(
+            maxsize=db_settings_pool.maxconn
+        )
+        self._all_conns: list[MySQLdb.Connection] = []
+        self._closed = False
+
+        for _ in range(db_settings_pool.minconn):
+            conn = self._create_connection()
+            self._pool.put(conn)
+            self._all_conns.append(conn)
+
+        print(datetime.now(UTC), self.__class__.__name__, self.__init__.__name__)
+
+    def _create_connection(self) -> MySQLdb.Connection:
+        conn = MySQLdb.connect(
+            host=self.db_settings_pool.host,
+            port=self.db_settings_pool.port,
+            user=self.db_settings_pool.user,
+            passwd=self.db_settings_pool.password,
+            db=self.db_settings_pool.database,
+            connect_timeout=self.db_settings_pool.connect_timeout,
+            charset="utf8mb4",
+            autocommit=False,
+            cursorclass=MySQLdb.cursors.DictCursor,
+        )
+        return conn
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        """Close the shared connection pool."""
+        self.closeall()
+        print(datetime.now(UTC), self.__class__.__name__, self.__exit__.__name__)
+
+    def getconn(self) -> MySQLdb.Connection:
+        """return conn_pool"""
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("Connection pool is closed")
+            try:
+                conn = self._pool.get_nowait()
+                try:
+                    conn.ping(True)
+                except Exception:
+                    conn = self._create_connection()
+                return conn
+            except queue.Empty:
+                if len(self._all_conns) < self.db_settings_pool.maxconn:
+                    conn = self._create_connection()
+                    self._all_conns.append(conn)
+                    return conn
+        try:
+            conn = self._pool.get(timeout=self.db_settings_pool.connect_timeout)
+            try:
+                conn.ping(True)
+            except Exception:
+                conn = self._create_connection()
+            return conn
+        except queue.Empty:
+            raise TimeoutError("Timeout waiting for connection from pool") from None
+
+    def putconn(self, conn: MySQLdb.Connection):
+        """putconn"""
+        with self._lock:
+            if self._closed:
+                try:
+                    conn.close()
+                except Exception:
+                    pass
+                return
+            try:
+                self._pool.put_nowait(conn)
+            except queue.Full:
+                try:
+                    conn.close()
+                except Exception:
+                    pass
+                if conn in self._all_conns:
+                    self._all_conns.remove(conn)
+
+    def closeall(self):
+        """close all connections in pool"""
+        with self._lock:
+            self._closed = True
+            for conn in self._all_conns:
+                try:
+                    conn.close()
+                except Exception:
+                    pass
+            self._all_conns.clear()
+            while not self._pool.empty():
+                try:
+                    self._pool.get_nowait()
+                except queue.Empty:
+                    break
+
+
+db_set_and_pool: dict[str, ClientPool] = {}
+
+
+def cleanup():
+    for pool_inst in db_set_and_pool.values():
+        try:
+            pool_inst.closeall()
+        except Exception:
+            pass
+
+
+atexit.register(cleanup)
+
+
+class Client:
+    """database client"""
+
+    # Class-level shared connection pool
+    _conn_pool: ClientPool
+
+    def __init__(self, db_settings: Settings):
+        self.conn: connection
+        self.in_with_block = False
+        self.db_settings = db_settings
+        self.qry = Query(
+            qry_settings=QrySettings(
+                use_en_ko_column_alias=db_settings.use_en_ko_column_alias,
+                use_conditional=db_settings.use_conditional,
+                all_query=db_settings.all_query,
+            )
+        )
+        self.query_recent = ""
+
+        db_set_key = db_settings.key
+        if db_set_key not in db_set_and_pool:
+            client_pool = ClientPool(db_settings)
+            db_set_and_pool[db_set_key] = client_pool
+            Client._conn_pool = client_pool
+
+    def __enter__(self):
+        # Called when entering the 'with' block
+        self.conn = Client._conn_pool.getconn()
+        self.in_with_block = True
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        # Called when exiting the 'with' block
+        try:
+            if exc_type is None:
+                # No exception, commit the transaction
+                self.conn.commit()
+            else:
+                # Exception occurred, roll back the transaction
+                self.conn.rollback()
+        finally:
+            Client._conn_pool.putconn(self.conn)
+            self.in_with_block = False
+
+    def read_row(
+        self,
+        qry_key: str,
+        params: dict,
+        *,
+        en: bool = False,
+    ) -> dict | None:
+        """Return single row"""
+
+        rows = self.read_rows(qry_key, params, en=en)
+        if not rows:
+            return None
+
+        return rows[0]
+
+    def read_rows(
+        self,
+        qry_key: str,
+        params: dict,
+        *,
+        en: bool = False,
+    ) -> list[dict]:
+        """Return all rows"""
+
+        def read_rows_by_param(
+            qry_key: str,
+            params: dict,
+            *,
+            en: bool = False,
+            cursor: MySQLdb.cursors.DictCursor,
+        ) -> list[dict]:
+            if not isinstance(params, dict):
+                params = vars(params)
+
+            qry_str = self.qry.get_query_by_key(qry_key, params, "read", en)
+            self.query_recent = qry_str
+
+            start = 0
+            if self.db_settings.before_read_execute:
+                self.db_settings.before_read_execute(
+                    qry_key,
+                    params,
+                    qry_str,
+                    get_query_with_value(qry_str, params),
+                )
+                start = time.time()
+
+            cursor.execute(qry_str, params)
+            rows = cursor.fetchall()
+
+            if self.db_settings.after_read_execute:
+                duration = round((time.time() - start) * 1000)
+                self.db_settings.after_read_execute(qry_key, duration)
+
+            if not rows:
+                return []
+
+            return list(rows)
+
+        rows: list[dict] = []
+        if self.in_with_block:
+            cursor = self.conn.cursor(MySQLdb.cursors.DictCursor)
+            rows = read_rows_by_param(qry_key, params, en=en, cursor=cursor)
+            cursor.close()
+        else:
+            conn_pool = Client._conn_pool
+            conn = conn_pool.getconn()
+            try:
+                cursor = conn.cursor(MySQLdb.cursors.DictCursor)
+                rows = read_rows_by_param(qry_key, params, en=en, cursor=cursor)
+                cursor.close()
+            finally:
+                conn_pool.putconn(conn)
+
+        return rows
+
+    async def read_csv_partial_async(
+        self,
+        qry_key: str,
+        params: dict,
+        *,
+        row_count_partial: int = 100,
+        en: bool = False,
+    ) -> AsyncGenerator[bytes]:
+        """Return rows partially in batches with async
+
+        Arguments:
+            qry_key: key of the Dictionary registered in the clients/queries folder
+            params: key, value pairs to pass as parameters to the SQL query.
+            row_count_partial: Number of rows to return at a time
+
+        Returns:
+            CSV format converted to UTF-8-BOM
+        """
+
+        async def read_csv_partial_async_by_param(
+            qry_key: str,
+            params: dict,
+            *,
+            row_count_partial: int = 100,
+            en: bool = False,
+            cursor: MySQLdb.cursors.DictCursor,
+        ) -> AsyncGenerator[bytes]:
+            if not isinstance(params, dict):
+                params = vars(params)
+
+            qry_str = self.qry.get_query_by_key(qry_key, params, "csv", en)
+
+            is_second = False
+
+            # without UTF-8 BOM, hangul will be broken.
+            utf8_bom = b"\xef\xbb\xbf"
+            yield utf8_bom
+
+            start = 0
+            if self.db_settings.before_read_execute:
+                self.db_settings.before_read_execute(
+                    qry_key,
+                    params,
+                    qry_str,
+                    get_query_with_value(qry_str, params),
+                )
+                start = time.time()
+
+            cursor.execute(qry_str, params)
+            while True:
+                rows = (
+                    cursor.fetchmany(row_count_partial)
+                    if hasattr(cursor, "fetchmany")
+                    else cursor.fetchall()
+                )
+
+                if not is_second and self.db_settings.after_read_execute:
+                    duration = round((time.time() - start) * 1000)
+                    self.db_settings.after_read_execute(qry_key, duration)
+
+                if not rows:
+                    break
+
+                csv_out = io.StringIO()
+                csv_w = csv.writer(csv_out)
+                if not is_second and cursor.description:
+                    column_names = [desc[0] for desc in cursor.description]
+                    csv_w.writerow(column_names)
+                csv_w.writerows(
+                    [list(r.values()) if isinstance(r, dict) else r for r in rows]
+                )
+
+                yield csv_out.getvalue().encode("utf-8")
+
+                is_second = True
+
+        if self.in_with_block:
+            cursor = self.conn.cursor(MySQLdb.cursors.DictCursor)
+            try:
+                async for value in read_csv_partial_async_by_param(
+                    qry_key,
+                    params,
+                    row_count_partial=row_count_partial,
+                    en=en,
+                    cursor=cursor,
+                ):
+                    yield value
+            finally:
+                cursor.close()
+        else:
+            conn_pool = Client._conn_pool
+            conn = conn_pool.getconn()
+            try:
+                cursor = conn.cursor(MySQLdb.cursors.DictCursor)
+                try:
+                    async for value in read_csv_partial_async_by_param(
+                        qry_key,
+                        params,
+                        row_count_partial=row_count_partial,
+                        en=en,
+                        cursor=cursor,
+                    ):
+                        yield value
+                finally:
+                    cursor.close()
+            finally:
+                conn_pool.putconn(conn)
+
+    def read_csv_partial(
+        self,
+        qry_key: str,
+        params: dict,
+        *,
+        row_count_partial: int = 100,
+        en: bool = False,
+    ) -> Generator[bytes]:
+        """Return rows partially in batches
+
+        Arguments:
+            qry_key: key of the Dictionary registered in the clients/queries folder
+            params: key, value pairs to pass as parameters to the SQL query.
+            row_count_partial: Number of rows to return at a time
+
+        Returns:
+            CSV format converted to UTF-8-BOM
+        """
+
+        def read_csv_partial_by_param(
+            qry_key: str,
+            params: dict,
+            *,
+            row_count_partial: int = 100,
+            en: bool = False,
+            cursor: MySQLdb.cursors.DictCursor,
+        ) -> Generator[bytes]:
+            if not isinstance(params, dict):
+                params = vars(params)
+
+            qry_str = self.qry.get_query_by_key(qry_key, params, "csv", en)
+
+            is_second = False
+
+            # without UTF-8 BOM, hangul will be broken.
+            utf8_bom = b"\xef\xbb\xbf"
+            yield utf8_bom
+
+            start = 0
+            if self.db_settings.before_read_execute:
+                self.db_settings.before_read_execute(
+                    qry_key,
+                    params,
+                    qry_str,
+                    get_query_with_value(qry_str, params),
+                )
+                start = time.time()
+
+            cursor.execute(qry_str, params)
+            while True:
+                rows = (
+                    cursor.fetchmany(row_count_partial)
+                    if hasattr(cursor, "fetchmany")
+                    else cursor.fetchall()
+                )
+
+                if not is_second and self.db_settings.after_read_execute:
+                    duration = round((time.time() - start) * 1000)
+                    self.db_settings.after_read_execute(qry_key, duration)
+                if not rows:
+                    break
+
+                csv_out = io.StringIO()
+                csv_w = csv.writer(csv_out)
+                if not is_second and cursor.description:
+                    column_names = [desc[0] for desc in cursor.description]
+                    csv_w.writerow(column_names)
+                csv_w.writerows(
+                    [list(r.values()) if isinstance(r, dict) else r for r in rows]
+                )
+
+                yield csv_out.getvalue().encode("utf-8")
+
+                is_second = True
+
+        if self.in_with_block:
+            cursor = self.conn.cursor(MySQLdb.cursors.DictCursor)
+            try:
+                yield from read_csv_partial_by_param(
+                    qry_key,
+                    params,
+                    row_count_partial=row_count_partial,
+                    en=en,
+                    cursor=cursor,
+                )
+            finally:
+                cursor.close()
+        else:
+            conn_pool = Client._conn_pool
+            conn = conn_pool.getconn()
+            try:
+                cursor = conn.cursor(MySQLdb.cursors.DictCursor)
+                try:
+                    yield from read_csv_partial_by_param(
+                        qry_key,
+                        params,
+                        row_count_partial=row_count_partial,
+                        en=en,
+                        cursor=cursor,
+                    )
+                finally:
+                    cursor.close()
+            finally:
+                conn_pool.putconn(conn)
+
+    def update(
+        self,
+        qry_key: str,
+        params: dict,
+        params_out: dict | None = None,
+    ) -> int:
+        """call updates"""
+
+        params_out_used = params_out if params_out is not None else {}
+        row_counts = self.updates([(qry_key, params, params_out_used)])
+        return row_counts[0]
+
+    def updates(
+        self,
+        qry_key_params_list: list[tuple[str, dict, dict]] | list[tuple[str, dict]],
+    ) -> list[int]:
+        """Executes a list of SQL statements within a single transaction.
+        If all SQL commands succeed, returns a list of the number of rows affected
+        by each qry_key.
+        If any command fails, an error is raised.
+
+        Arguments:
+            qry_key_params_list: A list of tuples, each containing following two values:
+                qry_key: key of the dictionary registered in the clients/queries folder
+                params: key, value pairs to pass as parameters to the SQL query.
+
+        Returns:
+            The number of rows affected by the last SQL query.
+        """
+
+        def normalize_qry_key_params_list(
+            qry_key_params_list: list[tuple[str, dict, dict]] | list[tuple[str, dict]],
+        ) -> list[tuple[str, dict, dict]]:
+            qry_key_params_list_new: list[tuple[str, dict, dict]] = []
+            for item in qry_key_params_list:
+                if len(item) == 2:
+                    qry_key, params = item
+                    params_out = {}
+                else:
+                    qry_key, params, params_out = item
+
+                if not isinstance(params, (dict, list, tuple)):
+                    params = vars(params)
+
+                qry_key_params_list_new.append((qry_key, params, params_out))
+
+            return qry_key_params_list_new
+
+        def updates_by_param(
+            qry_key_params_list: list[tuple[str, dict, dict]] | list[tuple[str, dict]],
+            cursor: MySQLdb.cursors.DictCursor,
+        ) -> list[int]:
+            row_counts: list[int] = []
+            qry_strs: list[str] = []
+
+            qry_key_params_list_new = normalize_qry_key_params_list(qry_key_params_list)
+
+            for item in qry_key_params_list_new:
+                qry_key, params, params_out = item
+
+                qry_str = self.qry.get_query_by_key(qry_key, params, "update")
+
+                start = 0
+                if self.db_settings.before_update_execute:
+                    self.db_settings.before_update_execute(
+                        qry_key,
+                        params,
+                        params_out,
+                        qry_str,
+                        get_query_with_value(qry_str, params),
+                    )
+                    start = time.time()
+
+                if isinstance(params, (list, tuple)):
+                    cursor.executemany(qry_str, params)
+                else:
+                    cursor.execute(qry_str, params)
+
+                row_count = cursor.rowcount
+
+                if params_out and cursor.description:
+                    row = cursor.fetchone()
+                    if row:
+                        for k, v in row.items():
+                            if k in params_out:
+                                params_out[k] = v
+
+                if self.db_settings.after_update_execute:
+                    duration = round((time.time() - start) * 1000)
+                    self.db_settings.after_update_execute(
+                        qry_key, row_count, params_out, duration
+                    )
+
+                row_counts.append(row_count)
+                qry_strs.append(qry_str)
+
+            return row_counts
+
+        row_counts: list[int] = []
+        if self.in_with_block:
+            cursor = self.conn.cursor(MySQLdb.cursors.DictCursor)
+            try:
+                row_counts = updates_by_param(qry_key_params_list, cursor)
+            finally:
+                cursor.close()
+        else:
+            conn_pool = Client._conn_pool
+            conn = conn_pool.getconn()
+            try:
+                cursor = conn.cursor(MySQLdb.cursors.DictCursor)
+                try:
+                    row_counts = updates_by_param(qry_key_params_list, cursor)
+                    conn.commit()
+                except Exception:
+                    conn.rollback()
+                    raise
+                finally:
+                    cursor.close()
+            finally:
+                conn_pool.putconn(conn)
+
+        return row_counts

mysqlclient_client/query_by_key/query.py

@@ -0,0 +1,63 @@
+"""client_util"""
+
+import json
+from datetime import date, datetime
+from typing import Literal
+
+from .query_util import get_conditional, replace_en_ko_column_alias
+from .settings import Settings
+
+
+class Query:
+    """query"""
+
+    def __init__(self, qry_settings: Settings):
+        self.qry_settings = qry_settings
+
+    def get_query_by_key(
+        self,
+        qry_key: str,
+        params: dict,
+        func_type: Literal["update", "read", "csv"],
+        en: bool = False,
+    ) -> str:
+        """get query string by qry_key"""
+
+        def serial_date(obj):
+            """JSON serializer for objects not serializable by default json code"""
+
+            if isinstance(obj, (datetime, date)):
+                return obj.isoformat()
+            return str(obj)
+
+        query = self.qry_settings.all_query.get(qry_key)
+        if not query:
+            raise KeyError(f"{qry_key} not exists")
+
+        cond_params = (
+            params[0]
+            if isinstance(params, (list, tuple))
+            and params
+            and isinstance(params[0], dict)
+            else (params if isinstance(params, dict) else {})
+        )
+        info_params = (
+            f"[executemany: {len(params)} rows]"
+            if isinstance(params, (list, tuple)) and len(params) > 1
+            else params
+        )
+
+        info = {
+            "qry_key": qry_key,
+            "params": info_params,
+            "func_type": func_type,
+            "en": en,
+        }
+
+        if self.qry_settings.use_en_ko_column_alias and isinstance(en, bool):
+            query = replace_en_ko_column_alias(query, en)
+        if self.qry_settings.use_conditional and "#if" in query:
+            query = get_conditional(query, cond_params)
+
+        info_str = json.dumps(info, ensure_ascii=False, default=serial_date)
+        return f"/* {info_str.replace('%', '{percent}')} */{query}"

mysqlclient_client/query_by_key/query_util.py

@@ -0,0 +1,144 @@
+"""client_util"""
+
+import re
+from datetime import datetime
+
+
+def get_conditional(qry_str: str, params: dict) -> str:
+    """
+    return true or false part by condition.
+    `#if target == 'korea' ... #elif target == 'vietnam' ... #else ... #endif`
+    """
+
+    def eval_safe(to_eval: str, params: dict) -> bool:
+        """
+        # assert eval_safe('%(target)s != ""', {"target": ""}) is False
+        # assert eval_safe('"A" in %(targets)s', {"targets": ["A", "B"]}) is True
+        # assert eval_safe('"A" not in %(targets)s', {"targets": ["A", "B"]}) is False
+        # assert eval_safe("%(t)s in [i for i in range(10)]", {"t": 1}) is True
+        """
+
+        # remove '%(' and ')s' from %(target)s
+        to_eval = re.sub(r"%\((.*?)\)s", r"\1", to_eval)
+
+        # allow below:
+        # - string inside quotes
+        # - digit
+        to_check = re.sub(r"""(".*?"|'.*?'|\b\d+\b)""", "", to_eval)
+
+        param_set = {key for key in params}
+        op_set = {
+            "==",
+            "!=",
+            ">=",
+            "<=",
+            ">",
+            "<",
+            "in",
+            "not",
+            "and",
+            "or",
+            "[",
+            "]",
+            "(",
+            ")",
+            ",",
+        }
+
+        eval_set = set(to_check.split())
+        diff = eval_set - (param_set | op_set)
+        if diff:
+            raise ValueError(f"'{diff}' not in {param_set | op_set}")
+
+        is_include = bool(eval(to_eval, {}, params.copy()))
+        return is_include
+
+    lines = qry_str.split("\n")
+    rets = []
+    is_include = True
+    is_checked = False
+    for line in lines:
+        line_strip = line.strip()
+        if line_strip.startswith(("#if", "#elif")):
+            if not is_checked:
+                _, condition = line_strip.split(maxsplit=1)
+                is_include = eval_safe(condition, params.copy())
+                if is_include:
+                    is_checked = True
+            else:
+                is_include = False
+        elif line_strip.startswith("#else"):
+            is_include = not is_checked
+        elif line_strip.startswith("#endif"):
+            is_include = True
+            is_checked = False
+        elif is_include:
+            rets.append(line)
+
+    return "\n".join(rets)
+
+
+def rep_kv(query: str, tab_count: int, **kwargs) -> str:
+    """
+    replace {key} with value when `rev_ky("WHERE user_name = {key}", key="u.user_name")`
+    """
+
+    ret = query
+    ret = re.sub(r"^", " " * 4 * tab_count, ret, flags=re.MULTILINE)
+    for k, v in kwargs.items():
+        ret = ret.replace("{" + k + "}", str(v))
+
+    return ret
+
+
+def get_query_with_value(qry_str: str, params: dict) -> str:
+    """replace raw query to value filled query"""
+
+    def escape_literal(value) -> str:
+        ret = ""
+        if isinstance(value, str):
+            ret = "'" + value.replace("'", "''") + "'"
+        elif isinstance(value, datetime):
+            ret = f"'{value.strftime('%Y-%m-%d %H:%M:%S.%f')}'"
+        elif isinstance(value, (list, tuple)):
+            ret = str(value)
+        elif value is None:
+            ret = "NULL"
+        else:
+            ret = str(value)
+        return ret
+
+    if isinstance(params, (list, tuple)):
+        if not params:
+            return qry_str
+        params = params[0] if isinstance(params[0], dict) else {}
+
+    query_replaced = qry_str
+    for key, value in params.items():
+        find = f"%({key})s"
+        if find in query_replaced:
+            replace = escape_literal(value)
+            query_replaced = query_replaced.replace(find, replace)
+    # %% -> % : mysqlclient / db-api
+    # {{}} -> {} : python
+    query_replaced = (
+        query_replaced.replace("%%", "%").replace("{{", "{").replace("}}", "}")
+    )
+
+    return query_replaced
+
+
+def replace_en_ko_column_alias(qry_str: str, en: bool) -> str:
+    """ "
+    return en part or ko part separated by '|' using en variable
+    ex:
+    tbl.obj_nm "File Name|파일명"
+    ->
+    tbl.obj_nm "File Name"
+    """
+
+    pattern = r'(?P<ws>\s)"(?P<en>[^"]+)\|(?P<ko>[^"]+)"'
+    en_ko = "en" if en else "ko"
+    repl = rf'\g<ws>"\g<{en_ko}>"'
+    qry_str_new = re.sub(pattern, repl, qry_str, flags=re.MULTILINE | re.IGNORECASE)
+    return qry_str_new

mysqlclient_client/query_by_key/settings.py

@@ -0,0 +1,23 @@
+"""settings"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, kw_only=True)
+class Settings:
+    """query by key settings"""
+
+    use_en_ko_column_alias: bool
+    """SELECT file_name "File Name|파일명" """
+
+    use_conditional: bool
+    """
+    #if target == 'korea'
+        FROM tbl_korea
+    #else
+        FROM tbl_vietnam
+    #endif
+    """
+
+    all_query: dict[str, str]
+    """all query information"""

mysqlclient_client/settings.py

@@ -0,0 +1,61 @@
+"""settings"""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, kw_only=True)
+class Settings:
+    """db client settings"""
+
+    host: str
+    port: int
+    database: str
+    user: str
+    password: str
+
+    minconn: int
+    maxconn: int
+    connect_timeout: int
+
+    use_en_ko_column_alias: bool
+    """SELECT file_name "File Name|파일명" """
+    use_conditional: bool
+    """
+    #if target == 'korea'
+        FROM tbl_korea
+    #else
+        FROM tbl_vietnam
+    #endif
+    """
+    all_query: dict[str, str]
+    """all query information"""
+
+    before_read_execute: Callable[[str, dict, str, str], None]
+    """
+    qry_key: str, params: dict, qry_str: str, qry_with_value: str
+    """
+    after_read_execute: Callable[[str, int], None]
+    """
+    qry_key: str, duration: int
+    """
+    before_update_execute: Callable[
+        [str, dict, dict, str, str],
+        None,
+    ]
+    """
+    qry_key: str, params: dict, params_out: dict, qry_str: str, qry_with_value: str
+    """
+    after_update_execute: Callable[[str, int, dict, int], None]
+    """
+    qry_key: str, row_count: int, params_out: dict, duration: int
+    """
+
+    @property
+    def key(self):
+        """key for another dictionary"""
+
+        return (
+            f"{self.host},{self.port},{self.database},{self.user},{self.password}"
+            f"{self.minconn},{self.maxconn},{self.connect_timeout}"
+        )

mysqlclient_client-1.0.0.dist-info/METADATA

@@ -0,0 +1,296 @@
+Metadata-Version: 2.4
+Name: mysqlclient-client
+Version: 1.0.0
+Summary: MySQL helper function to run MySQL query with #if support
+Author-email: Gu Park <doctorgu@kakao.com>
+License: MIT License
+        
+        Copyright (c) 2025 doctorgu
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: homepage, https://github.com/doctorgu/mysqlclient-client
+Project-URL: repository, https://github.com/doctorgu/mysqlclient-client
+Project-URL: documentation, https://github.com/doctorgu/mysqlclient-client
+Keywords: mysqlclient client,mysqlclient helper,mysql helper
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mysqlclient
+Requires-Dist: pyhumps
+Requires-Dist: typing-extensions
+Requires-Dist: python-dotenv
+Requires-Dist: pydantic-settings
+Requires-Dist: Flask
+Requires-Dist: PyYAML
+Requires-Dist: ruff
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-env; extra == "test"
+Requires-Dist: pytest-mock; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: build; extra == "test"
+Dynamic: license-file
+
+# MysqlclientClient — Modern MySQL Helper for Python
+
+A lightweight, opinionated wrapper around **mysqlclient** (`MySQLdb`) with built-in support for:
+
+- Connection pooling (`minconn` / `maxconn`)
+- Query dictionary management
+- Conditional SQL (`#if` / `#elif` / `#endif`)
+- Bilingual column aliases (`en|ko`)
+- Simple transaction handling via context manager
+- Safe parameter binding (`%(param)s` syntax)
+- Streaming CSV export support
+
+> Successor-friendly alternative to raw mysqlclient with better developer experience.
+
+## Installation
+
+```bash
+pip install mysqlclient-client
+```
+
+> Note: `mysqlclient-client` is a custom helper class. See full source in repository.
+
+## Quick Start
+
+### 1. Define Queries
+
+YAML format in `queries` folder (or dictionary):
+
+```yaml
+- name: read_user_id_all
+  value: |
+    SELECT  user_id
+    FROM    t_user
+
+- name: upsert_user
+  value: |
+    INSERT INTO t_user
+        (
+            user_id, user_name, user_rank
+        )
+    VALUES
+        (
+            %(user_id)s, %(user_name)s, %(user_rank)s
+        )
+    ON DUPLICATE KEY UPDATE
+        user_name = %(user_name)s,
+        user_rank = %(user_rank)s,
+        update_time = CURRENT_TIMESTAMP
+```
+
+### 2. Configure Database Connection
+
+```python
+from mysqlclient_client.settings import Settings
+
+db_settings = Settings(
+    host="127.0.0.1",
+    port=3306,
+    database="test",
+    user="root",
+    password="password",
+    minconn=3,
+    maxconn=10,
+    connect_timeout=5,
+    use_en_ko_column_alias=True,
+    use_conditional=True,
+    all_query=qry_dic,
+    before_read_execute=lambda qry_key, params, qry_str, qry_with_value: print(
+        f'READ_ROWS_START, QRY_KEY: "{qry_key}", QRY_WITH_VALUE: {qry_with_value}'
+    ),
+    after_read_execute=lambda qry_key, duration: print(
+        f'READ_ROWS_END, QRY_KEY: "{qry_key}", DURATION: {duration}'
+    ),
+    before_update_execute=lambda qry_key, params, params_out, qry_str, qry_with_value: (
+        print(f'UPDATES_START, QRY_KEY: "{qry_key}", QRY_WITH_VALUE: {qry_with_value}')
+    ),
+    after_update_execute=lambda qry_key, row_count, params_out, duration: print(
+        f'UPDATES_END, QRY_KEY: "{qry_key}", DURATION: {duration}'
+    ),
+)
+```
+
+### 3. Basic Usage
+
+```python
+from mysqlclient_client.client import Client
+
+db = Client(db_settings=db_settings)
+
+# Read single row
+row = db.read_row("read_user_id_all", {})
+print(row)  # {'user_id': 'gildong.hong'}
+
+# Read all rows
+rows = db.read_rows("read_user_id_all", {})
+print(rows[:2])
+```
+
+## Create / Update / Delete Operations
+
+### `update()` — Single CUD Statement
+
+Returns affected row count:
+
+```python
+affected = db.update(
+    "upsert_user", {"user_id": "gildong.hong", "user_name": "홍길동", "user_rank": 1}
+)
+print("Affected rows:", affected)  # 1
+```
+
+### Capture Output Parameters
+
+```python
+params_out = {"user_name": "", "user_rank": 0}
+db.update(
+    "upsert_user",
+    {"user_id": "gildong.hong", "user_name": "홍길동", "user_rank": 1},
+    params_out=params_out,
+)
+print("Returned name:", params_out["user_name"], params_out["user_rank"])
+```
+
+### `updates()` — Batch Execution
+
+```python
+batch = [
+    ("upsert_user", {"user_id": "sunja.kim", "user_name": "김순자", "user_rank": 2}),
+    ("upsert_user", {"user_id": "malja.kim", "user_name": "김말자", "user_rank": 3}),
+]
+
+results = db.updates(batch)
+print("Batch results:", results)  # [1, 1]
+```
+
+## Transaction Support with `with`
+
+Automatically commits on success, rolls back on exception:
+
+```python
+with Client(db_settings=db_settings) as db:
+    new_id = "youngja.lee"
+    db.update("upsert_user", {"user_id": new_id, "user_name": "이영자", "user_rank": 4})
+    db.update("delete_user", {"user_id": new_id})
+    print("Committed successfully")
+```
+
+## Partially return CSV
+
+Read rows partially and return immediately to client to show progress:
+
+```python
+# Flask
+@app.route("/read-csv-partial")
+def read_csv_partial():
+    """read csv partial"""
+
+    db_client = Client(db_settings=db_settings)
+    filename = f"{datetime.now(UTC).strftime('%Y%m%d%H%M%S')}.csv"
+
+    return Response(
+        db_client.read_csv_partial("read_csv_partial", {}),
+        mimetype="text/csv",
+        headers={
+            "Access-Control-Expose-Headers": "Content-Disposition",
+            "Content-Disposition": f'attachment; filename="{filename}"',
+            "Cache-Control": "no-cache, no-store, must-revalidate",
+            "Pragma": "no-cache",
+            "Expires": "0",
+            "X-Accel-Buffering": "no",
+            "Transfer-Encoding": "chunked",
+        },
+    )
+```
+
+## Bilingual Column Aliases (English ↔ Korean)
+
+Enabled when `use_en_ko_column_alias=True` and `en` not omitted:
+
+```yaml
+- name: read_user_alias
+  value: |
+    SELECT  user_id "Id|아이디", user_name "Name|이름", user_rank "Rank|순위"
+    FROM    t_user
+    WHERE   user_id = %(user_id)s
+```
+
+### English mode (`en=True`)
+
+```python
+rows = db.read_rows("read_user_alias", {"user_id": "gildong.hong"}, en=True)
+print(rows[0])
+# {'Id': 'gildong.hong', 'Name': '홍길동', 'Rank': 1}
+```
+
+### Korean mode (`en=False`)
+
+```python
+rows = db.read_rows("read_user_alias", {"user_id": "gildong.hong"}, en=False)
+print(rows[0])
+# {'아이디': 'gildong.hong', '이름': '홍길동', '순위': 1}
+```
+
+## Conditional SQL (`#if`, `#elif`, `#endif`)
+
+Enabled when `use_conditional=True`:
+
+```yaml
+- name: read_user_search
+  value: |
+    SELECT  user_id, user_name, user_rank, insert_time, update_time
+    FROM    t_user
+    WHERE   1 = 1
+    #if user_id
+            AND user_id = %(user_id)s
+    #elif user_name
+            AND user_name LIKE %(user_name)s
+    #elif user_rank
+            AND user_rank <= %(user_rank)s
+    #endif
+```
+
+## Safety & Security
+
+The `#if` preprocessor only allows parameter names, string literals, numbers, and basic boolean operators. Any attempt to inject raw SQL will raise a parsing error before execution.
+
+## Features Summary
+
+| Feature                       | Notes                                                                           |
+| ----------------------------- | ------------------------------------------------------------------------------- |
+| Connection pooling            | Thread-safe pool via `minconn` / `maxconn`                                      |
+| Named queries                 | Stored in YAML / dictionary                                                     |
+| Single-row / multi-row fetch  | `read_row()` / `read_rows()`                                                    |
+| Single / batch CUD operations | `update()` / `updates()`                                                        |
+| Output parameters             | Via `params_out` dict                                                           |
+| Transactions via `with`       | Auto rollback on exception                                                      |
+| Partially return CSV          | `read_csv_partial` / `read_csv_partial_async`                                   |
+| Bilingual column aliases      | `"Name\|이름"` syntax                                                           |
+| Conditional SQL               | `#if` / `#elif` / `#endif`                                                      |
+| Logging support               | Before and after execute hooks via `before...` and `after...` callables         |
+| SQL injection protection      | Strict parsing in conditionals                                                  |
+
+## License
+
+MIT

mysqlclient_client-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+mysqlclient_client/client.py,sha256=JPRPJKcy6Avx30uGm6z7Tebc9UTuEWyZx-Z2hEjjH5E,19318
+mysqlclient_client/settings.py,sha256=DXxrIMkaPZTfXh0Im7oDC929rdUVnULFJZAU2WECYM4,1433
+mysqlclient_client/query_by_key/query.py,sha256=7RVBZKdxVkCE-17met40mcvTuklKbLTQFaMlBZ5m2Qs,1868
+mysqlclient_client/query_by_key/query_util.py,sha256=4vUlhdejomFLI7hk2ThbTPAS3ME4q6iGawSs7Q0PK8I,4227
+mysqlclient_client/query_by_key/settings.py,sha256=v3HEvUeTqYzYfdLb8Z9vvR2Jof5t5FavrJbXztzuQL8,423
+mysqlclient_client-1.0.0.dist-info/licenses/LICENSE,sha256=gFDlDjmqY3ZYsdSoSZrY2jivE561CTz5IV-1wo4gjyU,1065
+mysqlclient_client-1.0.0.dist-info/METADATA,sha256=Zh0JEd_2YM5KIXkAbtPvUKRixDcbF-LAZiJ7mTg53XQ,9740
+mysqlclient_client-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+mysqlclient_client-1.0.0.dist-info/top_level.txt,sha256=CnkGv3Ejoc5QVxNA_1KnHnL0d3VZPgxlURVm61B8g7E,19
+mysqlclient_client-1.0.0.dist-info/RECORD,,

mysqlclient_client-1.0.0.dist-info/WHEEL

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

mysqlclient_client-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 doctorgu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mysqlclient_client-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mysqlclient_client