ns-orm 0.0.0__py3-none-any.whl

ns_orm/__init__.py

@@ -0,0 +1,96 @@
+from ns_orm.database import (
+    AsyncDatabase,
+    Database,
+    get_connection,
+    register_connection,
+    set_connection_provider,
+)
+from ns_orm.expressions import Q
+from ns_orm.fields import (
+    JSON,
+    UUID,
+    Array,
+    BigInt,
+    Binary,
+    Boolean,
+    Char,
+    Date,
+    Date32,
+    DateTime,
+    DateTime64,
+    Decimal,
+    Double,
+    Enum8,
+    Enum16,
+    FixedString,
+    Float,
+    ForeignKey,
+    Int,
+    IPv4,
+    IPv6,
+    LowCardinality,
+    ManyToMany,
+    Map,
+    Nullable,
+    OneToOne,
+    Real,
+    SmallInt,
+    String,
+    Text,
+    TinyInt,
+    TupleType,
+    UBigInt,
+    UInt,
+    USmallInt,
+    UTinyInt,
+)
+from ns_orm.model import Model
+from ns_orm.schema import acreate_all, create_all
+
+__all__ = [
+    "Array",
+    "BigInt",
+    "Binary",
+    "Boolean",
+    "Char",
+    "AsyncDatabase",
+    "Database",
+    "Date",
+    "Date32",
+    "DateTime",
+    "DateTime64",
+    "Decimal",
+    "Double",
+    "Enum16",
+    "Enum8",
+    "FixedString",
+    "Float",
+    "ForeignKey",
+    "IPv4",
+    "IPv6",
+    "Int",
+    "JSON",
+    "LowCardinality",
+    "Map",
+    "ManyToMany",
+    "Model",
+    "Nullable",
+    "OneToOne",
+    "Q",
+    "Real",
+    "SmallInt",
+    "String",
+    "Text",
+    "TinyInt",
+    "TupleType",
+    "UBigInt",
+    "USmallInt",
+    "UTinyInt",
+    "UInt",
+    "UUID",
+    "acreate_all",
+    "create_all",
+    "get_connection",
+    "register_connection",
+    "set_connection_provider",
+]

