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

nia_etl_utils/processa_csv.py

@@ -1,14 +1,51 @@
 """Módulo para exportação de DataFrame para CSV.
 
 Fornece funções utilitárias para salvar DataFrames em formato CSV com
-nomenclatura padronizada e logging adequado.
+nomenclatura padronizada, logging adequado e tratamento de erros.
+
+Examples:
+    Exportação simples:
+
+    >>> from nia_etl_utils import exportar_para_csv
+    >>> import pandas as pd
+    >>> df = pd.DataFrame({"id": [1, 2], "valor": [100, 200]})
+    >>> caminho = exportar_para_csv(df, "vendas", "2025_01_20", "/tmp/dados")
+
+    Extração e exportação:
+
+    >>> from nia_etl_utils import extrair_e_exportar_csv
+    >>> def extrair_clientes():
+    ...     return pd.DataFrame({"id": [1, 2], "nome": ["Ana", "João"]})
+    >>> resultado = extrair_e_exportar_csv(
+    ...     nome_extracao="clientes",
+    ...     funcao_extracao=extrair_clientes,
+    ...     data_extracao="2025_01_20",
+    ...     diretorio_base="/tmp/dados"
+    ... )
+
+    Múltiplas extrações:
+
+    >>> extractions = [
+    ...     {"nome": "clientes", "funcao": extrair_clientes},
+    ...     {"nome": "vendas", "funcao": extrair_vendas},
+    ... ]
+    >>> resultados = exportar_multiplos_csv(extractions, "2025_01_20", "/tmp")
 """
-import sys
+
+from collections.abc import Callable
 from pathlib import Path
-from typing import Callable, Optional
+
 import pandas as pd
 from loguru import logger
 
