encino-orm 0.2.0__tar.gz

encino_orm-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    services:
+      mysql:
+        image: mysql:8.0
+        env:
+          MYSQL_ROOT_PASSWORD: admin
+          MYSQL_ROOT_HOST: "%"
+          MYSQL_DATABASE: encino_orm_test
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd="mysqladmin ping -h 127.0.0.1 --password=admin --silent"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=12
+
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: admin
+          POSTGRES_DB: encino_orm_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd="pg_isready -U postgres"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=12
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra http --extra security --extra graphql
+
+      - name: Run tests
+        env:
+          ENCINO_ORM_MYSQL_HOST: 127.0.0.1
+          ENCINO_ORM_MYSQL_PORT: "3306"
+          ENCINO_ORM_MYSQL_USER: root
+          ENCINO_ORM_MYSQL_PASSWORD: admin
+          ENCINO_ORM_MYSQL_DB: encino_orm_test
+          ENCINO_ORM_POSTGRES_HOST: 127.0.0.1
+          ENCINO_ORM_POSTGRES_PORT: "5432"
+          ENCINO_ORM_POSTGRES_USER: postgres
+          ENCINO_ORM_POSTGRES_PASSWORD: admin
+          ENCINO_ORM_POSTGRES_DB: encino_orm_test
+        run: uv run pytest -q

encino_orm-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write          # para trusted publishing (OIDC) si se usa
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build
+        run: uv build
+
+      # Publica a PyPI usando un token (secret PYPI_API_TOKEN).
+      # Alternativa sin token: Trusted Publishing (OIDC):
+      #   1. En PyPI > Settings > Publishing, añade el repo hvalles/encinorm
+      #      con el workflow "release.yml".
+      #   2. Sustituye este paso por: run: uv publish --trusted-publishing always
+      #      y elimina el env con el token.
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: uv publish
+
+      # Para probar contra TestPyPI de forma manual:
+      #   gh workflow run "Publish to PyPI" -f ... (o usa el botón "Run workflow")
+      # y comenta el paso anterior, descomentando:
+      # - name: Publish to TestPyPI
+      #   env:
+      #     UV_PUBLISH_TOKEN: ${{ secrets.TEST_PYPI_API_TOKEN }}
+      #   run: uv publish --publish-url https://test.pypi.org/legacy/

encino_orm-0.2.0/.gitignore

@@ -0,0 +1,25 @@
+# Entornos virtuales
+.venv/
+venv/
+env/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Pruebas y cobertura
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Entornos / editores
+.env
+.idea/
+.vscode/
+
+# Notas internas (no distribuir)
+prompts/

