Referencia de scripting

Esta página documenta la API pública para ejecución headless (sin interfaz) expuesta por el paquete studio de Python.

Se centra en estos símbolos públicos:

• StudioScenario

• install_logging_event

• enable_logging_stdout

• disable_logging_stdout

Si nunca has ejecutado un escenario en modo headless, primero lee la sección Headless y luego vuelve aquí para ver los detalles de la API.

---

Imports

Todas las APIs documentadas aquí se exportan desde el paquete de nivel superior studio:

from studio import (
	StudioScenario,
	install_logging_event,
	enable_logging_stdout,
	disable_logging_stdout,
)

---

Type Stubs

La interfaz pública para headless puede encontrarse aquí:

from __future__ import annotations

from typing import Any, Callable, Optional


def enable_logging_stdout() -> None: ...
def disable_logging_stdout() -> None: ...
def install_logging_event(event: Callable[[str], None]) -> None: ...


class StudioScenario:
	def __init__(self, *, verification_code: str = "") -> None: ...

	def load_scenario(self, path: str) -> Optional[StudioScenario]: ...
	def load_scenario_raw(self, content: str) -> bool: ...
	def save_scenario(self, path: str) -> bool: ...
	def clear_scenario(self) -> bool: ...
	def disable_load_errors(self) -> StudioScenario: ...
	def load_custom_nodes(self, path: str) -> bool: ...

	def get_ports(
		self,
		input_op_title: str = "Subsystem In",
		output_op_title: str = "Subsystem Out",
	) -> dict[str, list[str]]: ...
	def get_name(self) -> str: ...

	def run(self, args: tuple[Any, ...] = ()) -> tuple[list[Any], ...]: ...
	def run_server(
		self,
		inputs: tuple[Any, ...] = (),
		host: str = "127.0.0.1",
		port: int = 8080,
		display_controls: bool = False,
		header: str = "Scenario Server",
	) -> None: ...
	def cleanup(self) -> bool: ...

	def enable_logging_stdout(self) -> StudioScenario: ...
	def disable_logging_stdout(self) -> StudioScenario: ...
	def install_logging_hook(self, hook: Callable[[str, int], None], level: int = 0) -> StudioScenario: ...

	def installStartEvent(self, event: Callable[..., None]) -> StudioScenario: ...
	def installEndEvent(self, event: Callable[..., None]) -> StudioScenario: ...
	def installStepStartEvent(self, event: Callable[..., None]) -> StudioScenario: ...
	def installStepEndEvent(self, event: Callable[..., None]) -> StudioScenario: ...

---

StudioScenario

StudioScenario es el punto de entrada principal para cargar y ejecutar un archivo .pmod sin la interfaz de escritorio (modo headless).

Constructor

scenario = StudioScenario(verification_code="...")

verification_code

Este valor se usa para configurar la licencia en la ejecución headless.

Patrones comunes:

• Máquina local / servidor: pasa la cadena del verification code.

• Docker / CI: monta un archivo de licencia dentro del contenedor y pasa su ruta como verification_code.

Advertencia Para entornos no interactivos (Docker/CI/servicios), siempre pasa verification_code explícitamente.

---

Ciclo típico de uso

En la mayoría de los scripts harás:

1. Crear el escenario (StudioScenario(...))

2. Cargar un .pmod (load_scenario(...))

3. Ejecutarlo (run(...))

4. Limpiar recursos (cleanup())

Ejemplo:

import os

from studio import StudioScenario, enable_logging_stdout


def main() -> None:
	# Opcional: imprime logs de runtime en stdout (útil al depurar).
	enable_logging_stdout()

	verification_code = os.environ.get("AUGELAB_VERIFICATION_CODE", "")
	scenario = StudioScenario(verification_code=verification_code)

	try:
		loaded = scenario.load_scenario("your_scenario.pmod")
		if loaded is None:
			raise FileNotFoundError("Could not load .pmod file")

		# Si tu escenario tiene N puertos de entrada, debes pasar exactamente N args.
		result = scenario.run(args=())
		print("Scenario result:", result)
	finally:
		scenario.cleanup()


if __name__ == "__main__":
	main()

Nota cleanup() es importante en procesos de larga duración (servicios, jobs por lotes) para liberar memoria y resetear el estado de runtime.

---

Cargar un .pmod

scenario.load_scenario("path/to/scenario.pmod")

• Devuelve StudioScenario en caso de éxito.

• Devuelve None si la ruta no existe.

