sqlym 0.1.0__py3-none-any.whl

sqlym/__init__.py

@@ -0,0 +1,28 @@
+"""sqly: SQL-first database access library for Python."""
+
+from sqlym._parse import parse_sql
+from sqlym.dialect import Dialect
+from sqlym.escape_utils import escape_like
+from sqlym.exceptions import MappingError, SqlFileNotFoundError, SqlParseError, SqlyError
+from sqlym.loader import SqlLoader
+from sqlym.mapper import ManualMapper, RowMapper, create_mapper
+from sqlym.mapper.column import Column, entity
+from sqlym.parser.twoway import ParsedSQL, TwoWaySQLParser
+
+__all__ = [
+    "Column",
+    "Dialect",
+    "ManualMapper",
+    "MappingError",
+    "ParsedSQL",
+    "RowMapper",
+    "SqlFileNotFoundError",
+    "SqlLoader",
+    "SqlParseError",
+    "SqlyError",
+    "TwoWaySQLParser",
+    "create_mapper",
+    "entity",
+    "escape_like",
+    "parse_sql",
+]

sqlym/_parse.py

@@ -0,0 +1,36 @@
+"""parse_sql 便利関数."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from sqlym.parser.twoway import ParsedSQL, TwoWaySQLParser
+
+if TYPE_CHECKING:
+    from sqlym.dialect import Dialect
+
+
+def parse_sql(
+    sql: str,
+    params: dict[str, Any],
+    *,
+    placeholder: str = "?",
+    dialect: Dialect | None = None,
+) -> ParsedSQL:
+    """SQL をパースする便利関数.
+
+    Args:
+        sql: SQL テンプレート
+        params: パラメータ辞書
+        placeholder: プレースホルダ形式 ("?", "%s", ":name")
+        dialect: RDBMS 方言。指定時は dialect.placeholder を使用する。
+
+    Returns:
+        パース結果
+
+    Raises:
+        ValueError: dialect と placeholder (デフォルト以外) を同時に指定した場合
+
+    """
+    parser = TwoWaySQLParser(sql, placeholder=placeholder, dialect=dialect)
+    return parser.parse(params)

sqlym/config.py

@@ -0,0 +1,7 @@
+"""sqly の設定."""
+
+# エラーメッセージに SQL 断片を含めるか
+ERROR_INCLUDE_SQL: bool = True
+
+# エラーメッセージの言語 ("ja" / "en")
+ERROR_MESSAGE_LANGUAGE: str = "ja"

sqlym/dialect.py

@@ -0,0 +1,81 @@
+"""Dialect enum: RDBMS ごとの SQL 方言定義."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class Dialect(Enum):
+    """RDBMS ごとの SQL 方言.
+
+    POSTGRESQL と MYSQL は同じプレースホルダ ``%s`` を使用するが、
+    方言固有プロパティが異なるため別メンバーとして定義する。
+    """
+
+    SQLITE = ("sqlite", "?")
+    POSTGRESQL = ("postgresql", "%s")
+    MYSQL = ("mysql", "%s")
+    ORACLE = ("oracle", ":name")
+
+    def __init__(self, dialect_id: str, placeholder_fmt: str) -> None:
+        self._dialect_id = dialect_id
+        self._placeholder_fmt = placeholder_fmt
+
+    @property
+    def placeholder(self) -> str:
+        """プレースホルダ文字列を返す."""
+        return self._placeholder_fmt
+
+    @property
+    def like_escape_chars(self) -> frozenset[str]:
+        """LIKE 句でエスケープが必要な特殊文字を返す.
+
+        SQL 標準の LIKE ワイルドカード文字（``%``, ``_``）と
+        エスケープ文字自体（``#``）をエスケープ対象とする。
+
+        Note:
+            Oracle の LIKE ESCAPE 構文では、エスケープ文字の後には
+            ``%`` または ``_`` のみ指定可能（ORA-01424）。
+            全角文字（``％``, ``＿``）は Oracle のワイルドカードではないため、
+            エスケープ対象に含めない。
+
+        Returns:
+            エスケープ対象文字の frozenset
+        """
+        return frozenset({"#", "%", "_"})
+
+    @property
+    def in_clause_limit(self) -> int | None:
+        """IN 句に指定できる要素数の上限を返す.
+
+        Oracle は 1000 件の制限がある。他の RDBMS は制限なし。
+
+        Returns:
+            上限値。None は無制限を意味する。
+        """
+        match self:
+            case Dialect.ORACLE:
+                return 1000
+            case _:
+                return None
+
+    @property
+    def backslash_is_escape(self) -> bool:
+        """バックスラッシュが文字列リテラル内でエスケープ文字として機能するか.
+
+        MySQL と PostgreSQL ではデフォルトで True。
+        """
+        match self:
+            case Dialect.MYSQL | Dialect.POSTGRESQL:
+                return True
+            case _:
+                return False
+
+    @property
+    def like_escape_char(self) -> str:
+        """LIKE エスケープに使用するエスケープ文字を返す.
+
+        Returns:
+            エスケープ文字（デフォルト: ``#``）
+        """
+        return "#"

