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

nia_etl_utils/limpeza_pastas.py

@@ -1,12 +1,35 @@
-"""Funções utilitárias para manipulação de arquivos e diretórios."""
-import sys
+"""Funções utilitárias para manipulação de arquivos e diretórios.
+
+Fornece operações comuns de sistema de arquivos com logging
+apropriado e tratamento de erros consistente.
+
+Examples:
+    Limpar pasta antes de processamento:
+
+    >>> from nia_etl_utils import limpar_pasta
+    >>> limpar_pasta("/tmp/meu_pipeline")
+
+    Criar estrutura de diretórios:
+
+    >>> from nia_etl_utils import criar_pasta_se_nao_existir
+    >>> criar_pasta_se_nao_existir("/dados/processados/2025/01")
+
+    Remover pasta temporária:
+
+    >>> from nia_etl_utils import remover_pasta_recursivamente
+    >>> remover_pasta_recursivamente("/tmp/pasta_temporaria")
+"""
+
 import shutil
 from pathlib import Path
+
 from loguru import logger
 
+from .exceptions import DiretorioError
+
 
-def limpar_pasta(pasta: str, log: bool = True) -> None:
-    """Remove todos os arquivos de uma pasta, recriando-a se necessário.
+def limpar_pasta(pasta: str, log: bool = True) -> int:
+    """Remove todos os arquivos de uma pasta, preservando subdiretórios.
 
     Se a pasta não existir, ela será criada. Se existir, todos os arquivos
     dentro dela serão removidos (subdiretórios são preservados).
@@ -15,13 +38,22 @@ def limpar_pasta(pasta: str, log: bool = True) -> None:
         pasta: Caminho da pasta que será limpa.
         log: Se True, emite logs com Loguru. Defaults to True.
 
+    Returns:
+        Número de arquivos removidos.
+
     Raises:
-        SystemExit: Se houver erro ao criar ou limpar a pasta.
+        DiretorioError: Se houver erro ao criar ou limpar a pasta.
 
     Examples:
-        >>> from nia_etl_utils.limpeza_pastas import limpar_pasta
-        >>> limpar_pasta("/tmp/meu_pipeline")
-        >>> # Pasta criada ou limpa com sucesso
+        Limpar pasta de saída antes de processamento:
+
+        >>> from nia_etl_utils import limpar_pasta
+        >>> removidos = limpar_pasta("/tmp/meu_pipeline")
+        >>> print(f"{removidos} arquivo(s) removido(s)")
+
+        Limpar sem logging:
+
+        >>> limpar_pasta("/tmp/dados", log=False)
     """
     try:
         pasta_path = Path(pasta)
@@ -30,46 +62,66 @@ def limpar_pasta(pasta: str, log: bool = True) -> None:
             pasta_path.mkdir(parents=True, exist_ok=True)
             if log:
                 logger.info(f"Pasta criada: {pasta}")
-        else:
-            arquivos_removidos = 0
+            return 0
 
-            for item in pasta_path.iterdir():
-                if item.is_file():
-                    item.unlink()
-                    arquivos_removidos += 1
-                    if log:
-                        logger.debug(f"Arquivo removido: {item}")
+        arquivos_removidos = 0
 
-            if log:
-                logger.info(f"Pasta '{pasta}' limpa com sucesso. {arquivos_removidos} arquivo(s) removido(s).")
+        for item in pasta_path.iterdir():
+            if item.is_file():
+                item.unlink()
+                arquivos_removidos += 1
+                if log:
+                    logger.debug(f"Arquivo removido: {item}")
 
-    except PermissionError as error:
-        logger.error(f"Sem permissão para acessar/modificar a pasta '{pasta}': {error}")
-        sys.exit(1)
-    except OSError as error:
-        logger.error(f"Erro do sistema ao manipular a pasta '{pasta}': {error}")
-        sys.exit(1)
-    except Exception as error:
-        logger.error(f"Erro inesperado ao limpar a pasta '{pasta}': {error}")
-        sys.exit(1)
+        if log:
+            logger.info(
+                f"Pasta '{pasta}' limpa com sucesso. "
+                f"{arquivos_removidos} arquivo(s) removido(s)."
+            )
 
+        return arquivos_removidos
 
-def remover_pasta_recursivamente(pasta: str, log: bool = True) -> None:
+    except PermissionError as e:
+        raise DiretorioError(
+            f"Sem permissão para acessar/modificar a pasta '{pasta}'",
+            details={"pasta": pasta, "erro": str(e)}
+        ) from e
+    except OSError as e:
+        raise DiretorioError(
+            f"Erro do sistema ao manipular a pasta '{pasta}'",
+            details={"pasta": pasta, "erro": str(e)}
+        ) from e
+
+
+def remover_pasta_recursivamente(pasta: str, log: bool = True) -> bool:
     """Remove uma pasta e todo seu conteúdo (arquivos e subpastas).
 
