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

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/exceptions.py

@@ -27,23 +27,22 @@ Hierarquia:
 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)
 """
 
 
@@ -84,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
@@ -124,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
 
@@ -156,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
 
@@ -219,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
@@ -251,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
 
@@ -272,40 +180,19 @@ 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.
-
-    Levantado quando não há destinatários configurados ou
-    quando os destinatários são inválidos.
-
-    Examples:
-        >>> raise DestinatarioError("Nenhum destinatário configurado")
-    """
+    """Erro relacionado a destinatários de email."""
 
     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}
-        ... )
-    """
+    """Erro de comunicação com servidor SMTP."""
 
     pass
 
@@ -316,59 +203,25 @@ class SmtpError(EmailError):
 
 
 class OcrError(NiaEtlError):
-    """Erro base para operações de OCR.
-
-    Examples:
-        >>> raise OcrError("Falha no processamento OCR")
-    """
+    """Erro base para operações de 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}
-        ... )
-    """
+    """Falha ao submeter documento para OCR."""
 
     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"}
-        ... )
-    """
+    """Falha no processamento do documento pela API."""
 
     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"}
-        ... )
-    """
+    """Timeout aguardando resultado do OCR."""
 
     pass
 
@@ -379,16 +232,6 @@ class OcrTimeoutError(OcrError):
 
 
 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

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.dist-info → nia_etl_utils-0.2.2.dist-info}/METADATA

@@ -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.dist-info → nia_etl_utils-0.2.2.dist-info}/RECORD

@@ -1,16 +1,16 @@
-nia_etl_utils/__init__.py,sha256=kQCql-D62cup5_BJ0DNixoGNwOGcAWwgdTU7LIBldKA,6624
+nia_etl_utils/__init__.py,sha256=a6KmJVa5UKpjfXir1xpI3y9d2DFDKcC8PzRVmRsP1YQ,7000
 nia_etl_utils/config.py,sha256=ITgG-BxmCOKGsyxTJnsQYqQJv5TeM2ng9JlGtUxz0Sw,11842
 nia_etl_utils/database.py,sha256=Ggn9EqSb7SyIRUpumx_DIO3bLN-9-ZrgwkKmuqfIKS0,10789
 nia_etl_utils/email_smtp.py,sha256=F4eVeVmNFnzK-4HU7bKijgPzMzWOWOWXTlFF_1fFdFc,8339
 nia_etl_utils/env_config.py,sha256=LH1FCpaAlo2nVx4SIuL9RGKchkgYP8jJurPe_3_IHEA,5506
-nia_etl_utils/exceptions.py,sha256=y4hVU5x5fiy49aXcbhc1V3PgBbTSfWmZONOEdjVN2Jo,10412
+nia_etl_utils/exceptions.py,sha256=Bp_wC2JhF1KIcpQbAJyNXj6-y1NppeyxxKrCs25zWpA,5936
 nia_etl_utils/limpeza_pastas.py,sha256=OuiSCp7Hxpby0WRgox2Ak-B3ATFpyj08uidmBMwV434,7906
 nia_etl_utils/logger_config.py,sha256=Thhv7uwuhvXMKxef6_2M7lTwE1MfN_LAxWuTHjbLPd0,6787
-nia_etl_utils/ocr.py,sha256=xv4-ohNhdt7G4L2Cc00ifrKIp8anGo43mOYCz30p_Ww,12383
+nia_etl_utils/ocr.py,sha256=u88Gp6syJoHUb4Xe2LvpqiWeBkDU21vYEDtVQ-GVeHA,10482
 nia_etl_utils/processa_csv.py,sha256=BzgN6UUq2mGXjqKdnOaimLOLTXWu9H1SYdE1tJSWZ3M,11834
 nia_etl_utils/processa_csv_paralelo.py,sha256=0tQwsbHzi6UYEc2fp6o2E3pl23XOTvKhCShwCdcqrW0,8859
 nia_etl_utils/results.py,sha256=ah0ZaIymjdDi-4lO24EYiBeZTQpm289_ZHmUpoNQEVs,9156
-nia_etl_utils-0.2.1.dist-info/METADATA,sha256=vjIfaH9k6_oe1FgvCRdJkd_JlgDAGbhgbvoUbQ05Z-w,20285
-nia_etl_utils-0.2.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-nia_etl_utils-0.2.1.dist-info/top_level.txt,sha256=LYLtk9Gh-GaiyyQkwpVs1CoOtnn1G9t8_ijxcFHyjfY,14
-nia_etl_utils-0.2.1.dist-info/RECORD,,
+nia_etl_utils-0.2.2.dist-info/METADATA,sha256=fueKq-dWiMmGL07xqMxw6UpAjF5O2lzZSO6jC87Kfeo,20256
+nia_etl_utils-0.2.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+nia_etl_utils-0.2.2.dist-info/top_level.txt,sha256=LYLtk9Gh-GaiyyQkwpVs1CoOtnn1G9t8_ijxcFHyjfY,14
+nia_etl_utils-0.2.2.dist-info/RECORD,,