Interfacciamento con Konga

Quando si installa Kongalib, oltre al modulo Python kongalib, vengono installati anche due moduli aggiuntivi: kongautil e kongaui. Questi moduli permettono una maggiore integrazione con Konga, e assumono che Konga stesso sia in esecuzione durante l’esecuzione del vostro script; in particolare si comportano in modo diverso se lo script è eseguito dall’interno di Konga stesso (dal menu Script o dall’editor di script) o dall’esterno (invocando lo script con Python da terminale).

Se le funzioni di kongautil e kongaui vengono usate dall’interno di Konga, l’input e l’output verranno gestiti da Konga tramite interfaccia grafica, altrimenti le funzioni opereranno sull’I/O del terminale da cui lo script è eseguito. Alcune funzionalità non saranno disponibili al di fuori di Konga, ed in tali casi verrà ritornata l’eccezione kongautil.KongaRequiredError.

Nota

kongalib, kongautil e kongaui sono pre-installate e sempre disponibili dall’interno di Konga.

kongautil

kongautil.PRINT_TARGET_PREVIEW = 0

Stampa a video

kongautil.PRINT_TARGET_PAPER = 1

Stampa su carta

kongautil.PRINT_TARGET_PDF = 2

Stampa su file PDF

kongautil.PRINT_TARGET_CSV = 3

Stampa su file CSV

kongautil.PRINT_TARGET_XLS = 4

Stampa su file Excel

exception kongautil.KongaRequiredError

Eccezione lanciata quando si esegue una funzione disponibile solo dall’interno di Konga.

exception kongautil.PrintError(log)

Eccezione lanciata se ci sono errori nell’esecuzione di una stampa con la funzione print_layout().

get_log()

Ottiene un oggetto di classe kongalib.Log contenente gli errori di stampa.

class kongautil.ScriptContext(database, company, tablename, record_id, record_code, record_data, **kwargs)

Classe per l’accesso al contesto di esecuzione delle azioni esterne lato client di Konga. La classe prevede l’uso di proprietà per accedere alle informazioni in lettura e scrittura.

property database

Ritorna un oggetto dict che contiene informazioni sul database attualmente connesso. Contiene le chiavi name, driver, desc e tutti i nomi dei campi della tabella EB_Master, i cui valori sono presi dal database.

property company

Ritorna un oggetto dict che contiene informazioni sull’azienda attualmente impostata nella finestra che sta eseguendo l’azione esterna. Contiene come chiavi tutti i campi delle tabelle EB_Aziende e EB_StatoArchivi (al contrario della proprietà database le cui chiavi sono nella forma <nomecampo>, qui i campi sono nella forma <nometabella>.<nomecampo> per evitare conflitti di nomi tra le tabelle EB_Aziende e EB_StatoArchivi) con i relativi valori presi dal database.

property tablename

Ritorna il nome della tabella su cui l’azione esterna sta operando.

property record_id

Ritorna l’ID (chiave primaria) del record su cui l’azione esterna sta operando. Vedere anche tablename().

property record_code

Ritorna il codice del record su cui l’azione esterna sta operando. Vedere anche tablename().

property record_data

Ritorna un dict con i dati del record visibili sulla scheda della finestra che sta eseguendo l’azione esterna.

property params

Ritorna un dict con i parametri che Konga passa allo script per l’esecuzione dell’azione esterna; questi parametri variano a seconda del tipo di azione che si sta eseguendo.

property result

Ritorna o imposta il valore di ritorno dell’azione esterna, in modo che Konga possa usarlo al termine dell’esecuzione dell’azione stessa. Il tipo ed il valore che andranno impostati dipendono dal tipo di azione esterna che si sta eseguendo.

kongautil.connect(host=None, port=None, driver=None, database=None, username=None, password=None, tenant_key=None, config=None)

