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

nia_etl_utils/exceptions.py

@@ -0,0 +1,327 @@
+"""Exceções customizadas para o pacote nia_etl_utils.
+
+Este módulo define a hierarquia de exceções usada em todo o pacote,
+permitindo tratamento granular de erros pelos consumidores da biblioteca.
+
+Hierarquia:
+    NiaEtlError (base)
+    ├── ConfiguracaoError
+    │   └── VariavelAmbienteError
+    ├── DatabaseError
+    │   └── ConexaoError
+    ├── ArquivoError
+    │   ├── EscritaArquivoError
+    │   ├── LeituraArquivoError
+    │   └── DiretorioError
+    ├── ExtracaoError
+    │   └── ExtracaoVaziaError
+    ├── EmailError
+    │   ├── DestinatarioError
+    │   └── SmtpError
+    └── ValidacaoError
+
+Examples:
+    Capturando erros específicos:
+
+    >>> from nia_etl_utils.exceptions import ConexaoError, ExtracaoVaziaError
+    >>>
+    >>> try:
+    ...     conn = conectar_postgresql(config)
+    ... except ConexaoError as e:
+    ...     logger.error(f"Falha na conexão: {e}")
+    ...     # tratamento específico
+
+    Capturando qualquer erro do pacote:
+
+    >>> from nia_etl_utils.exceptions import NiaEtlError
+    >>>
+    >>> try:
+    ...     executar_pipeline()
+    ... except NiaEtlError as e:
+    ...     logger.error(f"Erro no pipeline: {e}")
+    ...     sys.exit(1)  # decisão do CHAMADOR
+"""
+
+
+class NiaEtlError(Exception):
+    """Exceção base para todos os erros do pacote nia_etl_utils.
+
+    Todas as exceções customizadas do pacote herdam desta classe,
+    permitindo captura genérica quando necessário.
+
+    Attributes:
+        message: Descrição do erro.
+        details: Informações adicionais opcionais sobre o erro.
+
+    Examples:
+        >>> try:
+        ...     raise NiaEtlError("Algo deu errado", details={"codigo": 123})
+        ... except NiaEtlError as e:
+        ...     print(e.message)
+        ...     print(e.details)
+        Algo deu errado
+        {'codigo': 123}
+    """
+
+    def __init__(self, message: str, details: dict | None = None):
+        self.message = message
+        self.details = details or {}
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        if self.details:
+            return f"{self.message} | Detalhes: {self.details}"
+        return self.message
+
+
+# =============================================================================
+# CONFIGURAÇÃO
+# =============================================================================
+
+
+class ConfiguracaoError(NiaEtlError):
+    """Erro de configuração do sistema.
+
+    Levantado quando há problemas com configurações necessárias
+    para o funcionamento do pacote.
+
+    Examples:
+        >>> raise ConfiguracaoError("Configuração inválida para conexão")
+    """
+
+    pass
+
+
+class VariavelAmbienteError(ConfiguracaoError):
+    """Variável de ambiente ausente ou inválida.
+
+    Levantado quando uma variável de ambiente obrigatória não está
+    definida e nenhum valor padrão foi fornecido.
+
+    Attributes:
+        nome_variavel: Nome da variável de ambiente que causou o erro.
+
+    Examples:
+        >>> raise VariavelAmbienteError("DB_HOST")
+    """
+
+    def __init__(self, nome_variavel: str):
+        self.nome_variavel = nome_variavel
+        super().__init__(
+            f"Variável de ambiente '{nome_variavel}' não encontrada "
+            f"e nenhum valor padrão foi fornecido",
+            details={"variavel": nome_variavel}
+        )
+
+
+# =============================================================================
+# DATABASE
+# =============================================================================
+
+
+class DatabaseError(NiaEtlError):
+    """Erro base para operações de banco de dados.
+
+    Examples:
+        >>> raise DatabaseError("Falha na operação de banco de dados")
+    """
+
+    pass
+
+
+class ConexaoError(DatabaseError):
+    """Falha ao estabelecer conexão com banco de dados.
+
+    Levantado quando não é possível conectar ao banco de dados,
+    seja por credenciais inválidas, host inacessível ou outros
+    problemas de conectividade.
+
+    Examples:
+        >>> raise ConexaoError(
+        ...     "Timeout ao conectar",
+        ...     details={"host": "localhost", "port": 5432}
+        ... )
+    """
+
+    pass
+
+
+# =============================================================================
+# ARQUIVOS E DIRETÓRIOS
+# =============================================================================
+
+
+class ArquivoError(NiaEtlError):
+    """Erro base para operações de arquivo e diretório.
+
+    Examples:
+        >>> raise ArquivoError("Operação de arquivo falhou")
+    """
+
+    pass
+
+
+class EscritaArquivoError(ArquivoError):
+    """Falha ao escrever arquivo.
+
+    Levantado quando não é possível criar ou escrever em um arquivo,
+    seja por falta de permissão, disco cheio ou caminho inválido.
+
+    Examples:
+        >>> raise EscritaArquivoError(
+        ...     "Sem permissão para escrita",
+        ...     details={"caminho": "/etc/arquivo.csv"}
+        ... )
+    """
+
+    pass
+
+
+class LeituraArquivoError(ArquivoError):
+    """Falha ao ler arquivo.
+
+    Levantado quando não é possível ler um arquivo, seja porque
+    ele não existe, não há permissão ou está corrompido.
+
+    Examples:
+        >>> raise LeituraArquivoError(
+        ...     "Arquivo não encontrado",
+        ...     details={"caminho": "/tmp/dados.csv"}
+        ... )
+    """
+
+    pass
+
+
+class DiretorioError(ArquivoError):
+    """Falha em operação de diretório.
+
+    Levantado quando não é possível criar, limpar ou remover
+    um diretório.
+
+    Examples:
+        >>> raise DiretorioError(
+        ...     "Sem permissão para criar diretório",
+        ...     details={"caminho": "/root/dados"}
+        ... )
+    """
+
+    pass
+
+
+# =============================================================================
+# EXTRAÇÃO E PROCESSAMENTO
+# =============================================================================
+
+
+class ExtracaoError(NiaEtlError):
+    """Erro base para operações de extração de dados.
+
+    Examples:
+        >>> raise ExtracaoError("Falha na extração de dados")
+    """
+
+    pass
+
+
+class ExtracaoVaziaError(ExtracaoError):
+    """Extração retornou DataFrame vazio ou None.
+
+    Levantado quando uma função de extração não retorna dados.
+    Pode ser esperado em alguns contextos (extração incremental
+    sem novos dados) ou indicar um problema.
+
+    Attributes:
+        nome_extracao: Identificador da extração que falhou.
+
+    Examples:
+        >>> raise ExtracaoVaziaError("clientes_novos")
+    """
+
+    def __init__(self, nome_extracao: str):
+        self.nome_extracao = nome_extracao
+        super().__init__(
+            f"Nenhum dado retornado para extração '{nome_extracao}'",
+            details={"extracao": nome_extracao}
+        )
+
+
+class ProcessamentoError(ExtracaoError):
+    """Erro durante processamento de dados.
+
+    Levantado quando há falha durante transformação ou
+    processamento de dados.
+
+    Examples:
+        >>> raise ProcessamentoError(
+        ...     "Falha ao processar chunk",
+        ...     details={"chunk": 5, "erro": "memória insuficiente"}
+        ... )
+    """
+
+    pass
+
+
+# =============================================================================
+# EMAIL
+# =============================================================================
+
+
+class EmailError(NiaEtlError):
+    """Erro base para operações de email.
+
+    Examples:
+        >>> raise EmailError("Falha no envio de email")
+    """
+
+    pass
+
+
+class DestinatarioError(EmailError):
+    """Erro relacionado a destinatários de email.
+
+    Levantado quando não há destinatários configurados ou
+    quando os destinatários são inválidos.
+
+    Examples:
+        >>> raise DestinatarioError("Nenhum destinatário configurado")
+    """
+
+    pass
+
+
+class SmtpError(EmailError):
+    """Erro de comunicação com servidor SMTP.
+
+    Levantado quando há falha na conexão ou comunicação
+    com o servidor de email.
+
+    Examples:
+        >>> raise SmtpError(
+        ...     "Conexão recusada",
+        ...     details={"servidor": "smtp.empresa.com", "porta": 587}
+        ... )
+    """
+
+    pass
+
+
+# =============================================================================
+# VALIDAÇÃO
+# =============================================================================
+
+
+class ValidacaoError(NiaEtlError):
+    """Erro de validação de parâmetros ou dados.
+
+    Levantado quando parâmetros fornecidos são inválidos
+    ou não atendem aos requisitos esperados.
+
+    Examples:
+        >>> raise ValidacaoError(
+        ...     "Nome do arquivo não pode ser vazio",
+        ...     details={"parametro": "nome_arquivo", "valor": ""}
+        ... )
+    """
+
+    pass

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