Oggetto cursore¶

Cursor.__enter__()¶

Il punto di ingresso per il cursore come gestore di contesto. Si restituisce da solo.

Cursor.__exit__()¶

Il punto di uscita del cursore come gestore di contesto. Chiude il cursore.

Cursor.arraysize¶

Questo attributo di lettura-scrittura può essere utilizzato per regolare il numero di righe internallyfetched e buffered da chiamate interne al database durante il recupero di istruzioni rowsfrom SELECT e CURSORI REF. Il valore può influenzare drasticamente le prestazioni di una query poiché influisce direttamente sul numero di viaggi di networkround tra Python e il database. Per metodi comefetchone() e fetchall() non cambiaquante righe vengono restituite all’applicazione. Perfetchmany() è il numero predefinito di righe da recuperare.

A causa dei vantaggi delle prestazioni, il valore predefinito Cursor.arraysize è 100, invece di 1 raccomandato dall’API DB. Questo valore significa che 100 rowsare recuperati da ogni chiamata interna al database.

Vedere Ottimizzazione delle prestazioni di recupero per ulteriori informazioni.

Cursor.bindarraysize¶

Questo attributo di lettura-scrittura specifica il numero di righe da associare alla voltae viene utilizzato quando si creano variabili tramite setinputsizes()ovar(). Il valore predefinito è 1 che significa associare una singola riga alla volta.

Cursor.arrayvar(dataType, value)¶

Crea una variabile array associata al cursore del tipo specificato andsize e restituisce un oggetto variabile. Il valore è uninteger che specifica il numero di elementi da allocare o è un elenco e il numero di elementi allocati è tratto dalla dimensione dell’elenco. Se thevalue è una lista, la variabile viene impostata anche con il contenuto della lista. Ifthe dimensione non è specificata e il tipo è una stringa o binario, 4000 bytesis allocato. Questo è necessario per passare array a PL / SQL (nei casi in cui l’elenco potrebbe essere vuoto e il tipo non può essere determinato automaticamente) oreturning array da PL/SQL.

Le variabili array possono essere utilizzate solo per array associativi PL/SQL con chiavi contigue. Per gli array associativi PL / SQL con chiavi scarsamente popolate o per varray e tabelle nidificate, è necessario utilizzare l’approccio mostrato in thisexample.

Cursor.bindnames()¶

Restituisce l’elenco dei nomi di variabili bind associati all’istruzione. Si noti che astatement deve essere stato preparato prima.

Cursor.bindvars¶

Questo attributo di sola lettura fornisce le variabili di bind utilizzate per lastexecute. Il valore sarà un elenco o un dizionario a seconda di se l’associazione è stata eseguita per posizione o nome. Bisogna fare attenzione quandoriferendo questo attributo. In particolare, gli elementi non dovrebbero essere rimossio sostituito.

Cursor.callfunc(name, returnType, parameters=, keywordParameters = {})¶

Chiama una funzione con il nome specificato. Il tipo restituito è specificato nella stessa notazione richiesta da setinputsizes(). Thesequence dei parametri deve contenere una voce per ogni parametro che thefunction si aspetta. Tutti i parametri delle parole chiave saranno inclusi dopo ilparametri posizionali. Il risultato della chiamata è il valore restituito delfunzione.

Vedere PL/SQL Stored Functions per un esempio.

Cursor.callproc(name, parameters=, keywordParameters = {})¶

Chiama una procedura con il nome specificato. La sequenza di parametri devecontenere una voce per ogni parametro previsto dalla procedura. Il risultato della chiamata è una copia modificata della sequenza di input. I parametri di input sono lasciati intatti; i parametri di output e input/output vengono sostituiti con valori apparentemente nuovi. I parametri delle parole chiave verranno inclusi dopo i parametri posizionali e non vengono restituiti come parte della sequenza di output.

Vedere le stored procedure PL/SQL per un esempio.

Cursor.close()¶

Chiudi il cursore ora, piuttosto che ogni volta che viene chiamato _ _ del__. Il cursore sarà inutilizzabile da questo punto in avanti; verrà sollevata un’eccezione di errore se viene tentata qualsiasi operazione con il cursore.