sqlym/escape_utils.py

@@ -0,0 +1,48 @@
+"""エスケープ関連ユーティリティ."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from sqlym.dialect import Dialect
+
+
+def escape_like(value: str, dialect: Dialect, *, escape_char: str | None = None) -> str:
+    """LIKE 句で使用する値の特殊文字をエスケープする.
+
+    LIKE 句のワイルドカード文字（``%``, ``_``）およびエスケープ文字自体を
+    エスケープ処理する。Oracle では全角ワイルドカード（``％``, ``＿``）も対象。
+
+    Args:
+        value: エスケープ対象の文字列
+        dialect: RDBMS 方言
+        escape_char: エスケープ文字（省略時は dialect.like_escape_char を使用）
+
+    Returns:
+        エスケープ処理された文字列
+
+    Examples:
+        >>> from sqlym import Dialect, escape_like
+        >>> escape_like("10%off", Dialect.SQLITE)
+        '10#%off'
+        >>> escape_like("file_name", Dialect.ORACLE)
+        'file#_name'
+        >>> escape_like("100％達成", Dialect.ORACLE)
+        '100#％達成'
+
+    Note:
+        この関数でエスケープした値を LIKE 句で使用する場合、
+        SQL に ``ESCAPE '#'`` 句を追加する必要がある::
+
+            SELECT * FROM t WHERE name LIKE ? ESCAPE '#'
+
+    """
+    esc = escape_char if escape_char is not None else dialect.like_escape_char
+    escape_chars = dialect.like_escape_chars
+    result: list[str] = []
+    for ch in value:
+        if ch in escape_chars:
+            result.append(esc)
+        result.append(ch)
+    return "".join(result)

sqlym/exceptions.py

@@ -0,0 +1,17 @@
+"""sqly例外クラス."""
+
+
+class SqlyError(Exception):
+    """sqlyの基底例外."""
+
+
+class SqlParseError(SqlyError):
+    """SQLパースエラー."""
+
+
+class MappingError(SqlyError):
+    """マッピングエラー."""
+
+
+class SqlFileNotFoundError(SqlyError):
+    """SQLファイルが見つからない."""

sqlym/loader.py

@@ -0,0 +1,72 @@
+"""SqlLoader: SQL ファイルの読み込み."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from sqlym.exceptions import SqlFileNotFoundError
+
+if TYPE_CHECKING:
+    from sqlym.dialect import Dialect
+
+
+class SqlLoader:
+    """SQL ファイルの読み込み."""
+
+    def __init__(self, base_path: str | Path = "sql") -> None:
+        self.base_path = Path(base_path)
+
+    def load(self, path: str, *, dialect: Dialect | None = None) -> str:
+        """SQL ファイルを読み込む.
+
+        dialect が指定された場合、まず RDBMS 固有ファイル（例: ``find.oracle.sql``）を
+        探し、存在しなければ汎用ファイル（例: ``find.sql``）にフォールバックする。
+
+        Args:
+            path: base_path からの相対パス
+            dialect: RDBMS 方言。指定時は方言固有ファイルを優先
+
+        Returns:
+            SQL テンプレート文字列
+
+        Raises:
+            SqlFileNotFoundError: ファイルが存在しない場合
+
+        Examples:
+            >>> loader = SqlLoader("sql")
+            >>> # sql/find.oracle.sql があれば優先、なければ sql/find.sql
+            >>> sql = loader.load("find.sql", dialect=Dialect.ORACLE)
+
+        """
+        base_path = self.base_path.resolve()
+
+        if dialect is not None:
+            dialect_path = self._dialect_specific_path(path, dialect._dialect_id)
+            dialect_file_path = (base_path / dialect_path).resolve()
+            if self._is_valid_path(base_path, dialect_file_path):
+                return dialect_file_path.read_text(encoding="utf-8")
+
+        file_path = (base_path / path).resolve()
+        if not self._is_valid_path(base_path, file_path):
+            msg = f"SQL file not found: {file_path}"
+            raise SqlFileNotFoundError(msg)
+        return file_path.read_text(encoding="utf-8")
+
+    @staticmethod
+    def _is_valid_path(base_path: Path, file_path: Path) -> bool:
+        """ファイルパスが有効か（base_path 配下に存在するか）を判定する."""
+        if file_path != base_path and base_path not in file_path.parents:
+            return False
+        return file_path.is_file()
+
+    @staticmethod
+    def _dialect_specific_path(path: str, dialect_id: str) -> str:
+        """Dialect 固有のファイルパスを生成する.
+
+        ``find.sql`` → ``find.oracle.sql`` のように変換する。
+        """
+        if "." in path:
+            base, ext = path.rsplit(".", 1)
+            return f"{base}.{dialect_id}.{ext}"
+        return f"{path}.{dialect_id}"