-    ATENÇÃO: Esta função remove TUDO dentro da pasta, incluindo subdiretórios.
-    Use com cautela.
+    ATENÇÃO: Esta função remove TUDO dentro da pasta, incluindo
+    subdiretórios. Use com cautela.
 
     Args:
         pasta: Caminho da pasta que será removida completamente.
         log: Se True, emite logs com Loguru. Defaults to True.
 
+    Returns:
+        True se a pasta foi removida, False se não existia.
+
     Raises:
-        SystemExit: Se houver erro ao remover a pasta.
+        DiretorioError: Se o caminho não for um diretório ou
+            houver erro ao remover.
 
     Examples:
-        >>> from nia_etl_utils.limpeza_pastas import remover_pasta_recursivamente
-        >>> remover_pasta_recursivamente("/tmp/pasta_temporaria")
+        Remover pasta temporária:
+
+        >>> from nia_etl_utils import remover_pasta_recursivamente
+        >>> if remover_pasta_recursivamente("/tmp/pasta_temporaria"):
+        ...     print("Pasta removida")
+        ... else:
+        ...     print("Pasta não existia")
+
+        Remover sem logging:
+
+        >>> remover_pasta_recursivamente("/tmp/dados", log=False)
     """
     try:
         pasta_path = Path(pasta)
@@ -77,41 +129,58 @@ def remover_pasta_recursivamente(pasta: str, log: bool = True) -> None:
         if not pasta_path.exists():
             if log:
                 logger.warning(f"Pasta '{pasta}' não existe. Nada a remover.")
-            return
+            return False
 
         if not pasta_path.is_dir():
-            logger.error(f"'{pasta}' não é um diretório.")
-            sys.exit(1)
+            raise DiretorioError(
+                f"'{pasta}' não é um diretório",
+                details={"pasta": pasta, "tipo": "arquivo"}
+            )
 
         shutil.rmtree(pasta_path)
 
         if log:
             logger.info(f"Pasta '{pasta}' removida completamente (incluindo subpastas).")
 
-    except PermissionError as error:
-        logger.error(f"Sem permissão para remover a pasta '{pasta}': {error}")
-        sys.exit(1)
-    except OSError as error:
-        logger.error(f"Erro do sistema ao remover a pasta '{pasta}': {error}")
-        sys.exit(1)
-    except Exception as error:
-        logger.error(f"Erro inesperado ao remover a pasta '{pasta}': {error}")
-        sys.exit(1)
+        return True
 
+    except PermissionError as e:
+        raise DiretorioError(
+            f"Sem permissão para remover a pasta '{pasta}'",
+            details={"pasta": pasta, "erro": str(e)}
+        ) from e
+    except OSError as e:
+        raise DiretorioError(
+            f"Erro do sistema ao remover a pasta '{pasta}'",
+            details={"pasta": pasta, "erro": str(e)}
+        ) from e
 
-def criar_pasta_se_nao_existir(pasta: str, log: bool = True) -> None:
+
+def criar_pasta_se_nao_existir(pasta: str, log: bool = True) -> bool:
     """Cria uma pasta se ela não existir (incluindo pastas pai).
 
     Args:
         pasta: Caminho da pasta que será criada.
         log: Se True, emite logs com Loguru. Defaults to True.
 
+    Returns:
+        True se a pasta foi criada, False se já existia.
+
     Raises:
-        SystemExit: Se houver erro ao criar a pasta.
+        DiretorioError: Se houver erro ao criar a pasta.
 
     Examples:
-        >>> from nia_etl_utils.limpeza_pastas import criar_pasta_se_nao_existir
-        >>> criar_pasta_se_nao_existir("/tmp/dados/processados/2025")
+        Criar estrutura de diretórios:
+
+        >>> from nia_etl_utils import criar_pasta_se_nao_existir
+        >>> if criar_pasta_se_nao_existir("/tmp/dados/processados/2025"):
+        ...     print("Estrutura criada")
+        ... else:
+        ...     print("Já existia")
+
+        Criar sem logging:
+
+        >>> criar_pasta_se_nao_existir("/tmp/dados", log=False)
     """
     try:
         pasta_path = Path(pasta)
@@ -119,19 +188,83 @@ def criar_pasta_se_nao_existir(pasta: str, log: bool = True) -> None:
         if pasta_path.exists():
             if log:
                 logger.debug(f"Pasta '{pasta}' já existe.")
-            return
+            return False
 
         pasta_path.mkdir(parents=True, exist_ok=True)
 
         if log:
             logger.info(f"Pasta criada: {pasta}")
 
-    except PermissionError as error:
-        logger.error(f"Sem permissão para criar a pasta '{pasta}': {error}")
-        sys.exit(1)
-    except OSError as error:
-        logger.error(f"Erro do sistema ao criar a pasta '{pasta}': {error}")
-        sys.exit(1)
-    except Exception as error:
-        logger.error(f"Erro inesperado ao criar a pasta '{pasta}': {error}")
-        sys.exit(1)
+        return True
+
+    except PermissionError as e:
+        raise DiretorioError(
+            f"Sem permissão para criar a pasta '{pasta}'",
+            details={"pasta": pasta, "erro": str(e)}
+        ) from e
+    except OSError as e:
+        raise DiretorioError(
+            f"Erro do sistema ao criar a pasta '{pasta}'",
+            details={"pasta": pasta, "erro": str(e)}
+        ) from e
+
+
+def listar_arquivos(
+    pasta: str,
+    extensao: str | None = None,
+    recursivo: bool = False
+) -> list[Path]:
+    """Lista arquivos em uma pasta.
+
+    Args:
+        pasta: Caminho da pasta a ser listada.
+        extensao: Filtrar por extensão (ex: ".csv", ".json").
+            Se None, lista todos os arquivos.
+        recursivo: Se True, inclui arquivos em subpastas.
+
+    Returns:
+        Lista de objetos Path para cada arquivo encontrado.
+
+    Raises:
+        DiretorioError: Se a pasta não existir ou não for acessível.
+
+    Examples:
+        Listar todos os CSVs:
+
+        >>> arquivos = listar_arquivos("/tmp/dados", extensao=".csv")
+        >>> for arq in arquivos:
+        ...     print(arq.name)
+
+        Listar recursivamente:
+
+        >>> arquivos = listar_arquivos("/tmp/dados", recursivo=True)
+    """
+    try:
+        pasta_path = Path(pasta)
+
+        if not pasta_path.exists():
+            raise DiretorioError(
+                f"Pasta '{pasta}' não existe",
+                details={"pasta": pasta}
+            )
+
+        if not pasta_path.is_dir():
+            raise DiretorioError(
+                f"'{pasta}' não é um diretório",
+                details={"pasta": pasta}
+            )
+
+        if recursivo:
+            pattern = "**/*" if extensao is None else f"**/*{extensao}"
+            arquivos = [p for p in pasta_path.glob(pattern) if p.is_file()]
+        else:
+            pattern = "*" if extensao is None else f"*{extensao}"
+            arquivos = [p for p in pasta_path.glob(pattern) if p.is_file()]
+
+        return sorted(arquivos)
+
+    except PermissionError as e:
+        raise DiretorioError(
+            f"Sem permissão para acessar a pasta '{pasta}'",
+            details={"pasta": pasta, "erro": str(e)}
+        ) from e

nia_etl_utils/logger_config.py

@@ -1,8 +1,39 @@
-"""Módulo utilitário para configuração de logging com Loguru."""
-import sys
+"""Módulo utilitário para configuração de logging com Loguru.
+
+Fornece funções para configurar o logger com rotação automática,
+retenção configurável e estrutura de diretórios organizada.
+
+Examples:
+    Configuração básica:
+
+    >>> from nia_etl_utils import configurar_logger
+    >>> caminho = configurar_logger("extract", "2025_01_20")
+    >>> logger.info("Pipeline iniciado")
+
+    Configuração com padrões NIA:
+
+    >>> from nia_etl_utils import configurar_logger_padrao_nia
+    >>> caminho = configurar_logger_padrao_nia("ouvidorias_etl")
+
+    Configuração customizada:
+
+    >>> caminho = configurar_logger(
+    ...     prefixo="etl_vendas",
+    ...     data_extracao="2025_01_20",
+    ...     pasta_logs="/var/log/nia",
+    ...     rotation="50 MB",
+    ...     retention="30 days",
+    ...     level="INFO"
+    ... )
+"""
+
+from datetime import datetime
 from pathlib import Path
+
 from loguru import logger
 
+from .exceptions import DiretorioError, ValidacaoError
+
 
 def configurar_logger(
     prefixo: str,
@@ -14,32 +45,43 @@ def configurar_logger(
 ) -> 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.
+    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').
+            Usado para criar subdiretório e nomear arquivo.
         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".
+        pasta_logs: Diretório raiz onde os logs serão armazenados.
+            Defaults to "logs".
+        rotation: Critério de rotação do arquivo. Pode ser tamanho
+            ("10 MB", "500 KB") ou tempo ("1 day", "1 week").
+            Defaults to "10 MB".
+        retention: Tempo de retenção dos logs antigos antes de serem
+            removidos. Defaults to "7 days".
+        level: Nível mínimo de log a ser registrado. Opções: DEBUG,
+            INFO, WARNING, ERROR, CRITICAL. Defaults to "DEBUG".
 
     Returns:
-        str: Caminho completo do arquivo de log criado.
+        Caminho completo do arquivo de log criado.
 
     Raises:
-        SystemExit: Se houver erro ao criar diretórios ou configurar o logger.
+        ValidacaoError: Se prefixo ou data_extracao forem vazios.
+        DiretorioError: Se houver erro ao criar diretórios de log.
 
     Examples:
-        >>> from nia_etl_utils.logger_config import configurar_logger
-        >>> caminho_log = configurar_logger("extract", "2025_01_19")
+        Configuração básica:
+
+        >>> from nia_etl_utils import configurar_logger
+        >>> from loguru import logger
+        >>> caminho = 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(
+        Com configurações customizadas:
+
+        >>> caminho = configurar_logger(
         ...     prefixo="etl_ouvidorias",
         ...     data_extracao="2025_01_19",
         ...     pasta_logs="/var/logs/nia",
@@ -48,16 +90,20 @@ def configurar_logger(
         ...     level="INFO"
         ... )
     """
