sqlym 0.1.0__tar.gz → 0.1.1__tar.gz

{sqlym-0.1.0 → sqlym-0.1.1}/Makefile

@@ -1,4 +1,4 @@
-.PHONY: install test lint format lint-fix pre-commit clean db-up db-down test-postgresql test-mysql test-oracle test-db test-all
+.PHONY: install test lint format lint-fix pre-commit clean db-up db-down test-postgresql test-mysql test-oracle test-db test-all build release-test release
 
 install:
 	uv sync --dev
@@ -46,3 +46,13 @@ clean:
 	rm -rf .venv .ruff_cache .pytest_cache .coverage htmlcov dist build
 	find . -type d -name __pycache__ -exec rm -rf {} +
 	find . -type d -name "*.egg-info" -exec rm -rf {} +
+
+build:
+	rm -rf dist/
+	uv run python -m build
+
+release-test: build
+	uv run twine upload --repository testpypi dist/*
+
+release: build
+	uv run twine upload dist/*

{sqlym-0.1.0 → sqlym-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlym
-Version: 0.1.0
+Version: 0.1.1
 Summary: SQL-first database access library for Python
 Author: izuno4t
 License-Expression: MIT
@@ -85,26 +85,30 @@ WHERE
     AND status = /* $status */'active'
 ```
 
-### 3. Execute
+### 3. Parse and Execute
 
 ```python
-from sqlym import SqlExecutor, create_mapper
+from sqlym import SqlLoader, parse_sql, create_mapper
 
-executor = SqlExecutor(connection)
+# Load SQL template
+loader = SqlLoader("sql")
+sql_template = loader.load("employee/find_by_dept.sql")
+
+# Parse with parameters (lines with None are automatically removed)
+result = parse_sql(sql_template, {
+    "id": 100,
+    "dept_id": None,  # this line is removed
+    "status": "active",
+})
+
+# Execute with your database driver
+cursor.execute(result.sql, result.params)
+
+# Map results to entity
 mapper = create_mapper(Employee)
+employees = [mapper.map(row) for row in cursor.fetchall()]
 
-# Lines with None parameters are automatically removed
-result = executor.query(
-    "sql/employee/find_by_dept.sql",
-    {
-        "id": 100,
-        "dept_id": None,
-        "status": "active",
-    },  # dept_id line is removed
-    mapper=mapper
-)
-
-for emp in result:
+for emp in employees:
     print(emp.name)
 ```
 
@@ -154,7 +158,8 @@ If you want to hide the SQL snippet from error messages, disable it via
 config:
 
 ```python
-from sqlym import config
+from sqlym.config import ERROR_INCLUDE_SQL, ERROR_MESSAGE_LANGUAGE
+import sqlym.config as config
 
 config.ERROR_INCLUDE_SQL = False
 config.ERROR_MESSAGE_LANGUAGE = "en"

{sqlym-0.1.0 → sqlym-0.1.1}/README.ja.md

@@ -58,26 +58,30 @@ WHERE
     AND status = /* $status */'active'
 ```
 
-### 3. 実行
+### 3. パースと実行
 
 ```python
-from sqlym import SqlExecutor, create_mapper
+from sqlym import SqlLoader, parse_sql, create_mapper
 
-executor = SqlExecutor(connection)
+# SQL テンプレート読み込み
+loader = SqlLoader("sql")
+sql_template = loader.load("employee/find_by_dept.sql")
+
+# パラメータでパース（None の行は自動削除）
+result = parse_sql(sql_template, {
+    "id": 100,
+    "dept_id": None,  # この行は削除される
+    "status": "active",
+})
+
+# データベースドライバーで実行
+cursor.execute(result.sql, result.params)
+
+# 結果をエンティティにマッピング
 mapper = create_mapper(Employee)
+employees = [mapper.map(row) for row in cursor.fetchall()]
 
-# パラメータがNoneの行は自動削除される
-result = executor.query(
-    "sql/employee/find_by_dept.sql",
-    {
-        "id": 100,
-        "dept_id": None,
-        "status": "active",
-    },  # dept_idの行は消える
-    mapper=mapper
-)
-
-for emp in result:
+for emp in employees:
     print(emp.name)
 ```
 
@@ -127,7 +131,8 @@ SQL 断片を表示したくない場合は
 設定で無効化してください。
 
 ```python
-from sqlym import config
+from sqlym.config import ERROR_INCLUDE_SQL, ERROR_MESSAGE_LANGUAGE
+import sqlym.config as config
 
 config.ERROR_INCLUDE_SQL = False
 config.ERROR_MESSAGE_LANGUAGE = "en"

{sqlym-0.1.0 → sqlym-0.1.1}/README.md

@@ -58,26 +58,30 @@ WHERE
     AND status = /* $status */'active'
 ```
 
-### 3. Execute
+### 3. Parse and Execute
 
 ```python
-from sqlym import SqlExecutor, create_mapper
+from sqlym import SqlLoader, parse_sql, create_mapper
 
-executor = SqlExecutor(connection)
+# Load SQL template
+loader = SqlLoader("sql")
+sql_template = loader.load("employee/find_by_dept.sql")
+
+# Parse with parameters (lines with None are automatically removed)
+result = parse_sql(sql_template, {
+    "id": 100,
+    "dept_id": None,  # this line is removed
+    "status": "active",
+})
+
+# Execute with your database driver
+cursor.execute(result.sql, result.params)
+
+# Map results to entity
 mapper = create_mapper(Employee)
+employees = [mapper.map(row) for row in cursor.fetchall()]
 
-# Lines with None parameters are automatically removed
-result = executor.query(
-    "sql/employee/find_by_dept.sql",
-    {
-        "id": 100,
-        "dept_id": None,
-        "status": "active",
-    },  # dept_id line is removed
-    mapper=mapper
-)
-
-for emp in result:
+for emp in employees:
     print(emp.name)
 ```
 
@@ -127,7 +131,8 @@ If you want to hide the SQL snippet from error messages, disable it via
 config:
 
 ```python
-from sqlym import config
+from sqlym.config import ERROR_INCLUDE_SQL, ERROR_MESSAGE_LANGUAGE
+import sqlym.config as config
 
 config.ERROR_INCLUDE_SQL = False
 config.ERROR_MESSAGE_LANGUAGE = "en"

sqlym-0.1.1/examples/crud_example.py

@@ -0,0 +1,382 @@
+#!/usr/bin/env python3
+"""sqlym CRUD Example.
+
+This example demonstrates the basic usage of sqlym:
+- Entity definition (dataclass + Column mapping)
+- SQL file loading with SqlLoader
+- Dynamic conditional search (None parameters remove condition lines)
+- IN clause expansion
+- LIKE escape
+- Row mapping with create_mapper
+
+Usage:
+    uv run python examples/crud_example.py
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Annotated
+
+from sqlym import Column, Dialect, SqlLoader, create_mapper, escape_like, parse_sql
+
+
+# =============================================================================
+# Entity Definition
+# =============================================================================
+
+
+@dataclass
+class User:
+    """User entity.
+
+    Use Annotated[T, Column("DB_COLUMN_NAME")] to define
+    mapping between DB column names and field names.
+    """
+
+    id: int
+    name: str
+    email: str
+    department: str | None = None
+    created_at: Annotated[datetime | None, Column("created_at")] = None
+
+
+# =============================================================================
+# Database Setup
+# =============================================================================
+
+
+def setup_database() -> sqlite3.Connection:
+    """Set up SQLite database for testing."""
+    conn = sqlite3.connect(":memory:")
+    conn.row_factory = sqlite3.Row  # Enable dict-like access
+
+    conn.execute("""
+        CREATE TABLE users (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            name TEXT NOT NULL,
+            email TEXT NOT NULL UNIQUE,
+            department TEXT,
+            created_at TEXT
+        )
+    """)
+
+    # Insert sample data
+    sample_data = [
+        ("Tanaka Taro", "tanaka@example.com", "Sales", "2024-01-15 09:00:00"),
+        ("Suzuki Hanako", "suzuki@example.com", "Development", "2024-02-01 10:30:00"),
+        ("Sato Ichiro", "sato@example.com", "Sales", "2024-02-15 14:00:00"),
+        ("Yamada Misaki", "yamada@example.com", "Development", "2024-03-01 11:00:00"),
+        ("Takahashi 100% Achieved", "takahashi@example.com", "Sales", "2024-03-15 16:00:00"),
+    ]
+    conn.executemany(
+        "INSERT INTO users (name, email, department, created_at) VALUES (?, ?, ?, ?)",
+        sample_data,
+    )
+    conn.commit()
+    return conn
+
+
+# =============================================================================
+# CRUD Operations
+# =============================================================================
+
+
+def demo_select_all(conn: sqlite3.Connection) -> None:
+    """Demo: Select all records."""
+    print("=" * 60)
+    print("[SELECT ALL]")
+    print("=" * 60)
+
+    sql = "SELECT * FROM users ORDER BY id"
+    result = parse_sql(sql, {})
+
+    print(f"SQL: {result.sql}")
+    print(f"Parameters: {result.params}")
+    print()
+
+    cursor = conn.execute(result.sql, result.params)
+    rows = [dict(row) for row in cursor.fetchall()]
+
+    mapper = create_mapper(User)
+    users = mapper.map_rows(rows)
+
+    for user in users:
+        print(f"  {user}")
+    print()
+
+
+def demo_dynamic_search(conn: sqlite3.Connection, loader: SqlLoader) -> None:
+    """Demo: Dynamic conditional search.
+
+    When a parameter is None, that condition line is automatically removed
+    (for parameters with $ prefix).
+    """
+    print("=" * 60)
+    print("[DYNAMIC SEARCH] Only department specified (other conditions removed)")
+    print("=" * 60)
+
+    sql_template = loader.load("find_users.sql")
+    print("SQL Template:")
+    print(sql_template)
+    print()
+
+    # Only department specified, others are None -> those condition lines are removed
+    result = parse_sql(
+        sql_template,
+        {
+            "id": None,  # This line is removed
+            "name_pattern": None,  # This line is removed
+            "department": "Sales",  # This condition remains
+            "ids": None,  # This line is removed
+        },
+    )
+
+    print(f"Generated SQL:\n{result.sql}")
+    print(f"Parameters: {result.params}")
+    print()
+
+    cursor = conn.execute(result.sql, result.params)
+    rows = [dict(row) for row in cursor.fetchall()]
+    mapper = create_mapper(User)
+    users = mapper.map_rows(rows)
+
+    print("Results:")
+    for user in users:
+        print(f"  {user}")
+    print()
+
+
+def demo_in_clause(conn: sqlite3.Connection, loader: SqlLoader) -> None:
+    """Demo: IN clause expansion.
+
+    List parameters are automatically expanded.
+    Example: IN /* $ids */(1) -> IN (?, ?, ?)
+    """
+    print("=" * 60)
+    print("[IN CLAUSE] Search by multiple IDs")
+    print("=" * 60)
+
+    sql_template = loader.load("find_users.sql")
+
+    # Only ids specified, others are None
+    result = parse_sql(
+        sql_template,
+        {
+            "id": None,
+            "name_pattern": None,
+            "department": None,
+            "ids": [1, 3, 5],  # Expanded to IN clause
+        },
+    )
+
+    print(f"Generated SQL:\n{result.sql}")
+    print(f"Parameters: {result.params}")
+    print()
+
+    cursor = conn.execute(result.sql, result.params)
+    rows = [dict(row) for row in cursor.fetchall()]
+    mapper = create_mapper(User)
+    users = mapper.map_rows(rows)
+
+    print("Results:")
+    for user in users:
+        print(f"  {user}")
+    print()
+
+
+def demo_like_escape(conn: sqlite3.Connection, loader: SqlLoader) -> None:
+    """Demo: LIKE escape.
+
+    Use escape_like() to safely search strings containing
+    special characters (%, _, #).
+    """
+    print("=" * 60)
+    print("[LIKE ESCAPE] Search for names containing '100%'")
+    print("=" * 60)
+
+    sql_template = loader.load("find_users.sql")
+
+    # Search for users containing "100%" (% is a LIKE special char, needs escaping)
+    search_term = escape_like("100%", Dialect.SQLITE)
+    print(f"Search term: '100%' -> After escape: '{search_term}'")
+
+    result = parse_sql(
+        sql_template,
+        {
+            "id": None,
+            "name_pattern": f"%{search_term}%",  # Add % for partial match
+            "department": None,
+            "ids": None,
+        },
+        dialect=Dialect.SQLITE,
+    )
+
+    print(f"Generated SQL:\n{result.sql}")
+    print(f"Parameters: {result.params}")
+    print()
+
+    cursor = conn.execute(result.sql, result.params)
+    rows = [dict(row) for row in cursor.fetchall()]
+    mapper = create_mapper(User)
+    users = mapper.map_rows(rows)
+
+    print("Results:")
+    for user in users:
+        print(f"  {user}")
+    print()
+
+
+def demo_insert(conn: sqlite3.Connection, loader: SqlLoader) -> None:
+    """Demo: INSERT."""
+    print("=" * 60)
+    print("[INSERT] Register new user")
+    print("=" * 60)
+
+    sql_template = loader.load("insert_user.sql")
+
+    result = parse_sql(
+        sql_template,
+        {
+            "name": "New User",
+            "email": "newuser@example.com",
+            "department": "General Affairs",
+            "created_at": "2024-04-01 09:00:00",
+        },
+    )
+
+    print(f"Generated SQL:\n{result.sql}")
+    print(f"Parameters: {result.params}")
+    print()
+
+    cursor = conn.execute(result.sql, result.params)
+    conn.commit()
+    print(f"Inserted ID: {cursor.lastrowid}")
+    print()
+
+
+def demo_update(conn: sqlite3.Connection, loader: SqlLoader) -> None:
+    """Demo: UPDATE."""
+    print("=" * 60)
+    print("[UPDATE] Update user information")
+    print("=" * 60)
+
+    sql_template = loader.load("update_user.sql")
+
+    result = parse_sql(
+        sql_template,
+        {
+            "id": 1,
+            "name": "Tanaka Taro (Updated)",
+            "email": "tanaka-updated@example.com",
+            "department": "Sales (Transferred)",
+        },
+    )
+
+    print(f"Generated SQL:\n{result.sql}")
+    print(f"Parameters: {result.params}")
+    print()
+
+    conn.execute(result.sql, result.params)
+    conn.commit()
+
+    # Verify update result
+    cursor = conn.execute("SELECT * FROM users WHERE id = 1")
+    row = dict(cursor.fetchone())
+    mapper = create_mapper(User)
+    user = mapper.map_row(row)
+    print(f"After update: {user}")
+    print()
+
+
+def demo_delete(conn: sqlite3.Connection, loader: SqlLoader) -> None:
+    """Demo: DELETE."""
+    print("=" * 60)
+    print("[DELETE] Delete user")
+    print("=" * 60)
+
+    sql_template = loader.load("delete_user.sql")
+
+    result = parse_sql(
+        sql_template,
+        {"id": 6},  # User inserted by demo_insert
+    )
+
+    print(f"Generated SQL:\n{result.sql}")
+    print(f"Parameters: {result.params}")
+    print()
+
+    cursor = conn.execute(result.sql, result.params)
+    conn.commit()
+    print(f"Deleted rows: {cursor.rowcount}")
+    print()
+
+
+def demo_named_placeholder(conn: sqlite3.Connection) -> None:
+    """Demo: Named placeholder (:name format).
+
+    Supports :name format placeholders used by Oracle, etc.
+    """
+    print("=" * 60)
+    print("[NAMED PLACEHOLDER] :name format")
+    print("=" * 60)
+
+    sql = "SELECT * FROM users WHERE department = /* $department */'default'"
+    result = parse_sql(
+        sql,
+        {"department": "Development"},
+        placeholder=":name",  # Specify named placeholder
+    )
+
+    print(f"Generated SQL: {result.sql}")
+    print(f"Named parameters: {result.named_params}")
+    print()
+
+    # sqlite3 supports :name format
+    cursor = conn.execute(result.sql, result.named_params)
+    rows = [dict(row) for row in cursor.fetchall()]
+    mapper = create_mapper(User)
+    users = mapper.map_rows(rows)
+
+    print("Results:")
+    for user in users:
+        print(f"  {user}")
+    print()
+
+
+# =============================================================================
+# Main
+# =============================================================================
+
+
+def main() -> None:
+    """Run the examples."""
+    print("sqlym CRUD Example")
+    print("=" * 60)
+    print()
+
+    # Set up database and SqlLoader
+    conn = setup_database()
+    sql_dir = Path(__file__).parent / "sql"
+    loader = SqlLoader(sql_dir)
+
+    # Run each demo
+    demo_select_all(conn)
+    demo_dynamic_search(conn, loader)
+    demo_in_clause(conn, loader)
+    demo_like_escape(conn, loader)
+    demo_insert(conn, loader)
+    demo_update(conn, loader)
+    demo_delete(conn, loader)
+    demo_named_placeholder(conn)
+
+    print("=" * 60)
+    print("Example completed")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

sqlym-0.1.1/examples/sql/delete_user.sql

@@ -0,0 +1,4 @@
+-- User deletion SQL
+DELETE FROM users
+WHERE
+    id = /* id */1

sqlym-0.1.1/examples/sql/find_users.sql

@@ -0,0 +1,15 @@
+-- User search SQL (with dynamic conditions)
+-- 2way SQL: When a parameter is None, that condition line is automatically removed
+SELECT
+    id,
+    name,
+    email,
+    department,
+    created_at
+FROM users
+WHERE
+    id = /* $id */1
+    AND name LIKE /* $name_pattern */'%test%' ESCAPE '#'
+    AND department = /* $department */'Sales'
+    AND id IN /* $ids */(1, 2, 3)
+ORDER BY id

sqlym-0.1.1/examples/sql/insert_user.sql

@@ -0,0 +1,8 @@
+-- User registration SQL
+INSERT INTO users (name, email, department, created_at)
+VALUES (
+    /* name */'default_name',
+    /* email */'default@example.com',
+    /* department */'General',
+    /* created_at */'2024-01-01 00:00:00'
+)

sqlym-0.1.1/examples/sql/update_user.sql

@@ -0,0 +1,8 @@
+-- User update SQL
+UPDATE users
+SET
+    name = /* name */'default_name',
+    email = /* email */'default@example.com',
+    department = /* department */'General'
+WHERE
+    id = /* id */1

{sqlym-0.1.0 → sqlym-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlym"
-version = "0.1.0"
+version = "0.1.1"
 description = "SQL-first database access library for Python"
 readme = "README.md"
 license = "MIT"

{sqlym-0.1.0 → sqlym-0.1.1}/uv.lock

@@ -775,7 +775,7 @@ wheels = [
 
 [[package]]
 name = "sqlym"
-version = "0.1.0"
+version = "0.1.1"
 source = { editable = "." }
 
 [package.optional-dependencies]