Restituisce un oggetto kongalib.Client già connesso. Se eseguito dall’interno di Konga, la connessione sarà stabilita con il server, il database e l’utenza correntemente aperti sul programma, e i parametri passati a questa funzione saranno ignorati. Se eseguita fuori da Konga, la funzione proverà a collegarsi al primo server disponibile sulla rete locale, aprendo il primo database disponibile autenticandosi col l’utenza admin con password vuota; ogni parametro di connessione può essere forzato tramite i parametri passati a questa funzione, oppure da linea di comando specificando gli argomenti --host, --port, --driver, -d|--database, -u|--username, -p|--password e -k|--tenant-key. Inoltre, è possibile definire i parametri come variabili all’interno di un file di configurazione, nella sezione [kongautil.connect]; tale file deve avere il nome passato a questa funzione con il parametro config, altrimenti verranno ricercati nell’ordine anche il file con lo stesso nome dello script lanciato da terminale, ma con estensione .cfg, il file kongalib.cfg sempre nella stessa directory da cui si esegue lo script e infine il file ~/.kongalib (sotto Unix) o %userprofile%\kongalib.cfg (sotto Windows).

kongautil.get_window_vars()

Restituisce un dict contenente una serie di costanti definite per la finestra di navigazione correntemente aperta su Konga, incluse informazioni sull’azienda corrente, l’eventuale selezione se la finestra mostra una vista a lista, e molto altro. Se la funzione è eseguita fuori da Konga, il dict restituito sarà vuoto.

kongautil.print_layout(command_or_layout, builtins=None, code_azienda=None, code_esercizio=None, target=None, filename=None, progress=True, client=None)

Esegue una stampa su Konga. command_or_layout può essere un nome di comando di Konga, oppure un sorgente XML contenente la struttura stessa del layout da stampare; builtins è un dict i cui valori verranno passati al motore di stampa e saranno disponibili all’interno degli script del layout; code_azienda e code_esercizio identificano l’azienda e l’esercizio per cui eseguire la stampa, mentre target è una delle costanti PRINT_TARGET_* definite sopra, che specificano la destinazione della stampa (se non specificata e la funzione è eseguita all’interno di Konga, verrà assunta PRINT_TARGET_PREVIEW, altrimenti PRINT_TARGET_PDF); filename è il nome del file da salvare ed ha un senso solo quando si stampa su file. Se progress è True verrà mostrata a video una barra di progresso dell’operazione di stampa. La funzione restituisce un oggetto di classe kongalib.Log con il resoconto dell’operazione di stampa, oppure lancia un’eccezione di classe kongautil.PrintError in caso di errori.

Avvertimento

Se eseguita fuori da Konga, questa funzione richiede che sull’host sia stato installato Konga Client (o Konga), e non supporta come target i valori PRINT_TARGET_PREVIEW e PRINT_TARGET_PAPER. Konga Client (o Konga) verrà invocato e provvederà a connettersi al client corrente e stampare il documento richiesto; i parametri di connessione saranno ricavati automaticamente dal client ottenuto dall’ultima chiamata alla funzione kongautil.connect() oppure, se specificato, dal parametro client.

kongautil.print_log(log, title, target=0, filename=None)

Stampa il contenuto dell’oggetto log di classe kongalib.Log; se si esegue questa funzione dall’interno di Konga, verrà usata la funzione print_layout(), passando i parametri target e filename; viceversa se si esegue fuori da Konga, il log verrà stampato su terminale.

kongautil.suspend_timeout()

Sospende il timeout di esecuzione dello script. La funzione non comporta eccezioni ma non ha alcun effetto se eseguita al di fuori di Konga.

kongautil.resume_timeout(timeout)

Ripristina il timeout di esecuzione dello script. La funzione non comporta eccezioni ma non ha alcun effetto se eseguita al di fuori di Konga.

kongautil.set_timeout(timeout)

Imposta il timeout di esecuzione dello script in secondi, passati i quali verrà mostrata una finestra di avviso. La funzione non comporta eccezioni ma non ha alcun effetto se eseguita al di fuori di Konga.

kongautil.get_site_packages()

Restituisce una lista di percorsi di installazione dei pacchetti Python.

kongautil.notify_data_changes(table_name, row_id=None)

Notifica Konga che uno o tutti i record di una tabella sono stati modificati, causando un aggiornamento a tutti quei client Konga che stanno operando su tali record. Se row_id è None, tutti i record della tabella table_name verranno marcati come modificati, altrimenti il solo record con ID row_id. La funzione non comporta eccezioni ma non ha alcun effetto se eseguita al di fuori di Konga.

kongautil.get_context()

Restituisce un oggetto di classe kongautil.ScriptContext da usare per la gestione dell’I/O da parte degli script usati come azioni esterne di Konga.

Avvertimento

