nia-etl-utils 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

nia_etl_utils/processa_csv_paralelo.py

@@ -1,30 +1,80 @@
-"""Processamento paralelo de arquivos CSV grandes."""
-import sys
-from pathlib import Path
-from typing import Callable, List, Optional
+"""Processamento paralelo de arquivos CSV grandes.
+
+Fornece funções para processar arquivos CSV em chunks paralelos,
+otimizando o uso de CPU para transformações em arquivos grandes.
+
+Examples:
+    Processamento básico:
+
+    >>> from nia_etl_utils import processar_csv_paralelo
+    >>>
+    >>> def limpar_texto(texto):
+    ...     if pd.isna(texto):
+    ...         return texto
+    ...     return texto.strip().upper()
+    >>>
+    >>> processar_csv_paralelo(
+    ...     caminho_entrada="dados_brutos.csv",
+    ...     caminho_saida="dados_limpos.csv",
+    ...     colunas_para_tratar=["nome", "descricao"],
+    ...     funcao_transformacao=limpar_texto
+    ... )
+
+    Com configurações customizadas:
+
+    >>> processar_csv_paralelo(
+    ...     caminho_entrada="arquivo_grande.csv",
+    ...     caminho_saida="arquivo_processado.csv",
+    ...     colunas_para_tratar=["texto"],
+    ...     funcao_transformacao=minha_funcao,
+    ...     chunksize=5000,
+    ...     num_processos=4,
+    ...     remover_entrada=True
+    ... )
+"""
+
+from collections.abc import Callable
 from multiprocessing import Pool, cpu_count
+from pathlib import Path
 
 import pandas as pd
 from loguru import logger
 
+from .exceptions import LeituraArquivoError, ProcessamentoError
+
 
 def calcular_chunksize(caminho_arquivo: str) -> int:
     """Calcula tamanho ideal de chunk baseado no tamanho do arquivo.
 
+    Retorna um tamanho de chunk otimizado para balancear uso de memória
+    e eficiência de processamento paralelo.
+
     Args:
         caminho_arquivo: Caminho do arquivo CSV.
 
     Returns:
-        int: Tamanho do chunk otimizado.
+        Tamanho do chunk em número de linhas:
+            - Arquivo < 500MB: 10000 linhas
+            - Arquivo 500MB-2GB: 5000 linhas
+            - Arquivo 2-5GB: 2000 linhas
+            - Arquivo > 5GB: 1000 linhas
+
+    Raises:
+        LeituraArquivoError: Se o arquivo não existir.
 
     Examples:
         >>> chunksize = calcular_chunksize("dados_grandes.csv")
-        >>> # Arquivo < 500MB: 10000 linhas
-        >>> # Arquivo 500MB-2GB: 5000 linhas
-        >>> # Arquivo 2-5GB: 2000 linhas
-        >>> # Arquivo > 5GB: 1000 linhas
+        >>> print(f"Usando chunks de {chunksize} linhas")
     """
-    tamanho_mb = Path(caminho_arquivo).stat().st_size / (1024 * 1024)
+    arquivo = Path(caminho_arquivo)
+
+    if not arquivo.exists():
+        raise LeituraArquivoError(
+            f"Arquivo não encontrado: {caminho_arquivo}",
+            details={"caminho": caminho_arquivo}
+        )
+
+    tamanho_mb = arquivo.stat().st_size / (1024 * 1024)
 
     if tamanho_mb < 500:
         return 10000
@@ -39,7 +89,15 @@ def calcular_chunksize(caminho_arquivo: str) -> int:
 def _processar_chunk(args: tuple) -> pd.DataFrame:
     """Processa um chunk aplicando transformações.
 
-    Função interna usada pelo Pool.imap().
+    Função interna usada pelo Pool.imap(). Não deve ser chamada
+    diretamente.
+
+    Args:
+        args: Tupla contendo (chunk, colunas_para_tratar,
+            func_tratar_texto, normalizar_colunas).
+
+    Returns:
+        DataFrame com transformações aplicadas.
     """
     chunk, colunas_para_tratar, func_tratar_texto, normalizar_colunas = args
 
