nia-etl-utils 0.2.1__tar.gz → 0.2.2__tar.gz

{nia_etl_utils-0.2.1 → nia_etl_utils-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nia-etl-utils
-Version: 0.2.1
+Version: 0.2.2
 Summary: Utilitários compartilhados para pipelines ETL do NIA/MPRJ
 Author-email: Nícolas Esmael <nicolas.esmael@mprj.mp.br>
 License: MIT
@@ -51,7 +51,7 @@ Desenvolvida para eliminar duplicação de código, padronizar boas práticas e
 
 ---
 
-## Novidades da v0.2.1
+## Novidades da v0.2.2
 
 - **Módulo OCR** (`executar_ocr`) — processamento de OCR via API IntelliDoc com suporte a PDF, imagens e detecção automática de formato
 - **Exceções de OCR** (`OcrError`, `OcrSubmissaoError`, `OcrProcessamentoError`, `OcrTimeoutError`) — tratamento granular de erros de OCR
@@ -444,8 +444,7 @@ A API processa documentos de forma assíncrona:
 **Formatos suportados:** PDF, JPG, PNG, GIF, BMP, TIFF (detecção automática via magic bytes)
 
 ```python
-from nia_etl_utils import executar_ocr
-from nia_etl_utils.ocr import OcrError, OcrTimeoutError
+from nia_etl_utils import executar_ocr, OcrError, OcrTimeoutError
 
 # Uso básico com variável de ambiente
 with open("documento.pdf", "rb") as f:
@@ -683,7 +682,7 @@ Este projeto usa [Semantic Versioning](https://semver.org/):
 - **MINOR**: Novas funcionalidades (retrocompatíveis)
 - **PATCH**: Correções de bugs
 
-**Versão atual:** `v0.2.1`
+**Versão atual:** `v0.2.2`
 
 ---
 

{nia_etl_utils-0.2.1 → nia_etl_utils-0.2.2}/README.md

@@ -8,7 +8,7 @@ Desenvolvida para eliminar duplicação de código, padronizar boas práticas e
 
 ---
 
-## Novidades da v0.2.1
+## Novidades da v0.2.2
 
 - **Módulo OCR** (`executar_ocr`) — processamento de OCR via API IntelliDoc com suporte a PDF, imagens e detecção automática de formato
 - **Exceções de OCR** (`OcrError`, `OcrSubmissaoError`, `OcrProcessamentoError`, `OcrTimeoutError`) — tratamento granular de erros de OCR
@@ -401,8 +401,7 @@ A API processa documentos de forma assíncrona:
 **Formatos suportados:** PDF, JPG, PNG, GIF, BMP, TIFF (detecção automática via magic bytes)
 
 ```python
-from nia_etl_utils import executar_ocr
-from nia_etl_utils.ocr import OcrError, OcrTimeoutError
+from nia_etl_utils import executar_ocr, OcrError, OcrTimeoutError
 
 # Uso básico com variável de ambiente
 with open("documento.pdf", "rb") as f:
@@ -640,7 +639,7 @@ Este projeto usa [Semantic Versioning](https://semver.org/):
 - **MINOR**: Novas funcionalidades (retrocompatíveis)
 - **PATCH**: Correções de bugs
 
-**Versão atual:** `v0.2.1`
+**Versão atual:** `v0.2.2`
 
 ---
 

{nia_etl_utils-0.2.1 → nia_etl_utils-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "nia-etl-utils"
-version = "0.2.1"
+version = "0.2.2"
 description = "Utilitários compartilhados para pipelines ETL do NIA/MPRJ"
 authors = [
     {name = "Nícolas Esmael", email = "nicolas.esmael@mprj.mp.br"}

{nia_etl_utils-0.2.1 → nia_etl_utils-0.2.2}/src/nia_etl_utils/__init__.py

@@ -20,8 +20,9 @@ Exemplo de uso:
         conectar_postgresql_nia,
         exportar_para_csv,
         PostgresConfig,
+        ConexaoError,
+        OcrError,
     )
-    from nia_etl_utils.exceptions import ConexaoError, ExtracaoVaziaError
 
     # Configuração
     configurar_logger_padrao_nia("meu_pipeline")
@@ -33,39 +34,25 @@ Exemplo de uso:
             dados = conn.cursor.fetchall()
     except ConexaoError as e:
         logger.error(f"Falha na conexão: {e}")
-        sys.exit(1)  # decisão do CHAMADOR
-
-    # Ou com configuração explícita (para testes)
-    config = PostgresConfig(
-        host="localhost",
-        port="5432",
-        database="teste",
-        user="user",
-        password="pass"
-    )
-    with conectar_postgresql(config) as conn:
-        # ...
+        sys.exit(1)
 
 Exemplo de OCR:
 
-    from nia_etl_utils import executar_ocr
-    from nia_etl_utils.ocr import OcrError
+    from nia_etl_utils import executar_ocr, OcrError, OcrTimeoutError
 
     try:
         resultado = executar_ocr(blob_bytes, url_base="INTELLIDOC_URL")
         texto = resultado["full_text"]
         qualidade = resultado["overall_quality"]
+    except OcrTimeoutError as e:
+        logger.error(f"Timeout no OCR: {e}")
     except OcrError as e:
         logger.error(f"Falha no OCR: {e}")
 """
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"
 __author__ = "Nícolas Galdino Esmael"
 
-# =============================================================================
-# EXCEÇÕES - Importar primeiro para uso em type hints
-# =============================================================================
-
 # =============================================================================
 # CONFIGURAÇÕES (Dataclasses)
 # =============================================================================
@@ -76,8 +63,9 @@ from .config import (
     SmtpConfig,
 )
 
-# Database - Funções core
-# Database - Wrappers de conveniência
+# =============================================================================
+# DATABASE
+# =============================================================================
 from .database import (
     conectar_oracle,
     conectar_oracle_ouvidorias,
@@ -89,7 +77,9 @@ from .database import (
     obter_engine_postgresql_opengeo,
 )
 
-# Email
+# =============================================================================
+# EMAIL
+# =============================================================================
 from .email_smtp import (
     enviar_email,
     enviar_email_smtp,
@@ -99,13 +89,16 @@ from .email_smtp import (
 # =============================================================================
 # FUNÇÕES UTILITÁRIAS
 # =============================================================================
-# Configuração de ambiente
 from .env_config import (
     obter_variavel_env,
     obter_variavel_env_bool,
     obter_variavel_env_int,
     obter_variavel_env_lista,
 )
+
+# =============================================================================
+# EXCEÇÕES
+# =============================================================================
 from .exceptions import (
     # Arquivos
     ArquivoError,
@@ -125,41 +118,44 @@ from .exceptions import (
     LeituraArquivoError,
     # Base
     NiaEtlError,
+    # OCR
+    OcrError,
+    OcrProcessamentoError,
+    OcrSubmissaoError,
+    OcrTimeoutError,
     ProcessamentoError,
     SmtpError,
     # Validação
     ValidacaoError,
     VariavelAmbienteError,
 )
-
-# Manipulação de arquivos
 from .limpeza_pastas import (
     criar_pasta_se_nao_existir,
     limpar_pasta,
     listar_arquivos,
     remover_pasta_recursivamente,
 )
-
-# Logging
 from .logger_config import (
     configurar_logger,
     configurar_logger_padrao_nia,
     remover_handlers_existentes,
 )
 
+# =============================================================================
 # OCR
+# =============================================================================
 from .ocr import (
     executar_ocr,
 )
 
-# Processamento CSV
+# =============================================================================
+# CSV
+# =============================================================================
 from .processa_csv import (
     exportar_multiplos_csv,
     exportar_para_csv,
     extrair_e_exportar_csv,
 )
-
-# Processamento CSV Paralelo
 from .processa_csv_paralelo import (
     calcular_chunksize,
     processar_csv_paralelo,
@@ -204,6 +200,11 @@ __all__ = [
     "EmailError",
     "DestinatarioError",
     "SmtpError",
+    # Exceções - OCR
+    "OcrError",
+    "OcrSubmissaoError",
+    "OcrProcessamentoError",
+    "OcrTimeoutError",
     # Exceções - Validação
     "ValidacaoError",
     # Configurações

nia_etl_utils-0.2.2/src/nia_etl_utils/exceptions.py

@@ -0,0 +1,237 @@
+"""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
+    ├── OcrError
+    │   ├── OcrSubmissaoError
+    │   ├── OcrProcessamentoError
+    │   └── OcrTimeoutError
+    └── ValidacaoError
+
+Examples:
+    Capturando erros específicos:
+
+    >>> from nia_etl_utils import ConexaoError, OcrTimeoutError
+    >>>
+    >>> try:
+    ...     resultado = executar_ocr(documento)
+    ... except OcrTimeoutError as e:
+    ...     logger.error(f"Timeout no OCR: {e}")
+
+    Capturando qualquer erro do pacote:
+
+    >>> from nia_etl_utils import NiaEtlError
+    >>>
+    >>> try:
+    ...     executar_pipeline()
+    ... except NiaEtlError as e:
+    ...     logger.error(f"Erro no pipeline: {e}")
+    ...     sys.exit(1)
+"""
+
+
+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."""
+
+    pass
+
+
+class VariavelAmbienteError(ConfiguracaoError):
+    """Variável de ambiente ausente ou inválida."""
+
+    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."""
+
+    pass
+
+
+class ConexaoError(DatabaseError):
+    """Falha ao estabelecer conexão com banco de dados."""
+
+    pass
+
+
+# =============================================================================
+# ARQUIVOS E DIRETÓRIOS
+# =============================================================================
+
+
+class ArquivoError(NiaEtlError):
+    """Erro base para operações de arquivo e diretório."""
+
+    pass
+
+
+class EscritaArquivoError(ArquivoError):
+    """Falha ao escrever arquivo."""
+
+    pass
+
+
+class LeituraArquivoError(ArquivoError):
+    """Falha ao ler arquivo."""
+
+    pass
+
+
+class DiretorioError(ArquivoError):
+    """Falha em operação de diretório."""
+
+    pass
+
+
+# =============================================================================
+# EXTRAÇÃO E PROCESSAMENTO
+# =============================================================================
+
+
+class ExtracaoError(NiaEtlError):
+    """Erro base para operações de extração de dados."""
+
+    pass
+
+
+class ExtracaoVaziaError(ExtracaoError):
+    """Extração retornou DataFrame vazio ou None."""
+
+    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."""
+
+    pass
+
+
+# =============================================================================
+# EMAIL
+# =============================================================================
+
+
+class EmailError(NiaEtlError):
+    """Erro base para operações de email."""
+
+    pass
+
+
+class DestinatarioError(EmailError):
+    """Erro relacionado a destinatários de email."""
+
+    pass
+
+
+class SmtpError(EmailError):
+    """Erro de comunicação com servidor SMTP."""
+
+    pass
+
+
+# =============================================================================
+# OCR
+# =============================================================================
+
+
+class OcrError(NiaEtlError):
+    """Erro base para operações de OCR."""
+
+    pass
+
+
+class OcrSubmissaoError(OcrError):
+    """Falha ao submeter documento para OCR."""
+
+    pass
+
+
+class OcrProcessamentoError(OcrError):
+    """Falha no processamento do documento pela API."""
+
+    pass
+
+
+class OcrTimeoutError(OcrError):
+    """Timeout aguardando resultado do OCR."""
+
+    pass
+
+
+# =============================================================================
+# VALIDAÇÃO
+# =============================================================================
+
+
+class ValidacaoError(NiaEtlError):
+    """Erro de validação de parâmetros ou dados."""
+
+    pass

{nia_etl_utils-0.2.1 → nia_etl_utils-0.2.2}/src/nia_etl_utils/ocr.py

@@ -10,23 +10,13 @@ A API IntelliDoc processa documentos de forma assíncrona:
 Example:
     Uso básico com variável de ambiente:
 
-    >>> from nia_etl_utils.ocr import executar_ocr
+    >>> from nia_etl_utils import executar_ocr, OcrError
     >>>
-    >>> with open("documento.pdf", "rb") as f:
-    ...     resultado = executar_ocr(
-    ...         conteudo=f.read(),
-    ...         url_base="INTELLIDOC_URL",  # env var
-    ...     )
-    >>> print(resultado["full_text"])
-
-    Uso com URL direta e configurações customizadas:
-
-    >>> resultado = executar_ocr(
-    ...     conteudo=blob_bytes,
-    ...     url_base="http://google.com",
-    ...     timeout_polling=600,
-    ...     max_tentativas=5,
-    ... )
+    >>> try:
+    ...     resultado = executar_ocr(blob_bytes, url_base="INTELLIDOC_URL")
+    ...     print(resultado["full_text"])
+    ... except OcrError as e:
+    ...     logger.error(f"Falha no OCR: {e}")
 """
 
 import time
@@ -35,70 +25,11 @@ import requests
 from loguru import logger
 
 from .env_config import obter_variavel_env
-from .exceptions import NiaEtlError
-
-# =============================================================================
-# EXCEÇÕES
-# =============================================================================
-
-
-class OcrError(NiaEtlError):
-    """Erro base para operações de OCR.
-
-    Examples:
-        >>> raise OcrError("Falha no processamento OCR")
-    """
-
-    pass
-
-
-class OcrSubmissaoError(OcrError):
-    """Falha ao submeter documento para OCR.
-
-    Levantado quando não é possível enviar o documento para a API,
-    seja por problemas de rede, timeout ou resposta inválida.
-
-    Examples:
-        >>> raise OcrSubmissaoError(
-        ...     "Timeout ao submeter documento",
-        ...     details={"tentativas": 3, "status": 504}
-        ... )
-    """
-
-    pass
-
-
-class OcrProcessamentoError(OcrError):
-    """Falha no processamento do documento pela API.
-
-    Levantado quando a API retorna status FAILURE ou REVOKED,
-    indicando que o documento não pôde ser processado.
-
-    Examples:
-        >>> raise OcrProcessamentoError(
-        ...     "Documento corrompido",
-        ...     details={"document_id": "abc-123", "erro_api": "invalid format"}
-        ... )
-    """
-
-    pass
-
-
-class OcrTimeoutError(OcrError):
-    """Timeout aguardando resultado do OCR.
-
-    Levantado quando o tempo máximo de polling é atingido
-    sem que a API retorne um resultado final.
-
-    Examples:
-        >>> raise OcrTimeoutError(
-        ...     "Timeout após 300s",
-        ...     details={"document_id": "abc-123", "ultimo_status": "PENDING"}
-        ... )
-    """
-
-    pass
-
+from .exceptions import (
+    OcrProcessamentoError,
+    OcrSubmissaoError,
+    OcrTimeoutError,
+)
 
 # =============================================================================
 # CONSTANTES
@@ -369,15 +300,10 @@ def executar_ocr(
 
         >>> resultado = executar_ocr(
         ...     conteudo=pdf_bytes,
-        ...     url_base="http://google.com",
+        ...     url_base="http://intellidoc.mprj.mp.br",
         ...     timeout_polling=600,
         ... )
         >>> print(f"Qualidade: {resultado['overall_quality']}")
-
-        Acessando detalhes das páginas:
-
-        >>> for page in resultado["pages"]:
-        ...     print(f"Página {page['page_number']}: {page['extraction_method']}")
     """
     conteudo_bytes = _normalizar_para_bytes(conteudo)
     extensao = _detectar_extensao(conteudo_bytes)

{nia_etl_utils-0.2.1 → nia_etl_utils-0.2.2}/src/nia_etl_utils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nia-etl-utils
-Version: 0.2.1
+Version: 0.2.2
 Summary: Utilitários compartilhados para pipelines ETL do NIA/MPRJ
 Author-email: Nícolas Esmael <nicolas.esmael@mprj.mp.br>
 License: MIT
@@ -51,7 +51,7 @@ Desenvolvida para eliminar duplicação de código, padronizar boas práticas e
 
 ---
 
-## Novidades da v0.2.1
+## Novidades da v0.2.2
 
 - **Módulo OCR** (`executar_ocr`) — processamento de OCR via API IntelliDoc com suporte a PDF, imagens e detecção automática de formato
 - **Exceções de OCR** (`OcrError`, `OcrSubmissaoError`, `OcrProcessamentoError`, `OcrTimeoutError`) — tratamento granular de erros de OCR
@@ -444,8 +444,7 @@ A API processa documentos de forma assíncrona:
 **Formatos suportados:** PDF, JPG, PNG, GIF, BMP, TIFF (detecção automática via magic bytes)
 
 ```python
-from nia_etl_utils import executar_ocr
-from nia_etl_utils.ocr import OcrError, OcrTimeoutError
+from nia_etl_utils import executar_ocr, OcrError, OcrTimeoutError
 
 # Uso básico com variável de ambiente
 with open("documento.pdf", "rb") as f:
@@ -683,7 +682,7 @@ Este projeto usa [Semantic Versioning](https://semver.org/):
 - **MINOR**: Novas funcionalidades (retrocompatíveis)
 - **PATCH**: Correções de bugs
 
-**Versão atual:** `v0.2.1`
+**Versão atual:** `v0.2.2`
 
 ---
 

{nia_etl_utils-0.2.1 → nia_etl_utils-0.2.2}/tests/test_ocr.py

@@ -4,15 +4,18 @@ from unittest.mock import MagicMock, patch
 
 import pytest
 
-from nia_etl_utils.ocr import (
+from nia_etl_utils import (
+    NiaEtlError,
     OcrError,
     OcrProcessamentoError,
     OcrSubmissaoError,
     OcrTimeoutError,
+    executar_ocr,
+)
+from nia_etl_utils.ocr import (
     _detectar_extensao,
     _normalizar_para_bytes,
     _resolver_url_base,
-    executar_ocr,
 )
 
 
@@ -400,8 +403,6 @@ class TestExcecoesOcr:
     """Testes para exceções de OCR."""
 
     def test_ocr_error_herda_nia_etl_error(self) -> None:
-        from nia_etl_utils.exceptions import NiaEtlError
-
         erro = OcrError("teste")
         assert isinstance(erro, NiaEtlError)
 

nia_etl_utils-0.2.1/src/nia_etl_utils/exceptions.py

@@ -1,394 +0,0 @@
-"""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
-    ├── OcrError
-    │   ├── OcrSubmissaoError
-    │   ├── OcrProcessamentoError
-    │   └── OcrTimeoutError
-    └── 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
-
-
-# =============================================================================
-# OCR
-# =============================================================================
-
-
-class OcrError(NiaEtlError):
-    """Erro base para operações de OCR.
-
-    Examples:
-        >>> raise OcrError("Falha no processamento OCR")
-    """
-
-    pass
-
-
-class OcrSubmissaoError(OcrError):
-    """Falha ao submeter documento para OCR.
-
-    Levantado quando não é possível enviar o documento para a API,
-    seja por problemas de rede, timeout ou resposta inválida.
-
-    Examples:
-        >>> raise OcrSubmissaoError(
-        ...     "Timeout ao submeter documento",
-        ...     details={"tentativas": 3, "status": 504}
-        ... )
-    """
-
-    pass
-
-
-class OcrProcessamentoError(OcrError):
-    """Falha no processamento do documento pela API.
-
-    Levantado quando a API retorna status FAILURE ou REVOKED,
-    indicando que o documento não pôde ser processado.
-
-    Examples:
-        >>> raise OcrProcessamentoError(
-        ...     "Documento corrompido",
-        ...     details={"document_id": "abc-123", "erro_api": "invalid format"}
-        ... )
-    """
-
-    pass
-
-
-class OcrTimeoutError(OcrError):
-    """Timeout aguardando resultado do OCR.
-
-    Levantado quando o tempo máximo de polling é atingido
-    sem que a API retorne um resultado final.
-
-    Examples:
-        >>> raise OcrTimeoutError(
-        ...     "Timeout após 300s",
-        ...     details={"document_id": "abc-123", "ultimo_status": "PENDING"}
-        ... )
-    """
-
-    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