Cursor

class k_ctds.Cursor

A database cursor used to manage the context of a fetch operation.

PEP 0249#cursor-objects

Parameter

Convenience method to k_ctds.Parameter.

Returns:: A new Parameter object.
Return type:: k_ctds.Parameter

__enter__()

Enter the cursor’s runtime context. On exit, the cursor is closed automatically.

Returns:: The cursor object.
Return type:: k_ctds.Cursor

__exit__(exc_type, exc_val, exc_tb)

Exit the cursor’s runtime context, closing the cursor.

Parameters:

exc_type (type) – The exception type, if an exception is raised in the context, otherwise None.
exc_val (Exception) – The exception value, if an exception is raised in the context, otherwise None.
exc_tb (object) – The exception traceback, if an exception is raised in the context, otherwise None.

Returns:

None

__iter__(): Implement iter(self).

__next__(): Implement next(self).

__repr__(): Return repr(self).

arraysize

The number of rows to fetch at a time with fetchmany().

PEP 0249#arraysize

Return type:: int

callproc(sproc, parameters)

Call a stored database procedure with the given name. The sequence of parameters must contain one entry for each argument that the procedure expects. The result of the call is returned as modified copy of the input sequence. Input parameters are left untouched. Output and input/output parameters are replaced with output values.

Warning

Due to FreeTDS implementation details, stored procedures with both output parameters and resultsets are not supported.

Warning

Currently FreeTDS does not support passing empty string parameters. Empty strings are converted to NULL values internally before being transmitted to the database.

PEP 0249#callproc

Parameters:

sproc (str) – The name of the stored procedure to execute.
parameters (dict or tuple) – Parameters to pass to the stored procedure. Parameters passed in a dict must map from the parameter name to value and start with the @ character. Parameters passed in a tuple are passed in the tuple order.

Returns:

The input parameters with any output parameters replaced with the output values.

Return type:

dict or tuple

close()

Close the cursor.

PEP 0249#Cursor.close

connection

A reference to the Connection object on which the cursor was created.

PEP 0249#id28

Return type:: k_ctds.Connection

description

A description of the current result set columns. The description is a sequence of tuples, one tuple per column in the result set. The tuple describes the column data as follows:

name	The name of the column, if provided.
type_code	The specific type of the column.
display_size	The SQL type size of the column.
internal_size	The client size of the column.
precision	The precision of NUMERIC and DECIMAL columns.
scale	The scale of NUMERIC and DECIMAL columns.
null_ok	Whether the column allows NULL.

Note

In Python 3+, this is a tuple of collections.namedtuple() objects whose members are defined above.

PEP 0249#description

Returns:: A sequence of tuples or None if no results are available.
Return type:: tuple(tuple(str, int, int, int, int, int, bool))

execute(sql, parameters=None)

Prepare and execute a database operation. Parameters may be provided as sequence and will be bound to variables specified in the SQL statement. Parameter notation is specified by k_ctds.paramstyle.

PEP 0249#execute

Parameters:

sql (str) – The SQL statement to execute.
parameters (tuple) – Optional variables to bind.

executemany(sql, seq_of_parameters)

Prepare a database operation (query or command) and then execute it against all parameter sequences or mappings found in the sequence seq_of_parameters.

PEP 0249#executemany

Parameters:

sql (str) – The SQL statement to execute.
seq_of_parameters (typeiter) – An iterable of parameter sequences to bind.

fetchall()

Fetch all (remaining) rows of a query result, returning them as a sequence of sequences.

PEP 0249#fetchall

Returns:: A sequence of result rows.
Return type:: k_ctds.RowList

fetchmany(size=self.arraysize)

Fetch the next set of rows of a query result, returning a sequence of sequences. An empty sequence is returned when no more rows are available.

PEP 0249#fetchmany

Returns:: A sequence of result rows.
Return type:: k_ctds.RowList

fetchone()

Fetch the next row of a query result set, returning a single sequence, or None when no more data is available.

PEP 0249#fetchone

Returns:: The next row or None.

next()

Return the next row from the currently executing SQL statement using the same semantics as fetchone(). A StopIteration exception is raised when the result set is exhausted.

PEP 0249#next

Raises:: StopIteration – The result set is exhausted.
Returns:: The next row.

nextset()

Skip to the next available set, discarding any remaining rows from the current set.

PEP 0249#nextset

Returns:: True if there was another result set or None if not.
Return type:: bool

rowcount

The number of rows that the last execute() produced or affected.

Note

This value is unreliable when execute() is called with parameters and using a version of FreeTDS prior to 1.1.

PEP 0249#rowcount

Return type:: int

rownumber

The current 0-based index of the cursor in the result set or None if the index cannot be determined.

PEP 0249#rownumber

Return type:: int

setinputsizes()

This method has no effect.

PEP 0249#setinputsizes

setoutputsize()

This method has no effect.

PEP 0249#setoutputsize

spid

Retrieve the SQL Server Session Process ID (SPID) for the connection or None if the connection is closed.

Return type:: int

String Representation

repr(cursor) shows whether the cursor is open or closed, and the column count when a result set is active:

>>> cursor = conn.cursor()
>>> repr(cursor)
'<k_ctds.Cursor (open)>'
>>> cursor.execute('SELECT 1 AS a, 2 AS b')
>>> repr(cursor)
'<k_ctds.Cursor (open, 2 columns)>'
>>> cursor.close()
>>> repr(cursor)
'<k_ctds.Cursor (closed)>'

Added in version 2.1.0.