python-mapper 0.3.0__py3-none-any.whl

python_mapper/__init__.py

@@ -0,0 +1,139 @@
+"""PostgreSQL XML mapper with an asyncpg pool and implicit transactions."""
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from python_mapper import runtime
+from python_mapper.base import (
+    MapperBase,
+    bind_connection,
+    current_connection,
+    require_connection,
+    transactional,
+    transactional_scope,
+)
+from python_mapper.database import (
+    ConnectionLike,
+    PoolLike,
+    acquire_raw_connection,
+    close_database,
+    configure_database,
+    configure_pool,
+    get_pool,
+    open_database,
+    ping_database,
+)
+from python_mapper.errors import (
+    PaginationConflictError,
+    PaginationError,
+    PyMapperError,
+    TooManyResultsError,
+)
+from python_mapper.extension import MapperStartupState, PyMapperExtension
+from python_mapper.observability import SqlLoggingPlugin
+from python_mapper.pagination import (
+    DEFAULT_PAGE_SIZE,
+    MAX_PAGE_SIZE,
+    Page,
+    PageMetadata,
+    PaginationOptions,
+    QueryResult,
+)
+from python_mapper.plugins import (
+    StatementContext,
+    StatementExecutor,
+    StatementPlugin,
+    StatementResult,
+)
+from python_mapper.runtime import (
+    AMapper,
+    amapper,
+    configure_mapper_paths,
+    configure_plugins,
+    load_all_mappers,
+    load_mapper,
+    query,
+    render_sql,
+    reset_state,
+    scalar,
+    validate_result_types,
+)
+
+__version__ = "0.3.0"
+
+
+def configure(
+    *,
+    mapper_paths: Sequence[str | Path],
+    database_url: str | None = None,
+    pool: PoolLike | None = None,
+    min_pool_size: int = 1,
+    max_pool_size: int = 10,
+    command_timeout: float | None = None,
+    ssl=None,
+    statement_cache_size: int = 100,
+    plugins: Sequence[StatementPlugin] = (),
+) -> None:
+    """Bind one database backend and the application's XML roots."""
+    if (database_url is None) == (pool is None):
+        raise ValueError("configure requires exactly one of database_url or pool")
+    if pool is not None:
+        configure_pool(pool)
+    else:
+        configure_database(
+            dsn=database_url or "",
+            min_size=min_pool_size,
+            max_size=max_pool_size,
+            command_timeout=command_timeout,
+            ssl=ssl,
+            statement_cache_size=statement_cache_size,
+        )
+    configure_mapper_paths(tuple(mapper_paths))
+    configure_plugins(tuple(plugins))
+
+
+__all__ = [
+    "AMapper",
+    "ConnectionLike",
+    "DEFAULT_PAGE_SIZE",
+    "MAX_PAGE_SIZE",
+    "MapperBase",
+    "MapperStartupState",
+    "Page",
+    "PageMetadata",
+    "PaginationConflictError",
+    "PaginationError",
+    "PaginationOptions",
+    "PoolLike",
+    "PyMapperError",
+    "PyMapperExtension",
+    "QueryResult",
+    "SqlLoggingPlugin",
+    "StatementContext",
+    "StatementExecutor",
+    "StatementPlugin",
+    "StatementResult",
+    "TooManyResultsError",
+    "__version__",
+    "amapper",
+    "acquire_raw_connection",
+    "bind_connection",
+    "close_database",
+    "configure",
+    "current_connection",
+    "get_pool",
+    "load_all_mappers",
+    "load_mapper",
+    "render_sql",
+    "open_database",
+    "ping_database",
+    "query",
+    "require_connection",
+    "reset_state",
+    "runtime",
+    "scalar",
+    "transactional",
+    "transactional_scope",
+    "validate_result_types",
+]

python_mapper/base.py

