python-mapper 0.3.0__py3-none-any.whl

python_mapper/database.py

@@ -0,0 +1,212 @@
+"""asyncpg pool lifecycle owned by python-mapper."""
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import AsyncGenerator, Callable
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import Any, Protocol, cast
+
+import asyncpg
+
+
+class ConnectionLike(Protocol):
+    """Execution surface used by the mapper runtime and test doubles."""
+
+    async def execute(self, query: str, *args: Any, timeout: float | None = None) -> str: ...
+
+    async def fetch(self, query: str, *args: Any, timeout: float | None = None) -> list[Any]: ...
+
+    async def fetchval(
+        self,
+        query: str,
+        *args: Any,
+        column: int = 0,
+        timeout: float | None = None,
+    ) -> Any: ...
+
+    def transaction(
+        self,
+        *,
+        isolation: str | None = None,
+        readonly: bool = False,
+        deferrable: bool = False,
+    ) -> Any: ...
+
+
+class PoolLike(Protocol):
+    """Pool surface required by the runtime."""
+
+    def acquire(self) -> Any: ...
+
+    async def close(self) -> None: ...
+
+
+PoolFactory = Callable[..., Any]
+
+
+@dataclass(frozen=True, slots=True)
+class DatabaseConfig:
+    dsn: str
+    min_size: int = 1
+    max_size: int = 10
+    command_timeout: float | None = None
+    ssl: Any = None
+    statement_cache_size: int = 100
+
+
+_DATABASE_CONFIG: DatabaseConfig | None = None
+_POOL: PoolLike | None = None
+_POOL_OWNED = False
+_POOL_FACTORY: PoolFactory = asyncpg.create_pool
+
+
+def _encode_json(value: Any) -> str:
+    """Accept native JSON values and legacy pre-serialized JSON strings."""
+    if isinstance(value, str):
+        return value
+    return json.dumps(value, ensure_ascii=False, default=str)
+
+
+async def _initialize_connection(connection: asyncpg.Connection) -> None:
+    """Decode PostgreSQL JSON/JSONB columns into native Python values."""
+    for type_name in ("json", "jsonb"):
+        await connection.set_type_codec(
+            type_name,
+            schema="pg_catalog",
+            encoder=_encode_json,
+            decoder=json.loads,
+            format="text",
+        )
+
+
+def normalize_asyncpg_dsn(dsn: str) -> str:
+    """Convert SQLAlchemy-style PostgreSQL URLs into asyncpg-compatible DSNs."""
+    normalized = dsn.strip()
+    if normalized.startswith("postgresql+asyncpg://"):
+        return "postgresql://" + normalized[len("postgresql+asyncpg://"):]
+    if normalized.startswith("postgres+asyncpg://"):
+        return "postgres://" + normalized[len("postgres+asyncpg://"):]
+    return normalized
+
+
+def configure_database(
+    *,
+    dsn: str,
+    min_size: int = 1,
+    max_size: int = 10,
+    command_timeout: float | None = None,
+    ssl: Any = None,
+    statement_cache_size: int = 100,
+    pool_factory: PoolFactory | None = None,
+) -> None:
+    """Register pool settings. Network connections are opened by ``open_database``."""
+    if _POOL is not None:
+        raise RuntimeError("cannot reconfigure python-mapper while its database pool is open")
+    if not dsn.strip():
+        raise ValueError("database dsn must not be empty")
+    if min_size < 0 or max_size < 1 or min_size > max_size:
+        raise ValueError("pool sizes must satisfy 0 <= min_size <= max_size")
+    global _DATABASE_CONFIG, _POOL_FACTORY
+    _DATABASE_CONFIG = DatabaseConfig(
+        dsn=normalize_asyncpg_dsn(dsn),
+        min_size=min_size,
+        max_size=max_size,
+        command_timeout=command_timeout,
+        ssl=ssl,
+        statement_cache_size=statement_cache_size,
+    )
+    if pool_factory is not None:
+        _POOL_FACTORY = pool_factory
+
+
+def configure_pool(pool: PoolLike) -> None:
+    """Inject an externally managed pool, primarily for tests and host integration."""
+    global _POOL, _POOL_OWNED
+    if _POOL is pool:
+        return
+    if _POOL is not None:
+        raise RuntimeError("python-mapper database pool is already configured")
+    _POOL = pool
+    _POOL_OWNED = False
+
+
+async def open_database() -> PoolLike:
+    """Open the configured asyncpg pool once during application startup."""
+    global _POOL, _POOL_OWNED
+    if _POOL is not None:
+        return _POOL
+    config = _DATABASE_CONFIG
+    if config is None:
+        raise RuntimeError("python-mapper database is not configured")
+    created = await _POOL_FACTORY(
+        dsn=config.dsn,
+        min_size=config.min_size,
+        max_size=config.max_size,
+        command_timeout=config.command_timeout,
+        ssl=config.ssl,
+        statement_cache_size=config.statement_cache_size,
+        init=_initialize_connection,
+    )
+    _POOL = cast(PoolLike, created)
+    _POOL_OWNED = True
+    return _POOL
+
+
+def get_pool() -> PoolLike:
+    """Return the active pool or fail before any SQL is attempted."""
+    if _POOL is None:
+        raise RuntimeError("python-mapper database pool is not open; call open_database() at startup")
+    return _POOL
+
+
+@asynccontextmanager
+async def acquire_raw_connection() -> AsyncGenerator[ConnectionLike]:
+    """Borrow one connection without opening an explicit transaction."""
+    async with get_pool().acquire() as connection:
+        yield cast(ConnectionLike, connection)
+
+
+async def ping_database() -> bool:
+    """Check the primary database through the same pool used by mappers."""
+    async with acquire_raw_connection() as connection:
+        return await connection.fetchval("SELECT 1") == 1
+
+
+async def close_database(*, timeout: float = 10.0) -> None:
+    """Close an owned pool during application shutdown."""
+    global _POOL, _POOL_OWNED
+    pool, owned = _POOL, _POOL_OWNED
+    _POOL = None
+    _POOL_OWNED = False
+    if pool is None or not owned:
+        return
+    await asyncio.wait_for(pool.close(), timeout=timeout)
+
+
+def clear_database_configuration() -> None:
+    """Clear unopened configuration and injected test pools."""
+    global _DATABASE_CONFIG, _POOL, _POOL_OWNED, _POOL_FACTORY
+    if _POOL is not None and _POOL_OWNED:
+        raise RuntimeError("close_database() must be awaited before resetting an owned pool")
+    _DATABASE_CONFIG = None
+    _POOL = None
+    _POOL_OWNED = False
+    _POOL_FACTORY = asyncpg.create_pool
+
+
+__all__ = [
+    "ConnectionLike",
+    "DatabaseConfig",
+    "PoolLike",
+    "acquire_raw_connection",
+    "clear_database_configuration",
+    "close_database",
+    "configure_database",
+    "configure_pool",
+    "get_pool",
+    "normalize_asyncpg_dsn",
+    "open_database",
+    "ping_database",
+]