Cursor.connection¶

Questo attributo di sola lettura restituisce un riferimento all’oggetto connessioneche è stato creato il cursore.

Cursor.description¶

Questo attributo di sola lettura è una sequenza di sequenze di 7 elementi. Ognuna di queste sequenze contiene informazioni che descrivono una colonna di risultati: (nome, tipo,display_size, internal_size, precision, scale, null_ok). Questo attributo sarà None per le operazioni che non restituiscono righe o se il cursore non ha ancora avuto un’operazione invocata tramite il metodo execute().

Il tipo sarà una delle costanti del tipo di database definite a livello di modulo.

Cursor.execute(dichiarazione, * * keywordParameters)¶

Eseguire una dichiarazione contro il database. Vedere Esecuzione SQL.

I parametri possono essere passati come un dizionario o sequenza o come keywordparameters. Se i parametri sono un dizionario, i valori saranno vincolati dal nome e se i parametri sono una sequenza i valori saranno vincolati da bypass. Si noti che se i valori sono vincolati dalla posizione, l’ordine di thevariables è da sinistra a destra come si incontrano nelle istruzioni statementand SQL vengono elaborati in modo diverso rispetto alle istruzioni PL/SQL. Per questo motivo, si consiglia generalmente di associare i parametri per nome anziché per posizione.

I parametri passati come dizionario sono coppie nome e valore. Il nome mapsto il nome della variabile bind utilizzato dall’istruzione e il valore mappe al valore thePython che si desidera associato a tale variabile bind.

Un riferimento all’istruzione verrà mantenuto dal cursore. Se None o thesame string object viene passato di nuovo, il cursore eseguirà di nuovo thatstatement senza eseguire una preparazione o un rebinding e una ridefinizione.Questo è più efficace per gli algoritmi in cui viene utilizzata la stessa istruzione, madiversi parametri sono associati ad esso (molte volte). Si noti che i parametri che non vengono passati durante le esecuzioni successive manterranno il valore passato durante l’ultima esecuzione che li conteneva.

Per la massima efficienza durante il riutilizzo di un’istruzione, è preferibile utilizzare il metodosetinputsizes() per specificare i tipi di parametri e dimensionare in anticipo; in particolare, si presume che None sia una stringa oflength 1, quindi qualsiasi valore che viene successivamente associato a numeri o date solleverà un’eccezione TypeError.

Se l’istruzione è una query, il cursore viene restituito per comodità a thecaller (quindi può essere utilizzato direttamente come iteratore sulle righe in thecursor); altrimenti, viene restituito None.

Cursor.executemany(statement, parameters, batcherrors = False, arraydmlrowcounts=False)¶

Preparare un’istruzione per l’esecuzione su un database e quindi eseguirla contro tutti i mapping o sequenze di parametri trovati nei sequenceparameters. Vedere Esecuzione di istruzioni batch e caricamento in blocco.

L’istruzione viene gestita nello stesso modo in cui la gestisce il metodo execute(). Se la dimensione dei buffer allocata per uno qualsiasi deii parametri superano i 2 GB, si riceverà l’errore ” DPI-1015: array sizeof < n > è troppo grande”, dove< n > varia con la dimensione di ogni elemento beingallocated nel buffer. Se si riceve questo errore, diminuire il numero dielementi nei parametri della sequenza.

Se non ci sono parametri o i parametri sono stati precedentemente associati, il numero di iterazioni può essere specificato come un numero intero invece di dover fornire un elenco di mappature o sequenze vuote.

Se true, il parametro batcherrors abilita il supporto degli errori batch all’interno di Oracle e garantisce che la chiamata abbia esito positivo anche se si verifica un’eccezione in una o più sequenze di parametri. Gli errori possono quindi essere rilevati utilizzando getbatcherrors().

Se true, il parametro arraydmlrowcounts abilita i conteggi di righe DML da prelevare da Oracle dopo il completamento del metodo. I conteggi delle righe possono essere recuperati usando getarraydmlrowcounts().

