Editor

Summary

The Editor object allows the use of edit sessions and operations to manage database transactions.

Edits are staged and not committed to the data until triggered. This allows better control if errors occur within an edit operation, or across multiple edit operations.

Discussion

Edit sessions and operations provide the following benefits:

• Group edits into atomic transactions. If an error occurs before all edits are completed, the edits can be discarded and the transaction can be rolled back.
• Optional edit operation undo and redo stacks are maintained by the geodatabase. After an edit operation is stopped, it is placed on the undo stack. The undo and redo stacks can be traversed by calling the undoOperation and redoOperation methods.
• Edit sessions and edit operations allow batched updates to occur, offering significant performance advantages when editing enterprise geodatabases.
• In geodatabases that allow multiple users to edit concurrently, an application in an edit session will not recognize changes made by other applications until the session is complete.

The Editor class can be used to start and stop distinct edit sessions and edit operations for geodatabases and shapefiles.

The startEditing method is used to start an edit session, and the startOperation method is used to start an edit operation. To commit an edit operation, call stopOperation. To cancel an edit operation, call abortOperation. To complete an edit session, call stopEditing, which accepts a Boolean parameter that indicates whether the changes made in the session will be committed or discarded.

Note:

Deviating from this pattern can cause unexpected results. For example, don't call stopEditing while an edit operation is in progress. Instead, cancel the edit operation and stop the edit session.

Edit operations must be controlled within the context of an edit session, and edit operations cannot be nested within other edit operations.

Edit sessions and with statements

Edit sessions and operations can also be used with with statements. The with statements act as context managers and handle the appropriate start, stop, and abort calls. The example below highlights the basic structure of the Editor class used with with statements.

import arcpy

# Open an edit session and start an edit operation
with arcpy.da.Editor(workspace):
    print('<your edits go here>')

    # If an exception is raised, the operation is cancelled, and the edit
    # session is closed without saving.

    # If no exceptions are raised, the operation stops, is saved, and the edit
    # session closes.

Use the undo and redo stacks

The undo and redo stacks are enabled or disabled for an edit session depending on the Boolean parameter of the startEditing method. If an edit session will contain multiple operations that may be conditionally rolled back (and redone), enable the undo and redo stacks. If not—for example, if the edit session will only contain a single operation—you can disable the undo and redo stacks for performance benefits by setting the parameter to False.

Note:

When starting a versioned edit session in an enterprise geodatabase, the undo and redo stacks are enabled. Nonversioned edit sessions do not support undo and redo operations.

The two methods that control the undo and redo stacks are undoOperation and redoOperation. The undoOperation rolls back the state of the edit session to the last edit operation and moves the edit operation onto the redo stack. The redoOperation method moves an edit operation from the top of the redo stack back onto the undo stack and rolls the state of the edit session forward to what it was after the edit operation. When an edit operation is committed, the redo stack is cleared, making it impossible to redo any operations that may have been on the redo stack.

Situations that require an edit session

The following includes some dataset types that can only be edited within an edit session:

• Feature classes participating in a topology
• Feature classes participating in a geometric network
• Feature classes participating in a network dataset
• Versioned datasets in enterprise geodatabases
• Some object and feature classes with class extensions

Edit sessions and cursors

Cursors should be scoped to a single edit operation. This means a new cursor should be instantiated and released for each operation. This is important when editing rows returned by a cursor, because the rows are tied to a specific state of the geodatabase. Avoid using a cursor across multiple edit operations, as doing so can result in unexpected behavior and data loss.

Edit sessions and versioned data

Enterprise geodatabase tables and feature classes may be versioned. The isVersioned property can be used to determine whether a table or feature class is versioned.

When editing enterprise geodatabase tables and feature classes, the edit session mode should be set according to the type of data being edited as follows:

• When editing a nonversioned table or feature class, set the multiuser_mode argument to False.
• When editing a versioned table or feature class, set the multiuser_mode argument to True.

Use either the Editor class's multiuser_mode argument or the Editor class's startEditing method's multiuser_mode argument to set the multiuser mode.

When the multiuser mode is not set correctly, you may receive an error that objects in this class cannot be updated outside an edit session.

Syntax

Editor (workspace, {multiuser_mode}, {version})

Parameter	Explanation	Data Type
workspace	The path to the workspace to edit. The editor can edit only one workspace at a time. The following are valid inputs: The path to a workspace, for example: r"c:\myProj\f.gdb" or r"c:\myProj\db.sde". An arcpy.Describe object. This can be the result of describing a workspace, or the workspace property returned by describing a layer, table, or feature class, for example: arcpy.Describe(fc).workspace. An arcpy.mp.Layer object. Note: If the value provided has an associated version, the edit session will use that version. This can be overridden with the version argument.	Object
multiuser_mode	Specifies how edits will be applied to the data source when editing an enterprise geodatabase. For any other data source, including a feature service with version management enabled, this parameter will be ignored. To allow editing on versioned data, set this parameter to True. Nonversioned data can be edited with the parameter set to either True or False. When this parameter is set to True, the following will occur: For versioned data, the undoOperation and redoOperation methods are supported, as well as saving or discarding the edit session. For nonversioned data (for example, nonversioned archived or unversioned) the edits created in the edit session can be saved or discarded. Neither the undoOperation or redoOperation methods are supported with nonversioned data. When this parameter is set to False, the following will occur: For versioned data, an error will occur when attempting to edit. For nonversioned data, edits will be committed when stopEditing(True) or rolled back when stopEditing(False). (The default value is True)	Boolean
version	The workspace's version that will be associated with the edit session. This parameter overrides the version associated with the value set using the workspace parameter. When the workspace does not have a version that matches the name provided, a RuntimeError exception will be raised.	String

