encino-orm 0.2.0__py3-none-any.whl

encino_orm/__init__.py

@@ -0,0 +1,62 @@
+from .base import Db
+from .context import bind, get_default_db, resolve_db, set_default_db
+from .engine import Engine, engine_of, is_mysql, is_postgres, is_sqlite
+from .query import Query
+from .sql import SqlFunctions, Weekday
+from .sqlite import SqliteDb
+from .mysql import MysqlDb
+from .postgresql import PostgresDb
+from .pool import PoolDb, create_db, session
+from .observability import OtelQueryTracer, QueryTracer, current_trace_id, trace_id
+from .migration import (
+    Migration,
+    apply_migration,
+    apply_migrations,
+    migrations_from_dir,
+    rollback_migration,
+)
+from .exceptions import (
+    EncinoOrmError,
+    ConnectionError,
+    QueryError,
+    UnsupportedEngineError,
+    MigrationError,
+    PoolExhaustedError,
+)
+
+__all__ = [
+    "Db",
+    "Query",
+    "Engine",
+    "engine_of",
+    "is_sqlite",
+    "is_mysql",
+    "is_postgres",
+    "SqlFunctions",
+    "Weekday",
+    "SqliteDb",
+    "MysqlDb",
+    "PostgresDb",
+    "PoolDb",
+    "create_db",
+    "session",
+    "set_default_db",
+    "get_default_db",
+    "bind",
+    "resolve_db",
+    "QueryTracer",
+    "OtelQueryTracer",
+    "trace_id",
+    "current_trace_id",
+    "Migration",
+    "apply_migration",
+    "apply_migrations",
+    "migrations_from_dir",
+    "rollback_migration",
+    "EncinoOrmError",
+    "ConnectionError",
+    "QueryError",
+    "UnsupportedEngineError",
+    "MigrationError",
+    "PoolExhaustedError",
+]

encino_orm/base.py

