sqlobjects 1.6.0__tar.gz → 1.8.0__tar.gz

{sqlobjects-1.6.0 → sqlobjects-1.8.0}/CHANGELOG.md

@@ -1,3 +1,30 @@
+## 1.8.0 (2026-03-26)
+
+### Feat
+
+- **logging**: export SQLCallerFilter and get_caller_frame in public API
+- **logging**: emit SQL log records in QueryExecutor
+- **logging**: add SQLCallerFilter
+- **logging**: add get_caller_frame() helper
+
+### Fix
+
+- **logging**: eliminate isEnabledFor race and fix test name
+- **logging**: restore logger level in test_no_log_when_logger_disabled
+- **logging**: guard timing code with isEnabledFor check
+- **logging**: simplify SQLCallerFilter extra_skip_packages handling
+- **logging**: fix frame-skip edge cases and improve code quality
+
+## 1.7.0 (2026-03-26)
+
+### Feat
+
+- **metadata**: add foreignkey() constraint builder
+
+### Fix
+
+- **raw**: allow SA expressions as arguments in raw() methods
+
 ## 1.6.0 (2026-03-18)
 
 ### Feat

{sqlobjects-1.6.0/sqlobjects.egg-info → sqlobjects-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlobjects
-Version: 1.6.0
+Version: 1.8.0
 Summary: Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>

{sqlobjects-1.6.0 → sqlobjects-1.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlobjects"
-version = "1.6.0"
+version = "1.8.0"
 description = "Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading"
 readme = "README.md"
 license = "MIT"

{sqlobjects-1.6.0 → sqlobjects-1.8.0}/sqlobjects/__init__.py

@@ -16,6 +16,7 @@ from .objects import (
     TransactionMode,
 )
 from .queryset import Q, QuerySet
+from .sql_logging import SQLCallerFilter, get_caller_frame
 
 
 __version__ = "0.3.0"
@@ -41,4 +42,7 @@ __all__ = [
     "TransactionMode",
     "ErrorHandling",
     "ConflictResolution",
+    # SQL logging
+    "SQLCallerFilter",
+    "get_caller_frame",
 ]

{sqlobjects-1.6.0 → sqlobjects-1.8.0}/sqlobjects/expressions/function.py

@@ -183,7 +183,9 @@ class FunctionExpression:
 
         Args:
             sql: Raw SQL function name or expression
-            *args: Arguments to pass to the function. Use ... (Ellipsis) as placeholder for current expression
+            *args: Arguments to pass to the function. Use ... (Ellipsis) as placeholder for current expression.
+                   SQLAlchemy expressions (ColumnElement, FunctionExpression) are passed through as-is;
+                   plain Python values are wrapped with literal().
             **kwargs: Additional keyword arguments passed to the function
 
         Returns:
@@ -198,12 +200,17 @@ class FunctionExpression:
             User.age.avg().raw('CUSTOM_FUNCTION', 'param1', ..., 'param2')
             # Generates: CUSTOM_FUNCTION('param1', avg(age), 'param2')
 
-            # Only current expression
-            User.age.raw('CUSTOM_FUNCTION')
-            # Generates: CUSTOM_FUNCTION(age)
+            # Passing another SA expression as argument
+            User.name.raw('CUSTOM_FUNCTION', other_func_expr)
+            # Generates: CUSTOM_FUNCTION(name, other_func_expr)
         """
         from sqlalchemy import literal
 
+        def _to_sql_arg(arg):
+            if isinstance(arg, (ColumnElement, FunctionExpression)):
+                return arg
+            return literal(arg)
+
         # Check if ... (Ellipsis) is used as placeholder
         if ... in args:
             # Replace ... with current expression
@@ -212,12 +219,10 @@ class FunctionExpression:
                 if arg is ...:
                     all_args.append(self.expression)
                 else:
-                    all_args.append(literal(arg))
+                    all_args.append(_to_sql_arg(arg))
         else:
             # Default behavior: current expression as first argument
-            all_args = [self.expression]
-            for arg in args:
-                all_args.append(literal(arg))
+            all_args = [self.expression] + [_to_sql_arg(arg) for arg in args]
 
         # Use func to create the raw function call
         raw_func = getattr(_sa_func, sql)
@@ -425,6 +430,38 @@ class _FuncWrapper:
 
         def nth_value(self, col: Any, n: int) -> NthValueFunction: ...
 
+        def raw(self, sql: str, *args) -> FunctionExpression: ...
+
+    def raw(self, sql: str, *args) -> "FunctionExpression":
+        """Call an arbitrary SQL function by name.
+
+        Unlike col.raw() / FunctionExpression.raw() which insert the current
+        expression as the first argument, this standalone form takes the function
+        name and all arguments explicitly.
+
+        Args:
+            sql: SQL function name (e.g. "ts_rank", "to_tsvector")
+            *args: Arguments passed to the function. SQLAlchemy expressions
+                   (ColumnElement, FunctionExpression) are used as-is; plain
+                   Python values are wrapped with literal().
+
+        Examples:
+            func.raw("ts_rank", DocumentIndexes.content_vector, query_vec)
+            # → ts_rank(document_indexes.content_vector, <query_vec>)
+
+            func.raw("to_tsvector", "'simple'::regconfig", "some text")
+            # → to_tsvector('simple'::regconfig, 'some text')
+        """
+        from sqlalchemy import literal
+
+        def _to_sql_arg(arg):
+            if isinstance(arg, (ColumnElement, FunctionExpression)):
+                return arg
+            return literal(arg)
+
+        sa_func = getattr(_sa_func, sql)
+        return FunctionExpression(sa_func(*[_to_sql_arg(a) for a in args]))
+
     def __getattr__(self, name: str) -> Any:
         """Delegate to SQLAlchemy func for all other functions."""
         return getattr(_sa_func, name)

{sqlobjects-1.6.0 → sqlobjects-1.8.0}/sqlobjects/fields/types/comparators.py

@@ -50,6 +50,12 @@ class ComparatorMixin:
 
     def raw(self, sql: str, *args, **kwargs) -> FunctionExpression:
         from sqlalchemy import literal
+        from sqlalchemy.sql.elements import ColumnElement
+
+        def _to_sql_arg(arg):
+            if isinstance(arg, (ColumnElement, FunctionExpression)):
+                return arg
+            return literal(arg)
 
         if ... in args:
             all_args = []
@@ -57,9 +63,9 @@ class ComparatorMixin:
                 if arg is ...:
                     all_args.append(self)
                 else:
-                    all_args.append(literal(arg))
+                    all_args.append(_to_sql_arg(arg))
         else:
-            all_args = [self] + [literal(arg) for arg in args]
+            all_args = [self] + [_to_sql_arg(arg) for arg in args]
         raw_func = getattr(func, sql)
         return FunctionExpression(raw_func(*all_args, **kwargs))
 

{sqlobjects-1.6.0 → sqlobjects-1.8.0}/sqlobjects/queries/executor.py

@@ -1,5 +1,7 @@
 import asyncio
 import gc
+import logging
+import time
 from collections.abc import AsyncGenerator
 from typing import Any, TypeVar, overload
 
@@ -13,6 +15,9 @@ from sqlalchemy import (
 )
 
 
+_sql_logger = logging.getLogger("sqlobjects.sql")
+
+
 _T = TypeVar("_T")
 
 
@@ -230,8 +235,33 @@ class QueryExecutor:
             else:  # exists
                 return False
 
+        # Compile SQL for logging only when the logger is active (avoids overhead)
+        _logging_active = _sql_logger.isEnabledFor(logging.DEBUG)
+        sql_str = ""
+        params: dict = {}
+        t0 = 0.0
+        if _logging_active:
+            try:
+                compiled = query.compile(
+                    dialect=session.bind.dialect,
+                    compile_kwargs={"literal_binds": False},
+                )
+                sql_str = str(compiled)
+                params = dict(compiled.params) if compiled.params else {}
+            except Exception:
+                sql_str = str(query)
+                params = {}
+            t0 = time.perf_counter()
+
         result = await session.execute(query)
 
+        if _logging_active:
+            duration_ms = (time.perf_counter() - t0) * 1000
+            _sql_logger.debug(
+                sql_str,
+                extra={"sql": sql_str, "params": params, "duration_ms": duration_ms},
+            )
+
         if query_type == "all":
             rows = result.fetchall()
             if model_class:

sqlobjects-1.8.0/sqlobjects/sql_logging.py

@@ -0,0 +1,156 @@
+"""SQL logging utilities for sqlobjects.
+
+Provides get_caller_frame() to surface user-code caller information in SQL log
+records, compatible with standard logging and loguru.
+
+Filter strategy:
+- Skips frames from site-packages (covers pip-installed sqlobjects/sqlalchemy)
+- Skips frames whose module name starts with "sqlobjects." or "sqlalchemy."
+  (covers editable installs via `pip install -e .`)
+- Skips frames from extra_skip_packages specified by the caller
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+import os
+
+
+__all__ = ["get_caller_frame", "SQLCallerFilter"]
+
+# Exact module names that are always considered internal
+_INTERNAL_MODULES = {"sqlobjects", "sqlalchemy"}
+
+# Module name prefixes that are always considered internal
+_INTERNAL_PREFIXES = ("sqlobjects.", "sqlalchemy.")
+
+# Absolute path of this file, used to skip itself reliably
+_THIS_FILE = os.path.abspath(__file__)
+
+
+def get_caller_frame(
+    extra_skip_packages: list[str] | None = None,
+    max_frames: int = 1,
+) -> str | list[str]:
+    """Inspect the call stack and return the first user-code frame(s).
+
+    Skips frames from:
+    - site-packages (pip install)
+    - sqlobjects.* and sqlalchemy.* modules (editable install)
+    - extra_skip_packages prefixes provided by the caller
+
+    Args:
+        extra_skip_packages: Additional module name prefixes to skip
+            (e.g. ["myapp.middleware"]). Matched against frame's __name__.
+        max_frames: How many user-code frames to return.
+            1 returns a str; >1 returns a list[str].
+
+    Returns:
+        Frame string "path/to/file.py:lineno in funcname", or a list of such
+        strings when max_frames > 1.
+    """
+    skip_prefixes = _INTERNAL_PREFIXES
+    if extra_skip_packages:
+        skip_prefixes = skip_prefixes + tuple(extra_skip_packages)
+
+    frames: list[str] = []
+
+    for frame_info in inspect.stack():
+        filepath = frame_info.filename
+        module = frame_info.frame.f_globals.get("__name__", "")
+
+        # Skip site-packages frames (pip-installed third-party libs)
+        if "site-packages" in filepath:
+            continue
+
+        # Skip sqlobjects/sqlalchemy frames (editable install)
+        if module in _INTERNAL_MODULES or module.startswith(skip_prefixes):
+            continue
+
+        # Skip this helper file itself
+        if os.path.abspath(filepath) == _THIS_FILE:
+            continue
+
+        rel_path = _relative_path(filepath)
+        frames.append(f"{rel_path}:{frame_info.lineno} in {frame_info.function}")
+
+        if len(frames) >= max_frames:
+            break
+
+    if not frames:
+        return "<unknown>" if max_frames == 1 else ["<unknown>"]
+
+    return frames[0] if max_frames == 1 else frames
+
+
+def _relative_path(filepath: str) -> str:
+    """Return path relative to cwd, or absolute if outside cwd."""
+    try:
+        return os.path.relpath(filepath)
+    except ValueError:
+        return filepath
+
+
+class SQLCallerFilter(logging.Filter):
+    """logging.Filter that rewrites LogRecord caller fields to user-code location.
+
+    Inspects the call stack at filter time, skips library frames (site-packages
+    and sqlobjects.*/sqlalchemy.* modules for editable installs), and overwrites
+    record.filename / record.funcName / record.lineno / record.pathname so that
+    any handler (including loguru interception) displays the real user-code
+    call site.
+
+    Also exposes record.caller (str or list[str]) for use in custom Formatters.
+
+    Args:
+        max_frames: Number of user-code frames to capture (default 1).
+            When 1, record.caller is a str and record location fields point
+            to that single frame.
+            When > 1, record.caller is a list[str] and record location fields
+            are set from the first (most recent) frame.
+        extra_skip_packages: Additional module name prefixes to skip
+            (matched against frame's __name__).
+    """
+
+    def __init__(
+        self,
+        max_frames: int = 1,
+        extra_skip_packages: list[str] | None = None,
+    ) -> None:
+        super().__init__()
+        self.max_frames = max_frames
+        self.extra_skip_packages: list[str] | None = list(extra_skip_packages) if extra_skip_packages else None
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        caller = get_caller_frame(
+            extra_skip_packages=self.extra_skip_packages,
+            max_frames=self.max_frames,
+        )
+        record.caller = caller
+
+        # Overwrite standard location fields from the first user frame
+        first = caller if isinstance(caller, str) else caller[0]
+        self._overwrite_record_location(record, first)
+
+        return True
+
+    @staticmethod
+    def _overwrite_record_location(record: logging.LogRecord, frame_str: str) -> None:
+        """Parse 'path/to/file.py:lineno in funcname' and overwrite record fields.
+
+        Frame string format: "relative/path/to/file.py:42 in func_name"
+        Uses rsplit to handle edge cases where function name could have spaces.
+        """
+        try:
+            # Split off the function name part (rightmost " in ")
+            path_part, func_part = frame_str.rsplit(" in ", 1)
+            # Split off the line number (rightmost ":")
+            filepath, lineno_str = path_part.rsplit(":", 1)
+            record.pathname = os.path.abspath(filepath)
+            record.filename = os.path.basename(filepath)
+            record.module = os.path.splitext(record.filename)[0]
+            record.funcName = func_part.strip()
+            record.lineno = int(lineno_str)
+        except (ValueError, AttributeError):
+            pass  # Keep original fields if parsing fails

{sqlobjects-1.6.0 → sqlobjects-1.8.0/sqlobjects.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlobjects
-Version: 1.6.0
+Version: 1.8.0
 Summary: Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>

{sqlobjects-1.6.0 → sqlobjects-1.8.0}/sqlobjects.egg-info/SOURCES.txt

@@ -20,6 +20,7 @@ sqlobjects/model.py
 sqlobjects/queryset.py
 sqlobjects/session.py
 sqlobjects/signals.py
+sqlobjects/sql_logging.py
 sqlobjects/validators.py
 sqlobjects.egg-info/PKG-INFO
 sqlobjects.egg-info/SOURCES.txt