Objet Curseur¶

Cursor.__enter__()¶

Le point d’entrée du curseur en tant que gestionnaire de contexte. Il se retourne.

Cursor.__exit__()¶

Le point de sortie du curseur en tant que gestionnaire de contexte. Il ferme le curseur.

Cursor.arraysize¶

Cet attribut de lecture-écriture peut être utilisé pour régler le nombre de lignes récupérées en interne et mises en mémoire tampon par des appels internes à la base de données lors de la récupération des instructions rowsfrom SELECT et des CURSEURS REF. La valeur peut affecter considérablement les performances d’une requête car elle affecte directement le nombre de trajets réseau entre Python et la base de données. Pour des méthodes telles que fetchone() et fetchall(), cela ne change pas combien de lignes sont renvoyées à l’application. Pour fetchmany(), c’est le nombre de lignes par défaut à récupérer.

En raison des avantages en termes de performances, la valeur par défaut Cursor.arraysize est 100 au lieu du 1 recommandé par l’API DB. Cette valeur signifie que 100 lignes sont récupérées par chaque appel interne à la base de données.

Voir Tuning Fetch Performance pour plus d’informations.

Cursor.bindarraysize¶

Cet attribut de lecture-écriture spécifie le nombre de lignes à lier à la fois et est utilisé lors de la création de variables via setinputsizes() ou var(). La valeur par défaut est 1, ce qui signifie lier une seule ligne à la fois.

Cursor.arrayvar( DataType, value)¶

Crée une variable de tableau associée au curseur du type et de la taille donnés et renvoie un objet variable. La valeur est soit aninteger spécifiant le nombre d’éléments à allouer, soit il s’agit d’une liste etle nombre d’éléments alloués est tiré de la taille de la liste. Si la valeur est une liste, la variable est également définie avec le contenu de la liste. Si la taille n’est pas spécifiée et que le type est une chaîne ou un binaire, 4000 octets sont alloués. Ceci est nécessaire pour passer des tableaux à PL / SQL (dans les cas où la liste peut être vide et le type ne peut pas être déterminé automatiquement) ou pour retourner des tableaux à partir de PL / SQL.Les variables de tableau

ne peuvent être utilisées que pour les tableaux associatifs PL/SQL avec des clés contiguës. Pour les tableaux associatifs PL / SQL avec des clés peu peuplées ou pour les tableaux varrays et les tables imbriquées, l’approche indiquée dans cet exemple doit être utilisée.

Cursor.bindnames()¶

Renvoie la liste des noms de variables de liaison liés à l’instruction. Notez qu’une déclaration doit avoir été préparée en premier.

Cursor.bindvars¶

Cet attribut en lecture seule fournit les variables de liaison utilisées pour lastexecute. La valeur sera soit une liste, soit un dictionnaire selon que la liaison a été effectuée par position ou nom. Des précautions doivent être prises lorsqueréférencer cet attribut. En particulier, les éléments ne doivent pas être enlevésou remplacés.

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

Appelle une fonction avec le nom donné. Le type de retour est spécifié dans la même notation que celle requise par setinputsizes(). Cette séquence de paramètres doit contenir une entrée pour chaque paramètre attendu par la fonction. Tous les paramètres de mots clés seront inclus après les paramètres positionnels. Le résultat de l’appel est la valeur de retour de la fonction.

Voir Fonctions stockées PL/SQL pour un exemple.

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

Appelle une procédure avec le nom donné. La séquence de paramètres doitcontient une entrée pour chaque paramètre attendu par la procédure. Le résultat de l’appel est une copie modifiée de la séquence d’entrée. Les paramètres d’entrée sont laissés intacts; les paramètres de sortie et d’entrée/ sortie sont remplacés par de nouvelles valeurs possibles. Les paramètres de mots clés seront inclus après les paramètres positionnels et ne seront pas renvoyés dans la séquence de sortie.

Voir les procédures stockées PL/SQL pour un exemple.

Cursor.close()¶

Fermez le curseur maintenant, plutôt que chaque fois que __del__ est appelé. Le curseur sera inutilisable à partir de ce moment ; une exception d’erreur sera levée si toute opération est tentée avec le curseur.