ns_orm/cli.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import argparse
+import importlib
+import sys
+from pathlib import Path
+from typing import Any, List, Optional
+
+from ns_orm.dialects import Dialect, dialect_from_url
+from ns_orm.migrations.autodetector import autodetect_migration
+from ns_orm.migrations.executor import MigrationExecutor
+from ns_orm.migrations.loader import MigrationLoader
+from ns_orm.migrations.writer import MigrationWriter
+from ns_orm.model import Model
+
+
+def _import_string(path: str) -> Any:
+    module_name, attr = path.rsplit(":", 1)
+    module = importlib.import_module(module_name)
+    return getattr(module, attr)
+
+
+def _load_models(modules: list[str]) -> list[type[Model]]:
+    out: list[type[Model]] = []
+    for m in modules:
+        importlib.import_module(m)
+    for cls in Model._registry.values():
+        if not isinstance(cls, type) or not issubclass(cls, Model):
+            continue
+        mod = getattr(cls, "__module__", "")
+        if any(mod == x or mod.startswith(x + ".") for x in modules):
+            out.append(cls)
+    unique = list(dict.fromkeys(out))
+    return unique
+
+
+def _dialect_from_arg(value: str) -> Dialect:
+    value = value.strip()
+    if "://" in value:
+        scheme = value.split("://", 1)[0]
+        return dialect_from_url(scheme)
+    return dialect_from_url(value)
+
+
+def _parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(prog="ns-orm")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    mk = sub.add_parser("makemigrations")
+    mk.add_argument(
+        "--models",
+        required=True,
+        help="模型模块路径，逗号分隔，例如: app.models,core.models",
+    )
+    mk.add_argument(
+        "--dialect",
+        required=True,
+        help="数据库方言或 URL scheme，例如: postgres 或 postgresql://",
+    )
+    mk.add_argument("--name", default="auto", help="迁移名称后缀，例如: add_user_email")
+    mk.add_argument("--migrations-dir", default="migrations", help="迁移文件输出目录")
+
+    mg = sub.add_parser("migrate")
+    mg.add_argument(
+        "--models",
+        required=True,
+        help="模型模块路径，逗号分隔，例如: app.models,core.models",
+    )
+    mg.add_argument(
+        "--dialect",
+        required=True,
+        help="数据库方言或 URL scheme，例如: postgres 或 postgresql://",
+    )
+    mg.add_argument(
+        "--db-factory",
+        required=True,
+        help="返回 ns_orm.Database/AsyncDatabase 的工厂函数路径，格式: pkg.module:func",
+    )
+    mg.add_argument("--migrations-dir", default="migrations", help="迁移文件目录")
+    mg.add_argument("--plan", action="store_true", help="仅输出计划，不执行")
+    mg.add_argument(
+        "--async", dest="is_async", action="store_true", help="使用异步执行器"
+    )
+
+    return parser.parse_args(argv)
+
+
+def main(argv: Optional[List[str]] = None) -> None:
+    ns = _parse_args(sys.argv[1:] if argv is None else argv)
+    models = [x.strip() for x in ns.models.split(",") if x.strip()]
+    if not models:
+        raise SystemExit("--models 不能为空")
+
+    dialect = _dialect_from_arg(ns.dialect)
+    migrations_dir = Path(ns.migrations_dir).resolve()
+
+    if ns.command == "makemigrations":
+        _cmd_makemigrations(
+            models=models,
+            dialect=dialect,
+            migrations_dir=migrations_dir,
+            name=ns.name,
+        )
+        return
+
+    if ns.command == "migrate":
+        _cmd_migrate(
+            models=models,
+            dialect=dialect,
+            migrations_dir=migrations_dir,
+            db_factory=ns.db_factory,
+            plan=bool(ns.plan),
+            is_async=bool(ns.is_async),
+        )
+        return
+
+    raise SystemExit(f"未知命令: {ns.command}")
+
+
+def _cmd_makemigrations(
+    *,
+    models: list[str],
+    dialect: Dialect,
+    migrations_dir: Path,
+    name: str,
+) -> None:
+    loaded_models = _load_models(models)
+    loader = MigrationLoader(migrations_dir=migrations_dir)
+    prev_state = loader.latest_state()
+
+    migration = autodetect_migration(
+        models=loaded_models,
+        dialect=dialect,
+        previous_state=prev_state,
+        name_suffix=name,
+    )
+    if migration is None:
+        print("No changes detected")
+        return
+
+    writer = MigrationWriter(migrations_dir=migrations_dir)
+    path = writer.write(migration)
+    print(str(path))
+
+
+def _cmd_migrate(
+    *,
+    models: list[str],
+    dialect: Dialect,
+    migrations_dir: Path,
+    db_factory: str,
+    plan: bool,
+    is_async: bool,
+) -> None:
+    _load_models(models)
+    loader = MigrationLoader(migrations_dir=migrations_dir)
+    factory = _import_string(db_factory)
+    db = factory(dialect)
+    executor = MigrationExecutor(
+        db=db, dialect=dialect, loader=loader, is_async=is_async
+    )
+
+    if plan:
+        for m in executor.plan():
+            print(f"{m.name}")
+        return
+
+    if is_async:
+        import asyncio
+
+        asyncio.run(executor.amigrate())
+        return
+
+    executor.migrate()

ns_orm/database.py

