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

nia_etl_utils/email_smtp.py

@@ -1,88 +1,147 @@
-"""Módulo responsável por enviar e-mails com ou sem anexo via SMTP."""
+"""Módulo responsável por enviar e-mails via SMTP.
+
+Fornece funções para envio de emails com suporte a anexos,
+múltiplos destinatários e configuração via variáveis de ambiente.
+
+Examples:
+    Envio simples:
+
+    >>> from nia_etl_utils import enviar_email_smtp
+    >>> enviar_email_smtp(
+    ...     corpo_do_email="Pipeline concluído com sucesso",
+    ...     assunto="[PROD] ETL Finalizado"
+    ... )
+
+    Envio com configuração explícita:
+
+    >>> from nia_etl_utils import enviar_email, SmtpConfig
+    >>> config = SmtpConfig(
+    ...     servidor="smtp.empresa.com",
+    ...     porta=587,
+    ...     remetente="sistema@empresa.com",
+    ...     destinatarios_padrao=["admin@empresa.com"]
+    ... )
+    >>> resultado = enviar_email(
+    ...     config=config,
+    ...     corpo="Relatório em anexo",
+    ...     assunto="Relatório Mensal",
+    ...     anexo="/tmp/relatorio.pdf"
+    ... )
+"""
+
 import os
 import smtplib
-import sys
 from email import encoders
 from email.mime.base import MIMEBase
 from email.mime.multipart import MIMEMultipart
 from email.mime.text import MIMEText
+from pathlib import Path
+
 from loguru import logger
 
+from .config import SmtpConfig
 from .env_config import obter_variavel_env
+from .exceptions import DestinatarioError, LeituraArquivoError, SmtpError
+from .results import ResultadoEmail
 
 
 def obter_destinatarios_padrao() -> list[str]:
-    """Obtém lista de destinatários da variável de ambiente EMAIL_DESTINATARIOS.
+    """Obtém lista de destinatários da variável de ambiente.
+
+    Busca a variável EMAIL_DESTINATARIOS e faz parse dos emails
+    separados por vírgula.
 
     Returns:
-        Lista de emails extraída da env var.
+        Lista de endereços de email.
 
     Raises:
-        SystemExit: Se EMAIL_DESTINATARIOS estiver vazia ou contiver apenas valores inválidos.
+        DestinatarioError: Se EMAIL_DESTINATARIOS estiver vazia
+            ou contiver apenas valores inválidos.
+
+    Examples:
+        >>> # Com EMAIL_DESTINATARIOS="admin@x.com,dev@x.com"
+        >>> destinatarios = obter_destinatarios_padrao()
+        >>> print(destinatarios)
+        ['admin@x.com', 'dev@x.com']
     """
     destinatarios_str = obter_variavel_env("EMAIL_DESTINATARIOS").strip()
-    destinatarios = [email.strip() for email in destinatarios_str.split(',') if email.strip()]
+    destinatarios = [
+        email.strip()
+        for email in destinatarios_str.split(',')
+        if email.strip()
+    ]
 
     if not destinatarios:
-        logger.error(
+        raise DestinatarioError(
             "EMAIL_DESTINATARIOS está vazia ou contém apenas valores inválidos. "
             "Configure a variável com destinatários separados por vírgula."
         )
-        sys.exit(1)
 
     return destinatarios
 
 
-def enviar_email_smtp(
-    corpo_do_email: str,
+def enviar_email(
+    config: SmtpConfig,
+    corpo: str,
     assunto: str,
     destinatarios: list[str] | None = None,
     anexo: str | None = None
-) -> None:
-    """Envia um e-mail com ou sem anexo via SMTP.
+) -> ResultadoEmail:
+    """Envia email via SMTP usando configuração explícita.
 
     Args:
-        corpo_do_email: Texto que será enviado no corpo do e-mail.
+        config: Configuração do servidor SMTP.
+        corpo: Texto do corpo do email.
         assunto: Assunto da mensagem.
-        destinatarios: Lista de endereços de e-mail. Se None, usa EMAIL_DESTINATARIOS da env var.
-        anexo: Caminho para arquivo anexo. Defaults to None.
+        destinatarios: Lista de destinatários. Se None, usa
+            config.destinatarios_padrao.
+        anexo: Caminho para arquivo anexo (opcional).
+
+    Returns:
+        ResultadoEmail com status do envio.
 
     Raises:
-        SystemExit: Se destinatários não forem fornecidos e EMAIL_DESTINATARIOS não existir,
-                   ou se ocorrer qualquer erro durante o envio do email.
+        DestinatarioError: Se nenhum destinatário for fornecido.
+        LeituraArquivoError: Se arquivo de anexo não existir.
+        SmtpError: Se houver erro na comunicação com servidor SMTP.
 
     Examples:
-        >>> # Uso padrão (destinatários da env var)
-        >>> enviar_email_smtp(
-        ...     corpo_do_email="Pipeline concluído",
-        ...     assunto="[PROD] ETL Finalizado"
-        ... )
-
-        >>> # Com destinatários específicos
-        >>> enviar_email_smtp(
-        ...     corpo_do_email="Relatório executivo",
-        ...     assunto="Relatório Mensal",
-        ...     destinatarios=["diretor@mprj.mp.br"],
+        >>> config = SmtpConfig.from_env()
+        >>> resultado = enviar_email(
+        ...     config=config,
+        ...     corpo="Relatório em anexo",
+        ...     assunto="Relatório Diário",
         ...     anexo="/tmp/relatorio.pdf"
         ... )
+        >>> if resultado.sucesso:
+        ...     print("Email enviado!")
     """
