mtpk-postgres 0.1.0__tar.gz

mtpk_postgres-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 José Jesús Andrés Zambrana
+
+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.

mtpk_postgres-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: mtpk_postgres
+Version: 0.1.0
+Summary: Librería para sincronización estructural de bases de datos Postgres con modelos Python (adaptación de mtpk_mariadb)
+Author-email: José Jesús Andrés Zambrana <jjandres@multiplika.es>
+License: MIT
+Project-URL: Homepage, https://github.com/jjandres/mtpk_postgres
+Project-URL: Repository, https://github.com/jjandres/mtpk_postgres
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Database
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psycopg[binary,pool]
+Requires-Dist: pydantic
+Requires-Dist: bcrypt
+Dynamic: license-file
+
+# mtpk_postgres
+
+Adaptación a Postgres (vía [psycopg 3](https://www.psycopg.org/psycopg3/)) de `mtpk_mariadb`: define tus tablas con
+dataclasses (`Tabla`, `Columna`, `ForeignKey`, `Index`), sincroniza la estructura de la base de datos automáticamente
+(CREATE/ALTER TABLE, índices, claves foráneas) y usa `AsyncCrudBase` para CRUD asíncrono.
+
+No modifica ni depende de `mtpk_mariadb`; es un paquete independiente. Ver `docs/mtpk-postgres-adaptacion.md` en el
+repo para el detalle de las diferencias frente a la versión MariaDB.
+
+## Instalación
+
+```
+pip install -e .
+```
+
+## Notas de la adaptación
+
+- Identificadores citados con `"comillas dobles"` en vez de backticks.
+- `auto_increment=True` genera `GENERATED ALWAYS AS IDENTITY` en vez de `AUTO_INCREMENT`; como Postgres no tiene
+  `lastrowid`, las inserciones vía `AsyncCrudBase.insert()`/`insertar()` añaden `RETURNING id`.
+- `Tabla.to_sql()` ya no incluye índices ni comentarios inline (Postgres no lo permite dentro de `CREATE TABLE`):
+  usa `Tabla.to_sql_indices()` y `Tabla.to_sql_comentarios()` para las sentencias `CREATE INDEX` y `COMMENT ON`
+  correspondientes. `ManagerDB` ya las ejecuta automáticamente al crear tablas.
+- `ENUM`/`SET` se traducen a `TEXT` + `CHECK`; al reconstruir la estructura desde la base de datos ambos se
+  reportan como `ENUM` (Postgres no permite distinguirlos después del hecho).
+- A diferencia de MariaDB, el DDL en Postgres es transaccional: los métodos de `ManagerDB` confirman (`COMMIT`)
+  explícitamente tras crear tablas, triggers y procedimientos.

mtpk_postgres-0.1.0/README.md

@@ -0,0 +1,27 @@
+# mtpk_postgres
+
+Adaptación a Postgres (vía [psycopg 3](https://www.psycopg.org/psycopg3/)) de `mtpk_mariadb`: define tus tablas con
+dataclasses (`Tabla`, `Columna`, `ForeignKey`, `Index`), sincroniza la estructura de la base de datos automáticamente
+(CREATE/ALTER TABLE, índices, claves foráneas) y usa `AsyncCrudBase` para CRUD asíncrono.
+
+No modifica ni depende de `mtpk_mariadb`; es un paquete independiente. Ver `docs/mtpk-postgres-adaptacion.md` en el
+repo para el detalle de las diferencias frente a la versión MariaDB.
+
+## Instalación
+
+```
+pip install -e .
+```
+
+## Notas de la adaptación
+
+- Identificadores citados con `"comillas dobles"` en vez de backticks.
+- `auto_increment=True` genera `GENERATED ALWAYS AS IDENTITY` en vez de `AUTO_INCREMENT`; como Postgres no tiene
+  `lastrowid`, las inserciones vía `AsyncCrudBase.insert()`/`insertar()` añaden `RETURNING id`.
+- `Tabla.to_sql()` ya no incluye índices ni comentarios inline (Postgres no lo permite dentro de `CREATE TABLE`):
+  usa `Tabla.to_sql_indices()` y `Tabla.to_sql_comentarios()` para las sentencias `CREATE INDEX` y `COMMENT ON`
+  correspondientes. `ManagerDB` ya las ejecuta automáticamente al crear tablas.
+- `ENUM`/`SET` se traducen a `TEXT` + `CHECK`; al reconstruir la estructura desde la base de datos ambos se
+  reportan como `ENUM` (Postgres no permite distinguirlos después del hecho).
+- A diferencia de MariaDB, el DDL en Postgres es transaccional: los métodos de `ManagerDB` confirman (`COMMIT`)
+  explícitamente tras crear tablas, triggers y procedimientos.

mtpk_postgres-0.1.0/mtpk_postgres/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.1.0"
+__author__ = "jjandres"
+
+from .interface import *
+from .crud import AsyncCrudBase

mtpk_postgres-0.1.0/mtpk_postgres/async_adapter.py

@@ -0,0 +1,333 @@
+#!/usr/bin/env python3
+#-*- coding: UTF-8 -*-
+# ----------------------------------------
+# jjandres 2025
+# Adaptación a Postgres (psycopg, modo async) de mtpk_mariadb.async_adapter
+# ----------------------------------------
+
+
+# Esta librería es un wrapper (envolvente) del conector psycopg para manejo de Postgres con funciones asíncronas.
+
+import psycopg
+from psycopg.rows import dict_row
+from typing import Optional, Union, List, Dict
+from .core_sync import Tabla, SQLLiteral
+from logging import Logger
+from contextlib import asynccontextmanager
+from contextvars import ContextVar
+
+
+class _PseudoPool:
+    """Sustituto de un pool real que NO reutiliza conexiones.
+    - Mantiene interfaz mínima usada: acquire(), close(), wait_closed(), _closed.
+    - Cada acquire() abre conexión con psycopg.AsyncConnection.connect() y la cierra al salir del contexto.
+    """
+    def __init__(self, host: str, user: str, password: str, db: str, port: int, autocommit: bool = False):
+        self._cfg = dict(host=host, user=user, password=password, dbname=db, port=port)
+        self._autocommit = autocommit
+        self._closed = False
+
+    @asynccontextmanager
+    async def acquire(self):
+        cx = await psycopg.AsyncConnection.connect(**self._cfg, autocommit=self._autocommit, row_factory=dict_row)
+        try:
+            yield cx
+        finally:
+            try:
+                if not cx.autocommit:
+                    try:
+                        await cx.rollback()
+                    except Exception:
+                        pass
+            finally:
+                await cx.close()
+
+    def close(self):
+        self._closed = True
+
+    async def wait_closed(self):
+        return
+
+
+class AsyncDatabase:
+    """
+    Clase AsyncDatabase para entornos asíncronos como FastAPI con Uvicorn.
+    Usa psycopg (modo async) como backend de conexión.
+    """
+
+    def __init__(self, host: str, user: str, password: str, db: str, port: int = 5432, logger: Optional[Logger] = None, **kwargs):
+        self.host = host
+        self.user = user
+        self.password = password
+        self.db = db
+        self.port = port
+        self.logger = logger
+        self.name = kwargs.get("name")  # Compatibilidad con configuraciones que incluyen 'name'
+
+        # Mantenemos el atributo pool por compatibilidad
+        self.pool = None
+
+        # Para compatibilidad con la gestión de tablas / sync
+        self.tablas: Dict[str, Tabla] = {}
+
+        # Último insert id (cuando la sentencia usa RETURNING)
+        self.ultimo_insert_id: Optional[int] = None
+
+        # Bandera de transacción por coroutine
+        self._tx_flag: ContextVar[bool] = ContextVar("mtpk_tx_flag", default=False)
+
+    def en_transaccion(self) -> bool:
+        """Indica si hay una transacción abierta en esta coroutine."""
+        return self._tx_flag.get()
+
+    @asynccontextmanager
+    async def transaccion(self, autocommit: bool = False):
+        """
+        Contexto de transacción con compatibilidad hacia atrás.
+
+        Params:
+            autocommit (bool): Se mantiene por compatibilidad con transaccion_simple().
+                - False (por defecto): se hace COMMIT/ROLLBACK al salir del bloque.
+                - True: NO se hace COMMIT/ROLLBACK; se cede la conexión tal cual.
+                        Útil para operaciones sueltas que quieren controlar su propio commit,
+                        o para simples lecturas.
+
+        Nota:
+            Aunque internamente no hay pool real, `self.pool.acquire()` usa _PseudoPool
+            y abre/cierra una conexión por bloque.
+        """
+        if self.pool is None:
+            await self.conectar()
+
+        token = self._tx_flag.set(True)
+        try:
+            async with self.pool.acquire() as cx:
+                try:
+                    await cx.set_autocommit(autocommit)
+                except Exception:
+                    pass
+
+                try:
+                    yield cx
+                    if not autocommit:
+                        await cx.commit()
+                except Exception:
+                    if not autocommit:
+                        try:
+                            await cx.rollback()
+                        except Exception:
+                            pass
+                    raise
+        finally:
+            self._tx_flag.reset(token)
+
+    transaccion_simple = transaccion  # Alias de transaccion
+
+    async def conectar(self):
+        """
+        Crea un 'pool' compatible si no está ya activo. En realidad es un _PseudoPool:
+        cada acquire() abre/cierra su propia conexión (sin reutilización).
+        """
+        if self.pool is None or getattr(self.pool, "_closed", False):
+            self.pool = _PseudoPool(
+                host=self.host, user=self.user, password=self.password,
+                db=self.db, port=self.port, autocommit=False
+            )
+        return self.pool
+
+    async def cerrar(self) -> None:
+        """
+        No-op seguro: mantiene compatibilidad con código que esperaba cerrar un pool.
+        """
+        try:
+            if hasattr(self, "pool") and self.pool:
+                try:
+                    self.pool.close()
+                    await self.pool.wait_closed()
+                except Exception:
+                    pass
+            self.pool = None
+        except Exception as e:
+            if self.logger:
+                self.logger.error("Error cerrando pool: %s", e, exc_info=True)
+
+    def add_tabla(self, tabla: Tabla):
+        """
+        Añade un objeto `Tabla` a la base de datos.
+
+        - Args:
+            - `tabla` (Tabla): Objeto que representa una tabla definida por el usuario.
+        """
+        self.tablas[tabla.nombre] = tabla
+
+    def get_tabla(self, nombre: str) -> Tabla:
+        """
+        Recupera un objeto `Tabla` anteriormente añadido (o lanza KeyError si no existe).
+        """
+        if nombre not in self.tablas:
+            raise KeyError(f"La tabla '{nombre}' no está registrada.")
+        return self.tablas[nombre]
+
+    async def query_multi_action(self, sql: str, lista_valores: List[tuple], conexion=None) -> int:
+        """
+        Ejecuta múltiples acciones SQL con la misma sentencia y diferentes valores usando `executemany`.
+
+        - Si se pasa `conexion`, NO se hace commit ni rollback aquí (compatibilidad con transacciones externas).
+        - Si NO se pasa `conexion`, se abre una conexión propia (vía _PseudoPool.acquire()) y se hace commit.
+
+        Nota: a diferencia de MariaDB, Postgres no tiene un `lastrowid` global tras un `executemany`,
+        así que este método no actualiza `self.ultimo_insert_id`.
+        """
+        if not lista_valores:
+            return 0
+
+        if conexion is not None:
+            async with conexion.cursor() as cursor:
+                await cursor.executemany(sql, lista_valores)
+                return cursor.rowcount
+        else:
+            if self.pool is None:
+                await self.conectar()
+
+            async with self.pool.acquire() as cx:
+                try:
+                    async with cx.cursor() as cursor:
+                        await cursor.executemany(sql, lista_valores)
+                        total_filas = cursor.rowcount
+                    await cx.commit()
+                    return total_filas
+                except Exception:
+                    try:
+                        await cx.rollback()
+                    except Exception:
+                        pass
+                    raise
+
+    async def query(self, sql: str, params=None, conexion=None, uno: bool = False):
+        """
+        Ejecuta una consulta SQL detectando si es de lectura o de acción según la primera palabra del SQL.
+
+        Si comienza por SELECT/SHOW/EXPLAIN → delega en `_query_select`.
+        En caso contrario → delega en `_query_accion`.
+
+        Gestión de conexión:
+        - Si `conexion` es None, abre y cierra conexión internamente y gestiona commit/rollback cuando proceda.
+        - Si `conexion` no es None, reutiliza la transacción/conn proporcionada y NO hace commit/rollback.
+
+        Args:
+            sql (str): Sentencia SQL completa.
+            params (Any, opcional): Parámetros de la consulta (tuple/list/dict según driver).
+            conexion (Any, opcional): Conexión o transacción activa a reutilizar.
+            uno (bool, opcional): Solo para lecturas; si True retorna una sola fila.
+
+        Returns:
+            Any:
+            - Lectura: lista de filas o una sola fila si `uno=True` (formato según `_query_select`).
+            - Acción: resultado/contador según `_query_accion` (filas afectadas, y `ultimo_insert_id` si hay RETURNING).
+
+        Raises:
+            Exception: Re-lanza errores del driver/adapter subyacente.
+        """
+
+        comando = sql.strip().split()[0].upper() if sql else ""
+        if comando in {"SELECT", "SHOW", "EXPLAIN"}:
+            return await self._query_select(sql, params, conexion, uno)
+        else:
+            return await self._query_accion(sql, params, conexion)
+
+    async def _query_select(self, sql: str, params=None, conexion=None, uno: bool = False) -> Union[List[Dict], Dict, None]:
+        """
+        SELECT/SHOW/etc. Si `conexion` es None, usa una conexión propia vía _PseudoPool.
+        Devuelve el número de filas obtenidas
+        """
+        if conexion is not None:
+            async with conexion.cursor(row_factory=dict_row) as cursor:
+                await cursor.execute(sql, params)
+                if uno:
+                    return await cursor.fetchone()
+                return await cursor.fetchall()
+        else:
+            if self.pool is None:
+                await self.conectar()
+            async with self.pool.acquire() as cx:
+                async with cx.cursor(row_factory=dict_row) as cursor:
+                    await cursor.execute(sql, params)
+                    if uno:
+                        return await cursor.fetchone()
+                    return await cursor.fetchall()
+
+    async def _query_accion(self, sql: str, params=None, conexion=None) -> int:
+        """
+        INSERT/UPDATE/DELETE/etc. Postgres no tiene `lastrowid`: si la sentencia incluye una
+        cláusula RETURNING, el primer valor de la primera fila devuelta se guarda en
+        `self.ultimo_insert_id`. Devuelve el número de filas afectadas.
+        """
+        if conexion is not None:
+            async with conexion.cursor() as cursor:
+                await cursor.execute(sql, params)
+                filas = cursor.rowcount
+                if cursor.description:
+                    fila = await cursor.fetchone()
+                    if fila:
+                        self.ultimo_insert_id = fila[0]
+                return filas
+        else:
+            if self.pool is None:
+                await self.conectar()
+
+            async with self.pool.acquire() as cx:
+                try:
+                    async with cx.cursor() as cursor:
+                        await cursor.execute(sql, params)
+                        filas = cursor.rowcount
+                        if cursor.description:
+                            fila = await cursor.fetchone()
+                            if fila:
+                                self.ultimo_insert_id = fila[0]
+                    await cx.commit()
+                    return filas
+                except Exception as e:
+                    try:
+                        await cx.rollback()
+                    except Exception:
+                        pass
+                    if self.logger:
+                        self.logger.error("Error en _query_accion: %s", e)
+                    raise
+
+    async def call_proc(self, nombre: str, parametros: tuple = (), conexion=None, uno: bool = True) -> Optional[Union[dict, List[dict]]]:
+        """
+        Ejecuta un procedimiento almacenado.
+        - Si devuelve SELECT, retorna dict/list; si no devuelve nada, None.
+        - Si `conexion` es None, abre/cierra conexión propia.
+        """
+        sql = f"CALL {nombre}({', '.join(['%s'] * len(parametros))})" if parametros else f"CALL {nombre}()"
+
+        if conexion is not None:
+            async with conexion.cursor(row_factory=dict_row) as cursor:
+                await cursor.execute(sql, parametros)
+                try:
+                    return await cursor.fetchone() if uno else await cursor.fetchall()
+                except Exception:
+                    return None
+        else:
+            if self.pool is None:
+                await self.conectar()
+            async with self.pool.acquire() as cx:
+                try:
+                    async with cx.cursor(row_factory=dict_row) as cursor:
+                        await cursor.execute(sql, parametros)
+                        try:
+                            resultado = await cursor.fetchone() if uno else await cursor.fetchall()
+                        except Exception:
+                            resultado = None
+                    await cx.commit()
+                    return resultado
+                except Exception as e:
+                    try:
+                        await cx.rollback()
+                    except Exception:
+                        pass
+                    if self.logger:
+                        self.logger.error("Error en call_proc('%s'): %s", nombre, e)
+                    raise