encino_orm-0.2.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+Todos los cambios notables del proyecto se documentan en este archivo.
+
+El formato sigue [Keep a Changelog](https://keepachangelog.com/es/1.1.0/) y el
+proyecto usa [Versionado Semántico](https://semver.org/lang/es/). Mientras esté
+en `0.x`, **no hay garantía de estabilidad** (ver `README.md`).
+
+## [Unreleased]
+
+### Añadido
+
+- `Model.cursor(db=None, **values)`: instancia de consulta sin validación de
+  pydantic, para operaciones de lectura (`load`/`search`/`count`/`paginate`) y
+  de esquema (`create_table`) sobre modelos con campos `required=True`, sin
+  recurrir a `model_construct()` manual.
+
+### Corregido
+
+- Ejemplos de `README.md` y `docs/getting-started.md` que requerían definir un
+  helper `_cursor()` manual: ahora usan el classmethod `cursor()`.
+
+## [0.1.0] - 2026-08-30
+
+### Añadido
+
+- Núcleo ORM asíncrono para SQLite, MySQL y PostgreSQL (`Db`, `PoolDb`,
+  `session`, `create_db`).
+- `Model` declarativo (basado en `pydantic`) con restricciones reutilizables
+  (`make_constraint` y presets `STR_*`, `INT`, `CURRENCY`, `DATETIME`,
+  `DECIMAL`, `JSON`, …).
+- CRUD completo: `insert`, `save`, `upsert`, `load`, `update`, `delete`,
+  `search`, `count`, `paginate`, `insert_many` (bulk).
+- Claves primarias simples (auto-incremental), naturales y **compuestas**, y
+  claves foráneas compuestas.
+- Relaciones 1:1 y 1:N con carga por lotes (`batch_reference`,
+  `batch_has_many`).
+- `Filter` componible y `QueryBuilder` con `join`, agregados y subconsultas.
+- Migraciones versionadas (`Migration`, `migrations_from_dir`), `create_table`,
+  `diff_schema` y `sync_schema`.
+- Conexión implícita (`set_default_db`, `bind`, `resolve_db`).
+- Capas opcionales: REST (FastAPI), GraphQL (Strawberry), seguridad (RBAC + JWT)
+  y codegen/CLI (`encino_orm generate models`).
+- Observabilidad (`trace_id`, `QueryTracer`) y caché (`CachedModel` +
+  `CacheBackend`).
+- Documentación de usuario (`README.md` y `docs/`), guía para agregar motores y
+  licencia MIT.

encino_orm-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 encino_orm contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

encino_orm-0.2.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.5
+Name: encino-orm
+Version: 0.2.0
+Summary: Librería asíncrona de interfaz unificada para SQLite, MySQL y PostgreSQL
+Project-URL: Repository, https://github.com/hvalles/encinorm
+Author-email: Hector <valles.hector@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: aiomysql<0.3.2,>=0.2
+Requires-Dist: aiosqlite
+Requires-Dist: asyncpg>=0.31.0
+Requires-Dist: pydantic>=2.13.4
+Provides-Extra: graphql
+Requires-Dist: strawberry-graphql>=0.200; extra == 'graphql'
+Provides-Extra: http
+Requires-Dist: fastapi>=0.110; extra == 'http'
+Provides-Extra: security
+Requires-Dist: fastapi>=0.110; extra == 'security'
+Requires-Dist: pyjwt<2.13,>=2.8; extra == 'security'
+Description-Content-Type: text/markdown
+
+# encino_orm · v0.2.0
+
+ORM asíncrono de interfaz unificada para **SQLite**, **MySQL** y **PostgreSQL**,
+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.2.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/`;
+> estado de preparación en `prompts/analisys-07.md`.
+
+---
+
+## Características
+
+- **Tres motores** con un único API: `SqliteDb`, `MysqlDb`, `PostgresDb`, 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**: `set_default_db`, `bind` y `session` eliminan la
+  necesidad de pasar `db` a cada instancia.
+- **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
+
+```bash
+# núcleo (SQLite + MySQL + PostgreSQL)
+pip install -e .
+
+# con extras opcionales
+pip install -e ".[http,security,graphql]"
+```
+
+Extras disponibles:
+
+| Extra      | Incluye                                              |
+|------------|------------------------------------------------------|
+| `http`     | `fastapi` (REST CRUD)                                 |
+| `security` | `fastapi` + `PyJWT` (RBAC + JWT)                      |
+| `graphql`  | `strawberry-graphql` (GraphQL)                        |
+
+Requiere **Python 3.10+**.
+
+---
+
+## Inicio rápido
+
+```python
+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](docs/getting-started.md) | Instalación y primer modelo en 5 minutos. |
+| [Guía de uso](docs/guide.md) | Modelos, restricciones, CRUD, filtros, relaciones, claves primarias y foráneas. |
+| [Integraciones](docs/integrations.md) | REST, GraphQL, seguridad, codegen/CLI y observabilidad. |
+| [Agregar un motor](docs/engines.md) | Guía para desarrolladores: cómo añadir un nuevo motor de base de datos. |
+| [Créditos](docs/credits.md) | Herramientas y tecnologías utilizadas. |
+| [Diseño](docs/) | Documentos de diseño (`design_*.md`) de la arquitectura interna. |
+
+---
+
+## Pruebas
+
+```bash
+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 y PostgreSQL se omiten automáticamente si el servidor
+correspondiente no está disponible.
+
+---
+
+## Licencia
+
+Distribuido bajo la licencia [MIT](LICENSE). Consulta el archivo `LICENSE`
+para el texto íntegro.
+
+---
+
+## Versionado
+
+El proyecto sigue [Versionado Semántico](https://semver.org). 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](https://opencode.ai)** y el modelo
+**[DeepSeek V4 Pro](https://www.deepseek.com)**. Véase
+[docs/credits.md](docs/credits.md) para el detalle completo.

encino_orm-0.2.0/README.md

@@ -0,0 +1,146 @@
+# encino_orm · v0.2.0
+
+ORM asíncrono de interfaz unificada para **SQLite**, **MySQL** y **PostgreSQL**,
+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.2.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/`;
+> estado de preparación en `prompts/analisys-07.md`.
+
+---
+
+## Características
+
+- **Tres motores** con un único API: `SqliteDb`, `MysqlDb`, `PostgresDb`, 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**: `set_default_db`, `bind` y `session` eliminan la
+  necesidad de pasar `db` a cada instancia.
+- **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
+
+```bash
+# núcleo (SQLite + MySQL + PostgreSQL)
+pip install -e .
+
+# con extras opcionales
+pip install -e ".[http,security,graphql]"
+```
+
+Extras disponibles:
+
+| Extra      | Incluye                                              |
+|------------|------------------------------------------------------|
+| `http`     | `fastapi` (REST CRUD)                                 |
+| `security` | `fastapi` + `PyJWT` (RBAC + JWT)                      |
+| `graphql`  | `strawberry-graphql` (GraphQL)                        |
+
+Requiere **Python 3.10+**.
+
+---
+
+## Inicio rápido
+
+```python
+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](docs/getting-started.md) | Instalación y primer modelo en 5 minutos. |
+| [Guía de uso](docs/guide.md) | Modelos, restricciones, CRUD, filtros, relaciones, claves primarias y foráneas. |
+| [Integraciones](docs/integrations.md) | REST, GraphQL, seguridad, codegen/CLI y observabilidad. |
+| [Agregar un motor](docs/engines.md) | Guía para desarrolladores: cómo añadir un nuevo motor de base de datos. |
+| [Créditos](docs/credits.md) | Herramientas y tecnologías utilizadas. |
+| [Diseño](docs/) | Documentos de diseño (`design_*.md`) de la arquitectura interna. |
+
+---
+
+## Pruebas
+
+```bash
+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 y PostgreSQL se omiten automáticamente si el servidor
+correspondiente no está disponible.
+
+---
+
+## Licencia
+
+Distribuido bajo la licencia [MIT](LICENSE). Consulta el archivo `LICENSE`
+para el texto íntegro.
+
+---
+
+## Versionado
+
+El proyecto sigue [Versionado Semántico](https://semver.org). 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](https://opencode.ai)** y el modelo
+**[DeepSeek V4 Pro](https://www.deepseek.com)**. Véase
+[docs/credits.md](docs/credits.md) para el detalle completo.

encino_orm-0.2.0/docs/credits.md

@@ -0,0 +1,36 @@
+# Créditos
+
+Este proyecto fue desarrollado con la asistencia de las siguientes herramientas
+de inteligencia artificial:
+
+## OpenCode
+
+- **Sitio:** <https://opencode.ai>
+- **Rol:** agente de codificación en terminal utilizado para explorar el
+  repositorio, redactar e implementar los cambios del núcleo ORM, las capas de
+  producto (REST, GraphQL, seguridad, codegen), la documentación de usuario y los
+  documentos de diseño.
+
+## DeepSeek V4 Pro
+
+- **Modelo:** `deepseek/deepseek-v4-pro`
+- **Rol:** modelo de lenguaje que impulsa la generación de código, el análisis de
+  los documentos `prompts/analisys-*.md` y la redacción de `docs/*.md`.
+
+## Dependencias y ecosistema
+
+El proyecto se apoya en las siguientes bibliotecas de código abierto:
+
+| Biblioteca           | Uso                                        |
+|----------------------|--------------------------------------------|
+| `pydantic`           | Validación y modelos de datos.             |
+| `aiosqlite`          | Driver asíncrono de SQLite.                |
+| `aiomysql`           | Driver asíncrono de MySQL.                 |
+| `asyncpg`            | Driver asíncrono de PostgreSQL.            |
+| `fastapi`            | Capa REST (extra `http`/`security`).       |
+| `PyJWT`              | Tokens JWT (extra `security`).             |
+| `strawberry-graphql` | Capa GraphQL (extra `graphql`).            |
+| `pytest`             | Suite de pruebas (dev).                    |
+| `httpx`              | Cliente de pruebas ASGI (dev).             |
+
+Gracias a los mantenedores de estas herramientas por su trabajo.