sqlite3-client 1.0.0__py3-none-any.whl

sqlite3_client/query_by_key/query_util.py

@@ -0,0 +1,164 @@
+"""query_by_key_util"""
+
+import re
+from datetime import datetime
+
+
+def get_conditional(qry_str: str, params: dict) -> str:
+    """
+    return true or false part by condition.
+
+    ex:
+    SELECT  *
+    FROM
+    #if target == 'en'
+            tbl_en
+    #else
+            tbl_ko
+    #endif
+    ->
+    SELECT  *
+    FROM
+            tbl_en
+    """
+
+    def eval_safe(condition: str, params: dict) -> bool:
+        """
+        allow only params and operators for condition to call eval safely
+
+        # assert eval_safe(':target == "A"', {"target": "A"}) is True
+        # assert eval_safe(':target != "A"', {"target": "A"}) is False
+        # assert eval_safe(":target == 123", {"target": 123}) is True
+        # assert eval_safe(":target != 123", {"target": 123}) is False
+        # assert eval_safe(":target123 == 123", {"target123": 123}) is True
+        # assert eval_safe(":target123 != 123", {"target123": 123}) is False
+        # assert eval_safe(':target == ""', {"target": ""}) is True
+        # assert eval_safe(':target != ""', {"target": ""}) is False
+        # assert eval_safe('"A" in :targets', {"targets": ["A", "B"]}) is True
+        # assert eval_safe('"A" not in :targets', {"targets": ["A", "B"]}) is False
+        # assert eval_safe(":t in [i for i in range(10)]", {"t": 1}) is True  # '[i' not in
+        """
+
+        # remove ':' from :target
+        to_eval = re.sub(r":(\w+)", r"\1", condition)
+
+        # remove
+        # - double quoted string
+        # - single quoted string
+        # - digit
+        to_check = re.sub(r"""(".*?"|'.*?'|\b\d+\b)""", "", to_eval)
+
+        param_set = set([key for key in params])
+        op_set = {
+            "==",
+            "!=",
+            ">=",
+            ">",
+            "<=",
+            "<",
+            "+",
+            "-",
+            "/",
+            "//",
+            "*",
+            "**",
+            "and",
+            "or",
+            "not",
+            "in",
+            "True",
+            "False",
+        }
+        allowed_set = param_set | op_set
+
+        for word in to_check.split():
+            if word not in allowed_set:
+                raise ValueError(f"'{word}' not in {allowed_set}")
+
+        # pylint:disable=eval-used
+        return eval(to_eval, params)
+
+    rets = []
+    lines = qry_str.splitlines()
+
+    is_include = True
+    is_checked = False
+    for line in lines:
+        line_strip = line.strip()
+        if line_strip.startswith("#if") or line_strip.startswith("#elif"):
+            if not is_checked:
+                _, condition = line_strip.split(maxsplit=1)
+                # pylint:disable=eval-used
+                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):
+            ret = str(value)
+        elif value is None:
+            ret = "NULL"
+        else:
+            ret = str(value)
+        return ret
+
+    query_replaced = qry_str
+    for key, value in params.items():
+        replace = escape_literal(value)
+        query_replaced = re.sub(rf":{re.escape(key)}\b", replace, query_replaced)
+
+    # {{}} -> {} : python
+    query_replaced = query_replaced.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, count=0, flags=re.MULTILINE | re.IGNORECASE
+    )
+    return qry_str_new

sqlite3_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"""

sqlite3_client/settings.py

@@ -0,0 +1,65 @@
+"""settings"""
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True, kw_only=True)
+class Settings:
+    """db client settings"""
+
+    database: str
+    host: str = ""
+    port: int = 0
+    user: str = ""
+    password: str = ""
+
+    minconn: int = 1
+    maxconn: int = 5
+    connect_timeout: int = 5
+    timeout: float = 5.0
+
+    use_en_ko_column_alias: bool = False
+    """SELECT file_name "File Name|파일명" """
+    use_conditional: bool = False
+    """
+    #if target == 'korea'
+        FROM tbl_korea
+    #else
+        FROM tbl_vietnam
+    #endif
+    """
+    all_query: dict[str, str] = field(default_factory=dict)
+    """all query information"""
+
+    before_read_execute: Callable[[str, dict, str, str], None] | None = None
+    """
+    qry_key: str, params: dict, qry_str: str, qry_with_value: str
+    """
+    after_read_execute: Callable[[str, int], None] | None = None
+    """
+    qry_key: str, duration: int
+    """
+    before_update_execute: (
+        Callable[
+            [str, dict, dict, str, str],
+            None,
+        ]
+        | None
+    ) = 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] | None = 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}"
+        )

sqlite3_client-1.0.0.dist-info/METADATA

@@ -0,0 +1,422 @@
+Metadata-Version: 2.4
+Name: sqlite3-client
+Version: 1.0.0
+Summary: Sqlite3 helper function to run SQLite query with #if support
+Author-email: Gu Park <doctorgu@kakao.com>
+License: MIT License
+        
+        Copyright (c) 2026 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/sqlite3-client
+Project-URL: repository, https://github.com/doctorgu/sqlite3-client
+Project-URL: documentation, https://github.com/doctorgu/sqlite3-client
+Keywords: sqlite3 client,sqlite3 helper
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyhumps
+Requires-Dist: typing-extensions
+Requires-Dist: python-dotenv
+Requires-Dist: pydantic-settings
+Requires-Dist: Flask
+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
+
+# Sqlite3Client — Modern SQLite Helper for Python
+
+A lightweight, opinionated wrapper around **sqlite3** 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` syntax)
+- Streaming CSV export support
+
+> Successor-friendly alternative to raw sqlite3 with better developer experience.
+
+## Installation
+
+```bash
+pip install sqlite3-client
+```
+
+> Note: `sqlite3-client` is a custom helper class. See full source in repository.
+
+## Quick Start
+
+### 1. Define Queries
+
+```python
+qry_dic: dict[str, str] = {}
+
+qry_dic.update(
+    {
+        "read_user_id_all": """
+SELECT  user_id
+FROM    t_user
+"""
+    }
+)
+
+qry_dic.update(
+    {
+        "upsert_user": """
+INSERT INTO t_user
+    (
+        user_id, user_name, user_rank
+    )
+VALUES
+    (
+        :user_id, :user_name, :user_rank
+    )
+ON CONFLICT (user_id)
+DO UPDATE
+SET     user_name = :user_name,
+        user_rank = :user_rank,
+        update_time = CURRENT_TIMESTAMP
+RETURNING user_name, user_rank;
+"""
+    }
+)
+```
+
+### 2. Configure Database Connection
+
+```python
+from sqlite3_client.settings import Settings
+
+db_settings = Settings(
+    database="test.db",
+    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 sqlite3_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"])  # 홍길동 1
+```
+
+### `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})  # Oops! Will rollback entire block
+    print("This won't print if error occurs")
+```
+
+## Partially return CSV
+
+Read rows partially and return immediately to client to show progress in client:
+
+```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().strftime('%Y%m%d%H%M%S')}.csv"
+
+    return Response(
+        db_client.read_csv_partial("read_csv_partial", {}),
+        mimetype="text/csv",
+        headers={
+            # if FE and BE are on different origins,
+            # server must expose the Content-Disposition header
+            "Access-Control-Expose-Headers": "Content-Disposition",
+            "Content-Disposition": f'attachment; filename="{filename}"',
+            # Very important for progressive saving in many browsers
+            "Cache-Control": "no-cache, no-store, must-revalidate",
+            "Pragma": "no-cache",
+            "Expires": "0",
+            "X-Accel-Buffering": "no",  # Important if using nginx
+            "Transfer-Encoding": "chunked",
+        },
+    )
+
+
+# Fast API
+@router.get("/read-csv-partial-async")
+async def read_csv_partial_async():
+    """read csv partial async"""
+
+    db_client = Client(db_settings=db_settings)
+    filename = f"{datetime.now().strftime('%Y%m%d%H%M%S')}.csv"
+
+    return StreamingResponse(
+        content=db_client.read_csv_partial_async("read_csv_partial", {}),
+        media_type="text/csv",
+        headers={
+            # if FE and BE are on different origins,
+            # server must expose the Content-Disposition header
+            "Access-Control-Expose-Headers": "Content-Disposition",
+            "Content-Disposition": f'attachment; filename="{filename}"',
+            # Very important for progressive saving in many browsers
+            "Cache-Control": "no-cache, no-store, must-revalidate",
+            "Pragma": "no-cache",
+            "Expires": "0",
+            "X-Accel-Buffering": "no",  # Important if using nginx
+            "Transfer-Encoding": "chunked",
+        },
+    )
+```
+
+## Bilingual Column Aliases (English ↔ Korean)
+
+Enabled when `use_en_ko_column_alias=True` and `en` not omitted:
+
+```python
+qry_dic.update(
+    {
+        "read_user_alias": """
+SELECT  user_id "Id|아이디", user_name "Name|이름", user_rank "Rank|순위"
+FROM    t_user
+WHERE   user_id = :user_id
+"""
+    }
+)
+```
+
+### 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': '홍길동'}
+```
+
+### Korean mode (`en=False`)
+
+```python
+rows = db.read_rows("read_user_alias", {"user_id": "gildong.hong"}, en=False)
+print(rows[0])
+# {'아이디': 'gildong.hong', '이름': '홍길동'}
+```
+
+## Conditional SQL (`#if`, `#elif`, `#endif`)
+
+Enabled when `use_conditional=True`:
+
+```python
+qry_dic.update(
+    {
+        "read_user_search": """
+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
+#elif user_name
+        AND user_name LIKE :user_name
+#elif user_rank
+        AND user_rank <= :user_rank
+#endif
+"""
+    }
+)
+```
+
+### Example: Search by `user_id`
+
+```python
+rows = db.read_rows(
+    "read_user_search", {"user_id": "gildong.hong", "user_name": "", "user_rank": 0}
+)
+print([r["user_name"] for r in rows])
+# ['홍길동']
+```
+
+### Example: Search by `user_name` (partial match)
+
+```python
+rows = db.read_rows(
+    "read_user_search", {"user_id": "", "user_name": "%김%", "user_rank": 0}
+)
+print([r["user_name"] for r in rows])
+# ['김순자', '김말자']
+```
+
+### Example: Search by `user_rank` (partial match)
+
+```python
+rows = db.read_rows(
+    "read_user_search", {"user_id": "", "user_name": "", "user_rank": 3}
+)
+print([r["user_name"] for r in rows])
+# ['홍길동', '김순자', '김말자']
+```
+
+## Logging support
+
+- `before_read_execute` called before execute query for read
+- `after_read_execute` called after execute query for read
+- `before_update_execute` called before execute query for CUD
+- `after_update_execute` called after execute query for CUD
+
+Can be replaced `print` with `logger`:
+
+### Example: Use logger to write debug info
+
+```python
+import logging
+
+
+def get_sql_logger(name="sql"):
+    logger = logging.getLogger(name)
+    if not logger.handlers:
+        logging.basicConfig(
+            filename="sql.log",
+            level=logging.DEBUG,
+            format="%(asctime)s [%(levelname)7s] %(message)s",
+            encoding="utf-8",
+        )
+    return logger
+
+
+logger = get_sql_logger()
+db_settings.before_read_execute = lambda qry_key, params, qry_str, qry_with_value: (
+    logger.debug(
+        f'READ_ROWS_START, QRY_KEY: "{qry_key}", QRY_WITH_VALUE: {qry_with_value}'
+    )
+)
+```
+
+## Safety & Security
+
+### Q: Is conditional SQL safe from injection?
+
+**A: Yes — completely safe.**
+
+The `#if` preprocessor **only allows**:
+
+- Parameter names (e.g. `user_id` or `:user_id`)
+- String literals (`'active'`, `"pending"`)
+- Numbers and basic operators
+- Whitespace and comments
+
+Any attempt to inject raw SQL will raise a parsing error **before** execution.
+
+```python
+# This will RAISE an exception "ValueError: 'user_id;' not in ..." (not execute!)
+"#if user_id; DROP TABLE t_user; --"
+```
+
+## Features Summary
+
+| Feature                       | Notes                                                                           |
+| ----------------------------- | ------------------------------------------------------------------------------- |
+| Connection pooling            | Via `minconn` / `maxconn`                                                       |
+| Named queries                 | Stored in 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 to DB via `before...` and `after...` callable function |
+| SQL injection protection      | Strict parsing in conditionals                                                  |
+
+## License
+
+MIT (or as defined in your project)
+
+---
+
+Made with ❤️ for cleaner, safer SQLite code in Python.

sqlite3_client-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+sqlite3_client/client.py,sha256=ng5lHQtHAZD1F3Hq50kYDBWMMbS0JorHrT7RwZSVNKU,20121
+sqlite3_client/settings.py,sha256=FyvYiykObpC083c18_-XoaYih57Ky420K9auPefHB18,1634
+sqlite3_client/query_by_key/query.py,sha256=sqp7WFdgMDwkHVXEcaFX8J2l6E3_mSkBwnv3kdO2W9A,1461
+sqlite3_client/query_by_key/query_util.py,sha256=RQPH2MfVboi4oQnzJgRZNbIzVcisD4QYMlp9pSLzTS8,4773
+sqlite3_client/query_by_key/settings.py,sha256=v3HEvUeTqYzYfdLb8Z9vvR2Jof5t5FavrJbXztzuQL8,423
+sqlite3_client-1.0.0.dist-info/licenses/LICENSE,sha256=SceEQXH2EqmhxRLvy-52rf03gwxH8LrGttgH-lannvU,1065
+sqlite3_client-1.0.0.dist-info/METADATA,sha256=srWYYsQhy6qW22eRtVxwVNvFklHyAdVShbi7rVOIKrk,12796
+sqlite3_client-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+sqlite3_client-1.0.0.dist-info/top_level.txt,sha256=GqUbqR62xmkd2ZLf02OtkXIqCG8drGOt8Bxtm6EBRpM,15
+sqlite3_client-1.0.0.dist-info/RECORD,,

sqlite3_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
+