-    if destinatarios is None:
-        destinatarios = obter_destinatarios_padrao()
+    # Define destinatários
+    dest = destinatarios or config.destinatarios_padrao
 
-    if not destinatarios:
-        logger.error("Nenhum destinatário fornecido. E-mail não pode ser enviado.")
-        sys.exit(1)
+    if not dest:
+        raise DestinatarioError("Nenhum destinatário fornecido para envio do email")
+
+    # Valida anexo se fornecido
+    if anexo and not Path(anexo).exists():
+        raise LeituraArquivoError(
+            f"Arquivo de anexo não encontrado: {anexo}",
+            details={"caminho": anexo}
+        )
 
     try:
+        # Monta mensagem
         email_msg = MIMEMultipart()
-        email_msg['From'] = obter_variavel_env('MAIL_SENDER')
-        email_msg['To'] = ", ".join(destinatarios)
-        email_msg['Cc'] = 'gadg.etl@mprj.mp.br'
+        email_msg['From'] = config.remetente
+        email_msg['To'] = ", ".join(dest)
+        if config.cc:
+            email_msg['Cc'] = config.cc
         email_msg['Subject'] = assunto
 
-        corpo_da_mensagem = MIMEText(corpo_do_email, 'plain')
+        corpo_da_mensagem = MIMEText(corpo, 'plain')
         email_msg.attach(corpo_da_mensagem)
 
+        # Anexa arquivo se fornecido
         if anexo:
             attachment = MIMEBase('application', 'octet-stream')
             with open(anexo, 'rb') as attachment_file:
@@ -94,33 +153,108 @@ def enviar_email_smtp(
             )
             email_msg.attach(attachment)
 
