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

nia_etl_utils/__init__.py

@@ -11,6 +11,7 @@ Este pacote fornece funções reutilizáveis para:
 - Processamento e exportação de CSV (processa_csv)
 - Processamento paralelo de CSV grandes (processa_csv_paralelo)
 - Manipulação de arquivos e diretórios (limpeza_pastas)
+- Processamento de OCR via API IntelliDoc (ocr)
 
 Exemplo de uso:
 
@@ -19,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")
@@ -32,27 +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, 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.0"
+__version__ = "0.2.2"
 __author__ = "Nícolas Galdino Esmael"
 
-# =============================================================================
-# EXCEÇÕES - Importar primeiro para uso em type hints
-# =============================================================================
-
 # =============================================================================
 # CONFIGURAÇÕES (Dataclasses)
 # =============================================================================
@@ -63,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,
@@ -76,7 +77,9 @@ from .database import (
     obter_engine_postgresql_opengeo,
 )
 
-# Email
+# =============================================================================
+# EMAIL
+# =============================================================================
 from .email_smtp import (
     enviar_email,
     enviar_email_smtp,
@@ -86,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,
@@ -112,36 +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,
 )
 
-# Processamento CSV
+# =============================================================================
+# OCR
+# =============================================================================
+from .ocr import (
+    executar_ocr,
+)
+
+# =============================================================================
+# 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,
@@ -186,6 +200,11 @@ __all__ = [
     "EmailError",
     "DestinatarioError",
     "SmtpError",
+    # Exceções - OCR
+    "OcrError",
+    "OcrSubmissaoError",
+    "OcrProcessamentoError",
+    "OcrTimeoutError",
     # Exceções - Validação
     "ValidacaoError",
     # Configurações
@@ -233,4 +252,6 @@ __all__ = [
     "remover_pasta_recursivamente",
     "criar_pasta_se_nao_existir",
     "listar_arquivos",
+    # OCR
+    "executar_ocr",
 ]

nia_etl_utils/exceptions.py

@@ -18,28 +18,31 @@ Hierarquia:
     ├── EmailError
     │   ├── DestinatarioError
     │   └── SmtpError
+    ├── OcrError
+    │   ├── OcrSubmissaoError
+    │   ├── OcrProcessamentoError
+    │   └── OcrTimeoutError
     └── ValidacaoError
 
 Examples:
     Capturando erros específicos:
 
-    >>> from nia_etl_utils.exceptions import ConexaoError, ExtracaoVaziaError
+    >>> from nia_etl_utils import ConexaoError, OcrTimeoutError
     >>>
     >>> try:
-    ...     conn = conectar_postgresql(config)
-    ... except ConexaoError as e:
-    ...     logger.error(f"Falha na conexão: {e}")
-    ...     # tratamento específico
+    ...     resultado = executar_ocr(documento)
+    ... except OcrTimeoutError as e:
+    ...     logger.error(f"Timeout no OCR: {e}")
 
     Capturando qualquer erro do pacote:
 
-    >>> from nia_etl_utils.exceptions import NiaEtlError
+    >>> from nia_etl_utils import NiaEtlError
     >>>
     >>> try:
     ...     executar_pipeline()
     ... except NiaEtlError as e:
     ...     logger.error(f"Erro no pipeline: {e}")
-    ...     sys.exit(1)  # decisão do CHAMADOR
+    ...     sys.exit(1)
 """
 
 
@@ -80,30 +83,13 @@ class NiaEtlError(Exception):
 
 
 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")
-    """
+    """Erro de configuração do sistema."""
 
     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")
-    """
+    """Variável de ambiente ausente ou inválida."""
 
     def __init__(self, nome_variavel: str):
         self.nome_variavel = nome_variavel
@@ -120,28 +106,13 @@ class VariavelAmbienteError(ConfiguracaoError):
 
 
 class DatabaseError(NiaEtlError):
-    """Erro base para operações de banco de dados.
-
-    Examples:
-        >>> raise DatabaseError("Falha na operação de banco de dados")
-    """
+    """Erro base para operações 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}
-        ... )
-    """
+    """Falha ao estabelecer conexão com banco de dados."""
 
     pass
 
@@ -152,59 +123,25 @@ class ConexaoError(DatabaseError):
 
 
 class ArquivoError(NiaEtlError):
-    """Erro base para operações de arquivo e diretório.
-
-    Examples:
-        >>> raise ArquivoError("Operação de arquivo falhou")
-    """
+    """Erro base para operações de arquivo e diretório."""
 
     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"}
-        ... )
-    """
+    """Falha ao escrever arquivo."""
 
     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"}
-        ... )
-    """
+    """Falha ao ler arquivo."""
 
     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"}
-        ... )
-    """
+    """Falha em operação de diretório."""
 
     pass
 
@@ -215,28 +152,13 @@ class DiretorioError(ArquivoError):
 
 
 class ExtracaoError(NiaEtlError):
-    """Erro base para operações de extração de dados.
-
-    Examples:
-        >>> raise ExtracaoError("Falha na extração de dados")
-    """
+    """Erro base para operações de 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")
-    """
+    """Extração retornou DataFrame vazio ou None."""
 
     def __init__(self, nome_extracao: str):
         self.nome_extracao = nome_extracao
@@ -247,17 +169,7 @@ class ExtracaoVaziaError(ExtracaoError):
 
 
 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"}
-        ... )
-    """
+    """Erro durante processamento de dados."""
 
     pass
 
@@ -268,40 +180,48 @@ class ProcessamentoError(ExtracaoError):
 
 
 class EmailError(NiaEtlError):
-    """Erro base para operações de email.
-
-    Examples:
-        >>> raise EmailError("Falha no envio de email")
-    """
+    """Erro base para operações de email."""
 
     pass
 
 
 class DestinatarioError(EmailError):
-    """Erro relacionado a destinatários de email.
+    """Erro relacionado a destinatários de email."""
 
-    Levantado quando não há destinatários configurados ou
-    quando os destinatários são inválidos.
+    pass
 
-    Examples:
-        >>> raise DestinatarioError("Nenhum destinatário configurado")
-    """
+
+class SmtpError(EmailError):
+    """Erro de comunicação com servidor SMTP."""
 
     pass
 
 
-class SmtpError(EmailError):
-    """Erro de comunicação com servidor SMTP.
+# =============================================================================
+# OCR
+# =============================================================================
 
-    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}
-        ... )
-    """
+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
 
@@ -312,16 +232,6 @@ class SmtpError(EmailError):
 
 
 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": ""}
-        ... )
-    """
+    """Erro de validação de parâmetros ou dados."""
 
     pass