@@ -0,0 +1,292 @@
+from __future__ import annotations
+
+import contextlib
+from typing import (
+    Any,
+    AsyncGenerator,
+    Callable,
+    Dict,
+    Generator,
+    Optional,
+    Union,
+)
+
+from ns_orm.dialects import Dialect, PreparedSQL, dialect_from_url
+from ns_orm.exceptions import ConfigurationError, IntegrityError
+
+
+def _is_awaitable(v: Any) -> bool:
+    return hasattr(v, "__await__")
+
+
+def _require_callable(obj: Any, name: str) -> Callable[..., Any]:
+    fn = getattr(obj, name, None)
+    if fn is None or not callable(fn):
+        raise ConfigurationError(f"Database executor missing method: {name}")
+    return fn
+
+
+class LesscodeDatabaseExecutorAdapter:
+    def __init__(self, connect: Any):
+        self._connect = connect
+
+    def _call(self, names: list[str], *args: Any, **kwargs: Any) -> Any:
+        for n in names:
+            fn = getattr(self._connect, n, None)
+            if callable(fn):
+                return fn(*args, **kwargs)
+        raise ConfigurationError(
+            "lesscode-database connect object missing method: {}".format(
+                ", ".join(names)
+            )
+        )
+
+    def execute(self, sql: str, params: Any = None) -> Any:
+        if params is None:
+            return self._call(["execute", "exec", "run"], sql)
+        return self._call(["execute", "exec", "run"], sql, params)
+
+    def fetch_all(self, sql: str, params: Any = None) -> Any:
+        if params is None:
+            return self._call(
+                ["fetch_all", "fetchall", "query_all", "query", "select"], sql
+            )
+        return self._call(
+            ["fetch_all", "fetchall", "query_all", "query", "select"], sql, params
+        )
+
+    def fetch_one(self, sql: str, params: Any = None) -> Any:
+        fn = getattr(self._connect, "fetch_one", None)
+        if callable(fn):
+            return fn(sql, params) if params is not None else fn(sql)
+        fn = getattr(self._connect, "fetchone", None)
+        if callable(fn):
+            return fn(sql, params) if params is not None else fn(sql)
+        rows = self.fetch_all(sql, params)
+        if _is_awaitable(rows):
+
+            async def _coro():
+                data = await rows
+                return data[0] if data else None
+
+            return _coro()
+        return rows[0] if rows else None
+
+    def transaction(self) -> Any:
+        txn = getattr(self._connect, "transaction", None)
+        if callable(txn):
+            return txn()
+        return contextlib.nullcontext()
+
+
+class Database:
+    """
+    同步数据库执行器封装。
+
+    连接与连接池不由 ns-orm 负责，必须由外部库（例如 lesscode-database）
+    创建并传入 executor。
+
+    executor 最低需提供以下方法（duck-typing）：
+    - execute(sql, params=None) -> int | Any
+    - fetch_all(sql, params=None) -> list[dict]
+    - fetch_one(sql, params=None) -> dict | None
+
+    可选：
+    - transaction() -> context manager
+    """
+
+    def __init__(self, *, executor: Any, dialect: Dialect):
+        self.executor = executor
+        self.dialect = dialect
+        self._txn_depth: int = 0
+
+    @contextlib.contextmanager
+    def transaction(self) -> Generator[None, None, None]:
+        self._txn_depth += 1
+        try:
+            txn = getattr(self.executor, "transaction", None)
+            if callable(txn):
+                with txn():
+                    yield
+                return
+            yield
+        finally:
+            self._txn_depth = max(0, self._txn_depth - 1)
+
+    def _prepare(self, sql: str, params: Optional[Dict[str, Any]]) -> PreparedSQL:
+        params = params or {}
+        return self.dialect.prepare(sql, params)
+
+    def execute(self, sql: str, params: Optional[Dict[str, Any]] = None) -> int:
+        prepared = self._prepare(sql, params)
+        try:
+            fn = _require_callable(self.executor, "execute")
+            result = fn(prepared.sql, prepared.params)
+            if isinstance(result, int):
+                return result
+            return 0
+        except Exception as e:
+            raise IntegrityError(str(e)) from e
+
+    def executemany(self, sql: str, params_list: list[dict[str, Any]]) -> int:
+        if not params_list:
+            return 0
+        try:
+            fn = getattr(self.executor, "executemany", None)
+            if callable(fn):
+                prepared_list = [self._prepare(sql, p) for p in params_list]
+                if len({p.sql for p in prepared_list}) != 1:
+                    raise ConfigurationError(
+                        "executemany requires stable SQL after parameter preparation"
+                    )
+                result = fn(prepared_list[0].sql, [p.params for p in prepared_list])
+                return int(result) if isinstance(result, int) else 0
+
+            total = 0
+            for p in params_list:
+                total += self.execute(sql, p)
+            return total
+        except Exception as e:
+            raise IntegrityError(str(e)) from e
+
+    def fetch_all(
+        self, sql: str, params: Optional[Dict[str, Any]] = None
+    ) -> list[dict[str, Any]]:
+        prepared = self._prepare(sql, params)
+        fn = _require_callable(self.executor, "fetch_all")
+        rows = fn(prepared.sql, prepared.params)
+        if rows is None:
+            return []
+        return [dict(r) for r in rows]
+
+    def fetch_one(
+        self, sql: str, params: Optional[Dict[str, Any]] = None
+    ) -> Optional[dict[str, Any]]:
+        prepared = self._prepare(sql, params)
+        fn = _require_callable(self.executor, "fetch_one")
+        row = fn(prepared.sql, prepared.params)
+        return None if row is None else dict(row)
+
+
+class AsyncDatabase:
+    """
+    异步数据库执行器封装。
+
+    连接与连接池不由 ns-orm 负责，必须由外部库（例如 lesscode-database）
+    创建并传入 executor。
+
+    executor 最低需提供以下协程方法（duck-typing）：
+    - execute(sql, params=None) -> int | Any
+    - fetch_all(sql, params=None) -> list[dict]
+    - fetch_one(sql, params=None) -> dict | None
+
+    可选：
+    - transaction() -> async context manager
+    """
+
+    def __init__(self, *, executor: Any, dialect: Dialect):
+        self.executor = executor
+        self.dialect = dialect
+        self._txn_depth: int = 0
+
+    @contextlib.asynccontextmanager
+    async def transaction(self) -> AsyncGenerator[None, None]:
+        self._txn_depth += 1
+        try:
+            txn = getattr(self.executor, "transaction", None)
+            if callable(txn):
+                async with txn():
+                    yield
+                return
+            yield
+        finally:
+            self._txn_depth = max(0, self._txn_depth - 1)
+
+    def _prepare(self, sql: str, params: Optional[Dict[str, Any]]) -> PreparedSQL:
+        params = params or {}
+        return self.dialect.prepare(sql, params)
+
+    async def execute(self, sql: str, params: Optional[Dict[str, Any]] = None) -> int:
+        prepared = self._prepare(sql, params)
+        try:
+            fn = _require_callable(self.executor, "execute")
+            result = fn(prepared.sql, prepared.params)
+            if _is_awaitable(result):
+                result = await result
+            return int(result) if isinstance(result, int) else 0
+        except Exception as e:
+            raise IntegrityError(str(e)) from e
+
+    async def fetch_all(
+        self, sql: str, params: Optional[Dict[str, Any]] = None
+    ) -> list[dict[str, Any]]:
+        prepared = self._prepare(sql, params)
+        fn = _require_callable(self.executor, "fetch_all")
+        rows = fn(prepared.sql, prepared.params)
+        if _is_awaitable(rows):
+            rows = await rows
+        if rows is None:
+            return []
+        return [dict(r) for r in rows]
+
+    async def fetch_one(
+        self, sql: str, params: Optional[Dict[str, Any]] = None
+    ) -> Optional[dict[str, Any]]:
+        prepared = self._prepare(sql, params)
+        fn = _require_callable(self.executor, "fetch_one")
+        row = fn(prepared.sql, prepared.params)
+        if _is_awaitable(row):
+            row = await row
+        return None if row is None else dict(row)
+
+
+_connections: dict[str, Any] = {}
+_connection_provider: Callable[[str], Any] | None = None
+
+
+def register_connection(name: str, db: Union[Database, AsyncDatabase]) -> None:
+    _connections[name] = db
+
+
+def set_connection_provider(provider: Callable[[str], Any]) -> None:
+    global _connection_provider
+    _connection_provider = provider
+
+
+def _default_lesscode_database_provider(connect_name: str) -> Any:
+    try:
+        from lesscode_database.db_options import db_options  # type: ignore
+    except Exception as e:
+        raise ConfigurationError("lesscode-database is required") from e
+
+    if not connect_name:
+        raise ConfigurationError("connect_name is empty")
+
+    try:
+        connect, connect_info = getattr(db_options, connect_name)
+    except Exception as e:
+        raise ConfigurationError(f"Unknown connect_name: {connect_name}") from e
+
+    dialect = dialect_from_url(getattr(connect_info, "dialect", ""))
+    executor = LesscodeDatabaseExecutorAdapter(connect)
+
+    if bool(getattr(connect_info, "async_enable", False)):
+        return AsyncDatabase(executor=executor, dialect=dialect)
+    return Database(executor=executor, dialect=dialect)
+
+
+def _ensure_default_provider() -> None:
+    global _connection_provider
+    if _connection_provider is None:
+        _connection_provider = _default_lesscode_database_provider
+
+
+def get_connection(name: str) -> Any:
+    if name in _connections:
+        return _connections[name]
+    _ensure_default_provider()
+    if _connection_provider is not None:
+        db = _connection_provider(name)
+        _connections[name] = db
+        return db
+    raise ConfigurationError(f"Connection not found: {name}")