sqlym/mapper/__init__.py

@@ -0,0 +1,7 @@
+"""sqly マッパーパッケージ."""
+
+from sqlym.mapper.factory import create_mapper
+from sqlym.mapper.manual import ManualMapper
+from sqlym.mapper.protocol import RowMapper
+
+__all__ = ["ManualMapper", "RowMapper", "create_mapper"]

sqlym/mapper/column.py

@@ -0,0 +1,40 @@
+"""Column アノテーションと @entity デコレータ."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class Column:
+    """カラム名を指定するアノテーション."""
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+    def __repr__(self) -> str:
+        return f"Column({self.name!r})"
+
+
+def entity(
+    cls: type | None = None,
+    *,
+    column_map: dict[str, str] | None = None,
+    naming: str = "as_is",
+) -> Any:
+    """エンティティデコレータ.
+
+    Args:
+        cls: デコレート対象クラス
+        column_map: フィールド名→カラム名のマッピング
+        naming: 命名規則 ("as_is", "snake_to_camel", "camel_to_snake")
+
+    """
+
+    def decorator(cls: type) -> type:
+        cls.__column_map__ = column_map or {}  # type: ignore[attr-defined]
+        cls.__column_naming__ = naming  # type: ignore[attr-defined]
+        return cls
+
+    if cls is not None:
+        return decorator(cls)
+    return decorator

sqlym/mapper/dataclass.py

@@ -0,0 +1,97 @@
+"""DataclassMapper: dataclass 用の自動マッパー."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import fields, is_dataclass
+from typing import Annotated, Any, ClassVar, get_args, get_origin, get_type_hints
+
+from sqlym.mapper.column import Column
+
+
+class DataclassMapper:
+    """Dataclass 用の自動マッパー."""
+
+    _mapping_cache: ClassVar[dict[type, dict[str, str]]] = {}
+
+    def __init__(self, entity_cls: type) -> None:
+        if not is_dataclass(entity_cls):
+            msg = f"{entity_cls} is not a dataclass"
+            raise TypeError(msg)
+        self.entity_cls = entity_cls
+        self._mapping = self._get_mapping(entity_cls)
+
+    @classmethod
+    def _get_mapping(cls, entity_cls: type) -> dict[str, str]:
+        """フィールド名→カラム名のマッピングを取得（キャッシュ付き）."""
+        if entity_cls not in cls._mapping_cache:
+            cls._mapping_cache[entity_cls] = cls._build_mapping(entity_cls)
+        return cls._mapping_cache[entity_cls]
+
+    @classmethod
+    def _build_mapping(cls, entity_cls: type) -> dict[str, str]:
+        """フィールド名→カラム名のマッピングを構築."""
+        hints = get_type_hints(entity_cls, include_extras=True)
+        column_map: dict[str, str] = getattr(entity_cls, "__column_map__", {})
+        naming: str = getattr(entity_cls, "__column_naming__", "as_is")
+
+        mapping: dict[str, str] = {}
+
+        for f in fields(entity_cls):
+            field_name = f.name
+
+            # 1. Annotated[..., Column("X")] をチェック
+            type_hint = hints.get(field_name)
+            if type_hint and get_origin(type_hint) is Annotated:
+                for arg in get_args(type_hint)[1:]:
+                    if isinstance(arg, Column):
+                        mapping[field_name] = arg.name
+                        break
+
+            if field_name in mapping:
+                continue
+
+            # 2. column_map をチェック
+            if field_name in column_map:
+                mapping[field_name] = column_map[field_name]
+                continue
+
+            # 3. naming ルール適用
+            if naming == "snake_to_camel":
+                mapping[field_name] = cls._to_camel(field_name)
+            elif naming == "camel_to_snake":
+                mapping[field_name] = cls._to_snake(field_name)
+            else:
+                mapping[field_name] = field_name
+
+        return mapping
+
+    @staticmethod
+    def _to_camel(name: str) -> str:
+        """Snake_case → camelCase."""
+        components = name.split("_")
+        return components[0] + "".join(x.title() for x in components[1:])
+
+    @staticmethod
+    def _to_snake(name: str) -> str:
+        """CamelCase → snake_case."""
+        return re.sub(r"(?<!^)(?=[A-Z])", "_", name).lower()
+
+    def map_row(self, row: dict[str, Any]) -> Any:
+        """1行をエンティティに変換."""
+        row_lower = {k.lower(): v for k, v in row.items()}
+        kwargs: dict[str, Any] = {}
+        for field_name, col_name in self._mapping.items():
+            if col_name in row:
+                kwargs[field_name] = row[col_name]
+            elif col_name.lower() in row_lower:
+                kwargs[field_name] = row_lower[col_name.lower()]
+            elif field_name in row:
+                kwargs[field_name] = row[field_name]
+            elif field_name.lower() in row_lower:
+                kwargs[field_name] = row_lower[field_name.lower()]
+        return self.entity_cls(**kwargs)
+
+    def map_rows(self, rows: list[dict[str, Any]]) -> list[Any]:
+        """複数行をエンティティのリストに変換."""
+        return [self.map_row(row) for row in rows]