@@ -0,0 +1,162 @@
+import asyncio
+import logging
+import random
+from abc import ABC, abstractmethod
+from contextlib import asynccontextmanager
+
+from .query import Query
+
+logger = logging.getLogger("encino_orm")
+
+
+class Db(ABC):
+    MAX_TRIES = 9
+    WAITERS = [x * 0.02 for x in range(1, 11)]
+    MAX_WAIT = len(WAITERS) - 1
+
+    dialect: str = ""
+
+    @property
+    def fn(self):
+        """Namespace de funciones SQL portables (`db.fn.now()`, `db.fn.date_add(...)`)."""
+        from .sql import SqlFunctions
+
+        return SqlFunctions(self.dialect)
+
+    @abstractmethod
+    async def connect(self, **kwargs): ...
+
+    @abstractmethod
+    async def close(self): ...
+
+    @abstractmethod
+    async def is_alive(self): ...
+
+    @abstractmethod
+    async def in_transaction(self): ...
+
+    @asynccontextmanager
+    async def transaction(self):
+        try:
+            yield
+            await self.commit()
+        except Exception:
+            await self.rollback()
+            raise
+
+    @abstractmethod
+    async def commit(self): ...
+
+    @abstractmethod
+    async def rollback(self, save_point: str = None): ...
+
+    @abstractmethod
+    async def save_point(self, name: str): ...
+
+    @staticmethod
+    async def wait(waiter: int = -1):
+        """Mecanismo de espera en caso de bloqueo por deadlock en la base de datos."""
+        if waiter < 0:
+            waiter = random.randint(0, Db.MAX_WAIT)
+        await asyncio.sleep(Db.WAITERS[waiter])
+        return waiter
+
+    def is_lock_error(self, exc: Exception) -> bool:
+        """Indica si `exc` corresponde a un error de bloqueo/deadlock re-reintentable."""
+        return False
+
+    async def retry(self, coro, tries: int = None):
+        """Reintenta una coroutine ante errores de bloqueo (deadlock)."""
+        max_tries = tries if tries is not None else self.MAX_TRIES
+        last_exc = None
+        for attempt in range(max_tries):
+            try:
+                return await coro()
+            except Exception as exc:
+                if not self.is_lock_error(exc):
+                    raise
+                last_exc = exc
+                if attempt + 1 >= max_tries:
+                    break
+                await self.wait()
+        raise last_exc
+
+    @abstractmethod
+    def insert(self, tabla: str, data: dict, ignore_duplicated=False, replace=False): ...
+
+    @abstractmethod
+    def delete(self, tabla: str, keys: dict): ...
+
+    @abstractmethod
+    def update(self, tabla: str, keys: dict, values: dict): ...
+
+    @abstractmethod
+    async def execute(self, qry: Query): ...
+
+    @abstractmethod
+    async def fetch_all(self, qry: Query): ...
+
+    @abstractmethod
+    async def fetch_one(self, qry: Query): ...
+
+    @abstractmethod
+    async def fetch_many(self, qry: Query, limit: int, page: int): ...
+
+    @abstractmethod
+    async def exists(self, qry: Query): ...
+
+    @abstractmethod
+    async def last_id(self): ...
+
+    @abstractmethod
+    async def migrate(self, name: str, qry: Query): ...
+
+    @abstractmethod
+    async def migrate_status(self): ...
+
+    def _tables_sql(self) -> str:
+        """SQL base que lista las tablas del catálogo (por motor).
+
+        Opcional: los motores que no lo implementen no soportan `list_tables`.
+        """
+        raise NotImplementedError("introspección no soportada para este motor")
+
+    async def columns_of(self, table: str) -> list:
+        """Devuelve la especificación de columnas de una tabla (por motor).
+
+        Opcional: los motores que no lo implementen no soportan `columns_of`.
+        """
+        raise NotImplementedError("introspección no soportada para este motor")
+
+    async def list_tables(self, *, name: str = "", limit: int = 50, page: int = 1):
+        """Lista las tablas del catálogo con filtro por nombre y paginación."""
+        from .model.records import Records
+
+        sql = self._tables_sql()
+        params = []
+        if name:
+            sql += " AND name LIKE {0}"
+            params.append(f"%{name}%")
+        total = (await self.fetch_one(Query(f"SELECT COUNT(*) FROM ({sql})", params)))["COUNT(*)"]
+        rows = await self.fetch_many(Query(sql, params), limit, page)
+        return Records(rows=rows, total=total, limit=limit, page=page)
+
+    async def paginate(self, qry: Query, limit: int, page: int = 1):
+        """Devuelve un `Records` con la página y el total de un `Query` raw.
+
+        El total se calcula envolviendo el SQL en
+        ``SELECT COUNT(*) AS n FROM (...)``, por lo que solo es fiable para
+        SELECT simples (sin ``;`` final, sin su propio ``LIMIT``/``OFFSET`` y sin
+        cláusulas no re-embebibles como ``FOR UPDATE``). Conviene incluir
+        ``ORDER BY`` en el SQL para una paginación estable.
+        """
+        from .model.records import Records
+
+        rows = await self.fetch_many(qry, limit, page)
+        sql = qry.sql_template.strip().rstrip(";")
+        count_qry = Query(
+            f"SELECT COUNT(*) AS n FROM ({sql}) _encino_orm_count", list(qry.fields)
+        )
+        row = await self.fetch_one(count_qry)
+        total = row["n"] if row else 0
+        return Records(rows=rows, total=total, limit=limit, page=page)

encino_orm/cli.py