python_mapper/errors.py

@@ -0,0 +1,26 @@
+"""Public exception types raised by python-mapper."""
+from __future__ import annotations
+
+
+class PyMapperError(RuntimeError):
+    """Base class for python-mapper runtime errors."""
+
+
+class TooManyResultsError(PyMapperError):
+    """A ``single=true`` statement returned more than one database row."""
+
+
+class PaginationError(PyMapperError):
+    """A paginated query declaration or invocation is invalid."""
+
+
+class PaginationConflictError(PaginationError):
+    """Framework pagination conflicts with a manual SQL pagination clause."""
+
+
+__all__ = [
+    "PaginationConflictError",
+    "PaginationError",
+    "PyMapperError",
+    "TooManyResultsError",
+]

python_mapper/extension.py

@@ -0,0 +1,140 @@
+"""Application bootstrap for mapper discovery, validation and pool lifecycle."""
+from __future__ import annotations
+
+import importlib
+import logging
+import pkgutil
+from collections.abc import AsyncGenerator, Sequence
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+from python_mapper.database import (
+    PoolLike,
+    close_database,
+    configure_database,
+    configure_pool,
+    open_database,
+    ping_database,
+)
+from python_mapper.plugins import StatementPlugin
+from python_mapper.runtime import configure_mapper_paths, configure_plugins, load_all_mappers
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class MapperStartupState:
+    """Observable result of one mapper application startup."""
+
+    statement_count: int
+    database_ready: bool
+    database_error: Exception | None = None
+
+
+def _import_mapper_package(package_ref: str | ModuleType) -> tuple[str, ...]:
+    package = importlib.import_module(package_ref) if isinstance(package_ref, str) else package_ref
+    imported = [package.__name__]
+    package_paths = getattr(package, "__path__", None)
+    if package_paths is None:
+        return tuple(imported)
+    prefix = f"{package.__name__}."
+    module_names = sorted(
+        module_info.name
+        for module_info in pkgutil.walk_packages(package_paths, prefix=prefix)
+    )
+    for module_name in module_names:
+        importlib.import_module(module_name)
+    imported.extend(module_names)
+    return tuple(imported)
+
+
+class PyMapperExtension:
+    """Configure python-mapper once and own its application lifecycle.
+
+    Construction only records configuration; it never performs network I/O.
+    ``lifespan()`` imports every configured mapper package, validates all XML,
+    opens the asyncpg pool and closes the owned pool on exit.
+    """
+
+    def __init__(
+        self,
+        *,
+        mapper_paths: Sequence[str | Path],
+        mapper_packages: Sequence[str | ModuleType] = (),
+        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: Any = None,
+        statement_cache_size: int = 100,
+        plugins: Sequence[StatementPlugin] = (),
+    ) -> None:
+        if (database_url is None) == (pool is None):
+            raise ValueError("PyMapperExtension requires exactly one of database_url or pool")
+        self._mapper_packages = tuple(mapper_packages)
+        self._imported_modules: tuple[str, ...] = ()
+        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))
+
+    @property
+    def imported_modules(self) -> tuple[str, ...]:
+        return self._imported_modules
+
+    def load_mappers(self) -> int:
+        """Import configured packages and validate every mapper/XML contract."""
+        imported: list[str] = []
+        for package_ref in self._mapper_packages:
+            imported.extend(_import_mapper_package(package_ref))
+        self._imported_modules = tuple(dict.fromkeys(imported))
+        return load_all_mappers()
+
+    async def startup(self, *, require_database: bool = True) -> MapperStartupState:
+        """Load mappers and open the database pool.
+
+        ``require_database=False`` is intended for applications whose health
+        endpoint must report an unavailable database while the HTTP process stays
+        alive. XML/import errors always fail startup because they are code defects.
+        """
+        statement_count = self.load_mappers()
+        try:
+            await open_database()
+            database_ready = await ping_database()
+            return MapperStartupState(statement_count, database_ready)
+        except Exception as error:
+            logger.exception("python-mapper database startup failed")
+            if require_database:
+                raise
+            return MapperStartupState(statement_count, False, error)
+
+    async def shutdown(self) -> None:
+        await close_database()
+
+    @asynccontextmanager
+    async def lifespan(
+        self,
+        *,
+        require_database: bool = True,
+    ) -> AsyncGenerator[MapperStartupState]:
+        """Framework-neutral lifespan usable by FastAPI and other ASGI hosts."""
+        try:
+            yield await self.startup(require_database=require_database)
+        finally:
+            await self.shutdown()
+
+
+__all__ = ["MapperStartupState", "PyMapperExtension"]

