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

nia_etl_utils/logger_config.py

@@ -0,0 +1,146 @@
+"""Módulo utilitário para configuração de logging com Loguru."""
+import sys
+from pathlib import Path
+from loguru import logger
+
+
+def configurar_logger(
+    prefixo: str,
+    data_extracao: str,
+    pasta_logs: str = "logs",
+    rotation: str = "10 MB",
+    retention: str = "7 days",
+    level: str = "DEBUG"
+) -> str:
+    """Configura o logger da aplicação com Loguru.
+
+    Cria um handler de arquivo para o logger com rotação automática e retenção
+    configurável. O arquivo de log é criado em uma estrutura de diretórios
+    organizada por prefixo.
+
+    Args:
+        prefixo: Nome do módulo/pipeline (ex: 'extract', 'transform', 'load').
+        data_extracao: Data usada no nome do arquivo de log (ex: '2025_01_19').
+        pasta_logs: Diretório raiz onde os logs serão armazenados. Defaults to "logs".
+        rotation: Critério de rotação do arquivo (tamanho ou tempo). Defaults to "10 MB".
+        retention: Tempo de retenção dos logs antigos. Defaults to "7 days".
+        level: Nível mínimo de log a ser registrado. Defaults to "DEBUG".
+
+    Returns:
+        str: Caminho completo do arquivo de log criado.
+
+    Raises:
+        SystemExit: Se houver erro ao criar diretórios ou configurar o logger.
+
+    Examples:
+        >>> from nia_etl_utils.logger_config import configurar_logger
+        >>> caminho_log = configurar_logger("extract", "2025_01_19")
+        >>> logger.info("Pipeline iniciado")
+        >>> # Log salvo em: logs/extract/extract_2025_01_19.log
+
+        >>> # Com configurações customizadas
+        >>> caminho_log = configurar_logger(
+        ...     prefixo="etl_ouvidorias",
+        ...     data_extracao="2025_01_19",
+        ...     pasta_logs="/var/logs/nia",
+        ...     rotation="50 MB",
+        ...     retention="30 days",
+        ...     level="INFO"
+        ... )
+    """
+    try:
+        # Valida inputs
+        if not prefixo or not prefixo.strip():
+            logger.error("Prefixo não pode ser vazio.")
+            sys.exit(1)
+
+        if not data_extracao or not data_extracao.strip():
+            logger.error("Data de extração não pode ser vazia.")
+            sys.exit(1)
+
+        # Cria estrutura de diretórios
+        diretorio_log = Path(pasta_logs) / prefixo
+        diretorio_log.mkdir(parents=True, exist_ok=True)
+
+        # Define caminho do arquivo de log
+        caminho_log = diretorio_log / f"{prefixo}_{data_extracao}.log"
+
+        # Configura handler do Loguru
+        logger.add(
+            str(caminho_log),
+            rotation=rotation,
+            retention=retention,
+            level=level,
+            encoding="utf-8",
+            format="{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {name}:{function}:{line} - {message}"
+        )
+
+        logger.info(f"Logger configurado com sucesso. Arquivo de log: {caminho_log}")
+
+        return str(caminho_log)
+
+    except PermissionError as error:
+        logger.error(f"Sem permissão para criar diretório de logs '{pasta_logs}': {error}")
+        sys.exit(1)
+    except OSError as error:
+        logger.error(f"Erro do sistema ao configurar logger em '{pasta_logs}': {error}")
+        sys.exit(1)
+    except Exception as error:
+        logger.error(f"Erro inesperado ao configurar logger: {error}")
+        sys.exit(1)
+
+
+def configurar_logger_padrao_nia(nome_pipeline: str) -> str:
+    """Configura logger com padrões do NIA para pipelines de produção.
+
+    Esta é uma função de conveniência que aplica as configurações padrão
+    usadas pelos pipelines ETL do NIA:
+    - Rotação: 50 MB
+    - Retenção: 30 dias
+    - Nível: INFO (menos verboso que DEBUG)
+    - Pasta: logs/ (relativa ao diretório de execução)
+
+    Args:
+        nome_pipeline: Nome do pipeline (será usado como prefixo e na data).
+
+    Returns:
+        str: Caminho completo do arquivo de log criado.
+
+    Examples:
+        >>> from nia_etl_utils.logger_config import configurar_logger_padrao_nia
+        >>> from datetime import datetime
+        >>>
+        >>> caminho_log = configurar_logger_padrao_nia("ouvidorias_etl")
+        >>> logger.info("Pipeline iniciado com configurações padrão NIA")
+    """
+    from datetime import datetime
+
+    data_hoje = datetime.now().strftime("%Y_%m_%d")
+
+    return configurar_logger(
+        prefixo=nome_pipeline,
+        data_extracao=data_hoje,
+        pasta_logs="logs",
+        rotation="50 MB",
+        retention="30 days",
+        level="INFO"
+    )
+
+
+def remover_handlers_existentes() -> None:
+    """Remove todos os handlers existentes do logger.
+
+    Útil quando você precisa reconfigurar o logger do zero ou quando está
+    rodando múltiplos scripts em sequência que configuram o logger.
+
+    Examples:
+        >>> from nia_etl_utils.logger_config import remover_handlers_existentes, configurar_logger
+        >>>
+        >>> # Remove handlers anteriores
+        >>> remover_handlers_existentes()
+        >>>
+        >>> # Configura novo logger
+        >>> configurar_logger("novo_pipeline", "2025_01_19")
+    """
+    logger.remove()
+    logger.info("Todos os handlers do logger foram removidos.")

