205 lines
7.3 KiB
Markdown
205 lines
7.3 KiB
Markdown
# 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:
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
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`:**
|
|
```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.
|
|
|
|
```json
|
|
{
|
|
"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)
|
|
|
|
Ubicación: En el directorio raíz del grupo de scripts.
|
|
|
|
```json
|
|
{
|
|
"nombre_script.py": {
|
|
"display_name": "Nombre para mostrar en la UI",
|
|
"short_description": "Descripción breve del script",
|
|
"long_description": "Descripción detallada con explicación completa de funcionalidad, pasos que ejecuta, y contexto de uso",
|
|
"hidden": false
|
|
},
|
|
"script_interno.py": {
|
|
"display_name": "Script Interno",
|
|
"short_description": "Script de uso interno",
|
|
"long_description": "",
|
|
"hidden": true
|
|
}
|
|
}
|
|
```
|
|
|
|
### Propiedades Importantes
|
|
|
|
- **hidden**: `true` oculta el script del launcher (útil para scripts auxiliares)
|
|
- **display_name**: Nombre amigable que aparece en la interfaz
|
|
- **short_description**: Se muestra en la lista de scripts
|
|
- **long_description**: Se muestra al expandir detalles del script
|
|
|
|
### Ejemplo Práctico
|
|
|
|
Para un grupo "XML Parser to SCL":
|
|
|
|
**description.json:**
|
|
```json
|
|
{
|
|
"name": "Siemens-Tia : 03 : Procesador de XML LAD-SCL-AWL",
|
|
"description": "Scripts que procesan archivos XML exportados de TIA, convirtiendo LAD a SCL",
|
|
"version": "1.0",
|
|
"author": "Miguel"
|
|
}
|
|
```
|
|
|
|
**scripts_description.json:**
|
|
```json
|
|
{
|
|
"x0_main.py": {
|
|
"display_name": "1: Procesar Exportación XML completa",
|
|
"short_description": "Conversor principal de LAD/FUP XML a SCL",
|
|
"long_description": "Script orquestador que procesa todos los archivos XML...",
|
|
"hidden": false
|
|
},
|
|
"x1_to_json.py": {
|
|
"display_name": "x1_to_json",
|
|
"short_description": "Converter XML interno",
|
|
"long_description": "",
|
|
"hidden": true
|
|
}
|
|
}
|
|
``` |