@@ -0,0 +1,176 @@
+"""Implicit asyncpg connection and explicit transaction boundaries."""
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import AsyncGenerator, Awaitable, Callable
+from contextlib import asynccontextmanager
+from contextvars import ContextVar, Token
+from typing import ParamSpec, TypeVar
+
+from python_mapper.database import ConnectionLike, acquire_raw_connection
+
+CallableParameters = ParamSpec("CallableParameters")
+ReturnValue = TypeVar("ReturnValue")
+
+_ACTIVE_CONNECTION: ContextVar[ConnectionLike | None] = ContextVar(
+    "mapper_active_connection", default=None
+)
+_ACTIVE_TRANSACTION_OPTIONS: ContextVar[tuple[str | None, bool] | None] = ContextVar(
+    "mapper_active_transaction_options", default=None
+)
+_VALID_ISOLATION_LEVELS = {"READ COMMITTED", "REPEATABLE READ", "SERIALIZABLE"}
+
+
+def _normalize_isolation_level(value: str | None) -> str | None:
+    if value is None:
+        return None
+    normalized = value.strip().upper().replace("_", " ")
+    if normalized not in _VALID_ISOLATION_LEVELS:
+        raise ValueError(
+            "isolation_level must be READ COMMITTED, REPEATABLE READ or SERIALIZABLE"
+        )
+    return normalized
+
+
+def _asyncpg_isolation(value: str | None) -> str | None:
+    return value.lower().replace(" ", "_") if value is not None else None
+
+
+class MapperBase:
+    """Base contract for mappers that consume an implicit asyncpg connection."""
+
+    @classmethod
+    @asynccontextmanager
+    async def acquire_connection(cls) -> AsyncGenerator[ConnectionLike]:
+        """Reuse an active transaction or borrow a connection for one statement."""
+        current = _ACTIVE_CONNECTION.get()
+        if current is not None:
+            yield current
+            return
+        async with acquire_raw_connection() as connection:
+            yield connection
+
+    @classmethod
+    @asynccontextmanager
+    async def transaction_scope(
+        cls,
+        *,
+        requires_new: bool = False,
+        isolation_level: str | None = None,
+        read_only: bool = False,
+    ) -> AsyncGenerator[ConnectionLike]:
+        """Open one transaction, reusing the current one for REQUIRED semantics."""
+        normalized_isolation = _normalize_isolation_level(isolation_level)
+        current = _ACTIVE_CONNECTION.get()
+        if current is not None and not requires_new:
+            active_options = _ACTIVE_TRANSACTION_OPTIONS.get()
+            if (
+                normalized_isolation is not None
+                and active_options is not None
+                and active_options[0] != normalized_isolation
+            ):
+                raise RuntimeError(
+                    "cannot change transaction isolation while joining an active transaction"
+                )
+            if read_only and active_options is not None and not active_options[1]:
+                raise RuntimeError("cannot join a read-write transaction as read-only")
+            yield current
+            return
+
+        async with acquire_raw_connection() as connection:
+            connection_token = _ACTIVE_CONNECTION.set(connection)
+            options_token = _ACTIVE_TRANSACTION_OPTIONS.set(
+                (normalized_isolation, read_only)
+            )
+            try:
+                async with connection.transaction(
+                    isolation=_asyncpg_isolation(normalized_isolation),
+                    readonly=read_only,
+                ):
+                    yield connection
+            finally:
+                _ACTIVE_TRANSACTION_OPTIONS.reset(options_token)
+                _ACTIVE_CONNECTION.reset(connection_token)
+
+
+def current_connection() -> ConnectionLike | None:
+    return _ACTIVE_CONNECTION.get()
+
+
+def require_connection() -> ConnectionLike:
+    connection = current_connection()
+    if connection is None:
+        raise RuntimeError("当前调用不在 pymapper 事务上下文中")
+    return connection
+
+
+@asynccontextmanager
+async def bind_connection(connection: ConnectionLike) -> AsyncGenerator[ConnectionLike]:
+    """Borrow an externally managed connection without commit, rollback or close."""
+    connection_token: Token[ConnectionLike | None] = _ACTIVE_CONNECTION.set(connection)
+    options_token = _ACTIVE_TRANSACTION_OPTIONS.set((None, False))
+    try:
+        yield connection
+    finally:
+        _ACTIVE_TRANSACTION_OPTIONS.reset(options_token)
+        _ACTIVE_CONNECTION.reset(connection_token)
+
+
+def transactional(
+    *,
+    propagation: str = "REQUIRED",
+    isolation_level: str | None = None,
+    read_only: bool = False,
+):
+    """Wrap an async service method in an asyncpg transaction.
+
+    ``REQUIRED`` joins the task-local transaction. ``REQUIRES_NEW`` suspends it
+    and borrows another connection for an independent transaction.
+
+    Do not create child tasks that call mappers inside this boundary. ContextVars
+    are copied into child tasks, which would make concurrent tasks share one
+    asyncpg connection and fail with an InterfaceError or use it after release.
+    """
+    normalized = propagation.strip().upper()
+    if normalized not in {"REQUIRED", "REQUIRES_NEW"}:
+        raise ValueError("propagation must be REQUIRED or REQUIRES_NEW")
+    normalized_isolation = _normalize_isolation_level(isolation_level)
+
+    def decorator(
+        func: Callable[CallableParameters, Awaitable[ReturnValue]],
+    ) -> Callable[CallableParameters, Awaitable[ReturnValue]]:
+        if not inspect.iscoroutinefunction(func):
+            raise TypeError(
+                f"transactional 只能装饰 async 函数, {getattr(func, '__qualname__', func)!r} "
+                "是同步的"
+            )
+
+        @functools.wraps(func)
+        async def wrapper(
+            *args: CallableParameters.args,
+            **kwargs: CallableParameters.kwargs,
+        ) -> ReturnValue:
+            async with MapperBase.transaction_scope(
+                requires_new=normalized == "REQUIRES_NEW",
+                isolation_level=normalized_isolation,
+                read_only=read_only,
+            ):
+                return await func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+transactional_scope = MapperBase.transaction_scope
+
+
+__all__ = [
+    "MapperBase",
+    "bind_connection",
+    "current_connection",
+    "require_connection",
+    "transactional",
+    "transactional_scope",
+]

