10. API: Variable Objects

10.1. Variable Class

class oracledb.Var

A Var object should be created with Cursor.var() or Cursor.arrayvar().

This object is an extension to the DB API definition.

10.2. Variable Methods

Var.getvalue(pos: int = 0) → Any

Returns the value at the given position in the variable. For variables created using the method Cursor.arrayvar(), the value returned will be a list of each of the values in the PL/SQL index-by table. For variables bound to DML returning statements, the value returned will also be a list corresponding to the returned data for the given execution of the statement (as identified by the pos parameter).

Var.setvalue(pos: int, value: Any) → None

Sets the value at the given position in the variable.

10.3. Variable Attributes

property Var.actual_elements: int

This read-only attribute returns the actual number of elements in the variable. This corresponds to the number of elements in a PL/SQL index-by table for variables that are created using the method Cursor.arrayvar(). For all other variables, this value will be identical to the attribute num_elements.

For consistency and compliance with the PEP 8 naming style, the attribute actualElements was renamed to actual_elements. The old name will continue to work for a period of time.

property Var.buffer_size: int

This read-only attribute returns the size of the buffer allocated for each element in bytes.

For consistency and compliance with the PEP 8 naming style, the attribute bufferSize was renamed to buffer_size. The old name will continue to work for a period of time.

property Var.convert_nulls: bool

This read-only attribute returns whether null values are converted using the supplied outconverter.

Added in version 1.4.0.

property Var.inconverter: Callable | None

This read-only attribute specifies the method used to convert data from Python to the Oracle database. The method signature is converter(value) and the expected return value is the value to bind to the database. If this attribute is None, the value is bound directly without any conversion.

property Var.num_elements: int

This read-only attribute returns the number of elements allocated in an array, or the number of scalar items that can be fetched into the variable or bound to the variable.

For consistency and compliance with the PEP 8 naming style, the attribute numElements was renamed to num_elements. The old name will continue to work for a period of time.

property Var.outconverter: Callable | None

This read-only attribute specifies the method used to convert data from the Oracle database to Python. The method signature is converter(value) and the expected return value is the value to return to Python. If this attribute is None, the value is returned directly without any conversion.

property Var.size: int

This read-only attribute returns the size of the variable. For strings this value is the size in characters. For all others, this is the same value as the attribute buffer_size.

property Var.type: DbType | DbObjectType

This read-only attribute returns the type of the variable. This will be an Oracle Object Type if the variable binds Oracle objects; otherwise, it will be one of the database type constants.

Database type constants are now used when the variable is not used for binding Oracle objects.

property Var.values: list

This read-only attribute returns a copy of the value of all actual positions in the variable as a list. This is the equivalent of calling getvalue() for each valid position and the length will correspond to the value of the actual_elements attribute.