+from .exceptions import (
+    EscritaArquivoError,
+    ExtracaoError,
+    ExtracaoVaziaError,
+    ValidacaoError,
+)
+from .results import ResultadoExtracao, ResultadoLote
+
 
 def exportar_para_csv(
     df: pd.DataFrame,
@@ -18,36 +55,59 @@ def exportar_para_csv(
 ) -> str:
     """Salva um DataFrame como arquivo CSV.
 
+    Cria o diretório de destino se não existir e salva o DataFrame
+    com nomenclatura padronizada: {nome_arquivo}_{data_extracao}.csv
+
     Args:
-        df: DataFrame a ser salvo.
-        nome_arquivo: Nome base do arquivo (sem extensão).
-        data_extracao: Data que será usada no nome do arquivo (ex: "2025_01_19").
-        diretorio_base: Diretório onde o arquivo será salvo.
+        df: DataFrame a ser salvo. Não pode ser None ou vazio.
+        nome_arquivo: Nome base do arquivo (sem extensão e sem data).
+        data_extracao: Data no formato string para compor o nome
+            do arquivo (ex: "2025_01_19").
+        diretorio_base: Caminho do diretório onde o arquivo será salvo.
+            Será criado se não existir.
 
     Returns:
-        str: Caminho completo do arquivo salvo.
+        Caminho absoluto do arquivo CSV salvo.
 
     Raises:
-        SystemExit: Se houver erro ao salvar o arquivo.
+        ExtracaoVaziaError: Se df for None ou vazio.
+        ValidacaoError: Se nome_arquivo for vazio ou apenas espaços.
+        EscritaArquivoError: Se houver erro de permissão ou sistema
+            ao salvar o arquivo.
 
     Examples:
+        Exportação básica:
+
         >>> import pandas as pd
-        >>> from nia_etl_utils.processa_csv import exportar_para_csv
-        >>>
-        >>> df = pd.DataFrame({"col1": [1, 2], "col2": [3, 4]})
-        >>> caminho = exportar_para_csv(df, "dados", "2025_01_19", "/tmp")
-        >>> # Arquivo salvo: /tmp/dados_2025_01_19.csv
-    """
-    try:
-        # Valida inputs
-        if df is None or df.empty:
-            logger.warning("DataFrame vazio ou None fornecido. Nenhum arquivo será criado.")
-            return ""
+        >>> df = pd.DataFrame({"id": [1, 2], "valor": [100, 200]})
+        >>> caminho = exportar_para_csv(
+        ...     df=df,
+        ...     nome_arquivo="vendas",
+        ...     data_extracao="2025_01_19",
+        ...     diretorio_base="/tmp/dados"
+        ... )
+        >>> print(caminho)
+        /tmp/dados/vendas_2025_01_19.csv
+
+        Com tratamento de erro:
 
-        if not nome_arquivo or not nome_arquivo.strip():
-            logger.error("Nome do arquivo não pode ser vazio.")
-            sys.exit(1)
+        >>> from nia_etl_utils.exceptions import ExtracaoVaziaError
+        >>> try:
+        ...     exportar_para_csv(pd.DataFrame(), "vazio", "2025_01_19", "/tmp")
+        ... except ExtracaoVaziaError:
+        ...     print("DataFrame estava vazio")
+    """
+    # Validações
+    if df is None or df.empty:
+        raise ExtracaoVaziaError(nome_arquivo)
+
+    if not nome_arquivo or not nome_arquivo.strip():
+        raise ValidacaoError(
+            "Nome do arquivo não pode ser vazio",
+            details={"parametro": "nome_arquivo", "valor": nome_arquivo}
+        )
 
+    try:
         # Cria diretório se não existir
         diretorio = Path(diretorio_base)
         diretorio.mkdir(parents=True, exist_ok=True)
@@ -67,15 +127,16 @@ def exportar_para_csv(
 
         return str(caminho_arquivo)
 
-    except PermissionError as error:
-        logger.error(f"Sem permissão para salvar arquivo em '{diretorio_base}': {error}")
-        sys.exit(1)
-    except OSError as error:
-        logger.error(f"Erro do sistema ao salvar CSV em '{diretorio_base}': {error}")
-        sys.exit(1)
-    except Exception as error:
-        logger.error(f"Erro inesperado ao salvar CSV: {error}")
-        sys.exit(1)
+    except PermissionError as e:
+        raise EscritaArquivoError(
+            f"Sem permissão para salvar arquivo em '{diretorio_base}'",
+            details={"diretorio": diretorio_base, "erro": str(e)}
+        ) from e
+    except OSError as e:
+        raise EscritaArquivoError(
+            f"Erro do sistema ao salvar CSV em '{diretorio_base}'",
+            details={"diretorio": diretorio_base, "erro": str(e)}
+        ) from e
 
 
 def extrair_e_exportar_csv(
@@ -83,127 +144,209 @@ def extrair_e_exportar_csv(
     funcao_extracao: Callable[[], pd.DataFrame],
     data_extracao: str,
     diretorio_base: str,
-    falhar_se_vazio: bool = False
-) -> Optional[str]:
-    """Executa uma função de extração e salva o resultado como CSV.
+) -> ResultadoExtracao:
+    """Executa função de extração e salva resultado como CSV.
+
+    Orquestra o fluxo completo: executa a função fornecida, valida
+    o DataFrame retornado e persiste como CSV no diretório especificado.
 
     Args:
-        nome_extracao: Nome base para o arquivo CSV (sem extensão).
-        funcao_extracao: Função que retorna um DataFrame.
-        data_extracao: Data que será usada no nome do arquivo (ex: "2025_01_19").
-        diretorio_base: Diretório onde o arquivo será salvo.
-        falhar_se_vazio: Se True, encerra com sys.exit(1) quando DataFrame for vazio.
-                        Se False, apenas loga warning e retorna None. Defaults to False.
+        nome_extracao: Identificador da extração. Usado no nome do arquivo
+            e nos logs.
+        funcao_extracao: Callable sem argumentos que retorna pd.DataFrame.
+            Será executada dentro de try/except para captura de erros.
+        data_extracao: Data no formato string para compor o nome do arquivo
+            (ex: "2025_01_19").
+        diretorio_base: Caminho do diretório onde o arquivo será salvo.
 
     Returns:
-        str: Caminho do arquivo salvo, ou None se DataFrame estiver vazio e falhar_se_vazio=False.
+        ResultadoExtracao contendo:
+            - nome: Identificador da extração
+            - caminho: Path do arquivo salvo
+            - linhas: Quantidade de registros extraídos
+            - sucesso: True se exportação completou
+            - erro: None se sucesso, mensagem se falha
+            - colunas: Quantidade de colunas
+            - tamanho_bytes: Tamanho do arquivo
 
     Raises:
-        SystemExit: Se houver erro na extração, ao salvar o arquivo,
-                   ou se DataFrame for vazio e falhar_se_vazio=True.
+        ExtracaoVaziaError: Se a função retornar DataFrame vazio ou None.
+        ExtracaoError: Se houver erro na execução da função de extração.
+        ValidacaoError: Se parâmetros de exportação forem inválidos.
+        EscritaArquivoError: Se houver erro ao persistir o arquivo.
 
     Examples:
-        >>> from nia_etl_utils.processa_csv import extrair_e_exportar_csv
-        >>>
-        >>> def extrair_dados():
-        ...     return pd.DataFrame({"col1": [1, 2, 3]})
-        >>>
-        >>> caminho = extrair_e_exportar_csv(
-        ...     nome_extracao="dados_clientes",
-        ...     funcao_extracao=extrair_dados,
+        Extração simples:
+
+        >>> def extrair_clientes():
+        ...     return pd.DataFrame({"id": [1, 2], "nome": ["Ana", "João"]})
+        ...
+        >>> resultado = extrair_e_exportar_csv(
+        ...     nome_extracao="clientes",
+        ...     funcao_extracao=extrair_clientes,
         ...     data_extracao="2025_01_19",
         ...     diretorio_base="/tmp/dados"
         ... )
+        >>> resultado.sucesso
+        True
+        >>> resultado.linhas
+        2
+
+        Tratando extração vazia:
+
+        >>> from nia_etl_utils.exceptions import ExtracaoVaziaError
+        >>> def extrair_vazia():
+        ...     return pd.DataFrame()
+        ...
+        >>> try:
+        ...     extrair_e_exportar_csv(
+        ...         nome_extracao="vazia",
+        ...         funcao_extracao=extrair_vazia,
+        ...         data_extracao="2025_01_19",
+        ...         diretorio_base="/tmp/dados"
+        ...     )
+        ... except ExtracaoVaziaError as e:
+        ...     print(f"Esperado: {e.nome_extracao}")
+        Esperado: vazia
     """