Sia il parametro batcherrors che il parametro arraydmlrowcounts possono essere true solo quando si esegue un’istruzione insert, update, delete o merge; in tutti gli altri casi verrà generato un errore.

Per la massima efficienza, è preferibile utilizzare il metodosetinputsizes() per specificare i tipi di parametri e le dimensioni in anticipo; in particolare, si presume che None sia una stringa di lunghezza 1, quindi qualsiasi valore che viene successivamente associato a numeri o date solleverà un’eccezione TypeError.

Cursor.executemanyprepared(numIters)¶

Esegui l’istruzione precedentemente preparata e associata al numero specificato di volte. Le variabili che sono associate devono essere già state impostate sul loro valore desiderato prima di effettuare questa chiamata. Questo metodo è stato progettato per thecase dove la prestazione ottimale è richiesta come viene a ofcompatibility di spesa con l’API di DB.

Cursor.fetchall()¶

Recupera tutte le righe (rimanenti) di un risultato di query, restituendole come un elenco dituple. Un elenco vuoto viene restituito se non sono disponibili più righe. Si noti che l’attributo arraysize del cursore può influire sulle prestazioni di thisoperation, poiché le letture interne dal database vengono eseguite in batchescorrispondente a arraysize.

Viene sollevata un’eccezione se la chiamata precedente a execute()non ha prodotto alcun set di risultati o non è stata ancora emessa alcuna chiamata.

Vedere i metodi di recupero per un esempio.

Cursor.fetchmany()¶

Recupera la prossima serie di righe di un risultato di query, restituendo un elenco di tuples.An l’elenco vuoto viene restituito se non sono disponibili più righe. Si noti che l’attributo arraysize di thecursor può influire sulle prestazioni di questa operazione.

Il numero di righe da recuperare è specificato dal parametro. Se non è dato, l’attributo arraysize del cursore determina il numero di righe da inserire. Se il numero di righe disponibili da recuperare è inferiore a quello richiesto, verranno restituite meno righe.

Viene sollevata un’eccezione se la chiamata precedente a execute()non ha prodotto alcun set di risultati o non è stata ancora emessa alcuna chiamata.

Vedere i metodi di recupero per un esempio.

Cursor.fetchone()¶

Recupera la riga successiva di un set di risultati di query, restituendo una singola tupla o nessuna Quando non sono disponibili più dati.

Viene sollevata un’eccezione se la chiamata precedente a execute()non ha prodotto alcun set di risultati o non è stata ancora emessa alcuna chiamata.

Vedere i metodi di recupero per un esempio.

Cursor.fetchraw()¶

Recupera il prossimo set di righe di un risultato di query nei buffer interni delle variabili definite per il cursore. Il numero di righe effettivamente recuperatoè restituito. Questo metodo è stato progettato per il caso in cui è richiesta optimalperformance in quanto viene a scapito della compatibilità con l’API DB.

Viene sollevata un’eccezione se la chiamata precedente a execute()non ha prodotto alcun set di risultati o non è stata ancora emessa alcuna chiamata.

Cursor.fetchvars¶

Questo attributo di sola lettura specifica l’elenco delle variabili create per l’ultima query eseguita sul cursore. Bisogna fare attenzione quandoriferendo questo attributo. In particolare, gli elementi non dovrebbero essere rimossio sostituito.

Cursor.getarraydmlrowcounts()¶

Recupera i conteggi delle righe DML dopo una chiamata a executemany()con arraydmlrowcounts abilitato. Questo restituirà un elenco di integerscorrispondente al numero di righe interessate dall’istruzione DML per ogni elemento dell’array passato a executemany().

Cursor.getbatcherrors()¶

Recupera le eccezioni che si sono verificate dopo una chiamata aexecutemany() con batcherrors abilitato. Questo restituirà un elenco di oggetti Error, un errore per ogni iterazione che non è riuscita. L’offsetpuò essere determinato osservando l’attributo offset dell’oggetto error.

Cursor.getimplicitresults()¶

