nanasqlite 1.3.3.dev4__py3-none-any.whl

nanasqlite/exceptions.py

@@ -0,0 +1,117 @@
+"""
+NanaSQLite Exception Classes
+
+カスタム例外クラスを定義し、エラーハンドリングを統一する。
+"""
+
+
+class NanaSQLiteError(Exception):
+    """
+    NanaSQLiteの基底例外クラス
+
+    すべてのNanaSQLite固有の例外はこのクラスを継承する。
+    """
+
+    pass
+
+
+class NanaSQLiteValidationError(NanaSQLiteError):
+    """
+    バリデーションエラー
+
+    不正な入力値やパラメータに対して発生する。
+
+    Examples:
+        - 不正なテーブル名やカラム名
+        - 不正なSQL識別子
+        - パラメータの型エラー
+    """
+
+    pass
+
+
+class NanaSQLiteDatabaseError(NanaSQLiteError):
+    """
+    データベース操作エラー
+
+    SQLite/APSWのデータベース操作で発生するエラーをラップ。
+
+    Examples:
+        - データベースロック
+        - ディスク容量不足
+        - ファイル権限エラー
+        - SQL構文エラー
+    """
+
+    def __init__(self, message: str, original_error: Exception = None):
+        super().__init__(message)
+        self.original_error = original_error
+
+
+class NanaSQLiteTransactionError(NanaSQLiteError):
+    """
+    トランザクション関連エラー
+
+    トランザクションの開始、コミット、ロールバックで発生するエラー。
+
+    Examples:
+        - ネストしたトランザクションの試み
+        - トランザクション外でのコミット/ロールバック
+        - トランザクション中の接続クローズ
+    """
+
+    pass
+
+
+class NanaSQLiteConnectionError(NanaSQLiteError):
+    """
+    接続エラー
+
+    データベース接続の作成や管理で発生するエラー。
+
+    Examples:
+        - 閉じられた接続の使用
+        - 接続の初期化失敗
+        - 孤立した子インスタンスの使用
+    """
+
+    pass
+
+
+class NanaSQLiteClosedError(NanaSQLiteConnectionError):
+    """
+    Closed instance error / クローズ済みエラー
+
+    Occurs when operating on a closed instance, or on a child instance whose parent has been closed.
+    閉じられたインスタンスや、親が閉じられた子インスタンスを操作しようとした時に発生。
+    """
+
+    pass
+
+
+class NanaSQLiteLockError(NanaSQLiteError):
+    """
+    ロック取得エラー
+
+    データベースロックの取得に失敗した場合に発生。
+
+    Examples:
+        - ロック取得タイムアウト
+        - デッドロック検出
+    """
+
+    pass
+
+
+class NanaSQLiteCacheError(NanaSQLiteError):
+    """
+    キャッシュ関連エラー
+
+    キャッシュの操作で発生するエラー。
+
+    Examples:
+        - キャッシュサイズ超過
+        - キャッシュの不整合
+    """
+
+    pass

nanasqlite/sql_utils.py

