8.6 KiB

Raw Blame History

Guía de Configuración para Scripts Backend

Introducción

Esta guía explica cómo configurar y usar correctamente la función load_configuration() en scripts ubicados bajo el directorio /backend. La función carga configuraciones desde un archivo script_config.json ubicado en el mismo directorio que el script que la llama.

Configuración del Path e Importación

1. Configuración estándar del Path

Para scripts ubicados en subdirectorios bajo /backend, usa este patrón estándar:

import os
import sys

# Configurar el path al directorio raíz del proyecto
script_root = os.path.dirname(
    os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
)
sys.path.append(script_root)

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

Nota: El número de os.path.dirname() anidados depende de la profundidad del script:

Scripts en /backend/script_groups/grupo/: 4 niveles
Scripts en /backend/: 2 niveles

2. Importación Correcta

✅ Correcto:

from backend.script_utils import load_configuration

❌ Incorrecto:

from script_utils import load_configuration  # No funciona desde subdirectorios

Uso de la Función load_configuration()

Implementación Básica

def main():
    # Cargar configuraciones
    configs = load_configuration()
    
    # Obtener el directorio de trabajo
    working_directory = configs.get("working_directory", "")
    
    # Acceder a configuraciones por nivel
    level1_config = configs.get("level1", {})
    level2_config = configs.get("level2", {})
    level3_config = configs.get("level3", {})
    
    # Ejemplo de uso de parámetros específicos con valores por defecto
    scl_output_dir = level2_config.get("scl_output_dir", "scl_output")
    xref_output_dir = level2_config.get("xref_output_dir", "xref_output")
    
if __name__ == "__main__":
    main()

Estructura del Archivo script_config.json

El archivo script_config.json debe estar ubicado en el mismo directorio que el script que llama a load_configuration(). Estructura recomendada:

{
    "working_directory": "/ruta/al/directorio/de/trabajo",
    "level1": {
        "parametro_global_1": "valor1",
        "parametro_global_2": "valor2"
    },
    "level2": {
        "scl_output_dir": "scl_output",
        "xref_output_dir": "xref_output",
        "xref_source_subdir": "source",
        "aggregated_filename": "full_project_representation.md"
    },
    "level3": {
        "parametro_especifico_1": true,
        "parametro_especifico_2": 100
    }
}

Ejemplo Completo de Implementación

"""
Script de ejemplo que demuestra el uso completo de load_configuration()
"""

import os
import sys
import json

# Configuración del path
script_root = os.path.dirname(
    os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
)
sys.path.append(script_root)
from backend.script_utils import load_configuration


def main():
    print("=== Cargando Configuración ===")
    
    # Cargar configuraciones
    configs = load_configuration()
    
    # Verificar que se cargó correctamente
    if not configs:
        print("Error: No se pudo cargar la configuración")
        return
    
    # Obtener configuraciones
    working_directory = configs.get("working_directory", "")
    level1_config = configs.get("level1", {})
    level2_config = configs.get("level2", {})
    level3_config = configs.get("level3", {})
    
    # Mostrar configuraciones cargadas
    print(f"Directorio de trabajo: {working_directory}")
    print("Configuración Nivel 1:", json.dumps(level1_config, indent=2))
    print("Configuración Nivel 2:", json.dumps(level2_config, indent=2))
    print("Configuración Nivel 3:", json.dumps(level3_config, indent=2))
    
    # Ejemplo de uso de parámetros con valores 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 salida SCL: {scl_output_dir}")
    print(f"Directorio de salida XREF: {xref_output_dir}")


if __name__ == "__main__":
    main()

Manejo de Errores

La función load_configuration() maneja automáticamente los siguientes casos:

Archivo no encontrado: Retorna un diccionario vacío {}
JSON inválido: Retorna un diccionario vacío y muestra un mensaje de error
Errores de lectura: Retorna un diccionario vacío y muestra un mensaje de error

Verificación de Configuración Válida

configs = load_configuration()

# Verificar que se cargó correctamente
if not configs:
    print("Advertencia: No se pudo cargar la configuración, usando valores por defecto")
    working_directory = "."
else:
    working_directory = configs.get("working_directory", ".")

# Verificar directorio de trabajo
if not os.path.exists(working_directory):
    print(f"Error: El directorio de trabajo no existe: {working_directory}")
    return

Mejores Prácticas

Siempre proporciona valores por defecto al usar .get():

valor = config.get("clave", "valor_por_defecto")

Verifica la existencia de directorios críticos:

if not os.path.exists(working_directory):
    print(f"Error: Directorio no encontrado: {working_directory}")
    return

Documenta los parámetros esperados en tu script:

# Parámetros esperados en level2:
# - scl_output_dir: Directorio de salida para archivos SCL
# - xref_output_dir: Directorio de salida para referencias cruzadas

Usa nombres de parámetros consistentes en todos los scripts del mismo grupo.

Definición Técnica de load_configuration()

def load_configuration() -> Dict[str, Any]:
    """
    Load configuration from script_config.json in the current script directory.

    Returns:
        Dict containing configurations with levels 1, 2, 3 and working_directory

    Example usage in scripts:
        from backend.script_utils import load_configuration

        configs = load_configuration()
        level1_config = configs.get("level1", {})
        level2_config = configs.get("level2", {})
        level3_config = configs.get("level3", {})
        working_dir = configs.get("working_directory", "")
    """

La función utiliza inspect.stack() para determinar automáticamente el directorio del script que la llama, asegurando que siempre busque el archivo script_config.json en la ubicación correcta.

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)