Restituisce un elenco di cursori che corrispondono a risultati impliciti resi disponibili da un blocco o una procedura PL/SQL senza l’uso di parametri refcursor. Il blocco o la procedura PL/SQL apre i cursori e li segna per il ritorno al client utilizzando proceduredbms_sql.return_result. I cursori restituiti in questo modo non dovrebbero esserechiuso. Saranno chiusi automaticamente dal cursore genitore quando è chiuso. La chiusura del cursore genitore invaliderà i cursori restituiti daquesto metodo.

Cursor.inputtypehandler¶

Questo attributo read-write specifica un metodo chiamato per ogni valore associato a un’istruzione eseguita sul cursore e sovrascrive l’attributo con lo stesso nome sulla connessione, se specificato. La firma del metodo ishandler (cursore, valore, arraysize) e il valore restituito dovrebbero essere oggetto avariable o None, nel qual caso verrà creato un oggetto variabile predefinito. Se questo attributo è None, viene utilizzato il valore dell’attributo con lo stesso nome sulla connessione.

Cursor.__iter__()¶

Restituisce il cursore stesso da utilizzare come iteratore.

Cursor.lastrowid¶

Questo attributo di sola lettura restituisce l’id riga dell’ultima riga modificata da thecursor. Se nessuna riga è stata modificata dall’ultima operazione eseguita su thecursor, viene restituito il valore None.

Cursor.outputtypehandler¶

Questo attributo read-write specifica un metodo chiamato per ogni colonna che isto essere recuperato da questo cursore. La firma del metodo ishandler (cursore, nome, defaultType, lunghezza, precisione, scala) e returnvalue dovrebbe essere un oggetto variabile o Nessuno nel qual caso verrà creato un oggetto defaultvariable. Se questo attributo è None, viene utilizzato il valore dell’attributo con lo stesso nome sulla connessione.

Vedere Modifica dei tipi di dati recuperati con i gestori dei tipi di output.

Cursor.parse(istruzione)¶

Questo può essere usato per analizzare un’istruzione senza eseguirla effettivamente (questo passo viene fatto automaticamente da Oracle quando viene eseguita un’istruzione).

Cursor.prefetchrows¶

Questo attributo di lettura-scrittura può essere utilizzato per regolare il numero di righe che la libreria client theOracle recupera quando viene eseguita un’istruzione SELECT. Thisvalue può ridurre il numero di round-trip al database che sono requiredto recuperare righe, ma al costo di memoria aggiuntiva. Impostare questo valore su 0può essere utile quando la tempistica dei recuperi deve essere controllata esplicitamente.

Vedere Ottimizzazione delle prestazioni di recupero per ulteriori informazioni.

Cursor.prepare(istruzione)¶

Questo può essere usato prima di una chiamata a execute() per definire la dichiarazione che verrà eseguita. Quando ciò viene fatto, la fase di preparazione non verrà eseguita quando la chiamata a execute() viene effettuata con uno o lo stesso oggetto string dell’istruzione. Se specificato, la dichiarazione verrà restituita alla cache dell’istruzione con il tag specificato. Consultare la documentazione Oracle per ulteriori informazioni sulla cache delle istruzioni.

Vedere la memorizzazione nella cache delle istruzioni per ulteriori informazioni.

Cursor.rowcount¶

Questo attributo di sola lettura specifica il numero di righe che sono state recuperate dal cursore (per le istruzioni select), che sono state influenzate dall’operazione (per insert, update, delete e mergestatements) o il numero di esecuzioni riuscite dell’istruzione(per le istruzioni PL/SQL).

Cursor.rowfactory¶

Questo attributo read-write specifica un metodo da chiamare per ogni riga che isretrieved dal database. Normalmente viene restituita una tupla per ogni riga, ma se questo attributo è impostato, il metodo viene chiamato con la tupla che normalmente verrà restituita e il risultato del metodo viene restituitoinvece.

Vedere Modifica dei risultati delle query con Rowfactories.

Cursor.scroll(value = 0, mode= “relative”)¶

Scorrere il cursore nel set di risultati in una nuova posizione in base alla modalità.

Se la modalità è “relativa” (il valore predefinito), il valore viene preso come offsetto alla posizione corrente nel set di risultati. Se impostato su “assoluto”, valorestata una posizione di destinazione assoluta. Se impostato su “primo”, il cursore è posizionato sulla prima riga e se impostato su” ultimo”, il cursore è impostato sull’ultima riga nel set di risultati.

