Shori SDK para Python

El Shori SDK para Python es la librería oficial orientada a objetos para integrar aplicaciones Python con la plataforma Syntphony Process Management (Shori). Diseñado con tipado estricto, seguridad en entornos multihilo (thread-safety) y patrones inmutables, facilita la interacción con los servicios core de la plataforma.

Características Principales

Cliente HTTP de Alto Rendimiento: Construido sobre httpx con pool de conexiones activas y reutilización eficiente.
Auto-renovación de Token Bearer: Mecanismo de autenticación con single-flight lock; múltiples hilos concurrentes desencadenan únicamente 1 solicitud de renovación de token.
Inmutabilidad y Thread-Safety: Filtros y objetos de solicitud (Request) inmutables (frozen), seguros para compartir libremente entre hilos sin necesidad de bloqueos (locks).
Validación Robusta: Integración de Pydantic v2 para validación estricta de esquemas, equivalente a Zod en TypeScript.
Paralelización Inteligente: Descarga de archivos adjuntos y consultas concurrentes con pool acotado (max_workers), garantizando el orden de respuesta.
Soporte de Tipado Completo: Marcador py.typed incluido para soporte de tipado estricto en Pyright/Pylance y Mypy en Python ≥ 3.10.
Manejo de Errores: Jerarquía de excepciones personalizada para diferenciar errores de validación, autenticación, comunicación HTTP y errores generales del SDK.

Manejo de Errores

El SDK proporciona una jerarquía de excepciones personalizada para facilitar el manejo de errores durante la comunicación con los servicios de Shori.

Las excepciones permiten diferenciar entre errores de validación, autenticación, comunicación HTTP y errores generales del SDK, evitando que la aplicación consumidora tenga que depender directamente de las excepciones internas de httpx, Pydantic u otras librerías.

Manejo general

Para capturar cualquier error generado por el SDK se puede utilizar la excepción base:

from shori_sdk.exception import ShoriException

try:
    result = client.caso().search(
        CaseFilter.builder()
            .working_sub_state_id("uuid")
            .build()
    )
except ShoriException as e:
    print(f"Error en Shori SDK: {e}")

Manejo por tipo de error

Cuando se necesita un tratamiento específico según el tipo de error, se pueden capturar las excepciones correspondientes:

from shori_sdk.exception import (
    ShoriException,
    ShoriValidationException,
    ShoriAuthenticationException,
    ShoriHttpException,
)

try:
    result = client.caso().search(
        CaseFilter.builder()
            .working_sub_state_id("uuid")
            .build()
    )

except ShoriValidationException as e:
    print(f"Error de validación: {e}")

except ShoriAuthenticationException as e:
    print(f"Error de autenticación: {e}")

except ShoriHttpException as e:
    print(f"Error HTTP: {e}")

except ShoriException as e:
    print(f"Error del SDK: {e}")

Tipos de errores

Tipo	Descripción
`ShoriValidationException`	Los datos proporcionados no cumplen con las validaciones requeridas por el SDK.
`ShoriAuthenticationException`	Se produjo un problema durante la autenticación o renovación del token.
`ShoriHttpException`	La API de Shori respondió con un error HTTP.
`ShoriException`	Excepción base para errores generales del SDK.

Esta estructura permite manejar los errores de forma diferenciada según la necesidad de cada aplicación.

Estructura del Paquete

shori-api-client-py/
│
├── pyproject.toml
├── README.md
├── .env.example
│
├── src/
│   └── shori_sdk/
│       ├── __init__.py        ← API pública exportada
│       │
│       ├── config/            ← Clases de configuración e inmutabilidad
│       │
│       ├── auth/              ← TokenProvider y gestión de credenciales
│       │
│       ├── http/              ← HttpExecutor y cliente HTTP thread-safe
│       │
│       ├── client/             ← Cliente principal ShoriClient
│       │
│       ├── exception/         ← Jerarquía de excepciones personalizadas
│       │
│       ├── utils/             ← Utilidades de mapeo y codificación
│       │
│       └── modules/
│           ├── caso/          ← Gestión de casos, comentarios y estados
│           │
│           └── repo/          ← Gestión documental y descargas
│
└── tests/
    ├── unit/                  ← Pruebas unitarias sin red
    │
    └── integration/           ← Pruebas de integración contra entorno UAT

Características Principales​

Manejo de Errores​

Manejo general​

Manejo por tipo de error​

Tipos de errores​

Estructura del Paquete​