Si tu escenario referencia recursos externos, conserva la misma estructura de carpetas usada en la versión de escritorio (ver la sección “Transferring .pmod files”).

---

Ejecutar un escenario

outputs = scenario.run(args=(... ,))

El runtime valida que el número de argumentos coincida con el número de entradas del escenario.

Si tu .pmod tiene:

• 0 entradas: llama a scenario.run() o scenario.run(())

• 1 entrada: llama a scenario.run((value,))

• 2 entradas: llama a scenario.run((value1, value2))

Advertencia args debe ser una tupla. Para una sola entrada recuerda la coma final: (value,).

---

Más métodos de StudioScenario

Esta sección cubre métodos públicos adicionales que puedes usar para automatización y depuración.

Cargar sin fallar por recursos faltantes

Si mueves escenarios entre máquinas/contenedores y algunos recursos pueden no estar disponibles, puedes optar por cargar de forma más permisiva:

from studio import StudioScenario

scenario = StudioScenario(verification_code="YOUR_CODE")
scenario.disable_load_errors()
scenario.load_scenario("scenario.pmod")

Cargar / guardar

scenario.load_scenario_raw(content="...")
scenario.save_scenario("out.pmod")
scenario.clear_scenario()

Nodos personalizados

Carga módulos Python de nodos personalizados desde una carpeta:

scenario.load_custom_nodes("path/to/custom_nodes")

Advertencia Esto importa dinámicamente archivos Python. Solo carga código de confianza.

Nombre del escenario

name = scenario.get_name()

Puertos (entradas/salidas del escenario)

Puedes obtener los nombres de los puertos de entrada y salida:

ports = scenario.get_ports()
print("inputs:", ports["inputs"])
print("outputs:", ports["outputs"])

Ejecutar un servidor web (opcional)

Si quieres exponer un runner de escenario por HTTP:

scenario.run_server(host="0.0.0.0", port=8080)

Eventos

Instala callbacks alrededor del ciclo de ejecución del escenario:

def on_start() -> None:
	print("Scenario started")


scenario.installStartEvent(on_start)

---

Helpers de logging

AugeLab Studio tiene un logger de runtime usado por blocks y escenarios. En modo headless normalmente querrás una de estas opciones:

• imprimir logs en stdout mientras desarrollas

• reenviar logs a tu propio sistema de logging

Estos helpers son globales (afectan al logger de runtime usado por tu escenario headless).

---

enable_logging_stdout()

Habilita logging de runtime “amigable” hacia stdout.

Úsalo cuando quieras ver logs de blocks/escenario en la consola:

from studio import enable_logging_stdout

enable_logging_stdout()

---

disable_logging_stdout()

Deshabilita el logging de runtime hacia stdout.

Útil cuando:

• estás usando install_logging_event(...) y quieres evitar logs duplicados

• quieres una salida limpia (solo tus propios print(...) o el output de tu logger)

from studio import disable_logging_stdout

disable_logging_stdout()

---

install_logging_event(event: Callable[[str], None])

Instala un callback que recibe los mensajes de log del runtime.

Esta es la forma más sencilla de integrar los logs de AugeLab en tu propio framework de logging.

import logging

from studio import install_logging_event, disable_logging_stdout

logger = logging.getLogger("augelab")


def forward_to_python_logging(msg: str) -> None:
	logger.info(msg)


disable_logging_stdout()
install_logging_event(forward_to_python_logging)

StudioScenario.install_logging_hook(hook, level=0)

Si prefieres instalar un hook por escenario (con filtrado por nivel), usa:

def hook(msg: str, level: int) -> None:
	print(level, msg)


scenario.install_logging_hook(hook, level=20)

Advertencia Mantén tu callback rápido. Si necesitas hacer trabajo pesado (I/O, red), considera encolar los mensajes y procesarlos en otro hilo/proceso.

---

Patrones recomendados

1) Variable de entorno para la licencia

Para scripts que se ejecutan en distintos entornos (local vs CI vs Docker), pasar verification_code mediante variable de entorno mantiene el código portable:

import os
from studio import StudioScenario

scenario = StudioScenario(verification_code=os.environ["AUGELAB_VERIFICATION_CODE"])

2) Siempre limpiar con try/finally

from studio import StudioScenario

scenario = StudioScenario(verification_code="YOUR_CODE")
try:
	scenario.load_scenario("scenario.pmod")
	scenario.run(())
finally:
	scenario.cleanup()