Quartz 4

02 - I Vincoli Obbligatori

2 min read

2. I Vincoli Obbligatori

Un file Python è classificato come estensione FIRE solo se soddisfa i requisiti strutturali di identificazione e orchestrazione. La mancanza di uno di questi elementi impedisce il caricamento dello script nell’Hub delle Estensioni.

2.1. Frontmatter YAML

Ogni script deve iniziare con un blocco di metadati in formato YAML racchiuso tra delimitatori ---. Questo blocco permette allo ScriptLoader di catalogare l’estensione senza eseguire il codice Python, garantendo sicurezza e velocità di indicizzazione.

Campi Obbligatori:

  • id: Identificativo univoco (numero, senza spazi).
  • title: Nome visualizzato nella UI.
  • version: Versione semantica dello script.
  • type: Categoria (analyzer, exporter, o utility).
  • description: Breve sintesi della logica di business.
---
id: 0001
title: Volatility Analyzer
version: 1.0
file_name: statistical_vol_analyzer.py
type: analyzer
description: Calcola SL statistici basati su drawdown intraday.
---

2.2 Entry Point: run(context)

L’esecuzione dell’estensione è vincolata alla presenza di una funzione denominata run che accetta un unico argomento: context.

Meccanica:

  1. Il ScriptRunnerWorker importa lo script dinamicamente.
  2. Viene istanziato un oggetto ScriptContext (Facade).
  3. La funzione run(context) viene chiamata, iniettando l’oggetto context come interfaccia operativa.

⚠️ Errore critico: Definire codice operativo al di fuori della funzione run (es. logica nel corpo principale del file) causa l’esecuzione immediata durante la fase di scansione, provocando rallentamenti o crash della UI.

Esempio: Estensione Minima Valida

---
id: minimalist_test
title: Script di Test
version: 1.0
type: utility
description: Verifica l'integrità del collegamento SDK.
---
 
def run(context):
    # Unico punto di ingresso per la logica
    context.ui.log("Integrazione validata con successo", "SUCCESS")

Struttura dei File

  • Estensione: .py
  • Posizione: Directory configurata in Settings > AI Tools > Scripts Path.
  • Nomenclatura: Snake_case consigliato per i nomi dei file.

💡 Nota operativa: Utilizzare context.ui.show_message per validare rapidamente se l’entry point viene raggiunto correttamente durante la fase di debug iniziale.

Graph View

Backlinks