PyCursor (Jython API documentation)
Date: 2024-08-18

com.ziclix.python.sql

## Class PyCursor

- java.lang.Object
- - org.python.core.PyObject
  - - com.ziclix.python.sql.PyCursor

- All Implemented Interfaces:
    WarningListener, java.io.Serializable, ClassDictInit, ContextManager, Traverseproc
  Direct Known Subclasses:
    PyExtendedCursor

      public class PyCursor
      extends PyObject
      implements ClassDictInit, WarningListener, ContextManager, Traverseproc

  These objects represent a database cursor, which is used to manage the context of a fetch operation.
  Author:
    brian zimmer
  See Also:
    Serialized Form

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.python.core.PyObject

      `PyObject.ConversionException`

  - ### Field Summary

    - ### Fields inherited from class org.python.core.PyObject

      `gcMonitorGlobal, TYPE`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `__del__()` Delete the cursor.
    `PyObject` | `__enter__()`
    `PyObject` | `__enter__(ThreadState ts)`
    `boolean` | `__exit__(PyObject type, PyObject value, PyObject traceback)`
    `boolean` | `__exit__(ThreadState ts, PyException exception)`
    `PyObject` | `__findattr_ex__(java.lang.String name)` Gets the value of the attribute name.
    `PyObject` | `__iter__()` Returns an iteratable object.
    `PyObject` | `__iternext__()` Return the next element of the sequence that this is an iterator for.
    `void` | `__setattr__(java.lang.String name, PyObject value)` Sets the attribute name to value.
    `void` | `callproc(PyObject name, PyObject params, PyObject bindings, PyObject maxRows)` This method is optional since not all databases provide stored procedures.
    `static void` | `classDictInit(PyObject dict)` Initializes the object's namespace.
    `void` | `close()` Close the cursor now (rather than whenever __del__ is called).
    `void` | `execute(PyObject sql, PyObject params, PyObject bindings, PyObject maxRows)` Prepare and execute a database operation (query or command).
    `void` | `executemany(PyObject sql, PyObject params, PyObject bindings, PyObject maxRows)` Prepare a database operation (query or command) and then execute it against all parameter sequences or mappings found in the sequence seq_of_parameters.
    `PyObject` | `fetchall()` Fetch all (remaining) rows of a query result, returning them as a sequence of sequences (e.g. a list of tuples).
    `PyObject` | `fetchmany(int size)` Fetch the next set of rows of a query result, returning a sequence of sequences (e.g. a list of tuples).
    `PyObject` | `fetchone()` Fetch the next row of a query result set, returning a single sequence, or None when no more data is available.
    `DataHandler` | `getDataHandler()` Return the currently bound DataHandler.
    `static boolean` | `hasParams(PyObject params)` Method hasParams
    `static boolean` | `isSeq(PyObject object)` Method isSeq
    `static boolean` | `isSeqSeq(PyObject object)` Method isSeqSeq
    `PyObject` | `next()` Returns the next row from the currently executing SQL statement using the same semantics as .fetchone().
    `PyObject` | `nextset()` Move the result pointer to the next set if available.
    `PyStatement` | `prepare(PyObject sql)` Prepare a sql statement for later execution.
    `boolean` | `refersDirectlyTo(PyObject ob)` Optional operation.
    `void` | `scroll(int value, java.lang.String mode)` Scroll the cursor in the result set to a new position according to mode.
    `java.lang.String` | `toString()` String representation of the object.
    `int` | `traverse(Visitproc visit, java.lang.Object arg)` Traverses all directly contained `PyObject`s.
    `void` | `warning(WarningEvent event)` Adds a warning to the tuple and will follow the chain as necessary.

    - ### Methods inherited from class org.python.core.PyObject

      `__abs__, __add__, __and__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __cmp__, __coerce__, __coerce_ex__, __complex__, __contains__, __delattr__, __delattr__, __delete__, __delitem__, __delitem__, __delslice__, __delslice__, __dir__, __div__, __divmod__, __ensure_finalizer__, __eq__, __findattr__, __findattr__, __finditem__, __finditem__, __finditem__, __float__, __floordiv__, __format__, __ge__, __get__, __getattr__, __getattr__, __getitem__, __getitem__, __getnewargs__, __getslice__, __getslice__, __gt__, __hash__, __hex__, __iadd__, __iand__, __idiv__, __idivmod__, __ifloordiv__, __ilshift__, __imod__, __imul__, __index__, __int__, __invert__, __ior__, __ipow__, __irshift__, __isub__, __itruediv__, __ixor__, __le__, __len__, __long__, __lshift__, __lt__, __mod__, __mul__, __ne__, __neg__, __nonzero__, __not__, __oct__, __or__, __pos__, __pow__, __pow__, __radd__, __rand__, __rdiv__, __rdivmod__, __reduce__, __reduce_ex__, __reduce_ex__, __repr__, __rfloordiv__, __rlshift__, __rmod__, __rmul__, __ror__, __rpow__, __rrshift__, __rshift__, __rsub__, __rtruediv__, __rxor__, __set__, __setattr__, __setitem__, __setitem__, __setitem__, __setslice__, __setslice__, __str__, __sub__, __tojava__, __truediv__, __trunc__, __unicode__, __xor__, _add, _and, _callextra, _cmp, _div, _divmod, _doget, _doget, _doset, _eq, _floordiv, _ge, _gt, _iadd, _iand, _idiv, _idivmod, _ifloordiv, _ilshift, _imod, _imul, _in, _ior, _ipow, _irshift, _is, _isnot, _isub, _itruediv, _ixor, _jcall, _jcallexc, _jthrow, _le, _lshift, _lt, _mod, _mul, _ne, _notin, _or, _pow, _rshift, _sub, _truediv, _xor, asDouble, asIndex, asIndex, asInt, asInt, asIterable, asLong, asLong, asName, asName, asString, asString, asStringOrNull, asStringOrNull, bit_length, conjugate, delDict, delType, dispatch__init__, equals, fastGetClass, fastGetDict, getDict, getType, hashCode, implementsDescrDelete, implementsDescrGet, implementsDescrSet, invoke, invoke, invoke, invoke, invoke, invoke, isCallable, isDataDescr, isIndex, isInteger, isMappingType, isNumberType, isSequenceType, noAttributeError, object___subclasshook__, readonlyAttributeError, setDict, setType`

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Method Detail

    - #### toString

          public java.lang.String toString()

      String representation of the object.
      Overrides:
        `toString` in class `PyObject`
      Returns:
        a string representation of the object.

    - #### __setattr__

          public void __setattr__(java.lang.String name,
                                  PyObject value)

      Sets the attribute name to value.
      Overrides:
        `__setattr__` in class `PyObject`
      Parameters:
        `name` -
        `value` -
      See Also:
        `PyObject.__setattr__(PyString, PyObject)`

    - #### __findattr_ex__

          public PyObject __findattr_ex__(java.lang.String name)

      Gets the value of the attribute name.
      Overrides:
        `__findattr_ex__` in class `PyObject`
      Parameters:
        `name` -
      Returns:
        the attribute for the given name

    - #### classDictInit

          public static void classDictInit(PyObject dict)

      Initializes the object's namespace.
      Parameters:
        `dict` -

    - #### __del__

          public void __del__()

      Delete the cursor.

    - #### close

          public void close()

      Close the cursor now (rather than whenever __del__ is called). The cursor will be unusable from this point forward; an Error (or subclass) exception will be raised if any operation is attempted with the cursor.

    - #### __iter__

          public PyObject __iter__()

      Returns an iteratable object.
      Overrides:
        `__iter__` in class `PyObject`
      Returns:
        PyObject
      Since:
        Jython 2.2, DB API 2.0+

    - #### next

          public PyObject next()

      Returns 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 for Python versions 2.2 and later.
      Returns:
        PyObject
      Since:
        Jython 2.2, DB API 2.0+

    - #### __iternext__

          public PyObject __iternext__()

      Return the next element of the sequence that this is an iterator for. Returns null when the end of the sequence is reached.
      Overrides:
        `__iternext__` in class `PyObject`
      Returns:
        PyObject
      Since:
        Jython 2.2

    - #### getDataHandler

          public DataHandler getDataHandler()

      Return the currently bound DataHandler.
      Returns:
        DataHandler

    - #### callproc

          public void callproc(PyObject name,
                               PyObject params,
                               PyObject bindings,
                               PyObject maxRows)

      This method is optional since not all databases provide stored procedures. 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 replaced with possibly new values. The procedure may also provide a result set as output. This must then be made available through the standard fetchXXX() methods.
      Parameters:
        `name` -
        `params` -
        `bindings` -
        `maxRows` -

    - #### executemany

          public void executemany(PyObject sql,
                                  PyObject params,
                                  PyObject bindings,
                                  PyObject maxRows)

      Prepare a database operation (query or command) and then execute it against all parameter sequences or mappings found in the sequence seq_of_parameters. Modules are free to implement this method using multiple calls to the execute() method or by using array operations to have the database process the sequence as a whole in one call. The same comments as for execute() also apply accordingly to this method. Return values are not defined.
      Parameters:
        `sql` -
        `params` -
        `bindings` -
        `maxRows` -

    - #### execute

          public void execute(PyObject sql,
                              PyObject params,
                              PyObject bindings,
                              PyObject maxRows)

      Prepare and execute a database operation (query or command). Parameters may be provided as sequence or mapping and will be bound to variables in the operation. Variables are specified in a database-specific notation (see the module's paramstyle attribute for details). A reference to the operation will be retained by the cursor. If the same operation object is passed in again, then the cursor can optimize its behavior. This is most effective for algorithms where the same operation is used, but different parameters are bound to it (many times). For maximum efficiency when reusing an operation, it is best to use the setinputsizes() method to specify the parameter types and sizes ahead of time. It is legal for a parameter to not match the predefined information; the implementation should compensate, possibly with a loss of efficiency. The parameters may also be specified as list of tuples to e.g. insert multiple rows in a single operation, but this kind of usage is deprecated: executemany() should be used instead. Return values are not defined.
      Parameters:
        `sql` - sql string or prepared statement
        `params` - params for a prepared statement
        `bindings` - dictionary of (param index : SQLType binding)
        `maxRows` - integer value of max rows

    - #### fetchone

          public PyObject fetchone()

      Fetch the next row of a query result set, returning a single sequence, or None when no more data is available. An Error (or subclass) exception is raised if the previous call to executeXXX() did not produce any result set or no call was issued yet.
      Returns:
        a single sequence from the result set, or None when no more data is available

    - #### fetchall

          public PyObject fetchall()

      Fetch all (remaining) rows of a query result, returning them as a sequence of sequences (e.g. a list of tuples). Note that the cursor's arraysize attribute can affect the performance of this operation. An Error (or subclass) exception is raised if the previous call to executeXXX() did not produce any result set or no call was issued yet.
      Returns:
        a sequence of sequences from the result set, or an empty sequence when no more data is available

    - #### fetchmany

          public PyObject fetchmany(int size)

      Fetch the next set of rows of a query result, returning a sequence of sequences (e.g. a list of tuples). An empty sequence is returned when no more rows are available. The number of rows to fetch per call is specified by the parameter. If it is not given, the cursor's arraysize determines the number of rows to be fetched. The method should try to fetch as many rows as indicated by the size parameter. If this is not possible due to the specified number of rows not being available, fewer rows may be returned. An Error (or subclass) exception is raised if the previous call to executeXXX() did not produce any result set or no call was issued yet. Note there are performance considerations involved with the size parameter. For optimal performance, it is usually best to use the arraysize attribute. If the size parameter is used, then it is best for it to retain the same value from one fetchmany() call to the next.
      Parameters:
        `size` -
      Returns:
        a sequence of sequences from the result set, or an empty sequence when no more data is available

    - #### nextset

          public PyObject nextset()

      Move the result pointer to the next set if available.
      Returns:
        true if more sets exist, else None

    - #### prepare

          public PyStatement prepare(PyObject sql)

      Prepare a sql statement for later execution.
      Parameters:
        `sql` - The sql string to be prepared.
      Returns:
        A prepared statement usable with .executeXXX()

    - #### scroll

          public void scroll(int value,
                             java.lang.String mode)

      Scroll the cursor in the result set to a new position according to mode. If mode is 'relative' (default), value is taken as offset to the current position in the result set, if set to 'absolute', value states an absolute target position. An IndexError should be raised in case a scroll operation would leave the result set. In this case, the cursor position is left undefined (ideal would be to not move the cursor at all). Note: This method should use native scrollable cursors, if available, or revert to an emulation for forward-only scrollable cursors. The method may raise NotSupportedErrors to signal that a specific operation is not supported by the database (e.g. backward scrolling).
      Parameters:
        `value` -
        `mode` -

    - #### warning

          public void warning(WarningEvent event)

      Adds a warning to the tuple and will follow the chain as necessary.
      Specified by:
        `warning` in interface `WarningListener`
      Parameters:
        `event` -

    - #### isSeq

          public static boolean isSeq(PyObject object)

      Method isSeq
      Parameters:
        `object` -
      Returns:
        true for any PyList, PyTuple or java.util.List

    - #### hasParams

          public static boolean hasParams(PyObject params)

      Method hasParams
      Parameters:
        `params` -
      Returns:
        boolean

    - #### isSeqSeq

          public static boolean isSeqSeq(PyObject object)

      Method isSeqSeq
      Parameters:
        `object` -
      Returns:
        true is a sequence of sequences

    - #### __enter__

          public PyObject __enter__(ThreadState ts)

      Specified by:
        `__enter__` in interface `ContextManager`

    - #### __enter__

          public PyObject __enter__()

    - #### __exit__

          public boolean __exit__(ThreadState ts,
                                  PyException exception)

      Specified by:
        `__exit__` in interface `ContextManager`

    - #### __exit__

          public boolean __exit__(PyObject type,
                                  PyObject value,
                                  PyObject traceback)

    - #### traverse

          public int traverse(Visitproc visit,
                              java.lang.Object arg)

      Description copied from interface: `Traverseproc`
      Traverses all directly contained `PyObject`s. Like in CPython, `arg` must be passed unmodified to `visit` as its second parameter. If `Visitproc.visit(PyObject, Object)` returns nonzero, this return value must be returned immediately by traverse. `Visitproc.visit(PyObject, Object)` must not be called with a `null` PyObject-argument.
      Specified by:
        `traverse` in interface `Traverseproc`

    - #### refersDirectlyTo

          public boolean refersDirectlyTo(PyObject ob)

      Description copied from interface: `Traverseproc`
      Optional operation. Should only be implemented if it is more efficient than calling `Traverseproc.traverse(Visitproc, Object)` with a visitproc that just watches out for `ob`. Must return `false` if `ob` is `null`.
      Specified by:
        `refersDirectlyTo` in interface `Traverseproc`

Jython homepage