Questa funzione è disponibile solo all’interno di Konga; eseguendola da fuori verrà lanciata l’eccezione kongautil.KongaRequiredError.

kongautil.is_batch()

Restituisce True se lo script è eseguito con Python da linea di comando, False se è eseguito dall’interno di Konga.

kongaui

kongaui.BUTTON_OK = 1

Bottone «Ok»

kongaui.BUTTON_YES = 2

Bottone «Si»

kongaui.BUTTON_YES_ALL = 4

Bottone «Si tutti»

kongaui.BUTTON_NO = 8

Bottone «No»

kongaui.BUTTON_NO_ALL = 16

Bottone «No tutti»

kongaui.BUTTON_CANCEL = 32

Bottone «Annulla»

kongaui.BUTTON_OPEN = 64

Bottone «Apri»

kongaui.BUTTON_SAVE = 128

Bottone «Salva»

kongaui.BUTTON_SAVE_ALL = 256

Bottone «Salva tutti»

kongaui.BUTTON_CLOSE = 512

Bottone «Chiudi»

kongaui.BUTTON_DISCARD = 1024

Bottone «Tralascia»

kongaui.BUTTON_APPLY = 2048

Bottone «Applica»

kongaui.BUTTON_RESET = 4096

Bottone «Ripristina»

kongaui.BUTTON_ABORT = 8192

Bottone «Interrompi»

kongaui.BUTTON_RETRY = 16384

Bottone «Riprova»

kongaui.BUTTON_IGNORE = 32768

Bottone «Ignora»

kongaui.ICON_ERROR = 24

Icona di errore

kongaui.ICON_QUESTION = 25

Icona di domanda

kongaui.ICON_WARNING = 26

Icona di avviso

kongaui.ICON_INFORMATION = 27

Icona informativa

kongaui.message_box(text, title='', buttons=1, icon=27)

Mostra una finestra di dialogo modale con titolo title, messaggio text e icona icon (una delle costanti ICON_*). La finestra mostrerà i bottoni identificati da buttons, che può contenere uno o più costanti BUTTON_* in or tra loro, e ritornerà la costante relativa al bottone selezionato dall’utente per chiudere la finestra.

kongaui.open_file(message=None, specs=None, path='', multi=False)

Mostra una finestra di caricamento file con titolo message. *specs può essere una lista di tuple (extension, description) per permettere di caricare solo file di tipi specifici; path è il percorso predefinito, e multi permette di selezionare più di un file da caricare. Se multi è False, la funzione restituisce il percorso del file selezionato o None se l’utente ha annullato il caricamento, altrimenti restituisce la lista di file selezionati. Se eseguita al di fuori di Konga, questa funzione ignora i parametri specs, path e multi, e l’utente dovrà inserire il percorso completo del file da caricare; se verrà inserito un percorso vuoto, la funzione restituirà None.

kongaui.save_file(message=None, spec=None, path='')

Mostra una finestra di salvataggio file con titolo message. *spec può essere una tupla nella forma (extension, description) per permettere di salvare file di un tipo specifico; path è il percorso predefinito. La funzione restituisce il percorso del file da salvare oppure None se l’utente ha annullato il salvataggio. Se eseguita al di fuori di Konga, questa funzione ignora i parametri specs e path, e l’utente dovrà inserire il percorso completo del file da salvare; se verrà inserito un percorso vuoto, la funzione restituirà None.

kongaui.choose_directory(message=None, path='')

Mostra una finestra di selezione directory con titolo message e percorso iniziale path. La funzione restituisce il percorso della directory selezionata oppure None se l’utente ha annullato l’operazione. Se eseguita al di fuori di Konga, questa funzione ignora il parametro path, e l’utente dovrà inserire il percorso completo della directory; se verrà inserito un percorso vuoto, la funzione restituirà None.

kongaui.select_record(tablename, multi=False, size=None, where_expr=None, code_azienda=None, num_esercizio=None)

Mostra una finestra di selezione record di Konga; la finestra mostrerà i record della tabella tablename e avrà dimensione size (tupla di due elementi nella forma (width, height)). where_expr può essere un’espressione SQL WHERE per filtrare i record selezionabili; code_azienda e code_esercizio filtrano ulteriormente i record visualizzati usando l’azienda e l’esercizio specificati. Se multi è True, la funzione restituisce una lista di record selezionati sotto forma di dict, altrimenti restituisce il dict del singolo record selezionato. In tutti i casi se l’utente annulla l’operazione, la funzione restituirà None.