Cursor.connection¶

Cet attribut en lecture seule renvoie une référence à l’objet de connexion sur lequel le curseur a été créé.

Cursor.description¶

Cet attribut en lecture seule est une séquence de séquences de 7 éléments. Chacune de ces séquences contient des informations décrivant une colonne de résultat : (nom, type, display_size, internal_size, precision, scale, null_ok). Cet attribut sera None pour les opérations qui ne renvoient pas de lignes ou si le curseur n’a pas encore eu d’opération appelée via la méthode execute().

Le type sera l’un des types de base de données constantsdéfini au niveau du module.

Cursor.execute( instruction, ** keywordParameters)¶

Exécutez une instruction sur la base de données. Voir Exécution SQL.Les paramètres

peuvent être passés sous forme de dictionnaire ou de séquence ou de paramètres de mots clés. Si les paramètres sont un dictionnaire, les valeurs seront liées parname et si les paramètres sont une séquence, les valeurs seront liées parposition. Notez que si les valeurs sont liées par position, l’ordre des variables est de gauche à droite car elles sont rencontrées dans l’état et les instructions SQL sont traitées différemment des instructions PL / SQL. Pour cette raison, il est généralement recommandé de lier les paramètres par nom au lieu de par position.

Les paramètres passés en tant que dictionnaire sont des paires de noms et de valeurs. Le nom correspond au nom de la variable de liaison utilisée par l’instruction et la valeur correspond à la valeur de thePython que vous souhaitez lier à cette variable de liaison.

Une référence à l’instruction sera conservée par le curseur. Si aucun objet string ou le même objet string est à nouveau transmis, le curseur exécutera à nouveau thatstatement sans effectuer de préparation ou de rebindage et de redéfinition.Ceci est plus efficace pour les algorithmes où la même instruction est utilisée, maisdifférents paramètres y sont liés (plusieurs fois). Notez que les paramètres qui ne sont pas transmis lors des exécutions ultérieures conserveront la valeur saisie lors de la dernière exécution qui les contenait.

Pour une efficacité maximale lors de la réutilisation d’une instruction, il est préférable d’utiliser la méthode setinputsizes() pour spécifier les types et tailles de paramètres à l’avance; en particulier, None est supposé être une chaîne de longueur 1, de sorte que toutes les valeurs qui sont ensuite liées sous forme de nombres ou de dates soulèveront une exception TypeError.

Si l’instruction est une requête, le curseur est renvoyé par commodité à thecaller (il peut donc être utilisé directement comme itérateur sur les lignes de thecursor) ; sinon, None est renvoyé.

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

Prépare une instruction pour exécution sur une base de données, puis l’exécute contre tous les mappages de paramètres ou séquences trouvés dans les sequenceparameters. Voir Exécution des instructions par lots et Chargement en bloc.

L’instruction est gérée de la même manière que la méthode execute() la gère. Si la taille des tampons alloués à l’un desparamètres dépasse 2 Go, vous recevrez l’erreur « DPI-1015: la taille du tableau < n > est trop grande « , où < n > varie avec la taille de chaque élément alloué dans le tampon. Si vous recevez cette erreur, diminuez le nombre d’éléments dans les paramètres de séquence.

S’il n’y a pas de paramètres, ou si des paramètres ont déjà été liés, le nombre d’itérations peut être spécifié comme un entier au lieu de devoir fournir une liste de mappages ou de séquences vides.

Lorsqu’il est vrai, le paramètre batcherrors active la prise en charge des erreurs par lots au sein de l’intracle et garantit que l’appel réussit même si une exception se produit dans un ou plusieurs de la séquence de paramètres. Les erreurs peuvent ensuite être corrigées en utilisant getbatcherrors().

Lorsqu’il est vrai, le paramètre arraydmlrowcounts permet au nombre de lignes DML d’être supprimé d’Oracle une fois la méthode terminée. Le nombre de lignes peut ensuite être récupéré en utilisant getarraydmlrowcounts().

Le paramètre batcherrors et le paramètre arraydmlrowcounts ne peuvent être true que lors de l’exécution d’une instruction insert, update, delete ou merge; dans tous les autres cas, une erreur sera générée.

