Cursor Object¶

Cursor.__enter__()¶

o ponto de entrada para o cursor como um gestor de contexto. Volta sozinho.

Cursor.__exit__()¶

o ponto de saída do cursor como um gestor de contexto. Fecha o cursor.

Cursor.arraysize¶

este atributo read-write pode ser usado para sintonizar o número de linhas internallyfetched e buffer por chamadas internas para a base de dados, ao obter as linhas a partir de opções selecionadas e cursores de REF. O valor pode afetar drasticamente o desempenho de uma consulta, uma vez que afeta diretamente o número de viagens em rede entre Python e o banco de dados. Para métodos comofetchone() e fetchall(), não muda pois muitas linhas são devolvidas à aplicação. Para fetchmany() é o número por omissão de linhas a obter.

devido aos benefícios de desempenho, o padrão Cursor.arraysize é 100 em vez do 1 que o DB API recomenda. Este valor significa que 100 linhas são obtidas por cada chamada interna para a base de dados.

ver o desempenho de ajuste de busca para mais informações.

Cursor.bindarraysize¶

este atributo read-write especifica o número de linhas a ligar a um tempo e é usado ao criar variáveis via setinputsizes() ouvar(). O padrão é 1 significando vincular uma única linha ao mesmo tempo.

Cursor.arrayvar(dataType, value)¶

Create an array variable associated with the cursor of the given type andsize and return a variable object. O valor é um inteiro especificando o número de elementos a alocar ou é uma lista e o número de elementos alocados é extraído do tamanho da lista. Se o valor é uma lista, a variável também é definida com o conteúdo da lista. Se o tamanho não for especificado e o tipo for uma cadeia ou binário, 4000 bytesis alocados. Isto é necessário para passar arrays para PL/SQL (nos casos em que a lista pode estar vazia e o tipo não pode ser determinado automaticamente) ou reverter arrays de PL / SQL.

variáveis Array só podem ser usadas para arrays associativos PL / SQL com chaves contíguas. Para matrizes associativas PL / SQL com teclado escassamente povoado para varrays e tabelas aninhadas, a abordagem mostrada neste exemplo Precisa ser usada.

Cursor.bindnames()¶

Devolve a lista de nomes de variáveis vinculados à instrução. Note que astatement deve ter sido preparado primeiro.

Cursor.bindvars¶

este atributo read-only Fornece as variáveis bind usadas para o lastexecute. O valor será uma lista ou um dicionário, dependendo de se a ligação foi feita por posição ou nome. Deve ter-se cuidado ao fazer referência a este atributo. Em especial, os elementos não devem ser removidos ou substituídos.

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

Call a function with the given name. O tipo de retorno é especificado na mesma notação como é exigido por setinputsizes(). Aequência dos parâmetros deve conter uma entrada para cada parâmetro que a função espera. Todos os parâmetros da palavra-chave serão incluídos APÓS os parâmetros da posição. O resultado da chamada é o valor de retorno da função.

ver as funções armazenadas por PL/SQL, por exemplo.

Cursor.callproc(nome, parâmetros=, keywordParameters = {})¶

Call a procedure with the given name. A sequência de parâmetros deve conter uma entrada para cada parâmetro que o procedimento espera. O resultado da chamada é uma cópia modificada da sequência de entrada. Os parâmetros de entrada não são mexidos; os parâmetros de saída e de entrada/saída são substituídos por valores aparentemente novos. Os parâmetros da palavra-chave serão incluídos APÓS os parâmetros da posição e não serão devolvidos como parte da sequência de saída.

ver, por exemplo, os procedimentos armazenados em PL/SQL.

Cursor.close()¶

feche o cursor agora, em vez de quando ___ del_ é chamado. O cursor será inutilizável a partir deste ponto para a frente; uma exceção de erro será aumentada se qualquer operação for tentada com o cursor.

Cursor.connection¶

este atributo apenas para leitura devolve uma referência ao objecto de ligação no qual o cursor foi criado.

Cursor.description¶

este atributo apenas para leitura é uma sequência de sequências de 7 itens. Cada uma destas consequências contém informação que descreve uma coluna de resultado: (nome, tipo,display_size, internal_size, precisão, escala, null_ok). Esta atribuição não será nenhuma para as operações que não devolvem linhas ou se o cursor ainda não teve uma operação invocada através do método execute().

o tipo será um dos tipos de base de dados definidos ao nível dos módulos.

Cursor.execute(statement, * * keywordParameters)

Execute a statement against the database. Ver execução SQL.

os parâmetros podem ser passados como dicionário ou sequência ou como chaveiros. Se os parâmetros são um dicionário, os valores serão ligados byname e se os parâmetros são uma sequência os valores serão ligados byposition. Note que se os valores estão vinculados pela posição, a ordem das variáveis é da esquerda para a direita como eles são encontrados nas declarações de statement e SQL são processados de forma diferente das declarações PL/SQL. Por esta razão, é geralmente recomendado ligar parâmetros pelo nome em vez de por posição.