python_mapper/compiler.py

@@ -0,0 +1,365 @@
+"""Compile named XML parameters into asyncpg positional parameters."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class CompiledQuery:
+    sql: str
+    args: tuple[Any, ...]
+
+
+def _is_identifier_start(character: str) -> bool:
+    return character == "_" or character.isalpha()
+
+
+def _is_identifier_part(character: str) -> bool:
+    return character == "_" or character.isalnum()
+
+
+def _is_postgresql_identifier_part(character: str) -> bool:
+    """PostgreSQL permits dollar signs after the first identifier character."""
+    return character == "$" or _is_identifier_part(character)
+
+
+def _is_collection_parameter(value: Any) -> bool:
+    return isinstance(value, (list, tuple, set, frozenset))
+
+
+def _dollar_quote_delimiter(sql: str, offset: int) -> str | None:
+    if sql[offset] != "$":
+        return None
+    if offset > 0 and _is_postgresql_identifier_part(sql[offset - 1]):
+        return None
+    end = sql.find("$", offset + 1)
+    if end < 0:
+        return None
+    tag = sql[offset + 1:end]
+    if tag and (not _is_identifier_start(tag[0]) or not all(_is_identifier_part(c) for c in tag)):
+        return None
+    return sql[offset:end + 1]
+
+
+def _skip_single_quoted_string(sql: str, quote_offset: int) -> int:
+    """Return the first offset after a regular or PostgreSQL E-string."""
+    prefix_offset = quote_offset - 1
+    uses_backslash_escapes = (
+        prefix_offset >= 0
+        and sql[prefix_offset] in {"E", "e"}
+        and (
+            prefix_offset == 0
+            or not _is_postgresql_identifier_part(sql[prefix_offset - 1])
+        )
+    )
+    index = quote_offset + 1
+    length = len(sql)
+    while index < length:
+        if uses_backslash_escapes and sql[index] == "\\":
+            index = min(length, index + 2)
+            continue
+        if sql[index] == "'":
+            if index + 1 < length and sql[index + 1] == "'":
+                index += 2
+                continue
+            return index + 1
+        index += 1
+    return length
+
+
+def _scan_parameters(
+    sql: str,
+) -> tuple[list[tuple[int, int, str]], list[tuple[int, int, int]]]:
+    """Find named and native positional binds outside non-executable regions."""
+    named: list[tuple[int, int, str]] = []
+    positional: list[tuple[int, int, int]] = []
+    index = 0
+    length = len(sql)
+    while index < length:
+        character = sql[index]
+        if character == "'":
+            index = _skip_single_quoted_string(sql, index)
+            continue
+        if character == '"':
+            index += 1
+            while index < length:
+                if sql[index] == '"':
+                    if index + 1 < length and sql[index + 1] == '"':
+                        index += 2
+                        continue
+                    index += 1
+                    break
+                index += 1
+            continue
+        if sql.startswith("--", index):
+            newline = sql.find("\n", index + 2)
+            index = length if newline < 0 else newline + 1
+            continue
+        if sql.startswith("/*", index):
+            depth = 1
+            index += 2
+            while index < length and depth:
+                if sql.startswith("/*", index):
+                    depth += 1
+                    index += 2
+                elif sql.startswith("*/", index):
+                    depth -= 1
+                    index += 2
+                else:
+                    index += 1
+            continue
+        delimiter = _dollar_quote_delimiter(sql, index) if character == "$" else None
+        if delimiter is not None:
+            end = sql.find(delimiter, index + len(delimiter))
+            index = length if end < 0 else end + len(delimiter)
+            continue
+        if character == "$" and index + 1 < length and sql[index + 1].isdigit():
+            position_end = index + 2
+            while position_end < length and sql[position_end].isdigit():
+                position_end += 1
+            positional.append((index, position_end, int(sql[index + 1:position_end])))
+            index = position_end
+            continue
+        if (
+            character == ":"
+            and not sql.startswith("::", index)
+            and (index == 0 or sql[index - 1] != ":")
+        ):
+            name_start = index + 1
+            if name_start < length and _is_identifier_start(sql[name_start]):
+                name_end = name_start + 1
+                while name_end < length and _is_identifier_part(sql[name_end]):
+                    name_end += 1
+                named.append((index, name_end, sql[name_start:name_end]))
+                index = name_end
+                continue
+        index += 1
+    return named, positional
+
+
+def _scan_named_parameters(sql: str) -> list[tuple[int, int, str]]:
+    return _scan_parameters(sql)[0]
+
+
+def named_parameter_names(sql: str) -> set[str]:
+    return {name for _, _, name in _scan_named_parameters(sql)}
+
+
+def positional_parameter_numbers(sql: str) -> set[int]:
+    """Return native asyncpg ``$n`` binds outside literals and comments."""
+    return {number for _, _, number in _scan_parameters(sql)[1]}
+
+
+def sql_token_parenthesis_depths(sql: str, token: str) -> tuple[int, ...]:
+    """Return parenthesis depths for an exact token in executable SQL regions."""
+    if not token:
+        raise ValueError("token must not be empty")
+    depths: list[int] = []
+    index = 0
+    depth = 0
+    length = len(sql)
+    while index < length:
+        if sql.startswith(token, index):
+            depths.append(depth)
+            index += len(token)
+            continue
+        character = sql[index]
+        if character == "'":
+            index = _skip_single_quoted_string(sql, index)
+            continue
+        if character == '"':
+            index += 1
+            while index < length:
+                if sql[index] == '"':
+                    if index + 1 < length and sql[index + 1] == '"':
+                        index += 2
+                        continue
+                    index += 1
+                    break
+                index += 1
+            continue
+        if sql.startswith("--", index):
+            newline = sql.find("\n", index + 2)
+            index = length if newline < 0 else newline + 1
+            continue
+        if sql.startswith("/*", index):
+            comment_depth = 1
+            index += 2
+            while index < length and comment_depth:
+                if sql.startswith("/*", index):
+                    comment_depth += 1
+                    index += 2
+                elif sql.startswith("*/", index):
+                    comment_depth -= 1
+                    index += 2
+                else:
+                    index += 1
+            continue
+        delimiter = _dollar_quote_delimiter(sql, index) if character == "$" else None
+        if delimiter is not None:
+            end = sql.find(delimiter, index + len(delimiter))
+            index = length if end < 0 else end + len(delimiter)
+            continue
+        if character == "(":
+            depth += 1
+        elif character == ")" and depth:
+            depth -= 1
+        index += 1
+    return tuple(depths)
+
+
+def compile_query(sql: str, parameters: dict[str, Any]) -> CompiledQuery:
+    """Compile ``:name`` parameters and SQLAlchemy-style collection expansion."""
+    occurrences = _scan_named_parameters(sql)
+    missing = sorted({name for _, _, name in occurrences if name not in parameters})
+    if missing:
+        raise ValueError(f"SQL 缺少绑定参数: {missing}")
+
+    args: list[Any] = []
+    placeholders: dict[str, str] = {}
+    output: list[str] = []
+    cursor = 0
+    for start, end, name in occurrences:
+        output.append(sql[cursor:start])
+        placeholder = placeholders.get(name)
+        if placeholder is None:
+            value = parameters[name]
+            if _is_collection_parameter(value):
+                values = list(value)
+                if values:
+                    positions = []
+                    for item in values:
+                        args.append(item)
+                        positions.append(f"${len(args)}")
+                    placeholder = f"({', '.join(positions)})"
+                else:
+                    placeholder = "(SELECT NULL WHERE FALSE)"
+            else:
+                args.append(value)
+                placeholder = f"${len(args)}"
+            placeholders[name] = placeholder
+        output.append(placeholder)
+        cursor = end
+    output.append(sql[cursor:])
+    return CompiledQuery("".join(output), tuple(args))
+
+
+def contains_sql_keyword(sql: str, keyword: str) -> bool:
+    """Check a keyword outside SQL literals and comments."""
+    import re
+
+    executable = []
+    cursor = 0
+    for start, end, _ in _scan_named_parameters(sql):
+        executable.append(sql[cursor:start])
+        executable.append(" ")
+        cursor = end
+    executable.append(sql[cursor:])
+    text = "".join(executable)
+    text = re.sub(r"'(?:''|[^'])*'", " ", text)
+    text = re.sub(r'"(?:""|[^"])*"', " ", text)
+    text = re.sub(r"--[^\n]*", " ", text)
+    text = re.sub(r"/\*.*?\*/", " ", text, flags=re.S)
+    return re.search(rf"\b{re.escape(keyword)}\b", text, re.IGNORECASE) is not None
+
+
+def top_level_sql_word_positions(sql: str) -> tuple[tuple[str, int], ...]:
+    """Return executable words and offsets at parenthesis depth zero.
+
+    Strings, quoted identifiers, comments and PostgreSQL dollar-quoted bodies are
+    skipped. This is deliberately a lexer, not a SQL parser; it is sufficient for
+    detecting outer LIMIT/OFFSET/ORDER BY without rejecting limits in subqueries.
+    """
+    words: list[tuple[str, int]] = []
+    index = 0
+    depth = 0
+    length = len(sql)
+    while index < length:
+        character = sql[index]
+        if character == "'":
+            index = _skip_single_quoted_string(sql, index)
+            continue
+        if character == '"':
+            index += 1
+            while index < length:
+                if sql[index] == '"':
+                    if index + 1 < length and sql[index + 1] == '"':
+                        index += 2
+                        continue
+                    index += 1
+                    break
+                index += 1
+            continue
+        if sql.startswith("--", index):
+            newline = sql.find("\n", index + 2)
+            index = length if newline < 0 else newline + 1
+            continue
+        if sql.startswith("/*", index):
+            comment_depth = 1
+            index += 2
+            while index < length and comment_depth:
+                if sql.startswith("/*", index):
+                    comment_depth += 1
+                    index += 2
+                elif sql.startswith("*/", index):
+                    comment_depth -= 1
+                    index += 2
+                else:
+                    index += 1
+            continue
+        delimiter = _dollar_quote_delimiter(sql, index) if character == "$" else None
+        if delimiter is not None:
+            end = sql.find(delimiter, index + len(delimiter))
+            index = length if end < 0 else end + len(delimiter)
+            continue
+        if character == "(":
+            depth += 1
+            index += 1
+            continue
+        if character == ")":
+            depth = max(0, depth - 1)
+            index += 1
+            continue
+        if _is_identifier_start(character):
+            end = index + 1
+            while end < length and _is_postgresql_identifier_part(sql[end]):
+                end += 1
+            if depth == 0:
+                words.append((sql[index:end].upper(), index))
+            index = end
+            continue
+        index += 1
+    return tuple(words)
+
+
+def top_level_sql_words(sql: str) -> tuple[str, ...]:
+    """Return executable words at parenthesis depth zero."""
+    return tuple(word for word, _ in top_level_sql_word_positions(sql))
+
+
+def contains_top_level_keyword(sql: str, keyword: str) -> bool:
+    return keyword.upper() in top_level_sql_words(sql)
+
+
+def contains_top_level_sequence(sql: str, *keywords: str) -> bool:
+    expected = tuple(keyword.upper() for keyword in keywords)
+    if not expected:
+        return False
+    words = top_level_sql_words(sql)
+    width = len(expected)
+    return any(words[index:index + width] == expected for index in range(len(words) - width + 1))
+
+
+__all__ = [
+    "CompiledQuery",
+    "compile_query",
+    "contains_sql_keyword",
+    "contains_top_level_keyword",
+    "contains_top_level_sequence",
+    "named_parameter_names",
+    "positional_parameter_numbers",
+    "sql_token_parenthesis_depths",
+    "top_level_sql_word_positions",
+    "top_level_sql_words",
+]