Skip to content
hvallesPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

encino_orm · v0.3.0

ORM asíncrono de interfaz unificada para SQLite, MySQL, MariaDB, PostgreSQL, SQL Server y Oracle, construido sobre pydantic. Proporciona un modelo de datos declarativo, CRUD tipado, validación, relaciones (1:1 y 1:N), consultas con filtros y agregados, migraciones, y capas opcionales de producto: REST (FastAPI), GraphQL (Strawberry), seguridad (RBAC + JWT) y generación de código desde la base de datos.

Estado: experimental (v0.3.0). encino_orm se encuentra en fase experimental: la API pública y su comportamiento pueden cambiar sin previo aviso en versiones posteriores, sin garantía de compatibilidad retroactiva. El núcleo ORM está probado sobre los tres motores (más de 350 pruebas, con integraciones reales de MySQL y PostgreSQL), pero no se recomienda depender de una API estable en producción. Documentación de usuario en docs/; el detalle de los cambios incompatibles de esta versión vive en CHANGELOG.md y en la guía de migración a 0.3.0.


Características

  • Seis motores con un único API: SqliteDb, MysqlDb, MariadbDb, PostgresDb, MssqlDb y OracleDb, y un pool de conexiones PoolDb con transacciones atómicas por contextvar.
  • Modelos declarativos basados en pydantic, con restricciones reutilizables (STR_100, INT_POS, CURRENCY, DATETIME, DECIMAL, JSON, …).
  • CRUD completo: insert, save, upsert, load, update, delete, search, count, paginate, insert_many (bulk).
  • Claves primarias flexibles: id auto-incremental (por defecto), clave natural simple o clave compuesta, y claves foráneas compuestas.
  • Relaciones: referencias 1:1, colecciones 1:N (has_many), y carga por lotes (batch_reference/batch_has_many) para evitar N+1.
  • Consultas: Filter componible y QueryBuilder con join, group_by, agregados (sum/avg/min/max/count) y subconsultas.
  • Esquema: create_table, migraciones versionadas, diff_schema y sync_schema.
  • Hooks de ciclo de vida y caché (CachedModel + CacheBackend).
  • Conexión implícita: un ConnectionRegistry inyectable, más bind y session, eliminan la necesidad de pasar db a cada instancia. set_default_db/get_default_db siguen disponibles pero están deprecados (emiten DeprecationWarning); usa ConnectionRegistry (ver contexto).
  • Observabilidad: trace_id por request y QueryTracer con métricas.
  • Capas opcionales: REST (create_crud), GraphQL (build_schema), seguridad (emit_token, require, RBAC tri-estado) y CLI/codegen (encino_orm generate models).

Instalación

Para instalar la librería desde PyPI, fija la versión con ~=:

pip install "encino-orm~=0.2.6"

El operador ~= acepta únicamente parches de la misma minor (0.2.x) y no salta a la siguiente minor. Durante la ventana 0.x esto es esencial: pip no trata las versiones 0.x como especiales para un rango abierto (>=), de modo que pip install/pip install -U puede entrar en una minor nueva y auto-instalar sus cambios incompatibles. Con encino-orm~=0.2.6, una futura 0.3.0 solo se instala si la pides explícitamente.

Para desarrollo sobre el repositorio, instala en modo editable:

# núcleo (SQLite + MySQL + MariaDB + PostgreSQL)
pip install -e .

# con extras opcionales
pip install -e ".[http,security,graphql]"

# caché en Redis (CachedModel + RedisCacheBackend)
pip install -e ".[cache]"

# motores opcionales (SQL Server / Oracle)
pip install -e ".[mssql,oracle]"

Extras disponibles:

Extra Incluye
http fastapi (REST CRUD)
security fastapi + PyJWT (RBAC + JWT)
graphql strawberry-graphql (GraphQL)
cache redis (CachedModel + RedisCacheBackend)
mssql aioodbc + pyodbc (SQL Server, requiere ODBC Driver 18)
oracle oracledb (Oracle, modo thin)
all-db mssql + oracle

Requiere Python 3.10+.


Inicio rápido

import asyncio
from encino_orm import create_db
from encino_orm.model import Model, Filter, STR_100, INT_POS

class User(Model):
    _table = "users"
    name: STR_100(required=True)
    age: INT_POS()

async def main():
    db = await create_db("sqlite", database=":memory:")

    await User.cursor(db).create_table()       # genera el DDL y lo aplica

    u = User(db, name="Ana", age=30)
    await u.insert()                           # INSERT (id auto-incremental)

    found = await User.cursor(db, id=u.id).load()   # SELECT por clave primaria
    assert found.name == "Ana"

    adults = await User.cursor(db).search(Filter.ge("age", 18))  # SELECT ... WHERE age >= 18
    assert len(adults) == 1

    await db.close()

Ejemplo completo (incluidos Filter y las capas REST/GraphQL) en docs/getting-started.md.


Documentación

Documento Contenido
Getting started Instalación y primer modelo en 5 minutos.
Migración a 0.3.0 Rupturas acumuladas desde 0.2.6, con pares Antes/Después y la acción concreta para adaptar tu código.
Guía de uso Modelos, restricciones, CRUD, filtros, relaciones, claves primarias y foráneas.
Integraciones REST, GraphQL, seguridad, codegen/CLI y observabilidad.
Agregar un motor Guía para desarrolladores: cómo añadir un nuevo motor de base de datos.
Créditos Herramientas y tecnologías utilizadas.
Diseño Documentos de diseño (design_*.md) de la arquitectura interna.

Pruebas

uv run pytest              # suite completa (SQLite + MySQL + PostgreSQL)
uv run pytest -m "not integration"   # (si los servidores no están disponibles)

Las integraciones de MySQL, MariaDB, PostgreSQL, SQL Server y Oracle se omiten automáticamente si el servidor correspondiente no está disponible.

Credenciales SOLO para desarrollo local. Las credenciales de docker-compose.yml y de .env.example son valores desechables de juguete, pensados exclusivamente para levantar los servicios de prueba en tu máquina. Nunca las uses en producción: sustitúyelas siempre por secretos gestionados (variables de entorno del despliegue o un gestor de secretos).


Licencia

Distribuido bajo la licencia MIT. Consulta el archivo LICENSE para el texto íntegro.


Versionado

El proyecto sigue Versionado Semántico. Mientras esté en 0.x, no hay garantía de estabilidad: cada versión minor puede introducir cambios incompatibles. La estabilidad de la API se declarará a partir de 1.0.0.


Créditos

Desarrollado con la asistencia de OpenCode y el modelo DeepSeek V4 Pro. Véase docs/credits.md para el detalle completo.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages