nez-sdk 1.0.0

SDK de Python para la plataforma NEZ (Networking Execution Zone)

NEZ Python SDK

SDK profesional en Python para interactuar con la plataforma NEZ.

Este proyecto no es un wrapper simple. Su objetivo es abstraer un backend legacy e inconsistente, traduciendo errores, estabilizando payloads y ofreciendo una API de uso clara para el desarrollador.

Que resuelve

• Uso de access_token como query param en todos los requests.
• Traduccion de errores del backend a excepciones Python mas claras.
• Soporte para workflows manuales y workflows definidos por DSL.
• Reautenticacion automatica opcional contra el backend NEZ.
• Pruebas unitarias con pytest y script integral de validacion.

Requisitos

• Python 3.10 o superior
• Instancia activa de NEZ
• Token valido o credenciales validas para autoauth

Instalacion

pip install -e ".[dev]"

Estructura

nez_sdk/
├── auto_auth.py
├── exceptions.py
├── http_client.py
├── nez.py
├── models/
├── services/
└── utils/
tests/
test_nez_sdk.py
configuration.cfg

Inicio rapido con token

from nez_sdk.nez import Nez

nez = Nez(
    base_url="http://localhost:20510/api/v1",
    token="tu_access_token"
)

nfrs = nez.nfrs.list()
print("NFRs disponibles:", len(nfrs))

Inicio rapido con autoautenticacion

from nez_sdk.nez import Nez

nez = Nez(base_url="http://localhost:20510/api/v1")

token = nez.authenticate(
    user="tu_usuario_o_email",
    password="tu_password",
    use_gateway=False
)

print("Token obtenido:", token)

La autoautenticacion usa estos endpoints del backend NEZ:

• POST /auth/api.php?type=6
• POST /APIGateway/API.php?type=20

Modelos principales

Los modelos actuales viven en:

• nez_sdk.models.model_building_block.BuildingBlock
• nez_sdk.models.model_stage.Stage
• nez_sdk.models.model_workflow.Workflow
• nez_sdk.models.model_nfr.NFR

Building Blocks

Crear

from nez_sdk.models.model_building_block import BuildingBlock

bb = BuildingBlock(
    name="thumbnail-service",
    image="registry.example.com/thumbnail:1.0",
    command="python app.py",
    description="Procesa imagenes",
    port=8080
)

response = nez.buildingblocks.create(bb)
print(response)

Listar

buildingblocks = nez.buildingblocks.list()

for item in buildingblocks:
    print(item.id, item.name, item.image)

Actualizar y eliminar

nez.buildingblocks.update("1", bb)
nez.buildingblocks.delete("1")

Nota: los endpoints existen y el SDK los ejecuta, pero el backend NEZ puede responder con 405 u otros errores segun la instancia.

Workflows

Crear workflow manual

from nez_sdk.models.model_stage import Stage
from nez_sdk.models.model_workflow import Workflow

stage = Stage("stage-procesamiento", [bb])
workflow = Workflow("workflow-demo", [stage])

workflow_id = nez.build(workflow)
print(workflow_id)

Endpoints disponibles

nez.workflows.list()
nez.workflows.get("1")
nez.workflows.update("1", workflow)
nez.workflows.delete("1")
nez.workflows.stages("1")

Workflows usando DSL

Puedes definir workflows en configuration.cfg y convertirlos a objetos Python con DSLParser.

Ejemplo

from nez_sdk.utils.dsl_parser import DSLParser

workflow = DSLParser.from_file("configuration.cfg")

print(workflow.name)
print(len(workflow.stages))

workflow_id = nez.build(workflow)
print(workflow_id)

Ejecucion

nez.execution.run("1", platform="docker")
nez.execution.execute("1", puzzle_name="default")
nez.execution.stop("1", puzzle_name="default")
nez.execution.log("1", name="default", folder="/tmp")

Tambien existe la fachada:

nez.execute("1")

Manejo de errores

Excepciones principales:

• NezAPIError
• NezAuthError
• NezNotFoundError
• NezValidationError
• NezConnectionError
• NezResponseError

Ejemplo:

from nez_sdk.exceptions import NezAPIError

try:
    nez.workflows.update("1", workflow)
except NezAPIError as exc:
    print(exc)

Testing

Pruebas unitarias

pytest -q

Script integral/manual

python test_nez_sdk.py

El script test_nez_sdk.py muestra:

• modelos
• DSL
• autoauth
• NFRs
• building blocks
• workflows
• execution
• errores esperados

Demo

Puedes ejecutar el demo de uso general:

python demo_nez_sdk.py

Variables de entorno soportadas por demo_nez_sdk.py y test_nez_sdk.py:

• NEZ_BASE_URL
• NEZ_TOKEN
• NEZ_AUTH_USER
• NEZ_AUTH_PASSWORD
• NEZ_AUTH_USE_GATEWAY

Puedes partir de .env.example para configurar tu entorno local.

Documentacion

La documentacion del proyecto usa MkDocs + mkdocstrings.

Instalacion:

pip install -e ".[docs]"

Vista previa local:

mkdocs serve

Build:

mkdocs build --strict

El proyecto incluye un workflow de GitHub Actions para:

• validar y construir la documentacion en feature/sdk-refactor
• desplegar la documentacion en GitHub Pages desde main o mediante ejecucion manual

Releases y publicacion

El proyecto incluye un workflow de GitHub Actions para:

• construir el paquete Python
• crear automaticamente un Release en GitHub
• publicar automaticamente en PyPI cuando se cree un tag de version

Flujo esperado:

git tag v1.0.1
git push origin v1.0.1

La publicacion en PyPI esta preparada para funcionar con Trusted Publishing usando la accion oficial pypa/gh-action-pypi-publish.

Estado actual

Este SDK ya cubre:

• endpoints documentados del PDF
• autoautenticacion
• traduccion robusta de errores
• pruebas unitarias con alta cobertura

La principal fuente de inestabilidad sigue siendo el backend NEZ, no la estructura base del SDK.

Autor

Desarrollado por Ricardo Prieto Ortega
Correo: [e-mail]
GitHub: https://github.com/RicardoPrietoOrtega
LinkedIn: https://www.linkedin.com/in/ricardo-prieto-ortega/
Institucion: Instituto Tecnologico Superior de El Mante (TEC MANTE)