nia_etl_utils/processa_csv.py

@@ -0,0 +1,209 @@
+"""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.
+"""
+import sys
+from pathlib import Path
+from typing import Callable, Optional
+import pandas as pd
+from loguru import logger
+
+
+def exportar_para_csv(
+    df: pd.DataFrame,
+    nome_arquivo: str,
+    data_extracao: str,
+    diretorio_base: str
+) -> str:
+    """Salva um DataFrame como arquivo 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.
+
+    Returns:
+        str: Caminho completo do arquivo salvo.
+
+    Raises:
+        SystemExit: Se houver erro ao salvar o arquivo.
+
+    Examples:
+        >>> 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 ""
+
+        if not nome_arquivo or not nome_arquivo.strip():
+            logger.error("Nome do arquivo não pode ser vazio.")
+            sys.exit(1)
+
+        # Cria diretório se não existir
+        diretorio = Path(diretorio_base)
+        diretorio.mkdir(parents=True, exist_ok=True)
+
+        # Monta caminho completo
+        caminho_arquivo = diretorio / f"{nome_arquivo}_{data_extracao}.csv"
+
+        # Salva CSV
+        df.to_csv(caminho_arquivo, index=False, encoding='utf-8')
+
+        # Log com informações úteis
+        tamanho_kb = caminho_arquivo.stat().st_size / 1024
+        logger.success(
+            f"CSV salvo: {caminho_arquivo} "
+            f"({len(df)} linhas, {len(df.columns)} colunas, {tamanho_kb:.2f} KB)"
+        )
+
+        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)
+
+
+def extrair_e_exportar_csv(
+    nome_extracao: str,
+    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.
+
+    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.
+
+    Returns:
+        str: Caminho do arquivo salvo, ou None se DataFrame estiver vazio e falhar_se_vazio=False.
+
+    Raises:
+        SystemExit: Se houver erro na extração, ao salvar o arquivo,
+                   ou se DataFrame for vazio e falhar_se_vazio=True.
+
+    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,
+        ...     data_extracao="2025_01_19",
+        ...     diretorio_base="/tmp/dados"
+        ... )
+    """
+    try:
+        logger.info(f"Iniciando extração: {nome_extracao}")
+
+        # Executa função de extração
+        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)
+
+
+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.
+
+    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.
+
+    Returns:
+        dict: Mapeamento {nome_extracao: caminho_arquivo} para cada extração bem-sucedida.
+
+    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]})
+        >>>
+        >>> extractions = [
+        ...     {"nome": "clientes", "funcao": extrair_clientes},
+        ...     {"nome": "vendas", "funcao": extrair_vendas}
+        ... ]
+        >>>
+        >>> resultados = exportar_multiplos_csv(
+        ...     extractions=extractions,
+        ...     data_extracao="2025_01_19",
+        ...     diretorio_base="/tmp/dados"
+        ... )
+    """
+    resultados = {}
+
+    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
+
+    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")
+
+    return resultados

nia_etl_utils/processa_csv_paralelo.py

@@ -0,0 +1,151 @@
+"""Processamento paralelo de arquivos CSV grandes."""
+import sys
+from pathlib import Path
+from typing import Callable, List, Optional
+from multiprocessing import Pool, cpu_count
+
+import pandas as pd
+from loguru import logger
+
+
+def calcular_chunksize(caminho_arquivo: str) -> int:
+    """Calcula tamanho ideal de chunk baseado no tamanho do arquivo.
+
+    Args:
+        caminho_arquivo: Caminho do arquivo CSV.
+
+    Returns:
+        int: Tamanho do chunk otimizado.
+
+    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
+    """
+    tamanho_mb = Path(caminho_arquivo).stat().st_size / (1024 * 1024)
+
+    if tamanho_mb < 500:
+        return 10000
+    elif tamanho_mb < 2000:
+        return 5000
+    elif tamanho_mb < 5000:
+        return 2000
+    else:
+        return 1000
+
+
+def _processar_chunk(args: tuple) -> pd.DataFrame:
+    """Processa um chunk aplicando transformações.
+
+    Função interna usada pelo Pool.imap().
+    """
+    chunk, colunas_para_tratar, func_tratar_texto, normalizar_colunas = args
+
+    # Aplica transformação nas colunas especificadas
+    for coluna in colunas_para_tratar:
+        if coluna in chunk.columns:
+            chunk[coluna] = chunk[coluna].apply(func_tratar_texto)
+        else:
+            logger.warning(f"Coluna '{coluna}' não encontrada no chunk")
+
+    # Normaliza nomes de colunas se solicitado
+    if normalizar_colunas:
+        chunk.columns = [col.lower() for col in chunk.columns]
+
+    return chunk
+
+
+def processar_csv_paralelo(
+    caminho_entrada: str,
+    caminho_saida: str,
+    colunas_para_tratar: List[str],
+    funcao_transformacao: Callable,
+    chunksize: Optional[int] = None,
+    normalizar_colunas: bool = True,
+    remover_entrada: bool = False,
+    num_processos: Optional[int] = None
+) -> None:
+    """Processa CSV grande em paralelo aplicando transformações por chunk.
+
+    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().
+
+    Raises:
+        SystemExit: Se arquivo de entrada não existe ou erro no processamento.
+
+    Examples:
+        >>> from nia_etl_utils import processar_csv_paralelo
+        >>>
+        >>> def limpar_texto(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,
+        ...     remover_entrada=True
+        ... )
+    """
+    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)
+
+    try:
+        logger.info(f"Iniciando processamento paralelo: {caminho_entrada}")
+
+        # Define chunksize
+        if chunksize is None:
+            chunksize = calcular_chunksize(caminho_entrada)
+
+        logger.info(f"Chunksize: {chunksize} linhas | Processos: {num_processos or cpu_count()}")
+
+        # Processamento paralelo
+        primeiro_chunk = True
+
+        with Pool(processes=num_processos or cpu_count()) as pool:
+            reader = pd.read_csv(caminho_entrada, chunksize=chunksize)
+
+            # Prepara tasks para processamento paralelo
+            tasks = [
+                (chunk, colunas_para_tratar, funcao_transformacao, normalizar_colunas)
+                for chunk in reader
+            ]
+
+            # 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)")
+
+                chunk_processado.to_csv(
+                    caminho_saida,
+                    mode='w' if primeiro_chunk else 'a',
+                    header=primeiro_chunk,
+                    index=False
+                )
+                primeiro_chunk = False
+
+        logger.success(f"Processamento concluído: {caminho_saida}")
+
+        # Remove arquivo de entrada se solicitado
+        if remover_entrada:
+            try:
+                caminho_entrada_path.unlink()
+                logger.info(f"Arquivo de entrada removido: {caminho_entrada}")
+            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)