Parameters passed as a dictionary are name and value pairs. O nome mapeia o nome da variável bind usado pela declaração e o valor mapeia para o valor em que deseja ligar-se a essa variável bind.

uma referência à declaração será mantida pelo cursor. Se nenhum ou mesmo objeto de cadeia de caracteres for passado de novo, o cursor irá executar essa Declaração novamente sem executar um preparar ou refinar e redefinir.Isto é mais eficaz para algoritmos onde a mesma afirmação é usada, mas parâmetros diferentes estão ligados a ela (muitas vezes). Note – se que os paramétricos que não são repassados durante as execuções subsequentes manterão o valor acumulado durante a última execução que os conteve.

para a máxima eficiência ao reutilizar uma declaração, é melhor usar o métodosetinputsizes() para especificar os tipos de parâmetros e dimensionar antes do tempo; em particular, nenhum é assumido como uma string oflength 1 de modo que quaisquer valores que são posteriormente ligados como números ou datas Irão raisea TypeError exception.

se a instrução é uma consulta, o cursor é devolvido como uma conveniência para o jogador (para que ele possa ser usado diretamente como iterador sobre as linhas no corredor); caso contrário, None é retornado.

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

Prepare uma statement for execution against a database and then execute itagainst all parameter mappings or sequences found in the sequenceparameters. Veja a execução da Declaração de lote e o carregamento A Granel.

a declaração é gerida da mesma forma que o método execute()a gere. Se o tamanho dos buffers alocados para qualquer um dos parâmetros exceder 2 GB, você receberá o erro ” DPI-1015: o tamanho da matriz de <n > é muito grande”, onde <n> varia com o tamanho de cada elemento sendo alocado no buffer. Se você receber este erro, diminua o número de elementos nos parâmetros de sequência.

se não há parâmetros, ou parâmetros foram previamente ligados, o número de iterações pode ser especificado como um inteiro em vez de necessitar de fornecer uma lista de mapeamentos ou sequências vazias.Quando verdadeiro, o parâmetro batcherros permite o Suporte de erro do lote com o índice de erro e garante que a chamada é bem sucedida mesmo que uma excepção ocorra em uma ou mais da sequência de parâmetros. Os erros podem então ser tolerados usando getbatcherrors().

quando verdadeiro, o parâmetro “arraydmlrowcounts” permite que as contagens de linhas DML sejam toleradas pela Oracle após o método ter terminado. A contagem das linhas pode ser obtida utilizando getarraydmlrowcounts().

tanto o parâmetro batcherros e o parâmetro arraydmlrowcounts só podem ser verdadeiros ao executar uma declaração de inserção, actualização, remoção ou junção; em todos os outros casos, será levantado um erro.

Para a máxima eficiência, é melhor usar osetinputsizes() método para especificar os tipos de parâmetro andsizes antes do tempo; em particular, Nenhum é considerado uma seqüência de caracteres oflength 1 para quaisquer valores que são, posteriormente, vinculado como números ou datas serão raisea exceção TypeError.

Cursor.executemanyprepared(numeradores)

Execute a declaração previamente preparada e encadernada o número de vezes indicado. As variáveis que estão ligadas já devem ter sido ajustadas ao seu valor desejado antes desta chamada ser feita. Este método foi concebido para o caso em que é necessário um desempenho óptimo, à custa da compatibilidade com o DB API.

Cursor.fetchall()¶

obter todas (restantes) linhas de um resultado de uma consulta, retornando-as como uma lista deuplos. É devolvida uma lista em branco se não estiverem disponíveis mais linhas. Note que o atributo arraysize do cursor pode afetar o desempenho desta operação, como leituras internas do banco de dados são feitas em batchescorrespondentes ao arraysize.

uma exceção é levantada se a chamada anterior para execute() não produziu nenhum conjunto de resultados ou nenhuma chamada foi emitida ainda.

veja Métodos de Busca por exemplo.

Cursor.fetchmany()¶

obter o conjunto seguinte de linhas de um resultado de pesquisa, devolvendo uma lista de tuples.An a lista vazia é devolvida se não estiverem disponíveis mais linhas. Note – se que o atributo arraysize de thecursor pode afetar o desempenho desta operação.

o número de linhas a obter é especificado pelo parâmetro. Se não estiver disponível, o atributo arraysize do cursor determina o número de linhas a serem encaixadas. Se o número de linhas disponíveis para serem obtidas for inferior ao valor pedido, serão devolvidas menos linhas.