Properties

Property	Explanation	Data Type
isEditing (Read Only)	Specifies whether the Editor object is in an edit session.	Boolean
version (Read Only)	For a workspace that support versioning, this is the name of the workspace version that is associated with the object. The property value will be None when it is not applicable.	String
workspacePath (Read Only)	The path to the workspace associated with the object.	String

Method Overview

Method	Explanation
__enter__ ()	Starts an edit session.
__exit__ ()	If successful, the Editor object stops editing and saves the edit session. If an exception occurs, editing is stopped but not saved.
startEditing ({with_undo}, {multiuser_mode})	Starts an edit session.
stopEditing ({save_changes})	Stops an edit session.
startOperation ()	Starts an edit operation.
stopOperation ()	Stops an edit operation.
abortOperation ()	Aborts an edit operation.
undoOperation ()	Undoes an edit operation (rolls back modifications).
redoOperation ()	Redoes an edit operation.

Methods

__enter__ ()

__exit__ ()

startEditing ({with_undo}, {multiuser_mode})

Parameter	Explanation	Data Type
with_undo	Specifies whether the undo and redo stacks will be enabled or disabled for an edit session. If an edit session will contain multiple operations that might be conditionally rolled back (and redone), enable the undo and redo stacks by setting this argument to True. If not—for example, if the edit session will only contain a single operation—the undo and redo stacks can be disabled for performance benefits by setting this argument to False. When starting a versioned edit session in an enterprise geodatabase, the undo and redo stacks will always be enabled. Nonversioned edit sessions do not support undo and redo operations. (The default value is True)	Boolean
multiuser_mode	Specifies whether multiuser mode is enabled. When set to False, you have full control of editing a nonversioned or versioned dataset. If the dataset is nonversioned and you use stopEditing(False), the edits will not be committed (if set to True, the edits will be committed). (The default value is True)	Boolean

stopEditing ({save_changes})

Parameter	Explanation	Data Type
save_changes	Specifies whether the edits will be saved or discarded. (The default value is True)	Boolean

startOperation ()

stopOperation ()

abortOperation ()

undoOperation ()

redoOperation ()

Code sample

Editor example 1

The following code uses a with statement that starts an edit operation and uses the CalculateField function on a selected set of rows in a table. Any tool errors that occur will be handled and printed.

Since the CalculateField function is performed inside a with statement, if any exceptions occur, changes will not be saved. If CalculateField completes successfully, updates will be saved.

import arcpy

fc = 'C:/Portland/Portland.gdb/Land/Parks'
workspace = 'C:/Portland/Portland.gdb'
layer_name = 'Parks'

arcpy.management.MakeFeatureLayer(fc, layer_name)
arcpy.management.SelectLayerByAttribute(
    layer_name, 'NEW_SELECTION',
    """CUSTODIAN = 'City of Portland'""")

with arcpy.da.Editor(workspace):
    arcpy.management.CalculateField(layer_name, 'Usage', '"PUBLIC"', 'PYTHON')

Editor example 2

The following is an example of starting an edit session and an edit operation, creating a row in a table, and stopping the edit operation and committing the edit session.

import arcpy
import os

fc = 'C:/projects/Portland/Portland.sde/portland.jgp.schools'
workspace = os.path.dirname(fc)

# Start an edit session. Must provide the workspace.
edit = arcpy.da.Editor(workspace)

# Edit session is started without an undo/redo stack for versioned data

# Set multiuser_mode to False if working with unversioned enterprise gdb data
edit.startEditing(with_undo=False, multiuser_mode=True)

# Start an edit operation
edit.startOperation()

# Insert a row into the table.
with arcpy.da.InsertCursor(fc, ('SHAPE@', 'Name')) as icur:
    icur.insertRow([(7642471.100, 686465.725), 'New School'])

# Stop the edit operation.
edit.stopOperation()

# Stop the edit session and save the changes
edit.stopEditing(save_changes=True)

Editor example 3

The following is an example of using the Editor class as a context manager with versioned data.

import arcpy
import os

new_students = 'C:/projects/Portland/Portland.sde/ptld.main.students_new2022'
students = 'C:/projects/Portland/Portland.sde/ptld.main.students'

workspace = arcpy.Describe(students).workspace

# Start an edit session. Provide the workspace being acted on
# and with sde specify if data is edited in multiuser_mode.
with arcpy.da.Editor(workspace, multiuser_mode=True):

    # If all 3 edit operations run successfully without error
    # upon exiting this code block the edits will be applied to the data

    arcpy.management.CalculateField(new_students , 'arrived', '2022')
    arcpy.management.Append(new_students, students)
    arcpy.management.CalculateField(students, "active", True)

Editor example 4

The following shows the recommended pattern of using the Editor class in a script tool.

import arcpy

# arcpy.GetParameter(0) could be a feature class or layer in a map.
# If the dataset's workspace is versioned, the editor will use the same version
in_features = arcpy.GetParameter(0)
workspace = arcpy.Describe(in_features).workspace

with arcpy.da.Editor(workspace):
    # Perform edit operations here.
    print('Perform edit operations here')