Pour une efficacité maximale, il est préférable d’utiliser la méthode setinputsizes() pour spécifier les types et tailles de paramètres à l’avance; en particulier, None est supposé être une chaîne de longueur 1, de sorte que toutes les valeurs qui sont ensuite liées sous forme de nombres ou de dates soulèveront une exception TypeError.

Cursor.executemanyprepared( numIters)¶

Exécute l’instruction précédemment préparée et liée le nombre de fois donné. Les variables qui sont liées doivent avoir déjà été définies sur leur valeur désirée avant que cet appel ne soit effectué. Cette méthode a été conçue pour le cas où des performances optimales sont requises car elles se font au détriment de la compatibilité avec l’API DB.

Cursor.fetchall()¶

Récupérez toutes les lignes (restantes) d’un résultat de requête, en les renvoyant sous forme de liste oftuples. Une liste vide est renvoyée si plus aucune ligne n’est disponible. Notez que l’attribut arraysize du curseur peut affecter les performances de cette opération, car les lectures internes de la base de données sont effectuées en batchescorrespondant à la arraysize.

Une exception est déclenchée si l’appel précédent à execute() n’a produit aucun jeu de résultats ou si aucun appel n’a encore été émis.

Voir Méthodes de récupération pour un exemple.

Cursor.fetchmany()¶

Récupère le jeu de lignes suivant d’un résultat de requête, renvoyant une liste de tuples.An la liste vide est renvoyée si plus aucune ligne n’est disponible. Notez que l’attribut arraysize de thecursor peut affecter les performances de cette opération.

Le nombre de lignes à récupérer est spécifié par le paramètre. S’il n’est pas donné, l’attribut arraysize du curseur détermine le nombre de lignes à extraire. Si le nombre de lignes disponibles à récupérer est inférieur à la quantité demandée, moins de lignes seront renvoyées.

Une exception est déclenchée si l’appel précédent à execute() n’a produit aucun jeu de résultats ou si aucun appel n’a encore été émis.

Voir Méthodes de récupération pour un exemple.

Cursor.fetchone()¶

Récupérez la ligne suivante d’un jeu de résultats de requête, renvoyant un seul tuple ou Nonquand plus aucune donnée n’est disponible.

Une exception est déclenchée si l’appel précédent à execute() n’a produit aucun jeu de résultats ou si aucun appel n’a encore été émis.

Voir Méthodes de récupération pour un exemple.

Cursor.fetchraw()¶

Récupérez l’ensemble suivant de lignes d’un résultat de requête dans les tampons internes des variables définies pour le curseur. Le nombre de lignes réellement récupérées est renvoyé. Cette méthode a été conçue pour le cas où une performance optimale est requise car elle se fait au détriment de la compatibilité avec l’API DB.

Une exception est déclenchée si l’appel précédent à execute() n’a produit aucun jeu de résultats ou si aucun appel n’a encore été émis.

Cursor.fetchvars¶

Cet attribut en lecture seule spécifie la liste des variables créées pour la dernière requête exécutée sur le curseur. Des précautions doivent être prises lorsqueréférencer cet attribut. En particulier, les éléments ne doivent pas être enlevésou remplacés.

Cursor.getarraydmlrowcounts()¶

Récupérez le nombre de lignes DML après un appel à executemany() avec arraydmlrowcounts activé. Cela renverra une liste d’integerscorrespondant au nombre de lignes affectées par l’instruction DML pour chaque élément du tableau passé à executemany().

Cursor.getbatcherrors()¶

Récupérez les exceptions qui ont eu lieu après un appel à executemany() avec batcherrors activé. Cela renverra une liste d’objets d’erreur, une erreur pour chaque itération qui a échoué. L’offsetpeut être déterminé en regardant l’attribut offset de l’objet error.

Cursor.getimplicitresults()¶

