Python Database API

Kongalib supporta le specifiche 2.0 delle API Python per database, come definito sul PEP 0249. Per poter usare le API Python DB, occorre includere kongalib.db, dove è definita la funzione connect(). Tramite questa si può ottenere un oggetto Connection (vedere PEP 0249#connection-objects) su cui operare. Le API Python DB possono essere comode se tutto quello che si vuole fare è eseguire delle query SQL direttamente sul server; in tal caso questo approccio evita di dover instanziare ed usare un oggetto kongalib.Client.

kongalib.db.apilevel = '2.0'

Versione delle API, come da specifica

kongalib.db.threadsafety = 2

E” possibile usare le funzioni di modulo e gli oggetti Connection da thread diversi

kongalib.db.paramstyle = 'format'

Il formato dei parametri nelle query deve essere nello stile printf (WHERE name=%s)

exception kongalib.db.Error(msg)

Eccezione base, come da specifica.

exception kongalib.db.InternalError(msg)

Errore interno.

exception kongalib.db.OperationalError(msg)

Eccezione che viene lanciata su errori di connessione e/o comunicazione con il server Konga.

exception kongalib.db.ProgrammingError(msg)

Eccezione che viene lanciata se l’esecuzione di una query SQL ha generato un errore.

class kongalib.db.Connection

Classe che gestisce una connessione ad un server Konga. Viene usata per instanziare oggetti Cursor su cui poi operare, oppure per gestire le transazioni.

close()

Chiude la connessione con il server Konga.

commit()

Esegue una COMMIT per la transazione SQL corrente.

rollback()

Esegue una ROLLBACK per la transazione SQL corrente.

cursor()

Crea un nuovo oggetto Cursor associato a questa connessione.

class kongalib.db.Cursor(conn)

Questa classe permette di eseguire query SQL sulla connessione conn ad essa associata. Per instanziare oggetti di classe Cursor si usa il metodo Connection.cursor(). La classe può essere anche usato come iteratore; in tal caso per ogni ciclo verrà restituita la prossima riga del result set derivante dall’ultima query eseguita sul cursore stesso.

close()

Termina l’utilizzo di questo cursore; chiamate successive ai metodi di questo oggetto lanceranno un eccezione di tipo InternalError.

execute(command, *args)

Esegue la query SQL command sulla connessione associata al cursore; command può essere nel formato printf, e in tal caso args sono gli argomenti che vengono sostituiti nella stringa di formato.

executemany(operation, seq)

Esegue la stessa query SQL tante volte quanta la lunghezza della sequenza seq; l’elemento N di seq deve essere una tupla di argomenti da passare come args al metodo execute() per eseguire la query N-esima.

fetchone()

Restituisce la prossima riga del result set ottenuto dall’ultima query eseguita su questo cursore. La riga è restituita sotto forma di tupla di valori.

fetchmany(size=None)

Restituisce una lista di righe in cui ogni riga è nello stesso formato restituito da fetchone(). La lista includerà al massimo size righe; se size è None, verranno incluse al massimo arraysize righe.

fetchall()

Restituisce tutte le righe del result set corrente.

property connection

Proprietà in sola lettura che restituisce l’oggetto Connection associato a questo cursore.

property rowcount

Proprietà in sola lettura che restituisce il numero di righe del result set corrente.

property rownumber

Proprietà in sola lettura che restituisce il numero di riga corrente all’interno del result set.

property arraysize

Proprietà in lettura/scrittura che specifica il numero massimo di righe da includere nel risultato di fetchmany() se size è None.

kongalib.db.connect(host, port=0, driver=None, database=None, user=None, password=None)

Esegue una connessione al server Konga identificato da host e port, apre database usando il driver specificato, ed infine si autentica usando user e password. Restituisce un oggetto Connection; da questo è possibile ottenere un oggetto Cursor che permette di eseguire query SQL sul database aperto sulla connessione.