uma exceção é levantada se a chamada anterior para execute() não produziu nenhum conjunto de resultados ou nenhuma chamada foi emitida ainda.

veja Métodos de Busca por exemplo.

Cursor.fetchone()¶

obtenha a próxima linha de um conjunto de resultados da consulta, retornando uma única tupla ou não quando não houver mais dados disponíveis.

uma exceção é levantada se a chamada anterior para execute() não produziu nenhum conjunto de resultados ou nenhuma chamada foi emitida ainda.

veja Métodos de Busca por exemplo.

Cursor.fetchraw()¶

Buscar o próximo conjunto de linhas de um resultado de consulta para os buffers internos das variáveis definidas para o cursor. O número de linhas efectivamente obtidas é devolvido. Este método foi concebido para o caso em que é necessário um desempenho optimal, uma vez que se trata de um método à custa da compatibilidade com a DB API.

uma exceção é levantada se a chamada anterior para execute() não produziu nenhum conjunto de resultados ou nenhuma chamada foi emitida ainda.

Cursor.fetchvars¶

este atributo read-only especifica a lista de variáveis criadas para a última consulta que foi executada no cursor. Deve ter-se cuidado ao fazer referência a este atributo. Em especial, os elementos não devem ser removidos ou substituídos.

Cursor.getarraydmlrowcounts()¶

obter a contagem da linha DML após uma chamada para executemany()com as montagens arraydmlrow ativadas. Isto irá devolver uma lista de inteiros correspondentes ao número de linhas afetadas pela declaração DML para cada um dos elementos da matriz passados para executemany().

Cursor.getbatcherrors()¶

recuperar as excepções que ocorreram após uma chamada paraexecutemany() com os erros do bastão activados. Isto irá devolver a lista de objetos de Erro, um erro para cada iteração que falhou. A compensação pode ser determinada olhando para o atributo offset do objeto de erro.

Cursor.getimplicitresults()¶

devolver uma lista de cursores que correspondem a resultados implícitos disponíveis a partir de um bloco ou procedimento PL/SQL sem a utilização de Parâmetros de referência externos. O bloco ou procedimento PL/SQL abre os cursores e marca-os para serem devolvidos ao cliente usando o proceduredbms_sql.return_result. Cursores retornados desta forma não devem ser encerrados. Serão fechadas automaticamente pelo cursor pai quando for fechada. Se fechar o cursor pai irá invalidar os cursores devolvidos por este método.

Cursor.inputtypehandler¶

este atributo read-write especifica um método chamado para cada valor que está ligado a uma instrução executada no cursor e substitui a atribuição com o mesmo nome na ligação, se indicado. O método signature ishandler(cursor, valor, arraysize) e o valor return é esperado para ser um objeto variável ou nenhum, caso em que um objeto variável padrão será criado. Se este atributo não for Nenhum, é usado o valor do atributo com o mesmo nome na conexão.Este atributo é uma extensão da definição de DB API.

Cursor.__iter__()¶

Devolve o cursor para ser usado como iterador.

Cursor.lastrowid¶

este atributo apenas para leitura devolve o rowid da última linha modificada pelo motor. Se nenhuma linha foi modificada pela última operação realizada no motor, o valor nenhum é devolvido.

Cursor.outputtypehandler¶

este atributo read-write especifica um método chamado para cada coluna que deve ser obtido a partir deste cursor. O método signature ishandler (cursor, nome, defaultType, comprimento, precisão, escala) e o valor de retorno é esperado para ser um objeto variável ou nenhum, caso em que um objeto defaultvariável será criado. Se este atributo não for Nenhum, é utilizado o valor do atributo com o mesmo nome na ligação.

ver alterações nos tipos de dados obtidos com manipuladores do tipo de saída.Este atributo é uma extensão da definição de DB API.

Cursor.parse(instrução)¶

Isso pode ser usado para analisar uma declaração sem realmente executá-lo (thisstep é feito automaticamente pela Oracle quando uma instrução é executada).

Cursor.prefetchrows¶

este atributo read-write pode ser usado para sintonizar o número de linhas que a biblioteca cliente teoracle obtém quando uma instrução selecionada é executada. Thisvalue can reduce the number of round-trips to the database that are requiredd to fetch rows but at the cost of additional memory. A configuração deste valor para 0 pode ser útil quando o tempo de obtenção deve ser explicitamente controlado.

ver o desempenho de ajuste de busca para mais informações.

Cursor.prepare(statement)

This can be used before a call to execute() to definite theestatement that will be executed. Quando isso é feito, a fase de preparação não será realizada quando a chamada para execute() é feita sem um ou o mesmo objeto de cadeia de caracteres que a declaração. Se a declaração especificada for devolvida ao cache da declaração com a tag indicada. Veja a documentação do Oracle para mais informações sobre o cache de declarações.