Renvoie une liste de curseurs qui correspondent à des résultats implicites rendus disponibles à partir d’un bloc ou d’une procédure PL/SQL sans utiliser de paramètres de refcursor. Le bloc ou la procédure PL/SQL ouvre les curseurs et les marque pour un retour au client à l’aide de proceduredbms_sql.return_result. Les curseurs retournés de cette manière ne devraient pas êtrefermé. Ils seront fermés automatiquement par le curseur parent lorsqu’il est fermé. La fermeture du curseur parent invalidera les curseurs renvoyés par cette méthode.

Cursor.inputtypehandler¶

Cet attribut de lecture-écriture spécifie une méthode appelée pour chaque valeur qui est liée à une instruction exécutée sur le curseur et remplace l’attribut avec le même nom sur la connexion s’il est spécifié. La signature de la méthode est un gestionnaire (curseur, valeur, taille du tableau) et la valeur de retour devrait être un objet avariable ou None, auquel cas un objet variable par défaut sera créé. Si cet attribut est None, la valeur de l’attribut avec le même nom sur la connexion est utilisée.

Cursor.__iter__()¶

Renvoie le curseur lui-même à utiliser comme itérateur.

Cursor.lastrowid¶

Cet attribut en lecture seule renvoie le rowid de la dernière ligne modifiée par thecursor. Si aucune ligne n’a été modifiée par la dernière opération effectuée sur thecursor, la valeur None est renvoyée.

Cursor.outputtypehandler¶

Cet attribut de lecture-écriture spécifie une méthode appelée pour chaque colonne qui doit être extraite de ce curseur. La signature de la méthode ishandler (curseur, nom, type par défaut, longueur, précision, échelle) et la valeur de retour doit être un objet variable ou None, auquel cas un objet variable par défaut sera créé. Si cet attribut est None, la valeur del’attribut portant le même nom sur la connexion est utilisée à la place.

Voir Modification des Types de données Récupérées avec les Gestionnaires de type de sortie.

Cursor.parse( instruction)¶

Cela peut être utilisé pour analyser une instruction sans l’exécuter réellement (cette étape est effectuée automatiquement par Oracle lorsqu’une instruction est exécutée).

Cursor.prefetchrows¶

Cet attribut lecture-écriture peut être utilisé pour ajuster le nombre de lignes que la bibliothèque cliente theOracle récupère lorsqu’une instruction SELECT est exécutée. Cette valeur peut réduire le nombre d’allers-retours vers la base de données requis pour récupérer des lignes, mais au prix d’une mémoire supplémentaire. La définition de cette valeur à 0 peut être utile lorsque la synchronisation des extractions doit être explicitement contrôlée.

Voir Tuning Fetch Performance pour plus d’informations.

Cursor.prepare( instruction)¶

Ceci peut être utilisé avant un appel à execute() pour définir l’instruction qui sera exécutée. Lorsque cela est fait, la phase de préparation ne sera pas effectuée lorsque l’appel à execute() est effectué avec un seul ou le même objet chaîne que l’instruction. Si spécifié, thestatement sera renvoyé dans le cache d’instructions avec la balise donnée. Consultez la documentation Oracle pour plus d’informations sur le cache d’instructions.

Voir Mise en cache des instructions pour plus d’informations.

Cursor.rowcount¶

Cet attribut en lecture seule spécifie le nombre de lignes qui ont été récupérées à partir du curseur (pour les instructions select), qui ont été affectées par l’opération (pour les instructions insert, update, delete et mergestatements), ou le nombre d’exécutions réussies de l’instruction (pour les instructions PL/SQL).

Cursor.rowfactory¶

Cet attribut de lecture-écriture spécifie une méthode à appeler pour chaque ligne retirée de la base de données. Normalement, un tuple est renvoyé pour chaque ligne, mais si cet attribut est défini, la méthode est appelée avec le tuple qui serait normalement renvoyé, et le résultat de la méthode est renvoyé au lieu de cela.

Voir Modification des résultats de requête avec Rowfactories.

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

Faites défiler le curseur dans le jeu de résultats vers une nouvelle position selon le mode.

Si le mode est « relatif » (la valeur par défaut), la valeur est prise comme offsetto de la position actuelle dans le jeu de résultats. S’il est défini sur « absolu », valuest indique une position cible absolue. S’il est défini sur « premier », le curseur estpositionné à la première ligne et s’il est défini sur « dernier », le curseur est défini sur la dernière ligne du jeu de résultats.