-        logger.info("Iniciando conexão com o servidor SMTP...")
-        with smtplib.SMTP(
-            obter_variavel_env('MAIL_SMTP_SERVER'),
-            int(obter_variavel_env('MAIL_SMTP_PORT'))
-        ) as server:
-            server.sendmail(
-                obter_variavel_env('MAIL_SENDER'),
-                destinatarios,
-                email_msg.as_string()
-            )
-            logger.info(f"E-mail enviado com sucesso para {destinatarios}")
-
-    except smtplib.SMTPRecipientsRefused as error:
-        logger.error(f"Destinatários recusaram o e-mail: {error}")
-        sys.exit(1)
-    except smtplib.SMTPDataError as error:
-        logger.error(f"Erro durante a transferência de dados: {error}")
-        sys.exit(1)
-    except smtplib.SMTPException as error:
-        logger.error(f"Erro ao enviar o e-mail: {error}")
-        sys.exit(1)
-    except ConnectionError as error:
-        logger.error(f"Erro de conexão com servidor SMTP: {error}")
-        sys.exit(1)
-    except FileNotFoundError as error:
-        logger.error(f"Arquivo de anexo não encontrado: {error}")
-        sys.exit(1)
-    except Exception as error:
-        logger.error(f"Erro inesperado ao enviar e-mail: {error}")
-        sys.exit(1)
+        # Envia
+        logger.info(f"Conectando ao servidor SMTP {config.servidor}:{config.porta}...")
+
+        with smtplib.SMTP(config.servidor, config.porta) as server:
+            server.sendmail(config.remetente, dest, email_msg.as_string())
+            logger.success(f"Email enviado com sucesso para {dest}")
+
+        return ResultadoEmail(
+            sucesso=True,
+            destinatarios=dest,
+            assunto=assunto,
+            anexo=anexo
+        )
+
+    except smtplib.SMTPRecipientsRefused as e:
+        raise SmtpError(
+            "Destinatários recusaram o email",
+            details={"destinatarios": dest, "erro": str(e)}
+        ) from e
+    except smtplib.SMTPDataError as e:
+        raise SmtpError(
+            "Erro durante transferência de dados SMTP",
+            details={"erro": str(e)}
+        ) from e
+    except smtplib.SMTPException as e:
+        raise SmtpError(
+            "Erro SMTP ao enviar email",
+            details={"servidor": config.servidor, "erro": str(e)}
+        ) from e
+    except ConnectionError as e:
+        raise SmtpError(
+            f"Erro de conexão com servidor SMTP {config.servidor}",
+            details={"servidor": config.servidor, "porta": config.porta, "erro": str(e)}
+        ) from e
+
+
+def enviar_email_smtp(
+    corpo_do_email: str,
+    assunto: str,
+    destinatarios: list[str] | None = None,
+    anexo: str | None = None
+) -> ResultadoEmail:
+    """Envia email via SMTP usando variáveis de ambiente.
+
+    Função de conveniência que carrega configuração de variáveis
+    de ambiente automaticamente.
+
+    Variáveis utilizadas:
+        - MAIL_SMTP_SERVER: Endereço do servidor SMTP
+        - MAIL_SMTP_PORT: Porta do servidor
+        - MAIL_SENDER: Endereço do remetente
+        - EMAIL_DESTINATARIOS: Destinatários padrão (separados por vírgula)
+        - MAIL_CC: Endereço para cópia (opcional)
+
+    Args:
+        corpo_do_email: Texto que será enviado no corpo do email.
+        assunto: Assunto da mensagem.
+        destinatarios: Lista de endereços de email. Se None, usa
+            EMAIL_DESTINATARIOS da variável de ambiente.
+        anexo: Caminho para arquivo anexo (opcional).
+
+    Returns:
+        ResultadoEmail com status do envio.
+
+    Raises:
+        DestinatarioError: Se nenhum destinatário for fornecido e
+            EMAIL_DESTINATARIOS não existir.
+        LeituraArquivoError: Se arquivo de anexo não existir.
+        SmtpError: Se houver erro na comunicação com servidor SMTP.
+        ConfiguracaoError: Se variáveis de ambiente estiverem ausentes.
+
+    Examples:
+        Uso padrão (destinatários da variável de ambiente):
+
+        >>> enviar_email_smtp(
+        ...     corpo_do_email="Pipeline concluído",
+        ...     assunto="[PROD] ETL Finalizado"
+        ... )
+
+        Com destinatários específicos:
+
+        >>> enviar_email_smtp(
+        ...     corpo_do_email="Relatório executivo",
+        ...     assunto="Relatório Mensal",
+        ...     destinatarios=["diretor@mprj.mp.br"],
+        ...     anexo="/tmp/relatorio.pdf"
+        ... )
+
+        Com tratamento de erro:
+
+        >>> from nia_etl_utils.exceptions import SmtpError
+        >>> try:
+        ...     enviar_email_smtp("Teste", "Assunto Teste")
+        ... except SmtpError as e:
+        ...     logger.error(f"Falha no envio: {e}")
+    """
+    config = SmtpConfig.from_env()
+
+    return enviar_email(
+        config=config,
+        corpo=corpo_do_email,
+        assunto=assunto,
+        destinatarios=destinatarios,
+        anexo=anexo
+    )

