GeoEco.Datasets.UpdateCursor

class GeoEco.Datasets.UpdateCursor(dataset, fields, where, orderBy, rowCount, reportProgress, rowDescriptionSingular, rowDescriptionPlural)

Bases: SelectCursor

Base class for forward-only cursors used to read, update, or delete rows in a Table.

Not all Tables support update cursors. To determine if a Table instance supports update cursors, call its TestCapability() method with a capability of 'UpdateCursor'. Some Tables that support update cursors only support updating rows, not deleting them, or visa versa. To check this, test the 'UpdateRow' and 'DeleteRow' capabilities of the Table instance.

This class is not meant to be instantiated directly. Instead call Table.OpenUpdateCursor(). After obtaining a UpdateCursor instance, call NextRow() to advance the cursor to the first row. If NextRow() returns True, use the functions discussed below to read, update, or delete the row. Call NextRow() again to advance to the next row. When NextRow() returns False, no rows remain and the cursor is closed. The cursor is also closed automatically if the UpdateCursor instance is deleted, and you can explicitly close it with Close().

To read values from the row, use GetValue(), GetGeometry(), and GetOID(). To update values, use SetValue() and SetGeometry() and then, after updating all fields of interest, call UpdateRow(). After calling UpdateRow(), do not do anything else with the row, just call NextRow() to go on to the next one. To delete a row, call DeleteRow() and then NextRow().

Certain storage formats may implement a transactional updating scheme in which changes will not be committed to the underlying data store until the cursor has been closed. For more information, please see the documentation for the particular kind of Table you are working with.

The typical pattern for using UpdateCursor looks like this:

with table.OpenUpdateCursor(...) as cursor:
    while cursor.NextRow():
        value = cursor.GetXXXXX(...)
        ...
        if <need to update this row>:
            cursor.SetXXXXX(...)
            ...
            cursor.UpdateRow()
        elif <need to delete this row>:
            cursor.DeleteRow()

Properties

property AtEnd: (bool) If True, no more rows are available (and IsOpen will also be False). If False, more rows may be available. Read only.

property IsOpen: (bool) True if the cursor is open, False if it is closed. Read only.

property RowDescriptionPlural: (str) Word to use in progress and error messages for plural rows. If not supplied when the cursor was opened, an appropriate generic word will be automatically selected based on table’s geometry type, such as “points”, “lines”, “polygons”, and so on. If the table does not have geometry, “rows” will be used. Read only. Minimum length꞉ 1.

property RowDescriptionSingular: (str) Word to use in progress and error messages for a single row. If not supplied when the cursor was opened, an appropriate generic word will be automatically selected based on the table’s geometry type, such as “point”, “line”, “polygon”, and so on. If the table does not have geometry, “row” will be used. Read only. Minimum length꞉ 1.

property Table: (Table) Table the cursor is accessing. Read only.

Methods

`Close`	Closes the cursor.
`DeleteRow`	Deletes the current row.
`GetGeometry`	Retrieves the geometry of the current row.
`GetOID`	Retrieves the ArcGIS "object ID" of the current row.
`GetValue`	Retrieves the value of a field of the current row, given the name of the field.
`NextRow`	Advances the cursor to the next row.
`SetGeometry`	Sets the geometry of the current row.
`SetRowCount`	Sets the number of rows that this cursor is expected to process.
`SetValue`	Sets the value of a field of the current row, given the name of the field and its new value.
`UpdateRow`	Submits any changes made to the current row to the underlying data store.