sqlym/mapper/factory.py

@@ -0,0 +1,50 @@
+"""create_mapper ファクトリ関数."""
+
+from __future__ import annotations
+
+from dataclasses import is_dataclass
+from typing import Any
+
+from sqlym.mapper.manual import ManualMapper
+from sqlym.mapper.protocol import RowMapper
+
+
+def create_mapper(
+    entity_cls: type,
+    *,
+    mapper: Any = None,
+) -> Any:
+    """マッパーを生成する.
+
+    Args:
+        entity_cls: エンティティクラス
+        mapper: RowMapper インスタンス、Callable、または None（自動判定）
+
+    Returns:
+        RowMapper プロトコルを満たすマッパー
+
+    Raises:
+        TypeError: マッパーを自動判定できない場合
+
+    """
+    if mapper is not None:
+        if isinstance(mapper, RowMapper):
+            return mapper
+        if callable(mapper):
+            return ManualMapper(mapper)
+
+    if is_dataclass(entity_cls):
+        from sqlym.mapper.dataclass import DataclassMapper
+
+        return DataclassMapper(entity_cls)
+
+    if hasattr(entity_cls, "model_validate"):
+        from sqlym.mapper.pydantic import PydanticMapper
+
+        return PydanticMapper(entity_cls)
+
+    msg = (
+        f"Cannot create mapper for {entity_cls}. "
+        f"Use dataclass, Pydantic, or provide a custom mapper."
+    )
+    raise TypeError(msg)