ver Declaração Caching para mais informações.

Cursor.rowcount¶

este atributo apenas para leitura indica o número de linhas que foram obtidas do cursor (para seleccionar as declarações), que foram afectadas pela operação (para inserir, actualizar, apagar e reunir), ou o número de execuções bem-sucedidas da declaração(para as declarações PL/SQL).

Cursor.rowfactory¶

este atributo read-write especifica um método para chamar para cada linha que é extraída da base de dados. Normalmente uma tupla é devolvida para cada rowbut se este atributo for definido, o método é chamado com a tupla que normalmente seria retornada, e o resultado do método é retornado em vez.

ver a alteração dos resultados da consulta com os “Rowfactories”.

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

Scroll the cursor in the result set to a new position according to themode.

se o modo for “relativo” (o valor padrão), o valor é tomado como um contrapeso da posição atual no conjunto de resultados. Se definido como “absoluto”, O valor corresponde a uma posição-alvo absoluta. Se for definido como “primeiro”, o cursor é colocado na primeira linha e se for definido como” último”, o cursor é definido como a última linha no conjunto de resultados.

um erro é elevado se o modo for “relativo” ou “absoluto” e a posicionamento do cursor fora do conjunto de resultados.

Cursor.scrollable¶

este atributo booleano de leitura-escrita indica se o cursor pode ser rodado ou não. Por padrão, Cursores não são controláveis, como os serverresources e os tempos de resposta são maiores do que Cursores não controláveis. Este atributo é verificado e o modo correspondente definido no Oracle ao chamar o método execute().

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

This can be used before a call to execute(),callfunc() or callproc() to predefinemory areas for the operation’s parameters. Cada parâmetro deve ser objeto de tipo atype correspondente à entrada que será usada ou deve ser um número inteiro especificando o comprimento máximo de um parâmetro de cadeia de caracteres. Use keywordparameters quando ligar por nome e parâmetros posicionais quando ligar byposition. O Singleton None pode ser usado como um parâmetro ao usar parâmetros de posição para indicar que nenhum espaço deve ser reservado para essa posição.

Cursor.setoutputsize(size)

This method does nothing and is retained only for compatibility with theDB API. O módulo aloca automaticamente tanto espaço quanto necessário para fetchLONG e longas colunas RAW (ou CLOB como string e BLOB como bytes).

Cursor.statement¶

este atributo read-only Fornece o objecto string que foi anteriormente preparado com prepare() ou executado comexecute().

Cursor.var(dataType)¶

crie uma variável com as características especificadas. Este método foi concebido para ser usado com variáveis PL/SQL de entrada/saída onde o comprimento ou tipo de letra não pode ser determinado automaticamente a partir do objeto Python passado ou foruse em manipuladores de tipo de entrada e saída definidos em cursores ou conexões.

o parâmetro dataType especifica o tipo de dados que devem ser armazenados na variável. Este deve ser um dos thedatabase constantes de tipo, DB API constantes,um tipo de objeto retornado do método Connection.gettype() ou oneof os seguintes tipos de Python:

Python Tipo	Tipo de Banco de dados
bool	cx_Oracle.DB_TYPE_BOOLEAN
bytes	cx_Oracle.DB_TYPE_RAW
data / hora.data	cx_Oracle.DB_TYPE_DATE
datetime.datetime	cx_Oracle.DB_TYPE_DATE
datetime.timedelta	cx_Oracle.DB_TYPE_INTERVAL_DS
decimal.Decimal	cx_Oracle.DB_TYPE_NUMBER
float	cx_Oracle.DB_TYPE_NUMBER
int	cx_Oracle.DB_TYPE_NUMBER
str	cx_Oracle.DB_TYPE_VARCHAR

O tamanho do parâmetro especifica o comprimento da cadeia e matérias variáveis e isignored em todos os outros casos. Se não for especificado para string e variáveis raw,é utilizado o valor 4000.

o parâmetro arraysize especifica o número de elementos que a variável terá. Se não for especificado o tamanho da matriz de encadernação (geralmente 1) é usado. Quando avariável é criado em um manipulador de tipo de saída este parâmetro deve ser definido para o tamanho da matriz do cursor.

os parâmetros inconverter e outconverter especificam os métodos utilizados para obter valores de/para a base de dados. Mais informações podem ser encontradas na seção sobre objetos variáveis.

o parâmetro do nome do tipo especifica o nome de um tipo de objeto SQL e deve ser especificado ao usar o tipo cx_Oracle.OBJECT a menos que o objeto do tipo tenha passado diretamente como o primeiro parâmetro.

o parâmetro codificador erro especifica o que deve acontecer ao descodificar cadeias de caracteres da base de dados para cadeias de caracteres. Deve ser um dos valores assinalados na função de construção.