Une erreur est générée si le mode est « relatif » ou « absolu » et que l’opération de défilement positionne le curseur en dehors du jeu de résultats.

Cursor.scrollable¶

Cet attribut booléen en lecture-écriture spécifie si le curseur peut être roulé ou non. Par défaut, les curseurs ne sont pas déroulables, car les ressources du serveur et les temps de réponse sont supérieurs aux curseurs non déroulables. Cette attribut est cochée et le mode correspondant défini dans Oracle lors de l’appel de la méthode execute().

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

Ceci peut être utilisé avant un appel à execute(), callfunc() ou callproc() pour prédéfinir des zones de mémoire pour les paramètres de l’opération. Chaque paramètre doit être un objet atype correspondant à l’entrée qui sera utilisée ou il doit être un attribut spécifiant la longueur maximale d’un paramètre de chaîne. Utilisez des paramètres de mots clés lors de la liaison par nom et des paramètres de position lors de la liaison par position. Le singleton None peut être utilisé comme paramètre lors de l’utilisation de paramètres positionnels pour indiquer qu’aucun espace ne doit être réservé à cette position.

Cursor.setoutputsize( size)¶

Cette méthode ne fait rien et est conservée uniquement pour la compatibilité avec l’API theDB. Le module alloue automatiquement autant d’espace que nécessaire pour récupérer des colonnes BRUTES longues et LONGUES (ou CLOB sous forme de chaîne et BLOB sous forme d’octets).

Cursor.statement¶

Cet attribut en lecture seule fournit l’objet chaîne précédemment préparé avec prepare() ou exécuté avec execute().

Cursor.var( Type de données)¶

Créez une variable avec les caractéristiques spécifiées. Cette méthode a été conçue pour être utilisée avec des variables d’entrée/ sortie PL/SQL où la longueur ou le type ne peuvent pas être déterminés automatiquement à partir de l’objet Python transmis ou utilisés dans les gestionnaires de types d’entrée et de sortie définis sur des curseurs ou des connexions.

Le paramètre Type de données spécifie le type de données à stocker dans la variable. Cela devrait être l’une des constantes de type de base de données, des constantes d’API de base de données, un type d’objet renvoyé par la méthode Connection.gettype() ou l’un des types Python suivants:

Type Python	Type de base de données
bool	cx_Oracle.DB_TYPE_BOOLEAN
octets	cx_Oracle.DB_TYPE_RAW
date et heure.date	cx_Oracle.DB_TYPE_DATE
date et heure.date et heure	cx_Oracle.DB_TYPE_DATE
date et heure.timedelta	cx_Oracle.DB_TYPE_INTERVAL_DS
décimal.Décimal	cx_Oracle.DB_TYPE_NUMBER
flotteur	cx_Oracle.DB_TYPE_NUMBER
int	cx_Oracle.DB_TYPE_NUMBER
str	cx_Oracle.DB_TYPE_VARCHAR

Le paramètre size spécifie la longueur des variables string et raw et isignored dans tous les autres cas. Si elle n’est pas spécifiée pour les variables string et raw, la valeur 4000 est utilisée.

Le paramètre arraysize spécifie le nombre d’éléments que la variable aura. Si elle n’est pas spécifiée, la taille du tableau de liaison (généralement 1) est utilisée. Lorsque avariable est créé dans un gestionnaire de type de sortie, ce paramètre doit être défini à la taille du tableau du curseur.

Les paramètres discverter et outconverter spécifient les méthodes utilisées pour convertir des valeurs vers/depuis la base de données. Plus d’informations peuvent être trouvées dansla section sur les objets variables.

Le paramètre typename spécifie le nom d’un type d’objet SQL et doit être spécifié lors de l’utilisation du type cx_Oracle.OBJECT à moins que l’objet de type ne soit passé directement en tant que premier paramètre.

Le paramètre encodingErrors spécifie ce qui doit se passer lors du décodage des chaînes d’octets extraites de la base de données en chaînes. Ce devrait être l’une des valeurs notées dans la fonction intégrée.