Avvertimento

Questa funzione è disponibile solo all’interno di Konga; eseguendola da fuori verrà lanciata l’eccezione kongautil.KongaRequiredError.

kongaui.open_progress(title=None, cancellable=True)

Mostra una finestra di progresso con titolo title, potenzialmente annullabile dall’utente se cancellable è True; la funzione ritorna immediatamente. Se eseguita fuori da Konga, questa funzione ignora il parametro cancellable.

kongaui.close_progress()

Nasconde la finestra di progresso precedentemente mostrata con kongaui.open_progress().

kongaui.set_progress(progress=None, message=None, state=None)

Imposta l’avanzamento corrente nella finestra di progresso precedentemente mostrata con kongaui.open_progress(). progress può essere None per specificare un avanzamento indefinito, oppure un valore compreso tra 0 e 100 per specificare la percentuale di avanzamento completata. message e state sono messaggi aggiuntivi da mostrare nella finestra di avanzamento.

kongaui.is_progress_aborted()

Restituisce True se l’utente ha annullato la finestra di progresso precedentemente mostrata con kongaui.open_progress().

kongaui.open_window(command, key_id=None, key_code=None, code_azienda=None, num_esercizio=None)

Apre una finestra di Konga mostrando il comando command, ed eventualmente aprendo il record identificato univocamente o da key_id (ID del record), o dalla tupla (key_code, code_azienda, code_esercizio) (Codice del record, codice dell’azienda e codice dell’esercizio).

Avvertimento

Questa funzione è disponibile solo all’interno di Konga; eseguendola da fuori verrà lanciata l’eccezione kongautil.KongaRequiredError.

kongaui.execute_form(form_data, title=None, message=None, condition=None)

Apre un form di immissione dati con titolo title; se message è specificato, il testo corrispondente sarà visualizzato in alto nella finestra del form. form_data deve essere una lista di dict con le specifiche dei campi da mostrare; nel dict di un singolo campo, l’unica chiave richiesta è name, che deve identificare univocamente il nome del campo. E” possibile specificare l’etichetta da mostrare accando al campo stesso tramite la chiave label; la tipologia di dato consentità è specificata tramite la chiave type, che può assumere i valori:

• str: testo semplice, con possibile lunghezza massima length se la chiave è specificata;

• password: parola chiave;

• int: valore intero;

• decimal: valore decimale (kongalib.Decimal);

• range: valore intero compreso tra un valore minimo (specificato dalla chiave min con valore predefinito 0) e un valore massimo (specificato dalla chiave max con valore predefinito 100);

• slider: simile a range ma viene visualizzato come cursore di selezione valore scorrevole;

• bool: valore booleano;

• date: data (datetime.date);

• choice: valore interno che identifica l’indice di una scelta tra quelle specificate nella chiave items (lista di stringhe);

• listbox: simile a choice ma viene visualizzato come lista di elementi da cui fare una scelta;

• load: nome di file esistente da caricare;

• save: nome di file da salvare;

• dir: nome di directory esistente;

• code: stringa di testo che identifica il codice di un record, la cui tabella è indicata dalla chiave table;

• company_code: simile a code, specifica l’azienda su cui gli altri campi code possono essere ricercati;

• accounting_year_code: simile a code, specifica l’esercizio su cui gli altri campi code possono essere ricercati;

Se presente, la chiave default permette di specificare il valore predefinito per un dato campo; inoltre se è presente la chiave focus (con qualsiasi valore), il campo corrispondente prenderà il focus all’avvio della finestra. La chiave enabled permette di specificare anche se abilitare o meno un campo; il suo valore può essere un booleano oppure una stringa il cui contenuto viene valutato allo stesso modo del parametro condition (vedi sotto). Se l’utente annulla il form la funzione restituisce None, altrimenti un dict le cui chiavi sono i nome dei campi e i valori i dati immessi dall’utente. Il parametro condition, se presente, permette di specificare una condizione di validazione per il form sotto forma di espressione Python; i nomi dei campi specificati in form_data saranno disponibili come variabili nell’esecuzione di questa condizione, il cui esito determinerà se consentire o meno l’uscita dal form con successo.