pyEasyMatrixDb 0.1.0__py3-none-any.whl

pyeasymatrixdb/DbDriver.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from sqlalchemy import text, Engine, MetaData
+
+from .subclasses.DbDriverSearch import DbDriverSearch
+from .subclasses.DbDriverUpdate import DbDriverUpdate
+from .subclasses.DbDriverUtils import DbDriverUtils
+
+
+class DbDriver:
+	def __init__(self, metadata: MetaData, engine: Engine):
+		self._metadata = metadata
+		self._engine = engine
+		self.Pesquisar = DbDriverSearch(metadata, engine)
+		self.Atualizar = DbDriverUpdate(metadata, engine)
+
+	def execute(self, query: str, dialect: str = ""):
+		# Mantido o parâmetro dialect para compatibilidade com o descritivo.
+		del dialect
+		with self._engine.begin() as conn:
+			result = conn.execute(text(query))
+			if result.returns_rows:
+				columns = list(result.keys())
+				records = [list(row) for row in result]
+				return DbDriverUtils.to_matrix_from_records(columns, records)
+			return DbDriverUtils.to_meta_matrix(result.rowcount)
+
+	def execute_stmt(self, stmt):
+		with self._engine.begin() as conn:
+			result = conn.execute(stmt)
+			if result.returns_rows:
+				columns = list(result.keys())
+				records = [list(row) for row in result]
+				return DbDriverUtils.to_matrix_from_records(columns, records)
+			return DbDriverUtils.to_meta_matrix(result.rowcount)

pyeasymatrixdb/__init__.py

@@ -0,0 +1,3 @@
+from .DbDriver import DbDriver
+
+__all__ = ["DbDriver"]

pyeasymatrixdb/subclasses/DbDriverCore.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Any, List
+
+from .DbDriverUtils import DbDriverUtils
+
+from sqlalchemy import Engine, MetaData
+
+
+class DbDriverCore:
+    def __init__(self, metadata:MetaData, engine:Engine):
+        self._metadata = metadata
+        self._engine = engine
+        self._columns_definitions = DbDriverUtils.get_columns_definitions(metadata)
+        self._primary_keys = DbDriverUtils.get_primary_keys(metadata)
+
+    def reset(self):
+        for attr in list(vars(self).keys()):
+            if attr.startswith("_"):
+                continue
+            delattr(self, attr)
+
+    def define_filter(self, filter: List[List[Any]]):
+        positions, valid_filter = DbDriverUtils.get_valid_columns(self._columns_definitions, filter)
+        self.filter_positions = positions
+        self.filter = valid_filter
+        return self
+
+    def define_relationships(self, relationships: List[List[Any]]):
+        if relationships is None:
+            self.relationships = []
+            return self
+
+        valid_relationships = []
+        for rel in relationships:
+            if len(rel) < 4:
+                raise ValueError("Relacionamento inválido. Esperado ao menos 4 colunas.")
+
+            table_a, table_b, col_a, col_b = rel[0], rel[1], rel[2], rel[3]
+
+            if not DbDriverUtils.is_valid_table(self._columns_definitions, table_a):
+                raise ValueError(f"Tabela inválida em relacionamento: {table_a}")
+            if not DbDriverUtils.is_valid_table(self._columns_definitions, table_b):
+                raise ValueError(f"Tabela inválida em relacionamento: {table_b}")
+            if col_a not in self._columns_definitions[table_a]:
+                raise ValueError(f"Coluna inválida em relacionamento: {table_a}.{col_a}")
+            if col_b not in self._columns_definitions[table_b]:
+                raise ValueError(f"Coluna inválida em relacionamento: {table_b}.{col_b}")
+
+            valid_relationships.append(rel)
+
+        self.relationships = valid_relationships
+        return self

