mtpk-postgres 0.1.0__tar.gz → 0.1.2__tar.gz

{mtpk_postgres-0.1.0 → mtpk_postgres-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mtpk_postgres
-Version: 0.1.0
+Version: 0.1.2
 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
@@ -45,3 +45,23 @@ pip install -e .
   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.
+- Columnas `VECTOR(n)` (extensión [pgvector](https://github.com/pgvector/pgvector), hay que crearla antes con
+  `CREATE EXTENSION IF NOT EXISTS vector;`): `Columna(tipo="VECTOR", longitud=n)`. Es una extensión propia de este
+  paquete, no existe en `mtpk-mariadb`.
+- Índices con método (`GIN`, `GIST`, `HNSW`/`IVFFlat` de pgvector, etc.): `Index(columnas=[...], metodo="hnsw",
+  opclass="vector_cosine_ops", with_opciones="m = 16, ef_construction = 64")`. `metodo` es incompatible con `unico`
+  (Postgres no permite índices UNIQUE con esos métodos).
+
+## Historial
+
+- **0.1.2**: soporte nativo para columnas `VECTOR(n)` (pgvector) e índices con método (`USING gin/hnsw/...`,
+  `opclass`, `WITH (...)`) en `Index`. La introspección (`obtener_columnas_postgres`) ahora reconoce las columnas
+  `vector` por su `udt_name` y reconstruye su dimensión leyendo el catálogo (`pg_attribute`/`format_type`); sin esto,
+  `data_type` llegaba como `'USER-DEFINED'` y `comparar_generar_alter` proponía un `ALTER COLUMN` en cada ejecución
+  aunque la columna no hubiera cambiado.
+- **0.1.1**: corrige un bug bloqueante — `Tabla` no enlazaba `indice.tabla`/`fk.tabla`/`columna.tabla` cuando
+  `columnas`/`indices`/`foreign_keys` se pasaban directamente por el constructor (solo lo hacían `add_index()` y
+  compañía). Como `Index.to_sql()` necesita esa referencia para generar el `CREATE INDEX`, cualquier tabla definida
+  de la forma normal y con al menos un índice fallaba con `ValueError` al sincronizar el esquema. Se añadió
+  `Tabla.__post_init__` para enlazarlos siempre.
+- **0.1.0**: primera versión publicada.

mtpk_postgres-0.1.2/README.md

@@ -0,0 +1,47 @@
+# 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.
+- Columnas `VECTOR(n)` (extensión [pgvector](https://github.com/pgvector/pgvector), hay que crearla antes con
+  `CREATE EXTENSION IF NOT EXISTS vector;`): `Columna(tipo="VECTOR", longitud=n)`. Es una extensión propia de este
+  paquete, no existe en `mtpk-mariadb`.
+- Índices con método (`GIN`, `GIST`, `HNSW`/`IVFFlat` de pgvector, etc.): `Index(columnas=[...], metodo="hnsw",
+  opclass="vector_cosine_ops", with_opciones="m = 16, ef_construction = 64")`. `metodo` es incompatible con `unico`
+  (Postgres no permite índices UNIQUE con esos métodos).
+
+## Historial
+
+- **0.1.2**: soporte nativo para columnas `VECTOR(n)` (pgvector) e índices con método (`USING gin/hnsw/...`,
+  `opclass`, `WITH (...)`) en `Index`. La introspección (`obtener_columnas_postgres`) ahora reconoce las columnas
+  `vector` por su `udt_name` y reconstruye su dimensión leyendo el catálogo (`pg_attribute`/`format_type`); sin esto,
+  `data_type` llegaba como `'USER-DEFINED'` y `comparar_generar_alter` proponía un `ALTER COLUMN` en cada ejecución
+  aunque la columna no hubiera cambiado.
+- **0.1.1**: corrige un bug bloqueante — `Tabla` no enlazaba `indice.tabla`/`fk.tabla`/`columna.tabla` cuando
+  `columnas`/`indices`/`foreign_keys` se pasaban directamente por el constructor (solo lo hacían `add_index()` y
+  compañía). Como `Index.to_sql()` necesita esa referencia para generar el `CREATE INDEX`, cualquier tabla definida
+  de la forma normal y con al menos un índice fallaba con `ValueError` al sincronizar el esquema. Se añadió
+  `Tabla.__post_init__` para enlazarlos siempre.
+- **0.1.0**: primera versión publicada.

{mtpk_postgres-0.1.0 → mtpk_postgres-0.1.2}/mtpk_postgres/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 __author__ = "jjandres"
 
 from .interface import *

{mtpk_postgres-0.1.0 → mtpk_postgres-0.1.2}/mtpk_postgres/core_sync.py

@@ -62,12 +62,14 @@ class Columna:
     tipo: Literal[
         "TINYINT", "SMALLINT", "MEDIUMINT", "INT", "INTEGER", "BIGINT", "DECIMAL", "NUMERIC", "FLOAT", "DOUBLE",
         "CHAR", "VARCHAR", "TEXT", "TINYTEXT", "MEDIUMTEXT", "LONGTEXT", "BINARY", "VARBINARY", "BLOB", "TINYBLOB", "MEDIUMBLOB", "LONGBLOB",
-        "DATE", "TIME", "YEAR", "DATETIME", "TIMESTAMP", "ENUM", "SET", "BOOLEAN", "GEOMETRY", "POINT", "LINESTRING", "POLYGON"
+        "DATE", "TIME", "YEAR", "DATETIME", "TIMESTAMP", "ENUM", "SET", "BOOLEAN", "GEOMETRY", "POINT", "LINESTRING", "POLYGON",
+        "VECTOR"
     ]
-    """Tipo de dato del modelo (mismo vocabulario que mtpk-mariadb, traducido a Postgres en to_sql())"""
+    """Tipo de dato del modelo (mismo vocabulario que mtpk-mariadb, traducido a Postgres en to_sql());
+    VECTOR es una extensión propia de este paquete (no existe en mtpk-mariadb) para columnas `pgvector`."""
 
     longitud: Optional[int] = None
-    """Longitud para tipos como VARCHAR(n), CHAR(n)."""
+    """Longitud para tipos como VARCHAR(n), CHAR(n). Para VECTOR, es el número de dimensiones: VECTOR(n)."""
 
     precision: Optional[int] = None
     """Precisión para DECIMAL(p, s), etc."""
@@ -123,6 +125,7 @@ class Columna:
         "YEAR": "SMALLINT",
         "BOOLEAN": "BOOLEAN",
         "ENUM": "TEXT", "SET": "TEXT",
+        "VECTOR": "VECTOR",
     }
     _SIN_SOPORTE = {"GEOMETRY", "POINT", "LINESTRING", "POLYGON"}
 
@@ -135,6 +138,13 @@ class Columna:
             )
         base = self._MAPA_TIPOS.get(tipo_upper, tipo_upper)
 
+        if base == "VECTOR":
+            if self.longitud is None:
+                raise ValueError(
+                    f"La columna '{self.nombre}' es VECTOR pero no tiene 'longitud' (número de dimensiones)."
+                )
+            # Requiere la extensión pgvector: CREATE EXTENSION IF NOT EXISTS vector;
+            return f"{base}({self.longitud})"
         if base in {"VARCHAR", "CHAR"}:
             return f"{base}({self.longitud})"
         if base in {"DECIMAL", "NUMERIC"}:
@@ -230,12 +240,20 @@ class Index:
     - Atributos:
         - `columnas`    (List[str]): Lista de nombres de columnas incluidas en el índice. Pueden ser una o varias (índice compuesto).
         - `nombre`      (str, opcional): Nombre personalizado del índice. Si no se indica, se generará automáticamente combinando los nombres de las columnas.
-        - `unico`       (bool): Indica si el índice es único (`UNIQUE`). Por defecto es `False`.
+        - `unico`       (bool): Indica si el índice es único (`UNIQUE`). Por defecto es `False`. Incompatible con `metodo`.
+        - `metodo`      (str, opcional): Método de acceso del índice (`USING <metodo>`), p.ej. `"gin"`, `"gist"` o `"hnsw"`/`"ivfflat"`
+                        (estos dos últimos requieren la extensión `pgvector`). Si no se indica, se usa el btree normal de Postgres.
+        - `opclass`     (str, opcional): Clase de operador a aplicar a cada columna del índice, p.ej. `"vector_cosine_ops"`
+                        para un HNSW/IVFFlat sobre una columna `VECTOR`, o `"gin_trgm_ops"` para búsqueda por trigramas.
+        - `with_opciones` (str, opcional): Contenido crudo de la cláusula `WITH (...)`, p.ej. `"m = 16, ef_construction = 64"` (HNSW).
         - `tabla`       (Tabla, opcional): Referencia a la tabla que contiene este índice. Se asigna automáticamente al añadir el índice a la tabla.
     """
     columnas: List[str]
     nombre: Optional[str] = None
     unico: bool = False
+    metodo: Optional[str] = None
+    opclass: Optional[str] = None
+    with_opciones: Optional[str] = None
     tabla: Optional["Tabla"] = field(default=None, repr=False)
 
     def to_sql(self) -> str:
@@ -243,8 +261,25 @@ class Index:
             raise ValueError(
                 f"El índice sobre {self.columnas} no está asociado a ninguna tabla; no se puede generar el CREATE INDEX."
             )
-        cols = ", ".join(f'"{c}"' for c in self.columnas)
+        if self.metodo and self.unico:
+            raise ValueError(
+                f"El índice sobre {self.columnas} no puede ser UNIQUE y usar 'metodo' ({self.metodo}) a la vez "
+                "(GIN/HNSW/IVFFlat no admiten UNIQUE en Postgres)."
+            )
+
         nombre = self.nombre or f"{'_'.join(self.columnas)}_{'uk' if self.unico else 'idx'}"
+
+        if self.metodo:
+            cols = ", ".join(
+                f'"{c}" {self.opclass}' if self.opclass else f'"{c}"'
+                for c in self.columnas
+            )
+            sql = f'CREATE INDEX IF NOT EXISTS "{nombre}" ON "{self.tabla.nombre}" USING {self.metodo} ({cols})'
+            if self.with_opciones:
+                sql += f" WITH ({self.with_opciones})"
+            return sql
+
+        cols = ", ".join(f'"{c}"' for c in self.columnas)
         tipo_sql = "UNIQUE INDEX" if self.unico else "INDEX"
         return f'CREATE {tipo_sql} IF NOT EXISTS "{nombre}" ON "{self.tabla.nombre}" ({cols})'
 
@@ -283,6 +318,18 @@ class Tabla:
     database: Optional["Database"] = None
     db_name: Optional[str] = None  # ← nuevo campo, sin conflicto con Database
 
+    def __post_init__(self):
+        # Index.to_sql() necesita conocer su tabla (Postgres genera el CREATE INDEX aparte,
+        # no como cláusula del CREATE TABLE) — sin esto, pasar columnas/indices/foreign_keys
+        # por el constructor (en vez de add_columna/add_index/add_foreign_key) los deja sin
+        # enlazar a self y provoca un ValueError en cuanto la tabla tiene algún índice.
+        for col in self.columnas:
+            col.tabla = self
+        for idx in self.indices:
+            idx.tabla = self
+        for fk in self.foreign_keys:
+            fk.tabla = self
+
     def add_columna(self, columna: Columna):
         """
         Añade una columna a la tabla si no existe ya.
@@ -452,7 +499,7 @@ class Tabla:
             cursor.execute(
                 """
                 SELECT
-                    c.column_name, c.data_type, c.character_maximum_length,
+                    c.column_name, c.data_type, c.udt_name, c.character_maximum_length,
                     c.numeric_precision, c.numeric_scale, c.is_nullable,
                     c.column_default, c.is_identity,
                     COALESCE(pk.es_pk, false) AS es_pk,
@@ -484,21 +531,33 @@ class Tabla:
             filas = cursor.fetchall()
 
         checks_por_columna = self._obtener_opciones_check(conexion)
+        dimensiones_vector = self._obtener_dimensiones_vector(conexion)
 
         for fila in filas:
-            tipo_base = self._PG_A_MODELO.get(fila["data_type"], fila["data_type"].upper())
-            enum_opciones = None
-
-            if tipo_base == "TEXT" and fila["column_name"] in checks_por_columna:
-                # Postgres no distingue ENUM de SET tras reconstruir desde el CHECK: ambos
-                # se guardan como TEXT + CHECK (ver Columna.to_sql), así que se asume ENUM.
-                tipo_base = "ENUM"
-                enum_opciones = checks_por_columna[fila["column_name"]]
+            longitud = fila["character_maximum_length"]
+
+            if fila["udt_name"] == "vector":
+                # information_schema no expone el nº de dimensiones de un `vector(n)` (tipo de
+                # la extensión pgvector): data_type viene como 'USER-DEFINED' y
+                # character_maximum_length es NULL. Sin este caso especial, tipo_base quedaría
+                # como "USER-DEFINED" y nunca igualaría al "VECTOR" del modelo, provocando un
+                # ALTER COLUMN espurio en cada ejecución.
+                tipo_base = "VECTOR"
+                longitud = dimensiones_vector.get(fila["column_name"])
+                enum_opciones = None
+            else:
+                tipo_base = self._PG_A_MODELO.get(fila["data_type"], fila["data_type"].upper())
+                enum_opciones = None
+                if tipo_base == "TEXT" and fila["column_name"] in checks_por_columna:
+                    # Postgres no distingue ENUM de SET tras reconstruir desde el CHECK: ambos
+                    # se guardan como TEXT + CHECK (ver Columna.to_sql), así que se asume ENUM.
+                    tipo_base = "ENUM"
+                    enum_opciones = checks_por_columna[fila["column_name"]]
 
             col = Columna(
                 nombre=fila["column_name"],
                 tipo=tipo_base,
-                longitud=fila["character_maximum_length"],
+                longitud=longitud,
                 precision=fila["numeric_precision"],
                 escala=fila["numeric_scale"],
                 not_null=(fila["is_nullable"] == "NO"),
@@ -512,6 +571,33 @@ class Tabla:
 
         return columnas
 
+    def _obtener_dimensiones_vector(self, conexion) -> Dict[str, int]:
+        """
+        Devuelve {columna: dimensiones} para las columnas `vector(n)` (extensión pgvector) de
+        esta tabla, leyendo el modificador de tipo real desde los catálogos (atttypmod vía
+        format_type), ya que information_schema no lo expone para tipos definidos por extensión.
+        """
+        resultado: Dict[str, int] = {}
+        with conexion.cursor(row_factory=dict_row) as cursor:
+            cursor.execute(
+                """
+                SELECT a.attname AS columna,
+                       pg_catalog.format_type(a.atttypid, a.atttypmod) AS tipo_completo
+                FROM pg_attribute a
+                JOIN pg_class t ON t.oid = a.attrelid
+                JOIN pg_namespace n ON n.oid = t.relnamespace
+                JOIN pg_type ty ON ty.oid = a.atttypid
+                WHERE t.relname = %s AND n.nspname = 'public'
+                    AND ty.typname = 'vector' AND a.attnum > 0 AND NOT a.attisdropped
+                """,
+                (self.nombre,)
+            )
+            for fila in cursor.fetchall():
+                m = re.match(r"vector\((\d+)\)", fila["tipo_completo"] or "", re.IGNORECASE)
+                if m:
+                    resultado[fila["columna"]] = int(m.group(1))
+        return resultado
+
     def _obtener_opciones_check(self, conexion) -> Dict[str, List[str]]:
         """
         Reconstruye, de forma best-effort, las opciones de las columnas ENUM/SET (TEXT + CHECK)

{mtpk_postgres-0.1.0 → mtpk_postgres-0.1.2}/mtpk_postgres.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mtpk_postgres
-Version: 0.1.0
+Version: 0.1.2
 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
@@ -45,3 +45,23 @@ pip install -e .
   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.
+- Columnas `VECTOR(n)` (extensión [pgvector](https://github.com/pgvector/pgvector), hay que crearla antes con
+  `CREATE EXTENSION IF NOT EXISTS vector;`): `Columna(tipo="VECTOR", longitud=n)`. Es una extensión propia de este
+  paquete, no existe en `mtpk-mariadb`.
+- Índices con método (`GIN`, `GIST`, `HNSW`/`IVFFlat` de pgvector, etc.): `Index(columnas=[...], metodo="hnsw",
+  opclass="vector_cosine_ops", with_opciones="m = 16, ef_construction = 64")`. `metodo` es incompatible con `unico`
+  (Postgres no permite índices UNIQUE con esos métodos).
+
+## Historial
+
+- **0.1.2**: soporte nativo para columnas `VECTOR(n)` (pgvector) e índices con método (`USING gin/hnsw/...`,
+  `opclass`, `WITH (...)`) en `Index`. La introspección (`obtener_columnas_postgres`) ahora reconoce las columnas
+  `vector` por su `udt_name` y reconstruye su dimensión leyendo el catálogo (`pg_attribute`/`format_type`); sin esto,
+  `data_type` llegaba como `'USER-DEFINED'` y `comparar_generar_alter` proponía un `ALTER COLUMN` en cada ejecución
+  aunque la columna no hubiera cambiado.
+- **0.1.1**: corrige un bug bloqueante — `Tabla` no enlazaba `indice.tabla`/`fk.tabla`/`columna.tabla` cuando
+  `columnas`/`indices`/`foreign_keys` se pasaban directamente por el constructor (solo lo hacían `add_index()` y
+  compañía). Como `Index.to_sql()` necesita esa referencia para generar el `CREATE INDEX`, cualquier tabla definida
+  de la forma normal y con al menos un índice fallaba con `ValueError` al sincronizar el esquema. Se añadió
+  `Tabla.__post_init__` para enlazarlos siempre.
+- **0.1.0**: primera versión publicada.

{mtpk_postgres-0.1.0 → mtpk_postgres-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mtpk_postgres"
-version = "0.1.0"
+version = "0.1.2"
 description = "Librería para sincronización estructural de bases de datos Postgres con modelos Python (adaptación de mtpk_mariadb)"
 readme = "README.md"
 requires-python = ">=3.9"

mtpk_postgres-0.1.0/README.md

@@ -1,27 +0,0 @@
-# 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.