nia_etl_utils/env_config.py

@@ -1,43 +1,165 @@
-"""Módulo utilitário para buscar variáveis de ambiente com suporte a valor padrão e log de erro."""
+"""Módulo utilitário para gerenciamento de variáveis de ambiente.
+
+Fornece funções para buscar variáveis de ambiente com suporte a
+valores padrão, validação e logging apropriado.
+
+Examples:
+    Variável obrigatória:
+
+    >>> from nia_etl_utils import obter_variavel_env
+    >>> db_host = obter_variavel_env('DB_HOST')  # levanta exceção se não existir
+
+    Variável opcional com fallback:
+
+    >>> porta = obter_variavel_env('DB_PORT', default='5432')
+
+    Tratamento de erro:
+
+    >>> from nia_etl_utils.exceptions import VariavelAmbienteError
+    >>> try:
+    ...     valor = obter_variavel_env('VARIAVEL_INEXISTENTE')
+    ... except VariavelAmbienteError as e:
+    ...     print(f"Variável não encontrada: {e.nome_variavel}")
+"""
+
 import os
-import sys
+
 from dotenv import load_dotenv
 from loguru import logger
 
+from .exceptions import VariavelAmbienteError
+
+# Carrega variáveis do arquivo .env se existir
 load_dotenv()
 
 
-def obter_variavel_env(nome_env: str, default=None):
-    """Retorna o valor de uma variável de ambiente, com fallback opcional.
+def obter_variavel_env(nome_env: str, default: str | None = None) -> str:
+    """Retorna o valor de uma variável de ambiente.
 
-    Se a variável não existir e nenhum valor padrão for fornecido, o processo
-    é encerrado com código de saída 1 (falha), garantindo que pipelines no
-    Airflow detectem o erro corretamente.
+    Busca uma variável de ambiente pelo nome. Se a variável não existir
+    e nenhum valor padrão for fornecido, levanta VariavelAmbienteError.
 
     Args:
         nome_env: Nome da variável de ambiente a ser buscada.
-        default: Valor a ser retornado caso a variável não esteja definida. Defaults to None.
+        default: Valor a ser retornado caso a variável não esteja definida.
+            Se None (padrão), a variável é considerada obrigatória.
 
     Returns:
-        str: Valor da variável de ambiente ou valor padrão.
+        Valor da variável de ambiente ou valor padrão.
 
     Raises:
-        SystemExit: Se a variável não for encontrada e nenhum valor padrão for fornecido.
+        VariavelAmbienteError: Se a variável não for encontrada e
+            nenhum valor padrão for fornecido.
 
     Examples:
-        >>> # Variável obrigatória (falha se não existir)
-        >>> db_host = obter_variavel_env('DB_HOST')
+        Variável obrigatória (falha se não existir):
+
+        >>> db_host = obter_variavel_env('DB_POSTGRESQL_HOST')
+        >>> print(f"Conectando em {db_host}")
+
+        Variável opcional com fallback:
 
-        >>> # Variável opcional com fallback
         >>> porta = obter_variavel_env('DB_PORT', default='5432')