@@ -60,48 +118,85 @@ def _processar_chunk(args: tuple) -> pd.DataFrame:
 def processar_csv_paralelo(
     caminho_entrada: str,
     caminho_saida: str,
-    colunas_para_tratar: List[str],
+    colunas_para_tratar: list[str],
     funcao_transformacao: Callable,
-    chunksize: Optional[int] = None,
+    chunksize: int | None = None,
     normalizar_colunas: bool = True,
     remover_entrada: bool = False,
-    num_processos: Optional[int] = None
-) -> None:
+    num_processos: int | None = None
+) -> int:
     """Processa CSV grande em paralelo aplicando transformações por chunk.
 
+    Lê o arquivo CSV em chunks, processa cada chunk em paralelo usando
+    multiprocessing, e escreve o resultado no arquivo de saída.
+
     Args:
-        caminho_entrada: Arquivo CSV de entrada.
-        caminho_saida: Arquivo CSV de saída.
-        colunas_para_tratar: Lista de colunas para aplicar transformação.
-        funcao_transformacao: Função que recebe valor e retorna valor transformado.
-        chunksize: Tamanho do chunk. Se None, calcula automaticamente.
-        normalizar_colunas: Se True, converte nomes de colunas para lowercase.
-        remover_entrada: Se True, remove arquivo de entrada após processar.
-        num_processos: Número de processos paralelos. Se None, usa cpu_count().
+        caminho_entrada: Caminho do arquivo CSV de entrada.
+        caminho_saida: Caminho do arquivo CSV de saída.
+        colunas_para_tratar: Lista de nomes de colunas para aplicar
+            a função de transformação.
+        funcao_transformacao: Função que recebe um valor e retorna
+            o valor transformado. Deve tratar valores nulos (None/NaN).
+        chunksize: Número de linhas por chunk. Se None, calcula
+            automaticamente baseado no tamanho do arquivo.
+        normalizar_colunas: Se True, converte nomes de colunas para
+            lowercase. Defaults to True.
+        remover_entrada: Se True, remove arquivo de entrada após
+            processar com sucesso. Defaults to False.
+        num_processos: Número de processos paralelos. Se None, usa
+            o número de CPUs disponíveis.
+
+    Returns:
+        Número total de linhas processadas.
 
     Raises:
-        SystemExit: Se arquivo de entrada não existe ou erro no processamento.
+        LeituraArquivoError: Se arquivo de entrada não existir.
+        ProcessamentoError: Se houver erro durante o processamento.
 
     Examples:
-        >>> from nia_etl_utils import processar_csv_paralelo
-        >>>
+        Processamento básico:
+
         >>> def limpar_texto(texto):
+        ...     if pd.isna(texto):
+        ...         return texto
         ...     return texto.strip().upper()
         >>>
-        >>> processar_csv_paralelo(
+        >>> linhas = processar_csv_paralelo(
         ...     caminho_entrada="dados_brutos.csv",
         ...     caminho_saida="dados_limpos.csv",
         ...     colunas_para_tratar=["nome", "descricao"],
-        ...     funcao_transformacao=limpar_texto,
+        ...     funcao_transformacao=limpar_texto
+        ... )
+        >>> print(f"{linhas} linhas processadas")
+
+        Com configurações customizadas:
+
+        >>> linhas = processar_csv_paralelo(
+        ...     caminho_entrada="arquivo_grande.csv",
+        ...     caminho_saida="arquivo_processado.csv",
+        ...     colunas_para_tratar=["texto"],
+        ...     funcao_transformacao=minha_funcao,
+        ...     chunksize=5000,
+        ...     num_processos=4,
         ...     remover_entrada=True
         ... )
+
+        Tratando erros:
+
+        >>> from nia_etl_utils.exceptions import ProcessamentoError
+        >>> try:
+        ...     processar_csv_paralelo(...)
+        ... except ProcessamentoError as e:
+        ...     logger.error(f"Falha no processamento: {e}")
     """
     caminho_entrada_path = Path(caminho_entrada)
 
     # Validação de entrada
     if not caminho_entrada_path.exists():
-        logger.error(f"Arquivo de entrada não encontrado: {caminho_entrada}")
-        sys.exit(1)
+        raise LeituraArquivoError(
+            f"Arquivo de entrada não encontrado: {caminho_entrada}",
+            details={"caminho": caminho_entrada}
+        )
 
     try:
         logger.info(f"Iniciando processamento paralelo: {caminho_entrada}")