@@ -0,0 +1,139 @@
+"""CLI de encino_orm (solo stdlib `argparse`).
+
+Subcomandos: `encino_orm generate models <engine> [tablas...]` y
+`encino_orm copy <src-engine> <dst-engine> [tablas...]`.
+"""
+
+import argparse
+import asyncio
+import sys
+
+from .engine import Engine
+
+_ENGINE_CHOICES = [e.value for e in Engine]
+
+
+def _add_conn_args(parser, prefix: str, label: str):
+    def flag(name):
+        return f"--{prefix}-{name}" if prefix else f"--{name}"
+
+    parser.add_argument(flag("database"), help=f"archivo (sqlite) o nombre de BD {label}")
+    parser.add_argument(flag("host"), help=f"host {label} (mysql/postgresql)")
+    parser.add_argument(flag("port"), type=int, help=f"puerto {label} (mysql/postgresql)")
+    parser.add_argument(flag("user"), help=f"usuario {label} (mysql/postgresql)")
+    parser.add_argument(flag("password"), help=f"contraseña {label} (mysql/postgresql)")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="encino_orm",
+        description="Herramientas de encino_orm (codegen y copia de datos).",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    gen = sub.add_parser("generate", help="genera código desde la base de datos")
+    gen_sub = gen.add_subparsers(dest="subcommand")
+
+    models = gen_sub.add_parser("models", help="genera modelos desde tablas existentes")
+    models.add_argument("engine", choices=_ENGINE_CHOICES)
+    models.add_argument("tables", nargs="*", help="tablas a generar (default: todas)")
+    models.add_argument("--folder", default="models", help="carpeta de salida (default: models)")
+    _add_conn_args(models, "", "")
+
+    copy = sub.add_parser("copy", help="copia tablas/BD completa entre bases de datos")
+    copy.add_argument("src_engine", choices=_ENGINE_CHOICES)
+    copy.add_argument("dst_engine", choices=_ENGINE_CHOICES)
+    copy.add_argument("tables", nargs="*", help="tablas a copiar (default: todas)")
+    copy.add_argument("--create", action="store_true", help="crea las tablas en destino")
+    copy.add_argument("--truncate", action="store_true", help="vacía cada tabla destino antes de copiar")
+    copy.add_argument("--no-preserve-ids", action="store_true",
+                      help="no copiar la PK auto-incremental (dejar que el destino la asigne)")
+    copy.add_argument("--no-disable-fk", action="store_true",
+                      help="no desactivar las restricciones de FK durante la copia")
+    _add_conn_args(copy, "src", "origen")
+    _add_conn_args(copy, "dst", "destino")
+
+    return parser
+
+
+def _conn_kwargs(args) -> dict:
+    return _conn_kwargs_prefixed(args, "engine", "")
+
+
+def _conn_kwargs_prefixed(args, engine_attr: str, prefix: str) -> dict:
+    engine = getattr(args, engine_attr)
+
+    def get(name):
+        full = f"{prefix}_{name}" if prefix else name
+        return getattr(args, full, None)
+
+    if engine == Engine.SQLITE:
+        return {"database": get("database") or ":memory:"}
+    kw = {}
+    if get("host"):
+        kw["host"] = get("host")
+    if get("port"):
+        kw["port"] = get("port")
+    if get("user"):
+        kw["user"] = get("user")
+    if get("password"):
+        kw["password"] = get("password")
+    if get("database"):
+        kw["db" if engine == Engine.MYSQL else "database"] = get("database")
+    return kw
+
+
+async def _generate_models(args) -> int:
+    from .introspection import generate_model, list_tables
+    from .pool import create_db
+
+    db = await create_db(args.engine, **_conn_kwargs(args))
+    try:
+        tables = args.tables or [r["name"] for r in (await list_tables(db)).rows]
+        for table in tables:
+            print(await generate_model(db, table, folder=args.folder))
+        return 0
+    finally:
+        await db.close()
+
+
+async def _copy(args) -> int:
+    from .pool import create_db
+    from .transfer import copy_database
+
+    src = await create_db(args.src_engine, **_conn_kwargs_prefixed(args, "src_engine", "src"))
+    try:
+        dst = await create_db(args.dst_engine, **_conn_kwargs_prefixed(args, "dst_engine", "dst"))
+        try:
+            result = await copy_database(
+                src, dst, tables=args.tables or None,
+                create=args.create, truncate=args.truncate,
+                preserve_ids=not args.no_preserve_ids,
+                disable_fk=not args.no_disable_fk,
+            )
+            for table, count in result.items():
+                print(f"{table}: {count} filas")
+            return 0
+        finally:
+            await dst.close()
+    finally:
+        await src.close()
+
+
+def main(argv=None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "generate" and args.subcommand == "models":
+        try:
+            return asyncio.run(_generate_models(args))
+        except Exception as exc:  # pragma: no cover - depende del entorno
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+    if args.command == "copy":
+        try:
+            return asyncio.run(_copy(args))
+        except Exception as exc:  # pragma: no cover - depende del entorno
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+    parser.print_help()
+    return 1

encino_orm/context.py

@@ -0,0 +1,61 @@
+"""Conexión por defecto / ambiente para `Model` sin `db` explícito.
+
+Proporciona un "singleton" de conexión (por proceso) y un enlace ambiente por
+tarea/contexto (`contextvars`), de modo que los `Model` puedan resolver su
+conexión de forma implícita. El orden de resolución es:
+
+1. `db` explícito (constructor/método).
+2. transacción activa del pool (`_current_connection`).
+3. `bind()` / `session()` (ambiente).
+4. `set_default_db()` (proceso).
+5. error `ConnectionError`.
+"""
+
+import contextvars
+from contextlib import contextmanager
+
+from .exceptions import ConnectionError
+
+# Conexión/pool por defecto de TODO el proceso (el "singleton").
+_default_db = None
+
+# Conexión ambiente por tarea/contexto (bind / session).
+_ambient_db = contextvars.ContextVar("encino_orm_ambient_db", default=None)
+
+
+def set_default_db(db) -> None:
+    """Registra la conexión o pool por defecto del proceso."""
+    global _default_db
+    _default_db = db
+
+
+def get_default_db():
+    """Devuelve la conexión/pool por defecto del proceso, o `None`."""
+    return _default_db
+
+
+@contextmanager
+def bind(db):
+    """Establece la conexión ambiente para el bloque (async-safe vía contextvar)."""
+    token = _ambient_db.set(db)
+    try:
+        yield db
+    finally:
+        _ambient_db.reset(token)
+
+
+def resolve_db():
+    """Resuelve la conexión actual. Lanza `ConnectionError` si no hay ninguna."""
+    from .pool import _current_connection  # lazy: evita import circular
+
+    conn = _current_connection.get()        # 1. transacción activa del pool
+    if conn is not None:
+        return conn
+    ambient = _ambient_db.get()             # 2. bind()/session()
+    if ambient is not None:
+        return ambient
+    if _default_db is not None:             # 3. set_default_db()
+        return _default_db
+    raise ConnectionError(
+        "Sin conexión: pasa `db`, usa `bind()`, `set_default_db()` o `session()`"
+    )

encino_orm/engine.py

@@ -0,0 +1,45 @@
+"""Identificación tipada de motores de base de datos."""
+
+from enum import Enum
+
+
+class Engine(str, Enum):
+    """Motores soportados (miembro `str`, comparable con su valor).
+
+    ``Engine.SQLITE == "sqlite"`` es `True`; para claves de dict/parámetros que
+    exigen `str` usa ``engine.value``.
+    """
+
+    SQLITE = "sqlite"
+    MYSQL = "mysql"
+    POSTGRESQL = "postgresql"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+def engine_of(db) -> Engine:
+    """Devuelve el motor activo como `Engine`.
+
+    Acepta un `Db`/`PoolDb` (lee `dialect`), un `Engine` (se devuelve tal cual) o
+    una cadena (`"sqlite"`/`"mysql"`/`"postgresql"`). Un valor desconocido lanza
+    `ValueError`.
+    """
+    if isinstance(db, Engine):
+        return db
+    dialect = getattr(db, "dialect", db)
+    if isinstance(dialect, Engine):
+        return dialect
+    return Engine(dialect)
+
+
+def is_sqlite(db) -> bool:
+    return engine_of(db) is Engine.SQLITE
+
+
+def is_mysql(db) -> bool:
+    return engine_of(db) is Engine.MYSQL
+
+
+def is_postgres(db) -> bool:
+    return engine_of(db) is Engine.POSTGRESQL

encino_orm/exceptions.py

@@ -0,0 +1,22 @@
+class EncinoOrmError(Exception):
+    pass
+
+
+class ConnectionError(EncinoOrmError):
+    pass
+
+
+class QueryError(EncinoOrmError):
+    pass
+
+
+class UnsupportedEngineError(EncinoOrmError):
+    pass
+
+
+class MigrationError(EncinoOrmError):
+    pass
+
+
+class PoolExhaustedError(EncinoOrmError):
+    pass

encino_orm/graphql/__init__.py

@@ -0,0 +1,9 @@
+"""Subpaquete opcional `encino_orm.graphql` (Strawberry GraphQL).
+
+Genera tipos, queries y mutations a partir de los `Model` de encino_orm.
+`strawberry-graphql` es dependencia opcional (extras `graphql`).
+"""
+
+from .schema import build_schema
+
+__all__ = ["build_schema"]