+        >>> timeout = obter_variavel_env('DB_TIMEOUT', default='30')
+
+        Tratando ausência de variável:
+
+        >>> from nia_etl_utils.exceptions import VariavelAmbienteError
+        >>> try:
+        ...     api_key = obter_variavel_env('API_KEY_SECRETA')
+        ... except VariavelAmbienteError as e:
+        ...     logger.error(f"Configure a variável: {e.nome_variavel}")
+        ...     raise
     """
     value = os.getenv(nome_env, default)
 
     if value is None:
         logger.error(
-            f"Variável de ambiente '{nome_env}' não encontrada e nenhum valor padrão foi fornecido. "
+            f"Variável de ambiente '{nome_env}' não encontrada "
+            f"e nenhum valor padrão foi fornecido. "
             f"Configure esta variável antes de executar o script."
         )
-        sys.exit(1)
+        raise VariavelAmbienteError(nome_env)
 
     return value
+
+
+def obter_variavel_env_int(nome_env: str, default: int | None = None) -> int:
+    """Retorna o valor de uma variável de ambiente como inteiro.
+
+    Conveniência para variáveis numéricas como portas e timeouts.
+
+    Args:
+        nome_env: Nome da variável de ambiente.
+        default: Valor inteiro padrão se variável não existir.
+
+    Returns:
+        Valor da variável convertido para inteiro.
+
+    Raises:
+        VariavelAmbienteError: Se a variável não existir e não houver default.
+        ValueError: Se o valor não puder ser convertido para inteiro.
+
+    Examples:
+        >>> porta = obter_variavel_env_int('DB_PORT', default=5432)
+        >>> timeout = obter_variavel_env_int('TIMEOUT_SEGUNDOS', default=30)
+    """
+    default_str = str(default) if default is not None else None
+    valor = obter_variavel_env(nome_env, default=default_str)
+    return int(valor)
+
+
+def obter_variavel_env_bool(nome_env: str, default: bool = False) -> bool:
+    """Retorna o valor de uma variável de ambiente como booleano.
+
+    Valores considerados True: 'true', '1', 'yes', 'on' (case insensitive).
+    Qualquer outro valor é considerado False.
+
+    Args:
+        nome_env: Nome da variável de ambiente.
+        default: Valor booleano padrão se variável não existir.
+
+    Returns:
+        Valor da variável interpretado como booleano.
+
+    Examples:
+        >>> debug = obter_variavel_env_bool('DEBUG_MODE', default=False)
+        >>> verbose = obter_variavel_env_bool('VERBOSE_LOGGING')
+    """
+    default_str = str(default).lower()
+    valor = obter_variavel_env(nome_env, default=default_str)
+    return valor.lower() in ('true', '1', 'yes', 'on')
+
+
+def obter_variavel_env_lista(
+    nome_env: str,
+    separador: str = ',',
+    default: list[str] | None = None
+) -> list[str]:
+    """Retorna o valor de uma variável de ambiente como lista.
+
+    Útil para variáveis que contêm múltiplos valores separados
+    por um delimitador.
+
+    Args:
+        nome_env: Nome da variável de ambiente.
+        separador: Caractere separador dos valores. Padrão: vírgula.
+        default: Lista padrão se variável não existir.
+
+    Returns:
+        Lista de strings extraída da variável.
+
+    Raises:
+        VariavelAmbienteError: Se a variável não existir e não houver default.
+
+    Examples:
+        >>> # EMAIL_DESTINATARIOS="admin@x.com,dev@x.com"
+        >>> emails = obter_variavel_env_lista('EMAIL_DESTINATARIOS')
+        >>> # ['admin@x.com', 'dev@x.com']
+
+        >>> # HOSTS="host1;host2;host3"
+        >>> hosts = obter_variavel_env_lista('HOSTS', separador=';')
+    """
+    default_str = separador.join(default) if default is not None else None
+    valor = obter_variavel_env(nome_env, default=default_str)
+    return [item.strip() for item in valor.split(separador) if item.strip()]