@@ -110,12 +205,14 @@ def processar_csv_paralelo(
         if chunksize is None:
             chunksize = calcular_chunksize(caminho_entrada)
 
-        logger.info(f"Chunksize: {chunksize} linhas | Processos: {num_processos or cpu_count()}")
+        processos = num_processos or cpu_count()
+        logger.info(f"Chunksize: {chunksize} linhas | Processos: {processos}")
 
         # Processamento paralelo
         primeiro_chunk = True
+        total_linhas = 0
 
-        with Pool(processes=num_processos or cpu_count()) as pool:
+        with Pool(processes=processos) as pool:
             reader = pd.read_csv(caminho_entrada, chunksize=chunksize)
 
             # Prepara tasks para processamento paralelo
@@ -126,7 +223,9 @@ def processar_csv_paralelo(
 
             # Processa chunks em paralelo
             for i, chunk_processado in enumerate(pool.imap(_processar_chunk, tasks), start=1):
-                logger.info(f"Escrevendo chunk {i} ({len(chunk_processado)} linhas)")
+                linhas_chunk = len(chunk_processado)
+                total_linhas += linhas_chunk
+                logger.debug(f"Escrevendo chunk {i} ({linhas_chunk} linhas)")
 
                 chunk_processado.to_csv(
                     caminho_saida,
@@ -136,7 +235,7 @@ def processar_csv_paralelo(
                 )
                 primeiro_chunk = False
 
-        logger.success(f"Processamento concluído: {caminho_saida}")
+        logger.success(f"Processamento concluído: {caminho_saida} ({total_linhas} linhas)")
 
         # Remove arquivo de entrada se solicitado
         if remover_entrada:
@@ -146,6 +245,20 @@ def processar_csv_paralelo(
             except Exception as e:
                 logger.warning(f"Falha ao remover arquivo de entrada: {e}")
 
-    except Exception as error:
-        logger.exception(f"Erro no processamento paralelo: {error}")
-        sys.exit(1)
+        return total_linhas
+
+    except pd.errors.EmptyDataError as e:
+        raise ProcessamentoError(
+            f"Arquivo de entrada está vazio: {caminho_entrada}",
+            details={"caminho": caminho_entrada, "erro": str(e)}
+        ) from e
+    except pd.errors.ParserError as e:
+        raise ProcessamentoError(
+            f"Erro ao parsear CSV: {caminho_entrada}",
+            details={"caminho": caminho_entrada, "erro": str(e)}
+        ) from e
+    except Exception as e:
+        raise ProcessamentoError(
+            f"Erro no processamento paralelo: {caminho_entrada}",
+            details={"caminho": caminho_entrada, "erro": str(e)}
+        ) from e

nia_etl_utils/results.py

@@ -0,0 +1,304 @@
+"""Dataclasses de resultado para operações do pacote nia_etl_utils.
+
+Este módulo define estruturas de dados para retorno de operações,
+fornecendo informações estruturadas sobre o resultado de cada ação.
+
+Examples:
+    Resultado de extração:
+
+    >>> resultado = ResultadoExtracao(
+    ...     nome="clientes",
+    ...     caminho="/tmp/clientes_2025_01_20.csv",
+    ...     linhas=1500,
+    ...     sucesso=True
+    ... )
+    >>> if resultado.sucesso:
+    ...     print(f"Exportados {resultado.linhas} registros")
+
+    Resultado com erro:
+
+    >>> resultado = ResultadoExtracao(
+    ...     nome="vendas",
+    ...     caminho=None,
+    ...     linhas=0,
+    ...     sucesso=False,
+    ...     erro="Nenhum dado retornado"
+    ... )
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Conexao:
+    """Wrapper para conexão de banco de dados.
+
+    Encapsula cursor e connection, fornecendo interface consistente
+    e suporte a context manager para fechamento automático.
+
+    Attributes:
+        cursor: Cursor ativo para execução de queries.
+        connection: Objeto de conexão subjacente (psycopg2 ou cx_Oracle).
+        database: Nome/identificador do banco conectado.
+
+    Examples:
+        Uso com context manager (recomendado):
+
+        >>> with conectar_postgresql(config) as conn:
+        ...     conn.cursor.execute("SELECT * FROM tabela")
+        ...     dados = conn.cursor.fetchall()
+        ... # conexão fechada automaticamente
+
+        Uso manual:
+
+        >>> conn = conectar_postgresql(config)
+        >>> try:
+        ...     conn.cursor.execute("SELECT 1")
+        ...     resultado = conn.cursor.fetchone()
+        ... finally:
+        ...     conn.fechar()
+
+        Acesso aos componentes:
+
+        >>> conn = conectar_postgresql(config)
+        >>> conn.cursor.execute("SELECT COUNT(*) FROM usuarios")
+        >>> total = conn.cursor.fetchone()[0]
+        >>> conn.connection.commit()  # se necessário
+        >>> conn.fechar()
+    """
+
+    cursor: Any
+    connection: Any
+    database: str
+
+    def fechar(self) -> None:
+        """Encerra cursor e conexão de forma segura.
+
+        Tenta fechar cursor e conexão, logando warnings em caso
+        de erro mas nunca levantando exceções.
+
+        Examples:
+            >>> conn = conectar_postgresql(config)
+            >>> # ... usar conexão ...
+            >>> conn.fechar()  # sempre seguro
+        """
+        from loguru import logger
+
+        try:
+            if self.cursor:
+                self.cursor.close()
+                logger.debug("Cursor fechado com sucesso.")
+        except Exception as e:
+            logger.warning(f"Erro ao fechar cursor: {e}")
+
+        try:
+            if self.connection:
+                self.connection.close()
+                logger.debug("Conexão encerrada com sucesso.")
+        except Exception as e:
+            logger.warning(f"Erro ao fechar conexão: {e}")
+
+    def __enter__(self) -> "Conexao":
+        """Entrada do context manager."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Saída do context manager - fecha conexão automaticamente."""
+        self.fechar()
+
+
+@dataclass
+class ResultadoExtracao:
+    """Resultado de uma operação de extração e exportação CSV.
+
+    Fornece informações estruturadas sobre o resultado de uma
+    extração, incluindo métricas e status de sucesso/erro.
+
+    Attributes:
+        nome: Identificador da extração.
+        caminho: Caminho do arquivo CSV gerado (None se falhou).
+        linhas: Quantidade de registros extraídos.
+        sucesso: True se a operação completou com sucesso.
+        erro: Mensagem de erro se sucesso=False, None caso contrário.
+        colunas: Quantidade de colunas no DataFrame (opcional).
+        tamanho_bytes: Tamanho do arquivo em bytes (opcional).
+
+    Examples:
+        Extração bem-sucedida:
+
+        >>> resultado = ResultadoExtracao(
+        ...     nome="clientes",
+        ...     caminho="/tmp/clientes_2025_01_20.csv",
+        ...     linhas=1500,
+        ...     sucesso=True,
+        ...     colunas=12,
+        ...     tamanho_bytes=45000
+        ... )
+        >>> print(f"Exportados {resultado.linhas} registros para {resultado.caminho}")
+
+        Extração com falha:
+
+        >>> resultado = ResultadoExtracao(
+        ...     nome="vendas",
+        ...     caminho=None,
+        ...     linhas=0,
+        ...     sucesso=False,
+        ...     erro="Nenhum dado retornado para extração 'vendas'"
+        ... )
+        >>> if not resultado.sucesso:
+        ...     logger.warning(resultado.erro)
+
+        Verificando resultados em lote:
+
+        >>> resultados = exportar_multiplos_csv(extractions, ...)
+        >>> sucesso = [r for r in resultados if r.sucesso]
+        >>> falhas = [r for r in resultados if not r.sucesso]
+        >>> print(f"{len(sucesso)} OK, {len(falhas)} falhas")
+    """
+
+    nome: str
+    caminho: str | None
+    linhas: int
+    sucesso: bool
+    erro: str | None = None
+    colunas: int | None = None
+    tamanho_bytes: int | None = None
+
+    @property
+    def tamanho_kb(self) -> float | None:
+        """Tamanho do arquivo em kilobytes.
+
+        Returns:
+            Tamanho em KB ou None se tamanho_bytes não definido.
+
+        Examples:
+            >>> resultado.tamanho_bytes = 45000
+            >>> resultado.tamanho_kb
+            43.945...
+        """
+        if self.tamanho_bytes is None:
+            return None
+        return self.tamanho_bytes / 1024
+
+    @property
+    def tamanho_mb(self) -> float | None:
+        """Tamanho do arquivo em megabytes.
+
+        Returns:
+            Tamanho em MB ou None se tamanho_bytes não definido.
+
+        Examples:
+            >>> resultado.tamanho_bytes = 1048576
+            >>> resultado.tamanho_mb
+            1.0
+        """
+        if self.tamanho_bytes is None:
+            return None
+        return self.tamanho_bytes / (1024 * 1024)
+
+
+@dataclass
+class ResultadoLote:
+    """Resultado consolidado de operações em lote.
+
+    Agrupa múltiplos ResultadoExtracao e fornece métricas
+    consolidadas sobre o lote.
+
+    Attributes:
+        resultados: Lista de ResultadoExtracao individuais.
+        total: Número total de extrações no lote.
+        sucesso: Número de extrações bem-sucedidas.
+        falhas: Número de extrações que falharam.
+
+    Examples:
+        >>> lote = ResultadoLote(resultados=[r1, r2, r3])
+        >>> print(f"Taxa de sucesso: {lote.taxa_sucesso:.1%}")
+        >>> if lote.todos_sucesso:
+        ...     print("Todas extrações OK!")
+        >>> for falha in lote.extrações_falhas:
+        ...     print(f"Falhou: {falha.nome} - {falha.erro}")
+    """
+
+    resultados: list[ResultadoExtracao] = field(default_factory=list)
+
+    @property
+    def total(self) -> int:
+        """Número total de extrações no lote."""
+        return len(self.resultados)
+
+    @property
+    def sucesso(self) -> int:
+        """Número de extrações bem-sucedidas."""
+        return sum(1 for r in self.resultados if r.sucesso)
+
+    @property
+    def falhas(self) -> int:
+        """Número de extrações que falharam."""
+        return sum(1 for r in self.resultados if not r.sucesso)
+
+    @property
+    def todos_sucesso(self) -> bool:
+        """True se todas as extrações foram bem-sucedidas."""
+        return self.falhas == 0
+
+    @property
+    def taxa_sucesso(self) -> float:
+        """Taxa de sucesso (0.0 a 1.0)."""
+        if self.total == 0:
+            return 0.0
+        return self.sucesso / self.total
+
+    @property
+    def extracoes_sucesso(self) -> list[ResultadoExtracao]:
+        """Lista de extrações bem-sucedidas."""
+        return [r for r in self.resultados if r.sucesso]
+
+    @property
+    def extracoes_falhas(self) -> list[ResultadoExtracao]:
+        """Lista de extrações que falharam."""
+        return [r for r in self.resultados if not r.sucesso]
+
+    @property
+    def total_linhas(self) -> int:
+        """Total de linhas extraídas em todas as extrações."""
+        return sum(r.linhas for r in self.resultados)
+
+    def adicionar(self, resultado: ResultadoExtracao) -> None:
+        """Adiciona um resultado ao lote.
+
+        Args:
+            resultado: ResultadoExtracao a ser adicionado.
+
+        Examples:
+            >>> lote = ResultadoLote()
+            >>> lote.adicionar(resultado1)
+            >>> lote.adicionar(resultado2)
+        """
+        self.resultados.append(resultado)
+
+
+@dataclass
+class ResultadoEmail:
+    """Resultado de envio de email.
+
+    Attributes:
+        sucesso: True se o email foi enviado com sucesso.
+        destinatarios: Lista de destinatários do email.
+        assunto: Assunto do email enviado.
+        erro: Mensagem de erro se sucesso=False.
+        anexo: Caminho do anexo enviado (se houver).
+
+    Examples:
+        >>> resultado = ResultadoEmail(
+        ...     sucesso=True,
+        ...     destinatarios=["admin@empresa.com"],
+        ...     assunto="Relatório Diário"
+        ... )
+    """
+
+    sucesso: bool
+    destinatarios: list[str]
+    assunto: str
+    erro: str | None = None
+    anexo: str | None = None