293 lines
8.6 KiB
Markdown
293 lines
8.6 KiB
Markdown
# 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:
|
|
|
|
```python
|
|
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:**
|
|
```python
|
|
from backend.script_utils import load_configuration
|
|
```
|
|
|
|
**❌ Incorrecto:**
|
|
```python
|
|
from script_utils import load_configuration # No funciona desde subdirectorios
|
|
```
|
|
|
|
## Uso de la Función load_configuration()
|
|
|
|
### Implementación Básica
|
|
|
|
```python
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```python
|
|
"""
|
|
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:
|
|
|
|
1. **Archivo no encontrado**: Retorna un diccionario vacío `{}`
|
|
2. **JSON inválido**: Retorna un diccionario vacío y muestra un mensaje de error
|
|
3. **Errores de lectura**: Retorna un diccionario vacío y muestra un mensaje de error
|
|
|
|
### Verificación de Configuración Válida
|
|
|
|
```python
|
|
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
|
|
|
|
1. **Siempre proporciona valores por defecto** al usar `.get()`:
|
|
```python
|
|
valor = config.get("clave", "valor_por_defecto")
|
|
```
|
|
|
|
2. **Verifica la existencia de directorios críticos**:
|
|
```python
|
|
if not os.path.exists(working_directory):
|
|
print(f"Error: Directorio no encontrado: {working_directory}")
|
|
return
|
|
```
|
|
|
|
3. **Documenta los parámetros esperados** en tu script:
|
|
```python
|
|
# Parámetros esperados en level2:
|
|
# - scl_output_dir: Directorio de salida para archivos SCL
|
|
# - xref_output_dir: Directorio de salida para referencias cruzadas
|
|
```
|
|
|
|
4. **Usa nombres de parámetros consistentes** en todos los scripts del mismo grupo.
|
|
|
|
## Definición Técnica de load_configuration()
|
|
|
|
```python
|
|
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.
|
|
|
|
```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
|
|
}
|
|
}
|
|
``` |