-    try:
-        logger.info(f"Iniciando extração: {nome_extracao}")
+    logger.info(f"Iniciando extração: {nome_extracao}")
 
-        # Executa função de extração
+    # Executa função de extração
+    try:
         df_extraido = funcao_extracao()
-
-        # Valida resultado
-        if df_extraido is None or df_extraido.empty:
-            mensagem = f"Nenhum dado retornado para extração '{nome_extracao}'"
-
-            if falhar_se_vazio:
-                logger.error(mensagem)
-                sys.exit(1)
-            else:
-                logger.warning(mensagem)
-                return None
-
-        # Exporta para CSV
-        caminho = exportar_para_csv(
-            df=df_extraido,
-            nome_arquivo=nome_extracao,
-            data_extracao=data_extracao,
-            diretorio_base=diretorio_base,
-        )
-
-        logger.success(f"Extração concluída com sucesso: {nome_extracao}")
-        return caminho
-
-    except Exception as error:
-        logger.error(f"Erro ao extrair ou salvar '{nome_extracao}': {error}")
-        sys.exit(1)
+    except Exception as e:
+        raise ExtracaoError(
+            f"Erro ao executar extração '{nome_extracao}'",
+            details={"extracao": nome_extracao, "erro": str(e)}
+        ) from e
+
+    # Valida resultado
+    if df_extraido is None or df_extraido.empty:
+        raise ExtracaoVaziaError(nome_extracao)
+
+    # Exporta para CSV
+    caminho = exportar_para_csv(
+        df=df_extraido,
+        nome_arquivo=nome_extracao,
+        data_extracao=data_extracao,
+        diretorio_base=diretorio_base,
+    )
+
+    # Coleta métricas
+    tamanho_bytes = Path(caminho).stat().st_size
+
+    logger.success(f"Extração concluída: {nome_extracao}")
+
+    return ResultadoExtracao(
+        nome=nome_extracao,
+        caminho=caminho,
+        linhas=len(df_extraido),
+        sucesso=True,
+        colunas=len(df_extraido.columns),
+        tamanho_bytes=tamanho_bytes
+    )
 
 
 def exportar_multiplos_csv(
     extractions: list[dict],
     data_extracao: str,
     diretorio_base: str,
-    falhar_se_vazio: bool = False
-) -> dict[str, Optional[str]]:
-    """Executa múltiplas extrações e salva cada uma como CSV.
+    ignorar_vazios: bool = True
+) -> ResultadoLote:
+    """Executa múltiplas extrações em lote e salva cada uma como CSV.
+
+    Itera sobre a lista de extrações, executando cada uma sequencialmente.
+    O comportamento ao encontrar extrações vazias é controlado pelo
+    parâmetro ignorar_vazios.
 
     Args:
-        extractions: Lista de dicionários com 'nome' e 'funcao' para cada extração.
-        data_extracao: Data que será usada nos nomes dos arquivos.
-        diretorio_base: Diretório onde os arquivos serão salvos.
-        falhar_se_vazio: Se True, encerra quando algum DataFrame for vazio.
+        extractions: Lista de dicionários, cada um contendo:
+            - nome (str): Identificador da extração
+            - funcao (Callable[[], pd.DataFrame]): Função de extração
+        data_extracao: Data no formato string para compor os nomes dos
+            arquivos (ex: "2025_01_19").
+        diretorio_base: Caminho do diretório onde os arquivos serão salvos.
+        ignorar_vazios: Comportamento quando uma extração retorna vazio.
+            Se True (default), loga warning e continua com as próximas.
+            Se False, levanta ExtracaoVaziaError imediatamente.
 
     Returns:
-        dict: Mapeamento {nome_extracao: caminho_arquivo} para cada extração bem-sucedida.
+        ResultadoLote contendo lista de ResultadoExtracao e métricas
+        consolidadas (total, sucesso, falhas, taxa de sucesso).
+
+    Raises:
+        ExtracaoVaziaError: Se ignorar_vazios=False e alguma extração
+            retornar DataFrame vazio ou None.
+        ExtracaoError: Se houver erro crítico em alguma extração
+            (não relacionado a dados vazios).
 
     Examples:
-        >>> from nia_etl_utils.processa_csv import exportar_multiplos_csv
-        >>>
-        >>> def extrair_clientes():
-        ...     return pd.DataFrame({"id": [1, 2]})
-        >>>
-        >>> def extrair_vendas():
-        ...     return pd.DataFrame({"valor": [100, 200]})
-        >>>
+        Múltiplas extrações tolerando vazios:
+
         >>> extractions = [
         ...     {"nome": "clientes", "funcao": extrair_clientes},
-        ...     {"nome": "vendas", "funcao": extrair_vendas}
+        ...     {"nome": "vendas", "funcao": extrair_vendas},
         ... ]
-        >>>
-        >>> resultados = exportar_multiplos_csv(
+        >>> lote = exportar_multiplos_csv(
         ...     extractions=extractions,
         ...     data_extracao="2025_01_19",
         ...     diretorio_base="/tmp/dados"
         ... )
+        >>> print(f"{lote.sucesso}/{lote.total} bem-sucedidas")
+        >>> for r in lote.extracoes_sucesso:
+        ...     print(f"{r.nome}: {r.linhas} linhas")
+
+        Falhando na primeira extração vazia:
+
+        >>> try:
+        ...     exportar_multiplos_csv(
+        ...         extractions=extractions,
+        ...         data_extracao="2025_01_19",
+        ...         diretorio_base="/tmp/dados",
+        ...         ignorar_vazios=False
+        ...     )
+        ... except ExtracaoVaziaError:
+        ...     print("Pipeline interrompido por extração vazia")
+
+        Verificando falhas:
+
+        >>> lote = exportar_multiplos_csv(extractions, "2025_01_19", "/tmp")
+        >>> if not lote.todos_sucesso:
+        ...     for falha in lote.extracoes_falhas:
+        ...         logger.warning(f"{falha.nome}: {falha.erro}")
     """
-    resultados = {}
-
+    lote = ResultadoLote()
     logger.info(f"Iniciando {len(extractions)} extrações em lote")
 
     for extracao in extractions:
         nome = extracao["nome"]
         funcao = extracao["funcao"]
 
-        caminho = extrair_e_exportar_csv(
-            nome_extracao=nome,
-            funcao_extracao=funcao,
-            data_extracao=data_extracao,
-            diretorio_base=diretorio_base,
-            falhar_se_vazio=falhar_se_vazio
-        )
-
-        resultados[nome] = caminho
+        try:
+            resultado = extrair_e_exportar_csv(
+                nome_extracao=nome,
+                funcao_extracao=funcao,
+                data_extracao=data_extracao,
+                diretorio_base=diretorio_base,
+            )
+            lote.adicionar(resultado)
+
+        except ExtracaoVaziaError as e:
+            if ignorar_vazios:
+                logger.warning(str(e))
+                lote.adicionar(ResultadoExtracao(
+                    nome=nome,
+                    caminho=None,
+                    linhas=0,
+                    sucesso=False,
+                    erro=str(e)
+                ))
+            else:
+                raise
 
-    sucesso = sum(1 for v in resultados.values() if v is not None)
-    logger.info(f"Extrações concluídas: {sucesso}/{len(extractions)} bem-sucedidas")
+    logger.info(
+        f"Extrações concluídas: {lote.sucesso}/{lote.total} bem-sucedidas "
+        f"({lote.taxa_sucesso:.0%})"
+    )
 
-    return resultados
+    return lote