How I Build Geoprocessing Tools: #10 Cursors
Geoprocessing (GP) scripting is object oriented. With GP scripting you create and manipulate objects. These programming objects have methods and properties. Methods are "actions" the objects know how to perform. Properties are values or other-objects an object contains. Often the method of an object will create and return another object that may in turn have its own methods and properties. A graphic object model map shows how these object hierarchies are built and are related one to another.
A cursor is an object whose primary purpose is to provide access to information from within a database. The GP object's cursor methods create row objects in an orderly fashion. Cursors objects are created for the purpose of accessing data and are transient (temporary). Cursors are "programming things" not necessarily GIS or database "things'. Cursor objects are objects created for the sole purpose of giving you access to your data.
A cursor is a placeholder or a type of dynamic bookmark that allows you to manipulate rows in a database. There are three different types of geoprocessing cursors. I included a section of the scripting object model diagram in the last post that highlights the section that deals with the cursor. On that diagram you can see the three cursors and the things they can do (their supported methods).
All of the cursors give you access to a database row which in turn give you access to a collection of fields and their values. The Search Cursor is a read-only access to a data source. While the Update and Insert cursor also allows you to set the value of a field. In ArcGIS feature layers have a geometry field. Later we will be accessing this geometry field to get coordinates and modify them.
The Search Cursor is good for performing your own forms of selection or reporting. Since the cursor is read-only it is a “safe” way to get information out of a database.
The Insert Cursor will add a row to an existing database. Using an Insert Cursor on a new empty table is how you would build a new database or like its namesake insert data into an existing table or feature class.
The Update Cursor changes existing data. This is the most heavy handed of the cursors because it modifies your data. ...But, if you want to edit data this is the way to do it!
I have a choice then on how we want my MOVE tool to function. Do I want to Update the existing feature class and replace each feature with the modified feature so that the input data is changed? Or, do I want to create a tool that uses the information in an existing feature class to build a new feature class with modified coordinates? The answer is based on the confidence you have on your code. If you are confident that you tool is functioning well then what you may want is to change or edit your input. A more conservative position is to create a new feature class from the input. Especially for testing I would suggest a more conservative approach using the Insert Cursor to create a new feature class rather than the Update Cursor. It would be very simple to modify my script afterwards if Iwant to use an Update rather than Insert Cursor.
The Geoprocessing object has three cursor creating methods: the SearchCursor, InsertCursor, and UpdateCursor methods. After creating the GP object like I did in the previous post. I can create a cursor object by using one of these supported methods of the GP object. Fore example:
#Create a geoprocessing Insert Cursor
MyInCursor = GP.InsertCursor(InputTable)
Where MyInCursor is an Insert Cursor object and InputTable is a valid ArcGIS feature layer or table view.