python_mapper/mapping.py

@@ -0,0 +1,210 @@
+"""MyBatis-style result declarations, validation, and row materialization."""
+from __future__ import annotations
+
+import importlib
+import inspect
+import xml.etree.ElementTree as ET
+from dataclasses import fields, is_dataclass
+from pathlib import Path
+from typing import Any, NamedTuple
+
+from python_mapper.errors import TooManyResultsError
+
+
+class ResultSpec(NamedTuple):
+    dotted: str
+    column_map: dict[str, str] | None
+    single: bool
+
+
+# XML result declarations and imported model types are owned by this module.
+_RESULT_SPEC: dict[str, ResultSpec] = {}
+_RESULT_MAP_DEFS: dict[str, tuple[str, dict[str, str]]] = {}
+_TYPE_CACHE: dict[str, type] = {}
+
+
+def clear_result_mappings() -> None:
+    """Clear all XML-derived result declarations and resolved model classes."""
+    _RESULT_SPEC.clear()
+    _RESULT_MAP_DEFS.clear()
+    _TYPE_CACHE.clear()
+
+
+def load_result_map(namespace: str, elem: ET.Element, file: Path) -> None:
+    """Register one explicit ``resultMap`` declaration from mapper XML."""
+    map_id = elem.attrib.get("id")
+    dotted = elem.attrib.get("type")
+    if not map_id or not dotted:
+        raise ValueError(f"<resultMap> 必须带 id 与 type: {file}")
+    key = f"{namespace}.{map_id}"
+    if key in _RESULT_MAP_DEFS:
+        raise ValueError(f"<resultMap> id 重复: {key}")
+    column_map: dict[str, str] = {}
+    for sub in elem:
+        if sub.tag not in ("result", "id"):
+            raise ValueError(
+                f"<resultMap {map_id}> 含不支持的子元素 <{sub.tag}> "
+                f"({file.name}; 只支持 <result>/<id>)"
+            )
+        column, property_name = sub.attrib.get("column"), sub.attrib.get("property")
+        if not column or not property_name:
+            raise ValueError(
+                f"<resultMap {map_id}> 的 <{sub.tag}> 必须带 column 与 property "
+                f"({file.name})"
+            )
+        column_map[column] = property_name
+    _RESULT_MAP_DEFS[key] = (dotted, column_map)
+
+
+def load_result_spec(
+    namespace: str,
+    full_id: str,
+    elem: ET.Element,
+    file: Path,
+) -> None:
+    """Register ``resultType``/``resultMap`` and strict single-row semantics."""
+    result_map = elem.attrib.get("resultMap")
+    result_type = elem.attrib.get("resultType")
+    single = str(elem.attrib.get("single", "")).lower() in ("1", "true", "yes")
+    if result_map and result_type:
+        raise ValueError(
+            f"条目 '{full_id}' ({file.name}) 不能同时给 resultMap 与 resultType"
+        )
+    if result_map:
+        key = f"{namespace}.{result_map}"
+        if key not in _RESULT_MAP_DEFS:
+            available = sorted(
+                result_key.split(".")[-1]
+                for result_key in _RESULT_MAP_DEFS
+                if result_key.startswith(namespace + ".")
+            )
+            raise ValueError(
+                f"条目 '{full_id}' ({file.name}) 的 resultMap=\"{result_map}\" 未声明 "
+                f"(可用: {available})"
+            )
+        dotted, column_map = _RESULT_MAP_DEFS[key]
+        _RESULT_SPEC[full_id] = ResultSpec(dotted, column_map, single)
+    elif result_type:
+        _RESULT_SPEC[full_id] = ResultSpec(result_type, None, single)
+    elif single:
+        _RESULT_SPEC[full_id] = ResultSpec("", None, True)
+
+
+def _resolve_type(dotted: str, full_id: str) -> type:
+    cached = _TYPE_CACHE.get(dotted)
+    if cached is not None:
+        return cached
+    module_path, _, class_name = dotted.rpartition(".")
+    if not module_path:
+        raise ValueError(
+            f"条目 '{full_id}' 的 resultType '{dotted}' 不是合法点路径(要 模块.类名)"
+        )
+    try:
+        model_class = getattr(importlib.import_module(module_path), class_name)
+    except (ImportError, AttributeError) as exc:
+        raise ValueError(
+            f"条目 '{full_id}' 的 resultType '{dotted}' 无法导入: {exc}"
+        ) from exc
+    if not inspect.isclass(model_class):
+        raise ValueError(
+            f"条目 '{full_id}' 的 resultType '{dotted}' 指向的不是类: "
+            f"{type(model_class).__name__}"
+        )
+    _TYPE_CACHE[dotted] = model_class
+    return model_class
+
+
+def _model_init_fields(model_class: type) -> frozenset[str] | None:
+    """Return constructor fields; ``None`` means arbitrary kwargs are accepted."""
+    if is_dataclass(model_class):
+        return frozenset(field.name for field in fields(model_class) if field.init)
+
+    pydantic_fields = getattr(model_class, "model_fields", None)
+    if isinstance(pydantic_fields, dict):
+        return frozenset(pydantic_fields)
+
+    annotations: dict[str, Any] = {}
+    for base_class in reversed(model_class.__mro__):
+        annotations.update(getattr(base_class, "__annotations__", {}))
+    if annotations:
+        return frozenset(annotations)
+
+    try:
+        parameters = inspect.signature(model_class).parameters.values()
+    except (TypeError, ValueError):
+        return frozenset()
+    if any(parameter.kind is parameter.VAR_KEYWORD for parameter in parameters):
+        return None
+    return frozenset(
+        parameter.name
+        for parameter in parameters
+        if parameter.kind
+        in (parameter.POSITIONAL_OR_KEYWORD, parameter.KEYWORD_ONLY)
+    )
+
+
+def _validate_result_spec(full_id: str, spec: ResultSpec) -> None:
+    """Validate type paths and properties explicitly forced by ``resultMap``."""
+    if not spec.dotted:
+        return
+    model_class = _resolve_type(spec.dotted, full_id)
+    if spec.column_map is None:
+        return
+    model_fields = _model_init_fields(model_class)
+    if model_fields is None:
+        return
+    unknown_properties = sorted(set(spec.column_map.values()) - model_fields)
+    if unknown_properties:
+        raise ValueError(
+            f"条目 '{full_id}' 的 resultMap 显式映射了模型 {spec.dotted} 不存在的属性 "
+            f"{unknown_properties} (可用: {sorted(model_fields)})"
+        )
+
+
+def validate_result_types() -> None:
+    """Validate every result type after all mapper XML files have loaded."""
+    for full_id, spec in list(_RESULT_SPEC.items()):
+        _validate_result_spec(full_id, spec)
+
+
+def shape_rows(full_id: str, rows: list[Any]) -> Any:
+    """Auto-map known fields, ignore extra columns, and enforce result cardinality."""
+    spec = _RESULT_SPEC.get(full_id)
+    if spec is None:
+        return rows
+    if spec.dotted:
+        model_class = _resolve_type(spec.dotted, full_id)
+        _validate_result_spec(full_id, spec)
+        model_fields = _model_init_fields(model_class)
+        built = []
+        for row in rows:
+            row_data: dict[str, Any] = dict(row)
+            if spec.column_map is not None:
+                row_data = {
+                    spec.column_map.get(column, column): value
+                    for column, value in row_data.items()
+                }
+            if model_fields is not None:
+                row_data = {
+                    field_name: value
+                    for field_name, value in row_data.items()
+                    if field_name in model_fields
+                }
+            try:
+                built.append(model_class(**row_data))
+            except TypeError as exc:
+                raise TypeError(
+                    f"条目 '{full_id}' 结果映射到 {spec.dotted} 失败: {exc}; "
+                    f"实际填充字段={sorted(row_data)}"
+                ) from exc
+        rows = built
+    if spec.single:
+        if len(rows) > 1:
+            raise TooManyResultsError(
+                f"条目 '{full_id}' 声明 single=true，但查询返回了 {len(rows)} 行"
+            )
+        return rows[0] if rows else None
+    return rows
+
+
+__all__ = ["ResultSpec", "clear_result_mappings", "load_result_map", "load_result_spec", "shape_rows", "validate_result_types"]