-    try:
-        # Valida inputs
-        if not prefixo or not prefixo.strip():
-            logger.error("Prefixo não pode ser vazio.")
-            sys.exit(1)
+    # Validações
+    if not prefixo or not prefixo.strip():
+        raise ValidacaoError(
+            "Prefixo não pode ser vazio",
+            details={"parametro": "prefixo", "valor": prefixo}
+        )
 
-        if not data_extracao or not data_extracao.strip():
-            logger.error("Data de extração não pode ser vazia.")
-            sys.exit(1)
+    if not data_extracao or not data_extracao.strip():
+        raise ValidacaoError(
+            "Data de extração não pode ser vazia",
+            details={"parametro": "data_extracao", "valor": data_extracao}
+        )
 
+    try:
         # Cria estrutura de diretórios
         diretorio_log = Path(pasta_logs) / prefixo
         diretorio_log.mkdir(parents=True, exist_ok=True)
@@ -79,15 +125,16 @@ def configurar_logger(
 
         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)
+    except PermissionError as e:
+        raise DiretorioError(
+            f"Sem permissão para criar diretório de logs '{pasta_logs}'",
+            details={"pasta": pasta_logs, "erro": str(e)}
+        ) from e
+    except OSError as e:
+        raise DiretorioError(
+            f"Erro do sistema ao configurar logger em '{pasta_logs}'",
+            details={"pasta": pasta_logs, "erro": str(e)}
+        ) from e
 
 
 def configurar_logger_padrao_nia(nome_pipeline: str) -> str:
@@ -104,17 +151,19 @@ def configurar_logger_padrao_nia(nome_pipeline: str) -> str:
         nome_pipeline: Nome do pipeline (será usado como prefixo e na data).
 
     Returns:
-        str: Caminho completo do arquivo de log criado.
+        Caminho completo do arquivo de log criado.
+
+    Raises:
+        ValidacaoError: Se nome_pipeline for vazio.
+        DiretorioError: Se houver erro ao criar diretórios.
 
     Examples:
-        >>> from nia_etl_utils.logger_config import configurar_logger_padrao_nia
-        >>> from datetime import datetime
+        >>> from nia_etl_utils import configurar_logger_padrao_nia
+        >>> from loguru import logger
         >>>
-        >>> caminho_log = configurar_logger_padrao_nia("ouvidorias_etl")
+        >>> caminho = 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(
@@ -133,8 +182,12 @@ def remover_handlers_existentes() -> None:
     Útil quando você precisa reconfigurar o logger do zero ou quando está
     rodando múltiplos scripts em sequência que configuram o logger.
 
+    Note:
+        Após chamar esta função, apenas o handler padrão (stderr) estará
+        ativo. Chame configurar_logger() para adicionar novos handlers.
+
     Examples:
-        >>> from nia_etl_utils.logger_config import remover_handlers_existentes, configurar_logger
+        >>> from nia_etl_utils import remover_handlers_existentes, configurar_logger
         >>>
         >>> # Remove handlers anteriores
         >>> remover_handlers_existentes()
@@ -143,4 +196,9 @@ def remover_handlers_existentes() -> None:
         >>> configurar_logger("novo_pipeline", "2025_01_19")
     """
     logger.remove()
-    logger.info("Todos os handlers do logger foram removidos.")
+    logger.add(
+        sink=lambda msg: print(msg, end=""),
+        level="DEBUG",
+        format="{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {message}"
+    )
+    logger.debug("Handlers do logger foram resetados.")