pyeasymatrixdb/subclasses/DbDriverSearch.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Any, List
+
+from .DbDriverCore import DbDriverCore
+from .DbDriverUtils import DbDriverUtils
+
+
+class DbDriverSearch(DbDriverCore):
+    def reset(self):
+        super().reset()
+        for attr in ("table", "header", "filter"):
+            if hasattr(self, attr):
+                delattr(self, attr)
+
+    def define_header(self, header: List[List[Any]]):
+        positions, valid_header = DbDriverUtils.get_valid_columns(self._columns_definitions, header)
+        self.header_positions = positions
+        self.header = valid_header
+        self.table = valid_header[0][0] if valid_header and valid_header[0] else None
+        return self
+
+    def search(self, reset: bool = True, complete: bool = False, default: Any = None):
+        if not hasattr(self, "header"):
+            raise ValueError("Header não definido. Use define_header antes de pesquisar.")
+
+        relationships = getattr(self, "relationships", [])
+        filters = getattr(self, "filter", [])
+
+        stmt = DbDriverUtils.buid_select(
+            self._columns_definitions,
+            self.header,
+            relationships=relationships,
+            filters=filters,
+        )
+
+        with self._engine.connect() as conn:
+            result = conn.execute(stmt)
+            records = [list(row) for row in result]
+
+        if complete:
+            target_tables, target_headers, source_index_map = DbDriverUtils.expand_structure(
+                self._columns_definitions,
+                self.header,
+                include_md=False,
+            )
+            base_matrix = [self.header[0], self.header[1], *records]
+            output = DbDriverUtils.project_matrix(
+                base_matrix,
+                target_tables,
+                target_headers,
+                source_index_map,
+                default=default,
+            )
+        else:
+            output = [self.header[0], self.header[1], *records]
+
+        if reset:
+            self.reset()
+
+        return output

pyeasymatrixdb/subclasses/DbDriverUpdate.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+from typing import Any, List
+
+from sqlalchemy import delete, insert, select, update
+
+from .DbDriverCore import DbDriverCore
+from .DbDriverUtils import DbDriverUtils
+
+
+class DbDriverUpdate(DbDriverCore):
+    def define_data(self, data: List[List[Any]]):
+        positions, valid_data = DbDriverUtils.get_valid_columns(self._columns_definitions, data)
+
+        # A coluna MD pode não estar em colunas_definitions, então tratamos manualmente.
+        if "MD" in data[1]:
+            md_idx_original = data[1].index("MD")
+            if md_idx_original not in positions:
+                positions.append(md_idx_original)
+                positions = sorted(positions)
+                valid_data = [[row[i] if i < len(row) else None for i in positions] for row in data]
+
+        self.data_positions = positions
+        self.data = valid_data
+        return self
+
+    def update(self, reset: bool = True, complete: bool = False, default: Any = None):
+        if not hasattr(self, "data"):
+            raise ValueError("Data não definida. Use define_data antes de atualizar.")
+
+        data = self.data
+        if len(data) < 3:
+            raise ValueError("Data inválida. É necessário ao menos uma linha de dados.")
+        if "MD" not in data[1]:
+            raise ValueError('A última coluna deve se chamar "MD".')
+
+        md_idx = data[1].index("MD")
+        table_name = data[0][0]
+        table_obj = self._columns_definitions[table_name][data[1][0]]["table_obj"]
+        pk_col = self._primary_keys.get(table_name)
+        pk_idx = data[1].index(pk_col) if pk_col in data[1] else None
+        extra_filter = DbDriverUtils._build_filters(self._columns_definitions, getattr(self, "filter", []))
+
+        with self._engine.begin() as conn:
+            for row in data[2:]:
+                if md_idx >= len(row):
+                    continue
+
+                marker = row[md_idx]
+                if marker not in ("U", "A", "D"):
+                    raise ValueError(f"Valor inválido na coluna MD: {marker}")
+
+                values = {}
+                for idx, col_name in enumerate(data[1]):
+                    if col_name == "MD":
+                        continue
+                    if idx < len(row):
+                        values[col_name] = row[idx]
+
+                pk_value = None
+                if pk_idx is not None and pk_idx < len(row):
+                    pk_value = row[pk_idx]
+
+                if marker == "D":
+                    if not pk_col or pk_idx is None or pk_value is None:
+                        raise ValueError("Remoção exige chave primária presente no data.")
+
+                    stmt = delete(table_obj).where(table_obj.c[pk_col] == pk_value)
+                    if extra_filter is not None:
+                        stmt = stmt.where(extra_filter)
+                    conn.execute(stmt)
+                    continue
+
+                # U/A: tenta update se houver PK, caso contrário faz insert.
+                if pk_col and pk_idx is not None and pk_value is not None:
+                    update_values = {k: v for k, v in values.items() if k != pk_col}
+                    if update_values:
+                        stmt = update(table_obj).where(table_obj.c[pk_col] == pk_value).values(**update_values)
+                        if extra_filter is not None:
+                            stmt = stmt.where(extra_filter)
+                        updated = conn.execute(stmt).rowcount or 0
+                        if updated > 0:
+                            continue
+
+                    # Se o registro já existe pela PK, não deve cair em insert por causa de filtro extra.
+                    exists_stmt = select(table_obj.c[pk_col]).where(table_obj.c[pk_col] == pk_value).limit(1)
+                    exists = conn.execute(exists_stmt).first() is not None
+                    if exists:
+                        continue
+
+                insert_values = {k: v for k, v in values.items() if k != "MD"}
+
+                missing_required = []
+                for col_name, col_info in self._columns_definitions[table_name].items():
+                    if col_name in insert_values:
+                        continue
+                    if col_info["primary"]:
+                        continue
+                    has_default = col_info["default"] is not None
+                    if not col_info["nullable"] and not has_default:
+                        missing_required.append(col_name)
+
+                if missing_required:
+                    raise ValueError(
+                        "Insert inválido: faltam colunas obrigatórias sem default: "
+                        + ", ".join(missing_required)
+                    )
+
+                conn.execute(insert(table_obj).values(**insert_values))
+
+        if complete:
+            target_tables, target_headers, source_index_map = DbDriverUtils.expand_structure(
+                self._columns_definitions,
+                data,
+                include_md=True,
+            )
+            output = DbDriverUtils.project_matrix(
+                data,
+                target_tables,
+                target_headers,
+                source_index_map,
+                default=default,
+            )
+        else:
+            output = data
+
+        if reset:
+            self.reset()
+
+        return output