sqlym/mapper/manual.py

@@ -0,0 +1,21 @@
+"""ManualMapper: ユーザー提供の関数をラップするマッパー."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+
+class ManualMapper:
+    """ユーザー提供の関数をラップするマッパー."""
+
+    def __init__(self, func: Callable[[dict[str, Any]], Any]) -> None:
+        self._func = func
+
+    def map_row(self, row: dict[str, Any]) -> Any:
+        """1行をエンティティに変換."""
+        return self._func(row)
+
+    def map_rows(self, rows: list[dict[str, Any]]) -> list[Any]:
+        """複数行をエンティティのリストに変換."""
+        return [self._func(row) for row in rows]

sqlym/mapper/protocol.py

@@ -0,0 +1,20 @@
+"""RowMapper プロトコル定義."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, TypeVar, runtime_checkable
+
+T = TypeVar("T")
+
+
+@runtime_checkable
+class RowMapper(Protocol[T]):
+    """マッパーのインターフェース."""
+
+    def map_row(self, row: dict[str, Any]) -> T:
+        """1行をエンティティに変換."""
+        ...
+
+    def map_rows(self, rows: list[dict[str, Any]]) -> list[T]:
+        """複数行をエンティティのリストに変換."""
+        ...

sqlym/mapper/pydantic.py

@@ -0,0 +1,23 @@
+"""PydanticMapper: Pydantic BaseModel 用のマッパー."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class PydanticMapper:
+    """Pydantic BaseModel 用のマッパー."""
+
+    def __init__(self, entity_cls: type) -> None:
+        if not hasattr(entity_cls, "model_validate"):
+            msg = f"{entity_cls} is not a Pydantic BaseModel"
+            raise TypeError(msg)
+        self.entity_cls = entity_cls
+
+    def map_row(self, row: dict[str, Any]) -> Any:
+        """1行をエンティティに変換."""
+        return self.entity_cls.model_validate(row)
+
+    def map_rows(self, rows: list[dict[str, Any]]) -> list[Any]:
+        """複数行をエンティティのリストに変換."""
+        return [self.map_row(row) for row in rows]

sqlym/parser/line_unit.py

@@ -0,0 +1,36 @@
+"""行単位処理ユニット（Clione-SQL Rule 1）."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class LineUnit:
+    """1行を表すユニット（Clione-SQL Rule 1）."""
+
+    line_number: int
+    """元のSQL内での行番号."""
+
+    original: str
+    """元の行文字列."""
+
+    indent: int
+    """インデント深さ."""
+
+    content: str
+    """インデント除去後の内容."""
+
+    children: list[LineUnit] = field(default_factory=list)
+    """子LineUnitのリスト."""
+
+    parent: LineUnit | None = None
+    """親LineUnit."""
+
+    removed: bool = False
+    """削除フラグ."""
+
+    @property
+    def is_empty(self) -> bool:
+        """空行かどうか."""
+        return self.indent < 0 or not self.content.strip()