chastack-bdd 0.8.3

Abstracción de Bases de Datos en Python y constructor de modelos.

chastack_bdd

chastack_bdd es una librería de Python que permite definir clases que, en tiempo de ejecución, se poblan automáticamente con los atributos definidos en las tablas SQL homónimas. Se utiliza un enfoque de metaprogramación para que, al declarar una clase con metaclass=Tabla, la clase resultante herede de Registro y adquiera todos los métodos y comportamientos necesarios para interactuar con la base de datos de manera transparente y segura.

La inicialización de las clases es "vaga": la estructura de la tabla se consulta y se refleja en la clase solo cuando se instancia por primera vez o cuando se invocan ciertos métodos de clase. Esto garantiza que los atributos (__slots__) estén sincronizados con la base de datos y que los campos no modificables (como id, fecha_carga, fecha_modificacion) estén protegidos contra escritura directa.

[!TIP]
Todas las clases creadas con metaclass=Tabla aceptan el parámetro especial debug, que permite obtener información de diagnóstico sobre la inicialización, instanciación y otros eventos internos, facilitando el manejo de errores y la depuración.

Se provee un protocolo de base de datos (ProtocoloBaseDeDatos) para que el usuario pueda implementar su propia abstracción de acceso a datos. Además, se incluye una implementación acoplada a MySQL lista para usar.

---

Documentación

Tema	Enlace	Descripción breve
📑 Referencia de la API	Referencia de la API	Métodos, clases y firmas públicas
🧑‍💻 Ejemplos de uso	Ejemplos de uso	Casos prácticos, básicos y avanzados
🏗️ Creación de modelos	Creación de modelos	Cómo definir y manipular modelos con metaclass=Tabla
👤 Gestión de usuarios	Gestión de usuarios	Modelos de usuario, autenticación y seguridad
🔌 Extensión a otros motores	Extensión a otros motores de BDD	Implementar soporte para otros motores de base de datos
🗃️ Requisitos de las tablas	Requisitos de las tablas SQL	Estructura mínima y convenciones de las tablas

---

¿Qué es chastack_bdd?

chastack_bdd permite definir clases Python que representan tablas SQL, poblando automáticamente sus atributos y métodos según la estructura de la base de datos. Utiliza metaprogramación avanzada para garantizar sincronización, protección de campos críticos y soporte para relaciones complejas.

Modelos automáticos: Las clases declaradas con metaclass=Tabla adquieren dinámicamente los atributos y métodos necesarios para operar sobre la tabla homónima.
Relaciones y consultas: Se provee soporte nativo para relaciones muchos a muchos, así como para consultas avanzadas y ordenamientos personalizados.
Gestión de usuarios: Se incluye una clase base Usuario que implementa los mecanismos necesarios para autenticación y gestión segura de credenciales.
Backend desacoplado: La interacción con la base de datos se realiza a través de un protocolo ProtocoloBaseDeDatos, permitiendo utilizar la implementación incluida para MySQL o desarrollar una propia.

---

Ejemplo mínimo

Primero se debe definir (y crear) la tabla para la cual se quiere producir el model (debe ajustarse al requisito mínimo de Registro).

CREATE TABLE Cliente (
    id INT PRIMARY KEY AUTO_INCREMENT,
    , fecha_carga DATETIME DEFAULT CURRENT_TIMESTAMP
    , fecha_modificacion DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
    , email VARCHAR(100) NOT NULL
    , nombre VARCHAR(100) NOT NULL
);

Luego se debe crear la configuración y conexión para la base de datos, en el ejemplo usaremos MySQl, pero se puede utilizar cualquier abstracción que se ajuste al protocolo.

from chastack_bdd importConfigMySQL, BaseDeDatos_MySQL

config = ConfigMySQL(
    host="localhost",
    usuario="root_o_usuario",
    contrasena="contraseña_root_o_usuario",
    bdd="base_a_usar"
)

bdd = BaseDeDatos_MySQL(config)

Finalmente definimos la clase en Python, sin necesidad de declarar sus atributos.

from chastack_bdd import Tabla, Registro

class Cliente(metaclass=Tabla):
    pass

nuevo_cliente = Cliente(bdd, {"nombre": "Ana", "email": "[e-mail]"})
nuevo_cliente.guardar()

cliente_1 = Cliente(bdd, id=1)
print("Nombre:", cliente_1.nombre)
print("Email:", cliente_1.email)
print("Fecha de carga:", cliente_1.fecha_carga)

for columna, valor in cliente_1:
    print(f"{columna}: {valor}")

Para ejemplos avanzados, ver Ejemplos de uso.

---

Instalación

Aislada

pip install chastack_bdd

Como parte de chastack

pip install chastack

---

Licencia

MIT. Ver LICENSE.