pyeasymatrixdb/subclasses/DbDriverUtils.py

@@ -0,0 +1,417 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Tuple
+
+from sqlalchemy import MetaData, and_, delete, insert, or_, select, update
+
+class DbDriverUtils:
+    def __new__(cls, *args, **kwargs):
+        raise TypeError("This class cannot be instantiated")
+
+    @staticmethod
+    def get_columns_definitions(metadata: MetaData) -> Dict[str, Dict[str, Dict[str, Any]]]:
+        columns_definitions: Dict[str, Dict[str, Dict[str, Any]]] = {}
+
+        for table_name, table_obj in metadata.tables.items():
+            columns_definitions[table_name] = {}
+            for col in table_obj.columns:
+                default_value = None
+                if col.default is not None:
+                    default_value = getattr(col.default, "arg", col.default)
+
+                columns_definitions[table_name][col.name] = {
+                    "type": col.type,
+                    "primary": bool(col.primary_key),
+                    "unique": bool(col.unique),
+                    "default": default_value,
+                    "nullable": bool(col.nullable),
+                    "table_obj": table_obj,
+                    "column_obj": col,
+                }
+
+        return columns_definitions
+
+    @staticmethod
+    def get_primary_keys(metadata: MetaData) -> Dict[str, Any]:
+        primary_keys: Dict[str, Any] = {}
+        for table_name, table_obj in metadata.tables.items():
+            pks = [col.name for col in table_obj.primary_key.columns]
+            primary_keys[table_name] = pks[0] if pks else None
+        return primary_keys
+
+    @staticmethod
+    def get_valid_columns(
+        columns_definitions: Dict[str, Dict[str, Dict[str, Any]]],
+        matrix: List[List[Any]],
+    ) -> Tuple[List[int], List[List[Any]]]:
+        #valida se a matriz tem ao menos 2 linhas
+        if not matrix or len(matrix) < 2:
+            raise ValueError("Matriz inválida. É necessário ter ao menos 2 linhas.")
+
+        #separa a linha de tabelas e a linha de colunas
+        table_row = matrix[0]
+        header_row = matrix[1]
+
+        #erro caso o número de colunas seja diferente entre a linha de tabelas e a linha de colunas
+        if len(table_row) != len(header_row):
+            raise ValueError("Matriz inválida. O número de colunas na linha de tabelas e na linha de colunas deve ser o mesmo.")
+        
+        max_cols = len(header_row)
+
+        valid_positions: List[int] = []
+        for idx in range(max_cols):
+            table_name = table_row[idx]
+            column_name = header_row[idx]
+
+            if (
+                table_name in columns_definitions
+                and column_name in columns_definitions[table_name]
+            ):
+                valid_positions.append(idx)
+
+        if not valid_positions:
+            raise ValueError("Nenhuma coluna válida foi encontrada na matriz.")
+
+        #monta a matriz com as colunas válidas
+        valid_matrix = [[row[i] for i in valid_positions] for row in matrix]
+        return valid_positions, valid_matrix
+
+    @staticmethod
+    def is_valid_table(columns_definitions: Dict[str, Dict[str, Any]], table: str) -> bool:
+        return table in columns_definitions
+
+    @staticmethod
+    def buid_select(
+        columns_definitions: Dict[str, Dict[str, Dict[str, Any]]],
+        headers: List[List[Any]],
+        relationships: List[List[Any]] = [],
+        filters: List[List[Any]] = [],
+    ):
+        if not headers or len(headers) < 2:
+            raise ValueError("Header inválido para select.")
+
+        columns = []
+        for idx, column_name in enumerate(headers[1]):
+            table_name = headers[0][idx]
+            table_obj = columns_definitions[table_name][column_name]["table_obj"]
+            columns.append(table_obj.c[column_name])
+
+        base_table = columns_definitions[headers[0][0]][headers[1][0]]["table_obj"]
+        from_clause = base_table
+
+        for rel in reversed(relationships or []):
+            if len(rel) < 4:
+                continue
+
+            table_a, table_b, col_a, col_b = rel[0], rel[1], rel[2], rel[3]
+            inner = True if len(rel) < 5 else bool(rel[4])
+
+            table_a_obj = columns_definitions[table_a][col_a]["table_obj"]
+            table_b_obj = columns_definitions[table_b][col_b]["table_obj"]
+            condition = table_a_obj.c[col_a] == table_b_obj.c[col_b]
+
+            if inner:
+                from_clause = from_clause.join(table_a_obj, condition)
+            else:
+                from_clause = from_clause.outerjoin(table_a_obj, condition)
+
+        stmt = select(*columns).select_from(from_clause)
+        filter_condition = DbDriverUtils._build_filters(columns_definitions, filters)
+        if filter_condition is not None:
+            stmt = stmt.where(filter_condition)
+
+        return stmt
+
+    @staticmethod
+    def buid_update(
+        columns_definitions: Dict[str, Dict[str, Dict[str, Any]]],
+        data: List[List[Any]],
+        relationships: List[List[Any]] = [],
+        filters: List[List[Any]] = [],
+    ):
+        #valida se a matriz tem 3 linhas ou mais
+        if not data or len(data) < 3:
+            raise ValueError("Dados inválidos para update.")
+
+        table_name = data[0][0]
+        #valida se toda a primeira linha tem o mesmo nome de tabela
+        if any(t != table_name for t in data[0]):
+            raise ValueError("Dados inválidos para update. A primeira linha deve conter o mesmo nome de tabela.")
+
+        #coleta a tabela e o índice da coluna MD (se existir)
+        table_obj = columns_definitions[table_name][data[1][0]]["table_obj"]
+        md_idx = len(data[1])-1
+        if  data[1][md_idx] != "MD":
+            raise ValueError("A coluna MD é obrigatória.")
+
+        pk_col = None
+        for col_name, info in columns_definitions[table_name].items():
+            if info["primary"]:
+                pk_col = col_name
+                break
+        
+        #testa se a pk está presente no header
+        pk_idx = None
+        if pk_col:
+            if pk_col in data[1]:
+                pk_idx = data[1].index(pk_col)
+
+        #valida as possibilidades filter sem pk (com ou sem relationship), ou apenas pk sem filter/relationship
+        if pk_idx is None and not filters and not relationships:
+            raise ValueError("Dados inválidos para update. É necessário ter uma chave primária ou um filtro/relacionamento para identificar as linhas a serem atualizadas.")
+        if pk_idx is None:
+            if not filter:
+                raise ValueError("Dados inválidos para update. Filtro obrigatório quando não há chave primária.")
+        else:
+            if filters or relationships:
+                raise ValueError("Dados inválidos para update. Não é permitido usar filtros ou relacionamentos quando a chave primária está presente.")
+
+        #monta as regras
+        stmts = []
+        for row in data[2:]:
+            #verifica se precisa fazer algo pela coluna MD
+            marker = row[md_idx]
+            if marker not in ("U", "A"):
+                continue
+            
+            #inicia a montagem do update, ignorando colunas MD e PK
+            values = {}
+            for idx, col_name in enumerate(data[1]):
+                if col_name in ("MD", pk_col):
+                    continue
+                if idx < len(row) and row[idx] is not None:
+                    values[col_name] = row[idx]
+
+            if values:
+                stmt = update(table_obj)
+                if pk_idx is not None:
+                    stmt = stmt.where(table_obj.c[pk_col] == row[pk_idx]).values(**values)
+                else:
+                    if len(values) != 1:
+                        raise ValueError("Dados inválidos para update. Quando não há chave primária, deve haver exatamente uma linha com atualizações.")
+                    extra_filter = DbDriverUtils._build_filters(columns_definitions, filters)
+                    if not extra_filter:
+                        raise ValueError("Dados inválidos para update. Filtro inválido ou sem correspondência.")
+                    relationships_filter = None
+                    if relationships:
+                        for rel in reversed(relationships):
+                            if len(rel) < 4:
+                                continue
+
+                            table_a, table_b, col_a, col_b = rel[0], rel[1], rel[2], rel[3]
+                            table_a_obj = columns_definitions[table_a][col_a]["table_obj"]
+                            table_b_obj = columns_definitions[table_b][col_b]["table_obj"]
+                            condition = table_a_obj.c[col_a] == table_b_obj.c[col_b]
+
+                            if relationships_filter is None:
+                                relationships_filter = condition
+                            else:
+                                relationships_filter = and_(relationships_filter, condition)
+                    if relationships_filter is not None:
+                        stmt = stmt.where(relationships_filter)
+                    stmt = stmt.where(extra_filter).values(**values)
+                stmts.append(stmt)
+
+        return stmts
+
+    @staticmethod
+    def buid_insert(
+        columns_definitions: Dict[str, Dict[str, Dict[str, Any]]],
+        data: List[List[Any]],
+    ):
+        if not data or len(data) < 3:
+            raise ValueError("Dados inválidos para insert.")
+
+        table_name = data[0][0]
+        table_obj = columns_definitions[table_name][data[1][0]]["table_obj"]
+        md_idx = len(data[1])-1
+
+        rows = []
+        for row in data[2:]:
+            if md_idx != -1 and md_idx < len(row) and row[md_idx] in ("D",):
+                continue
+
+            values = {}
+            for idx, col_name in enumerate(data[1]):
+                if col_name == "MD":
+                    continue
+                if idx < len(row):
+                    values[col_name] = row[idx]
+            rows.append(values)
+
+        if not rows:
+            return None
+
+        return insert(table_obj).values(rows)
+
+    @staticmethod
+    def buid_delete(
+        columns_definitions: Dict[str, Dict[str, Dict[str, Any]]],
+        keys: List[List[Any]] = [],
+        relationships: List[List[Any]] = [],
+        filters: List[List[Any]] = [],
+    ):
+        if not keys or len(keys) < 3:
+            raise ValueError("Dados inválidos para delete.")
+
+        table_name = keys[0][0]
+        table_obj = columns_definitions[table_name][keys[1][0]]["table_obj"]
+        stmts = []
+
+        for row in keys[2:]:
+            row_filters = [keys[0], keys[1], row]
+            cond = DbDriverUtils._build_filters(columns_definitions, row_filters)
+            if cond is None:
+                continue
+
+            stmt = delete(table_obj).where(cond)
+            extra_filter = DbDriverUtils._build_filters(columns_definitions, filters)
+            if extra_filter is not None:
+                stmt = stmt.where(extra_filter)
+            stmts.append(stmt)
+
+        return stmts
+
+    @staticmethod
+    def _build_filters(
+        columns_definitions: Dict[str, Dict[str, Dict[str, Any]]],
+        filters: List[List[Any]],
+    ):
+        if not filters or len(filters) < 3:
+            return None
+
+        row_conditions = []
+        for row in filters[2:]:
+            col_conditions = []
+            for idx, raw_value in enumerate(row):
+                if idx >= len(filters[0]) or idx >= len(filters[1]):
+                    continue
+                if raw_value is None:
+                    continue
+
+                table_name = filters[0][idx]
+                col_name = filters[1][idx]
+                column = columns_definitions[table_name][col_name]["column_obj"]
+                value = DbDriverUtils._valid_info(str(column.type), raw_value)
+
+                if isinstance(raw_value, tuple) and len(raw_value) == 2:
+                    op, val = raw_value
+                    val = DbDriverUtils._valid_info(str(column.type), val)
+                    if op == "!=":
+                        col_conditions.append(column != val)
+                    elif op == ">":
+                        col_conditions.append(column > val)
+                    elif op == ">=":
+                        col_conditions.append(column >= val)
+                    elif op == "<":
+                        col_conditions.append(column < val)
+                    elif op == "<=":
+                        col_conditions.append(column <= val)
+                    elif op == "like":
+                        col_conditions.append(column.like(val))
+                    else:
+                        col_conditions.append(column == val)
+                else:
+                    col_conditions.append(column == value)
+
+            if col_conditions:
+                row_conditions.append(and_(*col_conditions))
+
+        if not row_conditions:
+            return None
+        return or_(*row_conditions)
+
+    @staticmethod
+    def _valid_info(type: str, info: Any) -> Any:
+        if info is None:
+            return None
+
+        type_upper = type.upper()
+        try:
+            if "INT" in type_upper:
+                return int(info)
+            if "FLOAT" in type_upper or "NUMERIC" in type_upper or "DECIMAL" in type_upper:
+                return float(info)
+            if "BOOL" in type_upper:
+                if isinstance(info, bool):
+                    return info
+                return str(info).strip().lower() in ("1", "true", "t", "y", "yes")
+            return info
+        except Exception:
+            return info
+
+    @staticmethod
+    def to_matrix_from_records(column_names: List[str], records: List[List[Any]]) -> List[List[Any]]:
+        if not column_names:
+            return []
+        table_row = ["__result__" for _ in column_names]
+        return [table_row, list(column_names), *records]
+
+    @staticmethod
+    def to_meta_matrix(rowcount: int) -> List[List[Any]]:
+        return [["__meta__"], ["rowcount"], [rowcount]]
+
+    @staticmethod
+    def expand_structure(
+        columns_definitions: Dict[str, Dict[str, Dict[str, Any]]],
+        matrix: List[List[Any]],
+        include_md: bool = False,
+    ) -> Tuple[List[Any], List[Any], List[int]]:
+        if not matrix or len(matrix) < 2:
+            raise ValueError("Matriz inválida. É necessário ter ao menos 2 linhas.")
+
+        src_tables = list(matrix[0])
+        src_headers = list(matrix[1])
+        src_pairs = [(src_tables[i], src_headers[i]) for i in range(min(len(src_tables), len(src_headers)))]
+
+        has_md = "MD" in src_headers
+        md_idx = src_headers.index("MD") if has_md else -1
+
+        tables_in_order: List[str] = []
+        for t in src_tables:
+            if t not in tables_in_order and t in columns_definitions:
+                tables_in_order.append(t)
+
+        target_tables: List[Any] = []
+        target_headers: List[Any] = []
+        for t in tables_in_order:
+            for col_name in columns_definitions[t].keys():
+                target_tables.append(t)
+                target_headers.append(col_name)
+
+        if include_md and has_md:
+            target_tables.append(src_tables[md_idx])
+            target_headers.append("MD")
+
+        source_index_map: List[int] = []
+        for i in range(len(target_headers)):
+            target_pair = (target_tables[i], target_headers[i])
+            idx = next((j for j, pair in enumerate(src_pairs) if pair == target_pair), -1)
+            source_index_map.append(idx)
+
+        return target_tables, target_headers, source_index_map
+
+    @staticmethod
+    def project_matrix(
+        matrix: List[List[Any]],
+        target_tables: List[Any],
+        target_headers: List[Any],
+        source_index_map: List[int],
+        default: Any = None,
+    ) -> List[List[Any]]:
+        if not matrix or len(matrix) < 2:
+            raise ValueError("Matriz inválida. É necessário ter ao menos 2 linhas.")
+
+        out: List[List[Any]] = [target_tables, target_headers]
+        for src_row in matrix[2:]:
+            dst_row: List[Any] = []
+            for src_idx in source_index_map:
+                if src_idx == -1:
+                    dst_row.append(default)
+                elif src_idx < len(src_row):
+                    dst_row.append(src_row[src_idx])
+                else:
+                    dst_row.append(default)
+            out.append(dst_row)
+
+        return out