@@ -0,0 +1,174 @@
+"""
+SQL utility functions for NanaSQLite.
+
+This module provides utility functions for SQL string processing,
+particularly for sanitizing SQL expressions to prevent injection attacks
+and handle edge cases in SQL parsing.
+"""
+
+
+def sanitize_sql_for_function_scan(sql: str) -> str:
+    """
+    Return a version of the SQL string where string literals and comments
+    are replaced with spaces so that function-like patterns inside them
+    are ignored by the validation regex.
+
+    This function implements a state machine that processes SQL character by character,
+    tracking whether we're inside:
+    - Single-quoted string literals (with '' escaping)
+    - Double-quoted identifiers/strings (with "" escaping)
+    - Line comments (-- to newline)
+    - Block comments (/* to */)
+
+    Args:
+        sql: The SQL string to sanitize
+
+    Returns:
+        A sanitized version of the SQL string where all content inside
+        string literals and comments is replaced with spaces, while
+        preserving the original length and newline positions.
+
+    Example:
+        >>> sanitize_sql_for_function_scan("SELECT 'COUNT(*)' FROM table")
+        'SELECT           FROM table'
+        >>> sanitize_sql_for_function_scan("SELECT COUNT(*) -- comment")
+        'SELECT COUNT(*)            '
+
+    Note:
+        This function handles SQL-specific escaping rules:
+        - Single quotes are escaped as ''
+        - Double quotes are escaped as ""
+        - Line comments start with -- and end at newline
+        - Block comments are /* ... */
+    """
+    if not sql:
+        return sql
+
+    result = []
+    i = 0
+    length = len(sql)
+    in_single = False
+    in_double = False
+    in_line_comment = False
+    in_block_comment = False
+
+    while i < length:
+        ch = sql[i]
+
+        # Inside line comment
+        if in_line_comment:
+            if ch == "\n":
+                in_line_comment = False
+                result.append(ch)
+            else:
+                result.append(" ")
+            i += 1
+            continue
+
+        # Inside block comment
+        if in_block_comment:
+            if ch == "*" and i + 1 < length and sql[i + 1] == "/":
+                in_block_comment = False
+                result.append("  ")  # Replace */
+                i += 2
+            else:
+                result.append(" ")
+                i += 1
+            continue
+
+        # Inside single-quoted string literal
+        if in_single:
+            if ch == "'" and i + 1 < length and sql[i + 1] == "'":
+                # Escaped single quote (SQL standard: '')
+                result.append("  ")
+                i += 2
+            elif ch == "'":
+                in_single = False
+                result.append(" ")
+                i += 1
+            else:
+                result.append(" ")
+                i += 1
+            continue
+
+        # Inside double-quoted identifier/string
+        if in_double:
+            if ch == '"' and i + 1 < length and sql[i + 1] == '"':
+                # Escaped double quote (SQL standard: "")
+                result.append("  ")
+                i += 2
+            elif ch == '"':
+                in_double = False
+                result.append(" ")
+                i += 1
+            else:
+                result.append(" ")
+                i += 1
+            continue
+
+        # Outside literals/comments - check for delimiters
+
+        # Line comment start
+        if ch == "-" and i + 1 < length and sql[i + 1] == "-":
+            in_line_comment = True
+            result.append("  ")
+            i += 2
+            continue
+
+        # Block comment start
+        if ch == "/" and i + 1 < length and sql[i + 1] == "*":
+            in_block_comment = True
+            result.append("  ")
+            i += 2
+            continue
+
+        # Single-quoted string start
+        if ch == "'":
+            in_single = True
+            result.append(" ")
+            i += 1
+            continue
+
+        # Double-quoted identifier start
+        if ch == '"':
+            in_double = True
+            result.append(" ")
+            i += 1
+            continue
+
+        # Normal code - preserve as-is
+        result.append(ch)
+        i += 1
+
+    return "".join(result)
+
+
+def fast_validate_sql_chars(expr: str) -> bool:
+    """
+    Validate that a SQL expression contains only safe characters.
+    This is a ReDoS-resistant alternative to complex regex for basic validation.
+
+    Safe characters include:
+    - Alphanumeric characters
+    - Underscore (_)
+    - Space ( )
+    - Comma (,) -- for ORDER BY/GROUP BY
+    - Dot (.) -- for table.column
+    - Parentheses (()) -- for function calls
+    - Operators: =, <, >, !, +, -, *, /
+    - Quotes: ', " (handled carefully by other layers)
+
+    Args:
+        expr: The SQL expression to validate
+
+    Returns:
+        True if all characters are within the safe set, False otherwise.
+    """
+    if not expr:
+        return True
+
+    # Safe character set: Alphanumeric, underscores, spaces, and common SQL punctuation/operators
+    # Including ?, :, @, $ for parameter placeholders
+    safe_chars = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_ ,.()'=<>!+-*/\"|?:@$")
+
+    return all(c in safe_chars for c in expr)

nanasqlite/utils.py

@@ -0,0 +1,202 @@
+"""
+Utility module for NanaSQLite: Provides ExpiringDict and other helper classes.
+(NanaSQLite用ユーティリティモジュール: 有効期限付き辞書やその他の補助クラスを提供)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import collections.abc
+import logging
+import threading
+import time
+from collections.abc import Iterator
+from enum import Enum
+from typing import Any, Callable
+
+logger = logging.getLogger(__name__)
+
+
+class ExpirationMode(str, Enum):
+    """
+    Modes for detecting and handling expired items.
+    (有効期限切れの検知と処理モード)
+    """
+
+    LAZY = "lazy"  # Check on access only (アクセ時にのみチェック)
+    SCHEDULER = "scheduler"  # Single background worker (単一のバックグラウンドワーカー)
+    TIMER = "timer"  # Individual timers for each key (キーごとの個別タイマー)
+
+
+class ExpiringDict(collections.abc.MutableMapping):
+    """
+    A dictionary-like object where keys expire after a set time.
+    Supports multiple expiration modes for different scales and precision requirements.
+    (キーが一定時間後に失効する辞書型オブジェクト。規模や精度に応じて複数の失効モードをサポート)
+    """
+
+    def __init__(
+        self,
+        expiration_time: float,
+        mode: ExpirationMode = ExpirationMode.SCHEDULER,
+        on_expire: Callable[[str, Any], None] | None = None,
+    ):
+        """
+        Args:
+            expiration_time: Time in seconds before a key expires. (失効までの時間（秒）)
+            mode: Expiration detection mode. (失効検知モード)
+            on_expire: Callback function called when an item expires. (失効時に呼ばれるコールバック)
+        """
+        self._data: dict[str, Any] = {}
+        self._exptimes: dict[str, float] = {}  # key -> expiry (Unix timestamp)
+        self._expiration_time = expiration_time
+        self._mode = mode
+        self._on_expire = on_expire
+
+        # Mode specific structures
+        self._timers: dict[str, threading.Timer] = {}
+        self._async_tasks: dict[str, asyncio.Task] = {}
+        self._scheduler_thread: threading.Thread | None = None
+        self._scheduler_running = False
+        self._lock = threading.RLock()
+
+        if self._mode == ExpirationMode.SCHEDULER:
+            self._start_scheduler()
+
+    def _start_scheduler(self) -> None:
+        """Start the background scheduler thread if not already running."""
+        with self._lock:
+            if self._scheduler_running:
+                return
+            self._scheduler_running = True
+            self._scheduler_thread = threading.Thread(target=self._scheduler_loop, daemon=True)
+            self._scheduler_thread.start()
+
+    def _scheduler_loop(self) -> None:
+        """Single background worker loop to evict expired items."""
+        while self._scheduler_running:
+            now = time.time()
+            expired_keys = []
+
+            with self._lock:
+                # Since items are added in order, the first item is the oldest (likely to expire first)
+                if not self._exptimes:
+                    sleep_time = 1.0
+                else:
+                    first_key = next(iter(self._exptimes))
+                    expiry = self._exptimes[first_key]
+                    if expiry <= now:
+                        expired_keys.append(first_key)
+                        sleep_time = 0  # Process next immediately
+                    else:
+                        sleep_time = min(expiry - now, 1.0)
+
+            # Do deletion outside of the common lock if possible, but for simplicity here we keep it safe
+            for key in expired_keys:
+                self._evict(key)
+
+            if sleep_time > 0:
+                time.sleep(sleep_time)
+
+    def _evict(self, key: str) -> None:
+        """Evict an item and trigger callback."""
+        with self._lock:
+            if key in self._data:
+                value = self._data.pop(key)
+                self._exptimes.pop(key, None)
+                if self._on_expire:
+                    try:
+                        self._on_expire(key, value)
+                    except Exception as e:
+                        logger.error(f"Error in ExpiringDict on_expire callback for key '{key}': {e}")
+                logger.debug(f"Key '{key}' expired and removed.")
+
+    def _check_expiry(self, key: str) -> bool:
+        """Check if a key is expired and remove it if it is (Lazy eviction)."""
+        now = time.time()
+        with self._lock:
+            if key in self._exptimes and self._exptimes[key] <= now:
+                self._evict(key)
+                return True
+        return False
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        expiry = time.time() + self._expiration_time
+        with self._lock:
+            # If item already exists, remove it first to maintain insertion order (for FIFO/Scheduler)
+            if key in self._data:
+                self._cancel_timer(key)
+                del self._data[key]
+                del self._exptimes[key]
+
+            self._data[key] = value
+            self._exptimes[key] = expiry
+
+            if self._mode == ExpirationMode.TIMER:
+                self._set_timer(key)
+
+    def _set_timer(self, key: str) -> None:
+        """Set individual timer (TIMER mode)."""
+        # Try to use current event loop if available, else use threading.Timer
+        try:
+            loop = asyncio.get_running_loop()
+            task = loop.call_later(self._expiration_time, self._evict, key)
+            self._async_tasks[key] = task  # type: ignore
+        except RuntimeError:
+            timer = threading.Timer(self._expiration_time, self._evict, args=(key,))
+            timer.daemon = True
+            timer.start()
+            self._timers[key] = timer
+
+    def _cancel_timer(self, key: str) -> None:
+        """Cancel individual timer (TIMER mode)."""
+        if key in self._timers:
+            self._timers[key].cancel()
+            del self._timers[key]
+        if key in self._async_tasks:
+            self._async_tasks[key].cancel()
+            del self._async_tasks[key]
+
+    def __getitem__(self, key: str) -> Any:
+        self._check_expiry(key)
+        with self._lock:
+            return self._data[key]
+
+    def __delitem__(self, key: str) -> None:
+        with self._lock:
+            self._cancel_timer(key)
+            if key in self._data:
+                del self._data[key]
+                del self._exptimes[key]
+
+    def __iter__(self) -> Iterator[str]:
+        # Clean up expired items during iteration to stay accurate
+        keys = list(self._data.keys())
+        for key in keys:
+            if not self._check_expiry(key):
+                yield key
+
+    def __len__(self) -> int:
+        # Note: could be inaccurate if items expired but not yet evicted
+        # But for performance we return current size.
+        return len(self._data)
+
+    def __contains__(self, key: object) -> bool:
+        if not isinstance(key, str):
+            return False
+        return not self._check_expiry(key) and key in self._data
+
+    def set_on_expire_callback(self, callback: Callable[[str, Any], None]) -> None:
+        """Update the expiration callback."""
+        self._on_expire = callback
+
+    def clear(self) -> None:
+        with self._lock:
+            for key in list(self._timers.keys()):
+                self._cancel_timer(key)
+            self._data.clear()
+            self._exptimes.clear()
+            self._scheduler_running = False
+
+    def __del__(self):
+        self._scheduler_running = False