Viene generato un errore se la modalità è “relativa” o “assoluta” e l’operazione di scorrimento posizionerà il cursore all’esterno del set di risultati.

Cursor.scrollable¶

Questo attributo booleano di lettura-scrittura specifica se il cursore può essere scrollato o meno. Per impostazione predefinita, i cursori non sono scorrevoli, poiché le risorse del server e i tempi di risposta sono maggiori dei cursori non registrabili. Thisattribute è controllato e la modalità corrispondente impostata in Oracle quando si chiama il metodo execute().

Cursor.setinputsizes(*args, **keywordArgs)¶

Può essere utilizzato prima di una chiamata a execute(),callfunc() o callproc() per definire le aree di memoria per i parametri dell’operazione. Ogni parametro dovrebbe essere un oggetto tipo corrispondente all’input che verrà utilizzato o dovrebbe essere uninteger che specifica la lunghezza massima di un parametro stringa. Utilizzare keywordparameters quando binding per nome e parametri posizionali quando binding byposition. Il singleton None può essere utilizzato come parametro quando si utilizzano parametri posizionali per indicare che nessuno spazio deve essere riservato a thatposition.

Cursor.setoutputsize(size)¶

Questo metodo non fa nulla e viene mantenuto esclusivamente per compatibilità con l’API dB. Il modulo alloca automaticamente tutto lo spazio necessario per recuperare colonne RAW lunghe e LUNGHE (o CLOB come stringa e BLOB come byte).

Cursor.statement¶

Questo attributo di sola lettura fornisce l’oggetto string precedentemente preparato con prepare() o eseguito conexecute().

Cursor.var(dataType)¶

Crea una variabile con le caratteristiche specificate. Questo metodo wasdesigned per l’uso con PL/SQL in / out variabili in cui la lunghezza o typecannot essere determinato automaticamente dall’oggetto Python passato o foruse in input e output tipo gestori definiti su cursori o connessioni.

Il parametro dataType specifica il tipo di dati da memorizzare nella variabile. Questo dovrebbe essere uno dei thedatabase costanti di tipo, DB costanti di API,un tipo di oggetto restituito dal metodo Connection.gettype() o uno dei seguenti tipi di Python:

Python Tipo	Tipo di Database
bool	cx_Oracle.DB_TYPE_BOOLEAN
byte	cx_Oracle.DB_TYPE_RAW
datetime.data	cx_Oracle.DB_TYPE_DATE
datetime.datetime	cx_Oracle.DB_TYPE_DATE
datetime.timedelta	cx_Oracle.DB_TYPE_INTERVAL_DS
decimale.Decimale	cx_Oracle.DB_TYPE_NUMBER
galleggiante	cx_Oracle.DB_TYPE_NUMBER
int	cx_Oracle.DB_TYPE_NUMBER
str	cx_Oracle.DB_TYPE_VARCHAR

La dimensione del parametro consente di specificare la lunghezza della stringa e crudo variabili e isignored in tutti gli altri casi. Se non specificato per le variabili stringa e non elaborate, viene utilizzato il valore 4000.

Il parametro arraysize specifica il numero di elementi che la variabile avrà. Se non specificato, viene utilizzata la dimensione dell’array bind (di solito 1). Quando avariable viene creato in un gestore del tipo di output, questo parametro deve essere impostato sulla dimensione dell’array del cursore.

I parametri inconverter e outconverter specificano i metodi utilizzati per la conversione dei valori da/verso il database. Maggiori informazioni possono essere trovate inla sezione sugli oggetti variabili.

Il parametro typename specifica il nome di un tipo di oggetto SQL e deve essere specificato quando si utilizza type cx_Oracle.OBJECT a meno che il type object sia passato direttamente come primo parametro.

Il parametro encodingErrors specifica cosa dovrebbe accadere quando decodingbyte stringhe recuperate dal database in stringhe. Dovrebbe essere uno dei valori annotati nel builtindecodefunction.