pyeasymatrixdb/subclasses/__init__.py

@@ -0,0 +1,11 @@
+from .DbDriverCore import DbDriverCore
+from .DbDriverSearch import DbDriverSearch
+from .DbDriverUpdate import DbDriverUpdate
+from .DbDriverUtils import DbDriverUtils
+
+__all__ = [
+    "DbDriverCore",
+    "DbDriverSearch",
+    "DbDriverUpdate",
+    "DbDriverUtils",
+]

pyeasymatrixdb-0.1.0.dist-info/METADATA

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: pyEasyMatrixDb
+Version: 0.1.0
+Summary: Easiest way to search and update a database using matrix like queries
+Author-email: Ricardo Nazar Rodrigues <ricardo@toxt.com.br>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: sqlalchemy>=2.0
+
+# pyEasyDb
+
+Biblioteca Python para consultar e modificar bancos de dados usando **matrizes bidimensionais** como interface.  
+Abstrai SELECT, INSERT, UPDATE e DELETE via SQLAlchemy Core — funciona com qualquer banco suportado (SQLite, PostgreSQL, MySQL, etc.).
+
+## Instalação
+
+```bash
+pip install pyeasymatrixdb
+```
+
+## GitHub
+
+https://github.com/RicNazar/toxt-p10_dbdriver
+
+## Início Rápido
+
+```pythons
+from sqlalchemy import create_engine, MetaData, Table, Column, Integer, String, ForeignKey
+
+# Cria uma engine em memória
+engine = create_engine("sqlite+pysqlite:///:memory:")
+metadata = MetaData()
+
+users = Table("users", metadata,
+    Column("id", Integer, primary_key=True),
+    Column("name", String(100), nullable=False),
+    Column("email", String(150), nullable=False),
+)
+
+orders = Table("orders", metadata,
+    Column("id", Integer, primary_key=True),
+    Column("user_id", ForeignKey("users.id"), nullable=False),
+    Column("product", String(100), nullable=False),
+)
+
+# Cria as tabelas caso não existam
+metadata.create_all(engine)
+
+from pyeasydb import DbDriver
+db = DbDriver(metadata, engine)
+```
+
+## Funcionalidades
+
+### 1. SQL puro — `execute()` / `execute_stmt()`
+
+```python
+# SQL como texto
+resultado = db.execute("SELECT id, name FROM users ORDER BY id")
+# → [["__result__", "__result__"], ["id", "name"], [1, "Ana"], [2, "Bruno"]]
+
+# Statement SQLAlchemy
+from sqlalchemy import select
+stmt = select(users.c.id, users.c.name).where(users.c.id >= 2)
+resultado = db.execute_stmt(stmt)
+```
+
+Comandos sem retorno de linhas devolvem `[["__meta__"], ["rowcount"], [n]]`.
+
+---
+
+### 2. Pesquisa — `db.Pesquisar`
+
+#### Pesquisa simples
+
+```python
+resultado = (
+    db.Pesquisar
+    .define_header([
+        ["users", "users"],
+        ["id",    "name"],
+    ])
+    .search()
+)
+# → [["users", "users"], ["id", "name"], [1, "Ana"], [2, "Bruno"], ...]
+```
+
+#### Pesquisa com JOIN + filtro
+
+```python
+resultado = (
+    db.Pesquisar
+    .define_header([
+        ["users",  "orders",  "orders"],
+        ["name",   "product", "status"],
+    ])
+    .define_relationships([
+        ["orders", "users", "user_id", "id", 1],  # INNER JOIN
+    ])
+    .define_filter([
+        ["orders"],
+        ["status"],
+        ["OPEN"],
+    ])
+    .search()
+)
+```
+
+#### Filtro com OR (múltiplas linhas)
+
+```python
+resultado = (
+    db.Pesquisar
+    .define_header([["users", "users"], ["id", "name"]])
+    .define_filter([
+        ["users"],
+        ["name"],
+        ["Ana"],     # OR
+        ["Carla"],
+    ])
+    .search()
+)
+```
+
+#### Filtro com operadores
+
+```python
+.define_filter([
+    ["users"],
+    ["id"],
+    [(">=", 2)],  # operadores: !=, >, >=, <, <=, like
+])
+```
+
+#### Pesquisa completa (todas as colunas)
+
+```python
+resultado = db.Pesquisar.define_header(header).search(complete=True, default=None)
+# Expande a saída para todas as colunas das tabelas envolvidas.
+# Colunas ausentes são preenchidas com o valor de `default`.
+```
+
+---
+
+### 3. Atualização — `db.Atualizar`
+
+A coluna `MD` (última) controla a operação por linha:
+
+- `"U"` / `"A"` → Upsert (UPDATE se PK existe ou exclusivo Filtro, INSERT caso contrário)
+- `"D"` → DELETE (exige PK ou exclusifi Filtro)
+
+#### Upsert (update + insert)
+
+```python
+resultado = (
+    db.Atualizar
+    .define_data([
+        ["users", "users", "users",     "users"],
+        ["id",    "name",  "email",     "MD"   ],
+        [1,       "Ana R.","ana@x.com", "U"    ],  # atualiza id=1
+        [5,       "Novo",  "novo@x.com","U"    ],  # insere id=5
+    ])
+    .update()
+)
+```
+
+#### Delete
+
+```python
+resultado = (
+    db.Atualizar
+    .define_data([
+        ["orders", "orders",  "orders"],
+        ["id",     "product", "MD"    ],
+        [101,      "Mouse",   "D"    ],
+    ])
+    .update()
+)
+```
+
+#### Atualização com filtro extra
+
+```python
+resultado = (
+    db.Atualizar
+    .define_data([
+        ["orders", "orders", "orders",  "orders"],
+        ["id",     "user_id","status",  "MD"    ],
+        [100,      1,        "CLOSED",  "U"     ],
+    ])
+    .define_filter([
+        ["orders"],
+        ["status"],
+        ["OPEN"],       # só atualiza se status = "OPEN"
+    ])
+    .update()
+)
+```
+
+#### Retorno completo
+
+```python
+resultado = db.Atualizar.define_data(data).update(complete=True, default="<vazio>")
+# Expande a saída para todas as colunas das tabelas, preenchendo ausentes com o default.
+```
+
+---
+
+### 4. Encadeamento (fluent API)
+
+Todos os métodos `define_*` retornam `self`, permitindo encadeamento:
+
+```python
+db.Pesquisar.define_header(h).define_relationships(r).define_filter(f).search()
+db.Atualizar.define_data(d).define_filter(f).update()
+```
+
+### 5. Reset automático
+
+Por padrão, `search()` e `update()` executam `reset()` após a operação, limpando header/filter/data para a próxima chamada. Passe `reset=False` para manter o estado.
+
+---
+
+## Formato das Matrizes
+
+| Modelo            | Linhas | Descrição                                                             |
+| ----------------- | ------ | --------------------------------------------------------------------- |
+| **header**        | 2      | `[tabelas, colunas]` — define colunas do SELECT                       |
+| **filter**        | ≥ 3    | `[tabelas, colunas, valores...]` — AND entre colunas, OR entre linhas |
+| **data**          | ≥ 3    | `[tabelas, colunas, valores...]` — última coluna = `"MD"`             |
+| **relationships** | N      | `[[tabelaA, tabelaB, colA, colB, inner?], ...]`                       |
+
+## Estrutura do Projeto
+
+```
+app/
+  DbDriver/
+    DbDriver.py        — Classe principal (execute, execute_stmt)
+    subclasses/
+      DbDriverCore.py   — Classe base (reset, define_filter, define_relationships)
+      DbDriverSearch.py — Pesquisa (define_header, search)
+      DbDriverUpdate.py — Escrita (define_data, update)
+      DbDriverUtils.py  — Utilitários estáticos (builders, validações)
+```
+
+## Licença
+
+Consulte o arquivo de licença do repositório.

