Editor (arcpy.da)

Summary

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

Edits are temporary until saved and permanently applied to your data. You can also quit an edit session without saving your changes.

Discussion

Edit sessions and operations provide the following benefits:

• Grouping edits into atomic. If an error occurs before all edits are completed, the transaction can be rolled back.
• Optional edit operation undo and redo stacks maintained by the geodatabase. After an edit operation is stopped, it is placed on the undo stack. The undo/redo stack 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 ArcSDE 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 edit sessions and edit operations for file, personal, and ArcSDE geodatabases and shapefiles. The Editor class can be used to start an edit session with versioned or nonversioned datasets.

Before starting an edit session, make sure that all of the datasets to be edited have been opened.

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 within the session should be committed or discarded.

Note:

Deviating from this pattern can cause unexpected results. For example, stopEditing should not be called while an edit operation is in progress. Instead, abort the edit operation, then 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 Python with statements. The with statements act as context managers and handle the appropriate start, stop, and abort calls for you. 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) as edit:
    # <your edits>

    # If an exception is raised, the operation will be aborted, and 
    #   edit session is closed without saving

    # If no exceptions are raised, stop the operation and save 
    #   and close the edit session

Using 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 is going to contain multiple operations that might be conditionally rolled back (and redone), the undo and redo stacks should be enabled. 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 the parameter to False.

Note:

When starting a versioned edit session in ArcSDE, the undo and redo stacks will always be 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 execution of the edit operation. When an edit operation is committed, the redo stack is cleared, making it impossible to redo any operations that might have been on the redo stack.

Situations requiring edit sessions

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
• Versioned datasets in ArcSDE 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 very 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. Doing so can result in unexpected behavior and data loss.

Syntax

Editor (workspace)

Parameter	Explanation	Data Type
workspace	Path to the workspace to edit. Editor can edit only one workspace at a time.	String

Method Overview

Method	Explanation
__enter__ ()	Starts an edit session.
__exit__ ()	If successful, stops editing and saves an edit session. If an exception, stops editing and doesn't save.
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 ()	Undo an edit operation (roll back modifications).
redoOperation ()	Redoes an edit operation.

Methods

__enter__ ()

__exit__ ()

startEditing ({with_undo}, {multiuser_mode})

Parameter	Explanation	Data Type
with_undo	Sets whether the undo and redo stacks are enabled or disabled for an edit session. If an edit session will contain multiple operations that might be conditionally rolled back (and redone), the undo and redo stacks should be enabled. 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 the argument to false. When starting a versioned edit session in ArcSDE, 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	When False, you have full control of editing a nonversioned, or versioned dataset. If your dataset is nonversioned and you use stopEditing(False), your edit will not be committed (otherwise, if set to True, your edits will be committed). (The default value is True)	Boolean

stopEditing (save_changes)

Parameter	Explanation	Data Type
save_changes	True to save changes; False to discard changes. (The default value is True)	Boolean

startOperation ()

stopOperation ()

abortOperation ()

undoOperation ()

redoOperation ()

Code Sample

Editor example 1

The following code uses a with statement which starts an edit operation and performs Calculate Field on a selected set of rows in a table. Any tools errors that occur will be handled and printed.

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

import arcpy

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

try:
    arcpy.MakeFeatureLayer_management(fc, layer_name)
    arcpy.SelectLayerByAttribute_management(
        layer_name, 'NEW_SELECTION',
        """CUSTODIAN = 'City of Portland'""")
    with arcpy.da.Editor(workspace) as edit:
        arcpy.CalculateField_management(
            layer_name, 'Usage', '"PUBLIC"', 'PYTHON')

except arcpy.ExecuteError:
    print(arcpy.GetMessages(2))

Editor example 2

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

import arcpy
import os

fc = 'Database Connections/Portland.sde/portland.jgp.schools'
workspace = os.path.dirname(fc)

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

# Edit session is started without an undo/redo stack for versioned data
#  (for second argument, use False for unversioned data)
edit.startEditing(False, 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(True)