gpf.cursors module¶

This module contains fast and user-friendly alternatives to Esri’s standard cursors. The SearchCursor, InsertCursor and UpdateCursor listed here inherit from Esri’s Data Access cursors, but there are some differences:

SearchCursors return _Row wrappers and have a getValue() function, similar to Esri’s legacy rows;

Insert- and UpdateCursors return _MutableRow wrappers that also have a setValue() function, similar to their legacy predecessors;

The ported getValue() function can return a default value when the field was not found (in the legacy function, it would raise an exception);

The cursors where_clause argument also accepts a gpf.tools.queries.Where instance.

In theory, one should be able to simply replace the legacy Esri cursors (in an old script, for example) with the ones in this module without too much hassle, since all legacy methods have been ported to the cursors in this module. The only thing you might need to replace and verify for compatibility is the initialization of the cursor itself.

Please refer to Esri’s documentation on the legacy cursors for the ported functions and the Data Access classes for cursor initialization and function overrides.

class gpf.cursors.Editor(path: Union[str, gpf.paths.Workspace], with_undo: bool = False)[source]¶

Context manager wrapper for Esri’s Data Access Editor class that opens an edit session on a workspace. This class does not do more than Esri’s Editor class, but it tends to be more user-friendly.

This Editor only has a start() and stop() method. The other available methods (startOperation(), undoOperation() etc.) have been disabled to avoid confusion.

The recommended way of using the Editor is as a context manager (using the with statement). This has the advantage that, upon failure, the edit session is closed automatically (optionally with rollback). If no failures occurred, the edit session is closed normally and all edits are saved (committed). However, one can also instantiate the Editor and call start() and stop() respectively when done.

Params:

path (str, unicode, class:gpf.paths.Workspace):

A path on which to open the edit session. This can be a table or feature class path, a workspace path or a class:gpf.paths.Workspace instance.
with_undo (bool):

If True (default = False), an undo stack will be kept. For versioned workspaces, this setting has no effect (always True). For all other workspaces, having this value set to False improves performance.

Note

The InsertCursor and UpdateCursor in this module use the Editor on demand, if these cursors are initialized with the auto_edit option set to True (default).

start(with_undo: bool = False) → None[source]¶

Starts the edit operation. If the Editor already is in an editing state, this method will do nothing.

Parameters:	with_undo – If set to `True`, the undo/redo stack is enabled. Note that this stack will always be enabled if the workspace is a versioned SDE geodatabase.

stop(save: bool = True) → None[source]¶

Stops the edit operation. If the Editor is not in an editing state, this method will do nothing.

Parameters:	save – If set to `True`, the edits will be saved. If set to `False`, the edits will be rolled back (and not saved) when either (a) the edit session was started with an undo/redo stack, or (b) the workspace is a versioned SDE database. If the undo stack was disabled (default) and save is `False`, the operation will be aborted.

isEditing¶: Returns True if this Editor instance has opened a session

workspacePath¶: Path to edit session’s workspace

class gpf.cursors.SearchCursor(in_table, {field_names}, {where_clause}, {spatial_reference}, {explode_to_points}, {sql_clause})[source]¶

Wrapper class to properly expose ArcPy’s Data Access SearchCursor and its methods. Returns a read-only cursor to iterate over (a set of) records in a table.

If where_clause is used and it’s a Where instance (recommended), the field delimiters will automatically be resolved (e.g. for Oracle, MS SQL, File Geodatabase etc.).

Params:

datatable:

The path to the feature class or table, or a Layer or table view.
field_names:

Single field name or a sequence of field names. When not set, all fields are returned. This is not recommended, as it tends to be slow and consumes more memory.
where_clause (str, unicode, gpf.tools.queries.Where):

An optional expression that filters the returned records.

Keyword params:

spatial_reference (str, int, arcpy.SpatialReference):

An optional SpatialReference object or its string representation or WKID equivalent. The returned features will be reprojected to this coordinate system on the fly.
explode_to_points (bool):

Optional. If True, features are deconstructed into individual vertices. This means that e.g. for a feature with 5 vertices, 5 features will be returned for each vertex.
sql_clause (tuple, list):

An optional sequence of 2 elements, containing a SQL prefix and postfix query respectively. These queries support clauses like GROUP BY, DISTINCT, ORDER BY and so on. The clauses do not support the use of gpf.tools.queries.Where instances.

fields¶: Returns a list of fields (in order) used by the cursor.

reset()[source]¶: Resets the cursor position to the first row so it can be iterated over again.

class gpf.cursors.InsertCursor(in_table, field_names, {auto_edit})[source]¶

Wrapper class to properly expose ArcPy’s Data Access InsertCursor and its methods. Returns a cursor to insert new records into a table.

Params:

datatable:

The path to the feature class or table, or a Layer or table view.
field_names:

Single field name or a sequence of field names. When not set, all fields are returned. This is not recommended, as it tends to be slow and consumes more memory.

Keyword params:

auto_edit (bool):

If set to True (default), an edit session is started automatically, if required.

fields¶: Returns a list of fields (in order) used by the cursor.

newRow(values: Iterable = None) → gpf.cursors._MutableRow[source]¶

Returns a new MutableRow instance (optionally populated with data).

Parameters:	values – Optional `list` or `tuple` of field values in the correct `InsertCursor` field order or a `dict` of key-value pairs, where the keys specify the field names to set.
Raises:	ValueError – If values is a `list` or `tuple` and the length does not match the number of cursor fields, or if values is a `dict` and one of the keys does not match with the cursor field names.

insertRow(row: Iterable) → int[source]¶

Inserts a new row.

Parameters:	row – The row values to insert.
Returns:	The ObjectID of the inserted row (when successful).

class gpf.cursors.UpdateCursor(in_table, {field_names}, {where_clause}, {spatial_reference}, {explode_to_points}, {sql_clause})[source]¶

Wrapper class to properly expose ArcPy’s Data Access UpdateCursor and its methods. Returns a cursor to iterate over and update (a set of) records in a table.

If where_clause is used and it’s a Where instance, the field delimiters will automatically be resolved (e.g. for Oracle, MS SQL, File Geodatabase etc.).

Params:

datatable:

The path to the feature class or table, or a Layer or table view.
field_names:

Single field name or a sequence of field names. When not set, all fields are returned. This is not recommended, as it tends to be slow and consumes more memory.
where_clause (str, unicode, gpf.tools.queries.Where):

An optional expression that filters the returned records.

Keyword params:

spatial_reference (str, int, arcpy.SpatialReference):

An optional SpatialReference object or its string representation or WKID equivalent. The returned features will be reprojected to this coordinate system on the fly.
explode_to_points (bool):

Optional. If True, features are deconstructed into individual vertices. This means that e.g. for a feature with 5 vertices, 5 features will be returned for each vertex.
sql_clause (tuple, list):

An optional sequence of 2 elements, containing a SQL prefix and postfix query respectively. These queries support clauses like GROUP BY, DISTINCT, ORDER BY and so on. The clauses do not support the use of gpf.tools.queries.Where instances.
auto_edit (bool):

If set to True (default), an edit session is started automatically, if required.

fields¶: Returns a list of fields (in order) used by the cursor.

reset()[source]¶: Resets the cursor position to the first row so it can be iterated over again.

deleteRow(dummy=None) → int[source]¶

Deletes the current row. The dummy argument only serves backwards compatibility and is not used.

Returns:	The ObjectID of the deleted row (when successful).

updateRow(row: Iterable) → int[source]¶

Updates the current row.

Parameters:	row – The row values to update.
Returns:	The ObjectID of the updated row (when successful).