7.3 KiB

Raw Blame History

Guía de Configuración para Scripts Backend

Introducción

Esta guía explica cómo usar la función load_configuration() para cargar parámetros desde un archivo script_config.json en los scripts del backend.

1. Configuración del Script

Para que tus scripts puedan encontrar los módulos del proyecto, necesitas añadir el directorio raíz al path de Python.

Path Setup e Importación

Coloca este código al inicio de tu script:

import os
import sys

# Añadir el directorio raíz al sys.path
# El número de `os.path.dirname()` depende de la profundidad del script.
# Para /backend/script_groups/grupo/script.py, son 4.
script_root = os.path.dirname(
    os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
)
sys.path.append(script_root)

# Importar la función
from backend.script_utils import load_configuration

2. Cargar la Configuración

La función load_configuration() busca y carga un archivo llamado script_config.json que debe estar en el mismo directorio que el script que la ejecuta. Devuelve un diccionario con todo el contenido del JSON.

Ejemplo de Uso

def main():
    # Cargar configuraciones del archivo script_config.json
    configs = load_configuration()
    
    # Es buena práctica verificar si la configuración se cargó
    if not configs:
        print("Error: No se pudo cargar la configuración. Saliendo.")
        return
    
    # Acceder a los parámetros usando .get() para evitar errores
    working_directory = configs.get("working_directory", "")
    level1_config = configs.get("level1", {})
    level2_config = configs.get("level2", {})
    level3_config = configs.get("level3", {})
     
    # Ejemplo de uso de un parámetro específico con valor por defecto
    scl_output_dir = level2_config.get("scl_output_dir", "scl_output")
    xref_output_dir = level2_config.get("xref_output_dir", "xref_output")
    
    print(f"Directorio de trabajo: {working_directory}")
    print(f"Directorio de salida SCL: {scl_output_dir}")

if __name__ == "__main__":
    main()

3. Archivo `script_config.json`

Este archivo contiene los parámetros de tu script. La estructura interna del JSON, como el uso de "level1", "level2", etc., es una convención para organizar los parámetros. load_configuration() simplemente lee el archivo y devuelve su contenido.

Ejemplo de script_config.json:

{
    "working_directory": "/ruta/al/directorio/de/trabajo",
    "level1": {
        "parametro_global_1": "valor1"
    },
    "level2": {
        "scl_output_dir": "scl_output",
        "xref_output_dir": "xref_output"
    },
    "level3": {
        "parametro_especifico_1": true
    }
}

4. Manejo de Errores

load_configuration() está diseñada para ser robusta:

Si script_config.json no se encuentra, retorna un diccionario vacío {}.
Si el JSON es inválido, imprime un error y también retorna {}.

Siempre comprueba si el diccionario devuelto está vacío para manejar estos casos de forma segura en tu script.

5. Jerarquía de Archivos de Configuración

El sistema utiliza un modelo de configuración en cascada para gestionar los parámetros de los scripts. Esta jerarquía permite establecer configuraciones a nivel global, de grupo y de trabajo. Antes de la ejecución, el launcher lee estos archivos, los combina y genera un único script_config.json en la carpeta del script. La función load_configuration() es la que finalmente lee este archivo consolidado.

A continuación se describe la finalidad y ubicación de cada archivo clave.

Archivos de Valores (Parámetros)

Contienen los datos y variables que utilizará el script. La configuración se superpone en el siguiente orden: Nivel 1 < Nivel 2 < Nivel 3.

data.json (Nivel 1 - Global)
- Ubicación: data/data.json
- Utilidad: Almacena variables globales disponibles para todos los scripts. Ideal para parámetros generales.
- Acceso: Sus datos se cargan en la clave "level1" del diccionario configs.
script_config.json (Nivel 2 - Grupo)
- Ubicación: En la raíz de cada directorio de grupo (ej: backend/script_groups/MiGrupo/script_config.json).
- Utilidad: Define parámetros compartidos por todos los scripts de un grupo.
- Acceso: Sus datos se cargan en la clave "level2".
work_dir.json (Nivel 3 - Directorio de Trabajo)
- Ubicación: Dentro del directorio de trabajo que el script va a procesar.
- Utilidad: Contiene parámetros para una ejecución específica. Es el nivel más específico y sobrescribe los anteriores.
- Acceso: Sus datos se cargan en la clave "level3".

Archivos de Esquema (Definiciones de Estructura)

No contienen valores, sino que describen la estructura y tipos de datos que los archivos de valores deben tener. Son usados por el launcher para validación y para generar interfaces de configuración.

esquema_group.json
- Ubicación: Raíz del directorio del grupo.
- Utilidad: Define la estructura del script_config.json del grupo.
esquema_work.json
- Ubicación: Raíz del directorio del grupo.
- Utilidad: Define la estructura del work_dir.json.

6. Documentación de Scripts para el Launcher

El sistema de launcher utiliza archivos JSON para mostrar información sobre los grupos de scripts y scripts individuales en la interfaz web.

Archivo description.json (Descripción del Grupo)

Ubicación: En el directorio raíz del grupo de scripts.

{
  "name": "Nombre del Grupo",
  "description": "Descripción del propósito y funcionalidad del grupo",
  "version": "1.0",
  "author": "Nombre del Autor"
}

Archivo scripts_description.json (Descripción de Scripts)