pyeasymatrixdb-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pyeasymatrixdb/DbDriver.py,sha256=IY473MddJQAlb2yLCHWB5TuwIr5DKzILDCot2TZCOgI,1276
+pyeasymatrixdb/__init__.py,sha256=8H2t3RhTOf1UmRcZ83CAnfY9MefOjHsrMgmwCa7FgTI,58
+pyeasymatrixdb/subclasses/DbDriverCore.py,sha256=9_s4iYUR61KzqUiaErdAmo0PR59ryj9wXDMnSpfNtCI,2103
+pyeasymatrixdb/subclasses/DbDriverSearch.py,sha256=K6ULdFWSctGCH6OGOKUHAoXPbR0bdtxxkmiYdNO3mmE,2077
+pyeasymatrixdb/subclasses/DbDriverUpdate.py,sha256=D1066nxVzk58F4fH4aZGDcoVR7wVFVZwztRToCypgeM,5457
+pyeasymatrixdb/subclasses/DbDriverUtils.py,sha256=djlE-5_n0NJUUOWYeaX_idEw7S08QMUwQct9ADRDMkQ,16739
+pyeasymatrixdb/subclasses/__init__.py,sha256=DjnMY74SJjl9rm6rSOZgaL9UTETF5nlQzDd1cVGNfbA,277
+pyeasymatrixdb-0.1.0.dist-info/METADATA,sha256=Z8DAldHE4ZnlAHULbiuLzc0qpyVi-genJuW_YEsf7_I,6529
+pyeasymatrixdb-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pyeasymatrixdb-0.1.0.dist-info/top_level.txt,sha256=VsJhZBUUDHyDZvxDXnoN5dg6f5bLNSDVBZaqAxbgirg,15
+pyeasymatrixdb-0.1.0.dist-info/RECORD,,

pyeasymatrixdb-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyeasymatrixdb-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyeasymatrixdb