Jun 16, 2011 ... ESRI has fully embraced Python for ArcGIS and sees Python as the language
that ... Python Tutorial is part of Python's own documentation.
What is Python? Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python
Python is a free, cross-platform, open-source programming language that is both powerful and easy to learn. It is widely used and supported. To learn more about Python, visit python.org. Python was introduced to the ArcGIS community at 9.0. Since then, it has been accepted as the scripting language of choice for geoprocessing users and continues to grow. Each release has furthered the Python experience, providing you with more capabilities and a richer, more Python-friendly experience. ESRI has fully embraced Python for ArcGIS and sees Python as the language that fulfills the needs of our user community. Here are just some of the advantages of Python:
Easy to learn and excellent for beginners, yet superb for experts
Highly scalable, suitable for large projects or small one-off programs known as scripts
Portable, cross-platform
Embeddable (making ArcGIS scriptable)
Stable and mature
A large user community
Python extends across ArcGIS and becomes the language for data analysis, data conversion, data management, and map automation, helping increase productivity.
Learning Python The information contained here is not a Python language reference. Certain Python syntax and behavior are explained with respect to examples and concepts used to demonstrate how to write a geoprocessing script. A suitable Python reference book is strongly recommended to augment the information you find here. For Python beginners, Learning Python by Mark Lutz and David Ascher, published by O’Reilly & Associates, and Core Python Programming by Wesley J. Chun, published by Prentice Hall, are both good introductions to the language and are not overwhelming in scope. There are many other books on Python and its particular uses, with new ones being released regularly, so explore what is available. The Python Web site has full documentation for Python, but it is concise and developer oriented. There is a large online Python community with many online resources that are accessible from the Python home page.
Python tutorials If you're new to Python, the external tutorials listed here are recommended for you.
Python Tutorial is part of Python's own documentation. Python for Non-Programmers provides tutorials for those with limited programming experience. Python Language Reference describes the syntax and semantics of Python.
Python tutorials for programmers
The external tutorials listed here are aimed at those who have previous experience with other programming languages (Perl, Visual Basic, C).
Python Tutorial is part of Python's own documentation. Python for Programmers provides tutorials for those with experience in other programming languages.
Related Topics A quick tour of Python Essential Python vocabulary What is ArcPy? What is the Python window?
Essential Python vocabulary Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python
This document introduces some vocabulary that is essential to understanding the Geoprocessing with Python help. Term
Description
Python
Python is an open-source programming language that was conceived in the late 1980s by Guido van Rossum, and introduced in 1991. It was first incorporated with ArcGIS 9.0 and has since become the preferred choice for users creating geoprocessing workflows. Python is supported by a growing and varied user community and provides easy readability, clean syntax, dynamic typing, and an extensive collection of standard and third-party libraries.
PythonWin
PythonWin is a widely used third-party Windows interface for Python and is available for installation on the ArcGIS installation media.
ArcPy
ArcGIS 10 introduces ArcPy (often referred to as the ArcPy site-package), which provides Python access for all geoprocessing tools, including extensions, as well as a wide variety of useful functions and classes for working with and interrogating GIS data. A site-package is Python's term for a library that adds additional functions to Python. Using Python and ArcPy, you can develop an infinite number of useful programs that operate on geographic data.
ArcPy
A module is a python file that generally includes functions and classes. ArcPy is
modules
supported by a series of modules, including a mapping module (arcpy.mapping), a Spatial Analyst module (arcpy.sa), and a Geostatistical Analyst module (arcpy.ga).
ArcPy classes
A class is analogous to an architectural blueprint. The blueprint provides the framework for how to create something. Classes can be used to create objects, often referred to as an instance. ArcPy classes, such as the SpatialReference and Extent classes, are often used as shortcuts to complete geoprocessing tool parameters that would otherwise have a more complicated string equivalent.
ArcPy
A function is a defined bit of functionality that does a specific task and can be
functions
incorporated into a larger program. In ArcPy all geoprocessing tools are provided as functions, but not all functions are geoprocessing tools. In addition to tools, ArcPy provides a number of functions to better support geoprocessing Python workflows. Functions or methods can be used to list certain datasets, retrieve a dataset's properties, validate a table name before adding it to a geodatabase, or perform many other useful scripting tasks.
Stand-alone
A Python script is a .py file that can be executed. A stand-alone Python script is a
Python script
.py file that can be executed from the operating system prompt or a development application like PythonWin or by double-clicking the .py in a Windows Explorer.
Python script
A Python script tool is a Python script that has been added to a geoprocessing
tool
toolbox. Once added as a script tool, the script tool becomes like any other geoprocessing tool—it can be opened and executed from the tool dialog box, used in the Python window and ModelBuilder, and called from other scripts and script tools.
Python
ArcGIS 10 introduces a new embedded Python experience. The geoprocessing
window
command line from past releases has been re-invented as a fully interactive Python window. This is a quick and convenient place to use Python from within ArcGIS to interactively run geoprocessing tools and functionality as well as take advantage of other Python modules and libraries. This window also provides a gateway for users to learn Python. The Python window can be used to execute a single line of Python code, with the resulting messages printed to the window. It is a useful place to experiment with syntax and work with short lengths of code and provides an opportunity to test your ideas outside a larger script.
A quick tour of Python Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python
Python is an open-source, general-purpose programming language used as a scripting language in ArcGIS geoprocessing. Geoprocessing functionality is accessible through Python using ArcGIS software's ArcPy site-package. ArcPy provides access to geoprocessing tools as well as additional functions, classes, and modules that allow you to create simple or complex workflows quickly and easily.
ArcGIS applications and scripts written using ArcPy benefit from being able to access and work with the numerous Python modules developed by GIS professionals and programmers from many different disciplines. The additional power of using ArcPy within Python is the fact that Python is a generalpurpose programming language that is easy to learn and use. It is interpreted and dynamically typed, which provides you with the ability to quickly prototype and test scripts in an interactive environment while still being powerful enough to support the writing of large applications. Broadly speaking, ArcPy is organized in tools, environments, functions, classes, and modules.
Running a tool This next example shows how to execute the Buffer tool. As the tool executes, the messages will appear by default on the right side of the Python window in the help section.
>>> arcpy.Buffer_analysis("c:/data/Portland.gdb/streets", "c:/data/Portland.gdb/steets_buffer", "500 METERS")
Here is another example of running tools. This example uses tools in the data management and conversion toolboxes. A field is added to the input streets feature class, the field is calculated, and the feature class is then loaded into an ArcSDE enterprise geodatabase.
>>> import arcpy >>> arcpy.AddField_management("c:/data/Portland.gdb/streets", "LENGTH_MILES", "TEXT") >>> arcpy.CalculateField_management("c:/data/Portland.gdb/streets", "LENGTH_MILES", "!shape.length@miles!", "PYTHON_9.3") >>> arcpy.FeatureClassToFeatureClass_conversion("c:/data/Portland.gdb/streets", "Database Connections/MySDE.sde/PortlandDataset", "streets") Learn more about using tools in Python
Getting results from a tool When a geoprocessing tool is executed, the results of the tool are returned in a result object. Typically, this object is the path to the output dataset produced or updated by the tool. In other cases, it may contain other value types, such as a number or Boolean. If an output for a tool is a multivalue parameter, the values can be returned as a list within a list. The following code examples show how return values are captured and what their values could be: Return the path of the output feature class. The result can be used as input to another function.
>>> result = arcpy.Buffer_analysis("rivers", "riverBuf", "50 METERS") >>> print result C:\Portland\Portland_OR.gdb\riverBuf >>> arcpy.Clip_analysis("streets", result, "streets_50m_of_rivers")
Return the number of features.
>>> result = arcpy.GetCount_management("streets_50m_of_rivers") >>> print result.getOutput(0) 54
Return a list of default spatial grid indexes for a feature class.
>>> result = arcpy.CalculateDefaultGridIndex_management("streets_50m_of_rivers") >>> for i in range(0, result.outputCount): ... print result.getOutput(i) ... 560 200 0
Using environment settings Geoprocessing environment settings can be thought of as additional parameters that affect a tool's results. They differ from normal tool parameters in that they are set separately from the tool and are interrogated and used by tools when they are run. Environment settings such as an area of interest, the coordinate system of the output dataset, and the cell size of a new raster dataset can all be specified and honored by the tools. Environment settings are available from the env class as properties. These properties can be used to retrieve the current environment values and set them. Below are examples of how to use environment values: Set the workspace environment.
>>> arcpy.env.workspace = "c:/data/Portland.gdb" >>> arcpy.Buffer_analysis("streets", "streetBuf", "500 METERS")
Set the spatial grid index to the return value of a tool.
>>> arcpy.env.spatialGrid1 = arcpy.CalculateDefaultSpatialGridIndex_management("streets").getOutput(0)
Get the current raster cell size setting and make sure it is a specific size for standard output.
if arcpy.env.cellSize != 30: arcpy.env.cellSize = 30 Learn more about using environment settings in Python
Using functions
A function is a defined bit of functionality that does a specific task and can be incorporated into a larger program. In addition to tools, ArcPy exposes a number of functions to better support geoprocessing workflows. Functions can be used to list certain datasets, retrieve a dataset's properties, check for existence of data, validate a table name before adding it to a geodatabase, or perform many other useful scripting tasks. The example code below shows getting the properties of data and checking out an extension:
import arcpy # prints True print arcpy.Exists("c:/data/Portland.gdb/streets") # prints NAD_1983_StatePlane_Oregon_North_FIPS_3601_Feet sr = arcpy.Describe("c:/data/Portland.gdb/streets").spatialReference print sr.name # prints Available print arcpy.CheckExtension("spatial") arcpy.CheckOutExtension("spatial") Learn more about using functions in Python
Using classes ArcPy classes, such as the SpatialReference and Extent classes, are often used as shortcuts to complete geoprocessing tool parameters that would otherwise have a more complicated string equivalent. A class is analogous to an architectural blueprint. The blueprint provides the framework for how to create something. Classes can be used to create objects; this is often referred to as an instance.
import arcpy prjFile = "c:/projections/North America Equidistant Conic.prj" spatialRef = arcpy.SpatialReference(prjFile) Learn more about using classes in Python
Working with modules ArcPy includes modules covering other areas of ArcGIS. ArcPy is supported by a series of modules, including a mapping module (arcpy.mapping), a Spatial Analyst module (arcpy.sa), and a Geostatistical Analyst module (arcpy.ga). For example, the tools of the arcpy.sa module use tools in the Spatial Analyst toolbox but are configured to support Map Algebra. Thus, executing arcpy.sa.Slope is the same as executing the Slope tool from the Spatial Analyst toolbox.
Related Topics Essential Python vocabulary What is Python?
Copyright © 1995-2011 Esri. All rights reserved. 6/16/2011
Importing ArcPy Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Accessing tools
ArcGIS 10 introduces ArcPy, a Python site package that encompasses and further enhances the arcgisscripting module introduced at ArcGIS 9.2. ArcPy provides a rich and dynamic environment for developing Python scripts while offering code completion and integrated documentation for each function, module, and class. ArcGIS applications and scripts written using ArcPy benefit from being able to access and work with the numerous Python modules developed by GIS professionals and programmers from many different disciplines. The additional power of using ArcPy within Python is the fact that Python is a general purpose programming language that is easy to learn and use. It is interpreted and dynamically typed, which provides you with the ability to quickly prototype and test scripts in an interactive environment while still being powerful enough to support the writing of large applications.
# Importing arcpy # import arcpy # Set the workspace environment and run Clip_analysis arcpy.env.workspace = "C:/Data/Tongass" arcpy.Clip_analysis("standb4", "clipcov", "standby_clip", "1.25")
Once you have imported ArcPy, you can run all geoprocessing tools found in the standard toolboxes installed with ArcGIS: Analysis toolboxCartography toolboxConversion toolboxData Management toolboxEditing toolboxGeocoding toolboxLinear Referencing toolboxMultidimension toolboxSpatial Statistics toolbox
Importing modules A module is a python file that generally includes functions and classes. ArcPy is supported by a series of modules, including a mapping module (arcpy.mapping), a Spatial Analyst module (arcpy.sa), and a Geostatistical Analyst module (arcpy.ga). To import an entire module, use the import module:
# Import all of arcpy #
import arcpy.mapping
Of course, Python has many other core and third-party modules. If you wanted to also work with Python's core os and sys modules, you might use a similar import:
# Import arcpy, os and sys # import arcpy import os import sys
In many cases, you might not plan or need to use the entire module. One way to import only a portion of a module is to use a from-import statement. The below example imports the env class (the env class contains all the geoprocessing environments). Now instead of having to access environments as arcpy.env, you can simplify it as env.
# Import env from arcpy and set the workspace environment # from arcpy import env env.workspace = "c:/data"
Following the same thought process, sometimes you might want to draw attention to what a module or part of a module is identified as to make your script more readable, or perhaps the default name is just too long for your preferences. In any of these cases, you can use the form from-import-as. Like the previous example, the below example also imports the env class but assigns it the name ENV:
# Import env from arcpy as ENV and set the workspace environment # from arcpy import env as ENV ENV.workspace = "c:/data"
You could import the mapping module in the same fashion:
# Import the mapping module from arcpy as MAP and create a MapDocument # object # from arcpy import mapping as MAP mxd = MAP.MapDocument("C:/maps/basemap.mxd")
Another version of importing is the form from-import-*. The contents of the module are imported directly into the namespace, meaning you can then use all those contents directly without needing to prefix them. For example:
# Import management from arcpy as *
# from arcpy.management import *
However, there are some risks associated with this approach. Other objects, variables, modules, and so forth, with the same name will be overwritten, not to mention that with large modules, your namespace can become particularly crowded and busy. Think about it this way: In the following example, both the management and analysis module are being imported as *. Both of these modules have a Clip tool. If you now try to use Clip, which Clip are you actually using? The answer is the second one, but this approach can lead to uncertainty and difficulty in reading the script.
# Import the management and analysis modules from arcpy as * # from arcpy.management import * from arcpy.analysis import * # Which Clip is it? # Clip("standb4", "clipcov", "standby_clip", "1.25")
However, in some cases, from-import-* can simplify your code, as in the case of the ArcGIS Spatial Analyst extension's sa module. One of the benefits of the sa module is that you can nest multiple classes and functions in a single line to produce an output raster object. License: Both of the following samples require the Spatial Analyst extension to run.
# Import arcpy and the sa module as * # import arcpy from arcpy.sa import * arcpy.CheckOutExtension("spatial") # Get input # inRaster1 = inRaster2 = inRaster3 =
parameters arcpy.GetParameterAsText(0) arcpy.GetParameterAsText(1) arcpy.GetParameterAsText(2)
outRaster = (Raster(inRaster1) + (Raster(inRaster2) - Raster(inRaster3)))
Now compare the next code block, which uses the conventional import-from statement. Now imagine adding a few more classes and functions into the code—the simple addition of sa. for every function and class adds up quickly, disrupting the readability and adding more bulk to the line.
# Import arcpy and the sa module #
import arcpy from arcpy import sa arcpy.CheckOutExtension("spatial") # Get input # inRaster1 = inRaster2 = inRaster3 =
parameters arcpy.GetParameterAsText(0) arcpy.GetParameterAsText(1) arcpy.GetParameterAsText(2)
outRaster = (sa.Raster(inRaster1) + (sa.Raster(inRaster2) sa.Raster(inRaster3)))
Paths and import When using an import statement, Python looks for a module matching that name in the following locations (and in the following order): 1. Paths specified in the PYTHONPATH system environment variable 2. A set of standard Python folders (the current folder, c:\python2x\lib, c:\python2x\Lib\site-packages, and so on) 3. Paths specified inside any .pth file found in 1 and 2 For more information on this, see the following: http://docs.python.org/install/index.html#modifying-python-s-search-path. The installation of ArcGIS 10.0 products will install Python 2.6 if it isn't already installed. The installation will also add the file Desktop10.pth (or Engine10.pth or Server10.pth) into python26\Lib\site-packages. The contents of this file are two lines containing the path to your system's ArcGIS installation's arcpy and bin folders. These two paths are required to import ArcPy successfully in Python version 2.6. When using an import statement, Python refers to your system's PYTHONPATH environment variable to locate module files. This variable is set to a list of directories. Tip: If importing ArcPy produces either of the following errors, the required modules could not be found:
ImportError: No module named arcpy
ImportError: No module named arcgisscripting
To address this, browse using Windows Explorer to the python26\Lib\site-packages folder and add or edit the Desktop10.pth file. The file should contain the two lines shown below (corrected to your system's path if they do not match):
c:\Program Files\ArcGIS\Desktop10.0\arcpy
c:\Program Files\ArcGIS\Desktop10.0\bin
Adding toolboxes in Python Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Accessing tools
Python is initially only aware of tools stored in ArcGIS system toolboxes like the Data Management Tools, Conversion Tools, and Analysis Tools toolboxes. Custom tools created by an individual, third party, or organization and stored in a custom toolbox can be accessed in the Python window like any system tool by importing the custom toolbox into the ArcPy site package. In the following example, the ImportToolbox function is used to allow tools contained in a custom toolbox to be accessed in Python. After importing the toolbox, the custom tools can be accessed as arcpy._.
>>> arcpy.ImportToolbox("c:/mytools/geometrytools.tbx") >>> arcpy.CreateRegularPolygons_geometry(
When a tool is accessed through the ArcPy site package, the toolbox alias where the tool is contained is a required suffix (arcpy._). Since ArcPy depends on toolbox aliases to access and execute the correct tool, aliases are extremely important when importing custom toolboxes. A good practice is to always define a custom toolbox's alias. However, if the toolbox alias is not defined, a temporary alias can be set as the second parameter of the ImportToolbox function.
>>> arcpy.ImportToolbox("c:/mytools/geometrytools.tbx", "mytools") >>> arcpy.CreateRegularPolygons_mytools(
Adding and removing server toolboxes Geoprocessing services can also be added to the scripting environment using ImportToolbox. Whether adding the geoprocessing service from a local or Internet server, the server and toolbox name are semicolon delimited. Learn more about geoprocessing services Sample syntax for adding a geoprocessing service
# Import a geoprocessing service # import arcpy # To add a toolbox from a Internet server, provide the url and toolbox name # delimited by a semi-colon #
arcpy.ImportToolbox("http://lab13/arcgis/services;BufferByVal")
Sample syntax for adding a local geoprocessing service
# Import a local geoprocessing service # import arcpy # To add a toolbox from a local server, provide the server and toolbox name # delimited by a semi-colon # arcpy.ImportToolbox("lab13;BufferByVal")
Related Topics Using tools in Python Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Accessing tools
Every geoprocessing tool has a fixed set of parameters that provide the tool with the information it needs for execution. Tools usually have input parameters that define the dataset or datasets that are typically used to generate new output data. Parameters have several important properties: Name
Each tool parameter has a unique name.
Type
The type of data expected, such as feature class, integer, string, and raster.
Direction
The parameter defines either input or output values.
Required
Either a value must be provided for a parameter or it is optional.
When a tool is used in a script, its parameter values must be correctly set so it can execute when the script is run. The documentation of each tool clearly defines its parameters and properties. Once a valid set of parameter values is provided, the tool is ready to be executed. Parameters are specified as either strings or objects. Strings are simply text that uniquely identifies a parameter value, such as a path to a dataset or a keyword. Most tool parameters can be specified as a simple string. For some parameters, such as a spatial reference, you can use an object instead of a string. In the following code example, input and output parameters are defined for the Buffer tool. Note that the tool name is always appended with its toolbox alias. In the example, two string variables are used to define the input and output parameters to make the call to the tool easier to read.
import arcpy roads = "c:/St_Johns/data.gdb/roads" output = "c:/St_Johns/data.gdb/roads_Buffer"
# Run Buffer using the variables set above and pass the remaining parameters # in as strings # arcpy.Buffer_analysis(roads, output, "distance", "FULL", "ROUND", "NONE")
In the following code example, the CreateFeatureClass tool is executed using a spatial reference object for its optional Coordinate System parameter. The spatial reference object is created using the SpatialReference class, and its information is loaded from a projection file.
import arcpy inputWorkspace = "c:/temp" outputName = "rivers.shp" # Create a spatial reference object # spatialRef = arcpy.SpatialReference() # Use a projection file to define the spatial reference's properties # spatialRef.createFromFile("c:/program files/arcgis/Desktop10.0/Coordinate Systems/" + \ "Projected Coordinate Systems/Continental/North America/North America Equidistant Conic.prj") # Run CreateFeatureclass using the spatial reference object # arcpy.CreateFeatureclass_management(inputWorkspace, outputName, "POLYLINE", "", "", "", spatialRef)
Tool organization Geoprocessing tools are organized in two different ways. All tools are available as functions on ArcPy but are also available in modules matching the toolbox alias name. Although most of the examples in the help show tools organized as functions available from ArcPy, both approaches are equally valid. Which approach you use will come down to a matter of personal preference and coding habits. In the following example, the GetCount tool is shown using both approaches.
import arcpy inFeatures = "c:/temp/rivers.shp" # Tools can be accessed as functions on the arcpy module, and # from modules matching the toolbox name. # arcpy.GetCount_management(inFeatures)
arcpy.management.GetCount(inFeatures)
When using tools in modules, sometimes you may want to draw attention to how a module is identified to make your script more readable. In this case, you can use the form from - import as.
# Clean up street centerlines that were digitized without having set # proper snapping environments # import arcpy from arcpy import edit as EDIT from arcpy import management as DM streets = "c:/data/streets.gdb/majorrds" streetsCopy = "c:/output/Output.gdb/streetsBackup" DM.CopyFeatures(streets, streetsBackup) EDIT.TrimLine(streets, "10 Feet", "KEEP_SHORT") EDIT.ExtendLine(streets, "15 Feet", "EXTENSION") License: Spatial Analyst tools are handled differently to accommodate Map Algebra and are available only in the arcpy.sa module and not as functions on ArcPy.
Getting results from a tool ArcPy returns the output values of a tool when it is executed as a Result object. The advantage of a result object is that you can maintain information about the execution of tools, including messages, parameters, and output. These results can be maintained even after several other tools have been run. The following examples show how to get the output from a result object following the execution of a geoprocessing tool.
import arcpy arcpy.env.workspace = "D:/St_Johns/data.gdb" # Geoprocessing tools return a result object of the derived # output dataset. # result = arcpy.CopyFeatures_management("roads", "urban_roads") # A print statement will display the string # representation of the output. # print result
# To get the output value, the result object has a getOutput method # resultValue = result.getOutput(0)
Note: The result object's getOutput method returns a Unicode string from result objects that have output values. This is an important consideration when running a tool such as GetCount, which provides a count of records in a table, or CalculateDefaultClusterTolerance, which provides a cluster tolerance value. To convert the value to the expected type, it will have to be converted from a unicode string using built-in Python functions such as int() or float().
import arcpy from arcpy import env import types env.workspace = "c:/St_Johns/data.gdb" # Many geoprocessing tools return a result object of the derived # output dataset. A print statement will display the string # representation of the output. # result = arcpy.GetCount_management("roads") resultValue = result.getOutput(0) # The result object's getOutput method returns values as a # unicode string. To convert to a different Python type, use # built-in Python functions: str(), int(), long(), float() # count = int(resultValue) print count print types.TypeType(count)
Result properties and methods Properties and methods
Explanation
inputCount
Returns the number of inputs.
outputCount
Returns the number of outputs.
messageCount
Returns the number of messages.
maxSeverity
Returns the maximum severity. The returned severity can be 0 (no errors/warnings raised), 1 (warnings raised), or 2 (errors raised).
resultID
Returns the unique result ID. If the tool is not a geoprocessing service, the resultID will be "".
status
Returns the status of the job on the server.
0—New
1—Submitted
2—Waiting
3—Executing
4—Succeeded
5—Failed
6—Timed Out
7—Canceling
8—Canceled
9—Deleting
10—Deleted
cancel()
Cancels the job on the server.
getInput(index)
Returns a given input. If a record set or raster data object, a RecordSet or RasterData object is returned.
getMapImageURL(ParameterList,
Get map service image for a given output.
Height, Width, Resolution) getMessage(index)
Returns a specific message.
getMessages(severity)
The type of messages to be returned. 0=message, 1=warning, 2=error. Not specifying a value returns all message types.
getOutput(index)
Returns a given output. If a record set or raster data object, a RecordSet or RasterData object is returned.
getSeverity(index) Result properties and methods
Getting results from a server tool
Returns the severity of a specific message.
Like other geoprocessing tools, geoprocessing server tools have a fixed set of parameters that provide the tool with the information it needs for execution. When using asynchronous server tools in a script, the output can be retrieved by the result's getOutput method. Tip: The IsSynchronous function can be used to determine whether a tool is run synchronously or asynchronously. When a tool is synchronous, the results are automatically returned, but no other action may be taken until the tool has completed. In the following example, the GetParameterValue function is used to get a FeatureSet object from a server tool. This FeatureSet object contains the schema of the tool's input parameter. The FeatureSet object is then loaded with a feature class, and the server tool is executed on the server. The script ends by using the result object's getOutput method to get the tool output's, which is then saved locally by using the FeatureSet's save method.
import arcpy import time # Add a toolbox from a server # arcpy.ImportToolbox("http://flame7/arcgis/services;GP/BufferByVal", "mytools") # Use GetParameterValue to get a featureset object with the default # schema of the first parameter of the tool 'bufferpoints' # inFeatureSet = arcpy.GetParameterValue("bufferpoints", 0) # Load a shapefile into the featureset # inFeatureSet.load("c:/base/roads.shp") # Run a server tool named BufferPoints with featureset created above # result = arcpy.BufferPoints_mytools(inFeatureSet, "5 feet") # Check the status of the result object every 0.2 seconds until it has a value # of 4 (succeeded) or greater # while result.status < 4: time.sleep(0.2) # Get the output FeatureSet back from the server and save to a local geodatabase # outFeatSet = result.getOutput(0) outFeatSet.save("c:/temp/base.gdb/towers_buffer")
Getting a raster result from a server tool Raster results are returned as Tagged Image File Format (TIFF). By default, when using getOutput, the TIFF is written to your system's TEMP folder. To control the location of the TIFF, set the scratchWorkspace environment to a folder.
import arcpy import time # Set the scratchworkspace to a folder. # arcpy.env.scratchWorkspace = "c:/temp/rasteroutput" # Add a toolbox from a server # arcpy.ImportToolbox("http://flame7/arcgis/services;SlopeByVal", "mytools") dem = "c:/dems/k_ne_g" # Run a server tool named RunSlope # result = arcpy.RunSlope_mytools(dem) # Check the status of the result object every 0.2 seconds until it has a value # of 4 (succeeded) or greater # while result.status < 4: print result.status time.sleep(0.2) # Raster output will be written to the scratchworkspace # outTIFF = result.getOutput(0)
Getting a map image Geoprocessing services can have a result map service to create a digital map image of task results. Digital maps contain visual representations of geographic datasets that communicate information. Digital maps are transported across the Web as images (such as a .jpeg). A map image, byte for byte, contains far more human-interpretable information than raw features in a feature class. Map images are also manageable—they are easily compressed, they can be tiled into manageable chunks, and there are established methods for transporting and viewing them across the Web. Map images are created by an ArcGIS Server map service and are the result of publishing an ArcMap document (.mxd). Because of the characteristics of a map image, you may want to create one for the results of your geoprocessing task and transport the image across the Web rather than transporting the result dataset or datasets. Geoprocessing services can have a result map service used by ArcGIS Server to create map images of your output data.
import arcpy import time import urllib # Add a toolbox from a server # arcpy.ImportToolbox("http://flame7/arcgis/services;GP/BufferByVal", "mytools") # Use GetParameterValue to get a featureset object with the default schema of the # first parameter of the tool 'bufferpoints' # inFeatureSet = arcpy.GetParameterValue("bufferpoints", 0) # Load a shapefile into the featureset # inFeatureSet.load("c:/base/roads.shp") # Run a server tool named BufferPoints with featureset created above # result = arcpy.BufferPoints_mytools(inFeatureSet, "5 feet") # Check the status of the result object every 0.2 seconds until it has a value # of 4 (succeeded) or greater # while result.status < 4: time.sleep(0.2) print result.status # Return a map service # mapimage = result.getMapImageURL(0) # Use Python's urllib module's urlretrieve method to copy the image locally # urllib.urlretrieve(mapimage, "c:/base/road_buffer.jpg")
Related Topics Using functions in Python Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Accessing tools
A function is a defined bit of functionality that does a specific task and can be incorporated into a larger program. In ArcPy, all geoprocessing tools are provided as functions, but not all functions are geoprocessing tools. In addition to tools, ArcPy provides a number of functions to better support geoprocessing workflows
using Python. Functions can be used to list certain datasets, retrieve a dataset's properties, validate a table name before adding it to a geodatabase, or perform many other useful geoprocessing tasks. These functions are available only from ArcPy and not as tools in ArcGIS applications, since they are designed for Python workflows. The general form of a function is similar to that of tool; it takes arguments, which may or may not be required, and returns something. The returned value of a non-tool function can be varied—anything from strings to geoprocessing objects. Tool functions will always return a Result object and provide geoprocessing messages support. The following example uses two ArcPy functions, GetParameterAsText to receive an input argument, and Exists to determine whether the input exists or not. The Exists function returns a boolean value (either True or False).
import arcpy input = arcpy.GetParameterAsText(0) if arcpy.Exists(input): print "Data exists" else: print "Data does not exist"
The following example creates a Python list of feature classes using the ListFeatureClasses function, then loops through the list, clipping each individual feature class with a boundary feature class.
import arcpy from arcpy import env import os # The workspace environment needs to be set before ListFeatureClasses # to identify which workspace the list will be based on # env.workspace = "c:/data" out_workspace = "c:/data/results/" clip_features = "c:/data/testarea/boundary.shp" # Loop through a list of feature classes in the workspace # for fc in arcpy.ListFeatureClasses(): # Set the output name to be the same as the input name, and # locate in the 'out_workspace' workspace # output = os.path.join(out_workspace, fc) # Clip each input feature class in the list # arcpy.Clip_analysis(fc, clip_features, output, 0.1)
Related Topics Using classes in Python Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Accessing tools
A class is analogous to an architectural blueprint. The blueprint provides the framework for how to create something. Classes can be used to create objects, often referred to as an instance. ArcPy classes, such as the SpatialReference and Extent classes, are often used as shortcuts to complete geoprocessing tool parameters that would otherwise have a more complicated string equivalent. ArcPy includes several classes, including SpatialReference, ValueTable, and Point. Once instantiated, its properties and methods may be used. Classes have one or more methods called constructors. A constructor is a method for initializing a new instance of a class. In the example below, SpatialReference(prjFile) is the class constructor—it creates the spatialRef object by reading a projection file.
import arcpy prjFile = "c:/projections/North America Equidistant Conic.prj" spatialRef = arcpy.SpatialReference(prjFile)
Like most other classes, SpatialReference contains a number of methods and properties. Building on the previous sample, you can access the properties of spatialRef.
import arcpy prjFile = "c:/projections/North America Equidistant Conic.prj" spatialRef = arcpy.SpatialReference(prjFile) # Print the SpatialReference's name, and type # print spatialRef.name print spatialRef.type
Classes can be used repeatedly; in the following example, two unique point objects are created by using the Point class.
import arcpy pointA = arcpy.Point(2.0, 4.5) pointB = arcpy.Point(3.0, 7.0) Note: The CreateObject function can also be used to create many of the objects that can be created using classes. However, using classes is both easier to use and more readable.
Using classes with geoprocessing tools
Tool parameters are usually defined using simple text strings. Dataset names, paths, keywords, field names, tolerances, and domain names can be specified using a quoted string. Some parameters are harder to define using simple strings; they are more complex parameters that require many properties. Instead of using long, complicated text strings to define these parameters, you can use classes (for example, SpatialReference, ValueTable, and Point classes). The documentation for each tool contains a scripting example of how each tool parameter is defined and used. In the following example, a SpatialReference object is created and used to define the output coordinate system of a new feature class created using the CreateFeatureClass tool.
import arcpy inputWorkspace = "c:/temp" outputName = "rivers.shp" prjFile = "c:/projections/North America Equidistant Conic.prj" spatialRef = arcpy.SpatialReference(prjFile) # Run CreateFeatureclass using the spatial reference object # arcpy.CreateFeatureclass_management(inputWorkspace, outputName, "POLYLINE", "", "", "", spatialRef)
The string equivalent for this parameter looks something like this: PROJCS['North_America_Equidistant_Conic',GEOGCS['GCS_North_American_1983',DATUM['D_No rth_American_1983',SPHEROID['GRS_1980',6378137.0,298.257222101]],PRIMEM['Greenwich',0 .0],UNIT['Degree',0.0174532925199433]],PROJECTION['Equidistant_Conic'],PARAMETER['Fal se_Easting',0.0],PARAMETER['False_Northing',0.0],PARAMETER['Central_Meridian',96.0],PARAMETER['Standard_Parallel_1',20.0],PARAMETER['Standard_Parallel_2',60.0],PAR AMETER['Latitude_Of_Origin',40.0],UNIT['Meter',1.0]];IsHighPrecision
Related Topics Using environment settings in Python Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Accessing tools
Each tool has a set of parameters it uses to execute an operation. Some of these parameters are common among all tools, such as a tolerance or output location. These parameters may obtain their default values from a geoprocessing environment that all tools utilize during their operation. When a tool is executed, the current environment settings can also be used as global input parameter values. Settings such as an area of interest, the spatial reference of the output dataset, and the cell size of a new raster dataset can all be specified with geoprocessing environments. A script can be executed in several different ways. It can be run as a script tool in an ArcGIS application, such as ArcMap. It can also be run from another script or by itself from a Python window. When a script is run inside a tool from an ArcGIS application or from another geoprocessing script, the environment
settings used by the calling application or script are passed to it. These settings become the default settings used by the tool's script when it is executed. The called script may alter the settings passed to it, but those changes are only used within that script or by any other tool it may call. Changes are not passed back to the calling script or application. The environment model can best be described as cascading, where values flow down to any process that uses the geoprocessing environment.
Getting and setting environment settings Environment settings are exposed as properties on the env class. These properties can be used to retrieve the current values or to set them. Each environment setting has a name and a label. Labels are displayed on the Environment Settings dialog box in ArcGIS. Names are used in scripts or at the command line in ArcGIS applications. Below are examples of how to use environment values: Note: Environments can be accessed as read/write properties from the environment class, as arcpy.env.. Alternatively, instead of prefixing each environment name with arcpy.env, you can simplify your code by taking advantage of Python's from-import statement. This alternative has the advantage of simplifying your code and making it easier to read. import arcpy
import arcpy
from arcpy import env
import arcpy from arcpy import env
arcpy.env.workspace = "c:/data" env.workspace = "c:/data"
Example 1: Setting environment values
import arcpy from arcpy import env # Set the workspace environment setting # env.workspace = "c:/St_Johns/data.gdb" # Set the XYTolerance environment setting # env.XYTolerance = 2.5 # Calculate the default spatial grid index, divide in half, then # set the spatial grid 1 environment setting # result = arcpy.CalculateDefaultGridIndex_management("roads") env.spatialGrid1 = float(result.getOutput(0)) / 2 # Clip the roads by the urban area feature class #
arcpy.Clip_analysis("roads","urban_area","urban_roads")
Example 2: Getting and setting an environment value
import arcpy from arcpy import env # Check the current raster cell size and make sure it is a certain size # for standard output # env.workspace = "c:/avalon/data" if env.cellSize < 10: env.cellSize = 10 elif env.cellSize > 20: env.cellSize = 20 arcpy.HillShade_3d("island_dem", "island_shade", 300) Caution: Spelling and case count when setting environment values. Assigning a value to arcpy.env.Workspace is not the same as setting arcpy.env.workspace (note: arcpy.env.workspace is the correct form). If you encounter a case where you've set an environment but are not seeing the effect on subsequent tools, check the spelling and case. The ListEnvironments function can be used to check proper environment names.
import arcpy print arcpy.ListEnvironments()
Saving and loading settings Automatic transfer of settings is only done when a script is executed by a geoprocessing tool. When a geoprocessing script calls another geoprocessing script, the environments are not automatically passed to the called script, since there is no way for the first script to know that the second script is using ArcPy. To facilitate the transfer of environment settings from one script to another and to save settings from one session to the next, settings can be saved to a file. ArcPy can then set its environments by loading a settings file. In the first example below, a script transfers its settings to a second script by saving them to a file and passing that file name as a parameter to a second script. The second example loads an environment settings file using a name passed as a script argument. Example 1:
# Import ArcPy site-package # import arcpy
from arcpy import env import os # Set the raster environment settings and the workspace # env.cellSize = 25 env.mask = "D:/St_Johns/Landcover" env.workspace = "D:/St_Johns" # Save the environment settings # envfile = arcpy.SaveSettings("c:/St_Johns/settings") # Call Python script and pass file name as argument # os.system('MyHillshade.py ' + envfile)
Example 2:
# Import ArcPy site-package # import arcpy # Get the input parameter value # envfile = arcpy.GetParameterAsText(0) # Load the environment settings # arcpy.LoadSettings(envfile) # Calculate hillshade # arcpy.Hillshade_3d("city_dem","city_shade",250)
Environment values can be passed between modules as arguments. Saving and loading settings between executing modules is not an efficient way of sharing values. Using a settings file is valid when used by modules that are not run together, which is the intent of the above example.
Related Topics Understanding message types and severity Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Accessing tools
During execution of a tool, messages are written that can be retrieved with geoprocessing functions, such as GetMessages(). These messages include such information as the following:
When the operation started and ended
The parameter values used
General information about the operation's progress (information message)
Warnings of potential problems (warning message)
Errors that cause the tool to stop execution (error message)
All communication between tools and users is done with messages. Depending on where you are running the tools from, messages appear in the Results window, the Python window, and the progress dialog box. From Python, you can fetch these messages within your script, interrogate them, print them, or write them to a file. All messages have a severity property, either informative, warning, or error. The severity is an integer where 0 = informative, 1 = warning, and 2 = error. Severity Informative
An informative message is just that—information about execution. It is never
message
used to indicate problems. Only general information, such as a tool's progress,
(severity = 0)
what time a tool started or completed, output data characteristics, or tool results, is found in informative messages.
Warning
Warning messages are generated when a tool experiences a situation that may
message
cause a problem during its execution or when the result may not be what you
(severity = 1)
expect. For example, defining a coordinate system for a dataset that already has a coordinate system defined generates a warning. You can take action when a warning is returned, such as canceling the tool's execution or making another parameter choice.
Error message
Error messages indicate a critical event that prevented a tool from executing.
(severity = 2)
Errors are generated when one or more parameters have invalid values or when a critical execution process or routine has failed.
Both warning and error messages are accompanied by a six-digit ID code. These ID codes have been documented to provide additional information on their causes and how they can be dealt with. When error or warning codes are shown in the tool or progress dialog box, Python window, or Result window, they have a link that allows you to go directly to the additional help for that message.
Getting messages Messages from the last tool executed are maintained by ArcPy and can be retrieved using the GetMessages function. This function returns a single string containing all the messages from the tool that was last executed. The returned messages can be filtered to include only those with a certain severity using the severity option. When using ArcPy, the first message gives the tool executed, and the last message gives the ending and elapsed time for the tool's execution. The tool's second and last messages always give the start and end time, respectively, for the tool's execution. Learn more about the GetMessageCount functionLearn more about the GetMessage functionLearn more about the GetMessages functionLearn more about the AddError functionLearn more about the AddIDMessage functionLearn more about the AddMessage functionLearn more about the AddReturnMessage functionLearn more about the AddWarning function
Getting geoprocessing messages
import arcpy # Execute the GetCount tool # arcpy.GetCount_management("c:/base/data.gdb/roads") # Get the resulting messages and print them # print arcpy.GetMessages() # The returned messages would look similar to the following: # Executing: GetCount c:/base/data.gdb/roads # Start Time: Wed Apr 07 11:28:21 2010 # Row Count = 373 # Succeeded at Wed April 07 11:28:21 2010 (Elapsed Time: 0.00 seconds)
Individual messages can be retrieved using the GetMessage function. This function has one parameter, which is the index position of the message. The GetMessageCount function returns the number of messages from the last tool executed. The example below shows how to print information about which tool was executed along with ending and elapsed times for the tool.
import arcpy arcpy.env.workspace = "D:/base/data.gdb" arcpy.Clip_analysis("roads", "urban_area", "urban_roads") # Print the first message - tool executed # print arcpy.GetMessage(0) # Print the last message - ending and elapsed times for tool # print arcpy.GetMessage(arcpy.GetMessageCount - 1)
Getting messages from a result object Messages can also be accessed from a tool using a Result object. Unlike getting messages from ArcPy, messages on a Result object can be maintained even after running multiple tools. The Result object supports several of the same functions used to get and interpret geoprocessing tool messages. Result properties and methods Properties and methods
Explanation
inputCount
Returns the number of inputs.
outputCount
Returns the number of outputs.
messageCount
Returns the number of messages.
maxSeverity
Returns the maximum severity. The returned severity can be 0 (no errors/warnings raised), 1 (warnings raised), or 2 (errors raised).
resultID
Returns the unique result ID. If the tool is not a geoprocessing service, the resultID will be "".
status
Returns the status of the job on the server.
0—New
1—Submitted
2—Waiting
3—Executing
4—Succeeded
5—Failed
6—Timed Out
7—Canceling
8—Canceled
9—Deleting
10—Deleted
cancel()
Cancels the job on the server.
getInput(index)
Returns a given input. If a record set or raster data object, a RecordSet or RasterData object is returned.
getMapImageURL(ParameterList,
Get map service image for a given output.
Height, Width, Resolution) getMessage(index)
Returns a specific message.
getMessages(severity)
The type of messages to be returned. 0=message, 1=warning, 2=error. Not specifying a value returns all message types.
getOutput(index)
Returns a given output. If a record set or raster data object, a RecordSet or RasterData object is
returned. getSeverity(index)
Returns the severity of a specific message.
Result properties and methods
The following sample runs two geoprocessing tools but waits until the tools are executed before reviewing the messages.
import arcpy arcpy.env.workspace = "D:/base/data.gdb" # Execute the Clip and GetCount tools # clipResult = arcpy.Clip_analysis("roads", "urban_area", "urban_roads") countResult = arcpy.GetCount_management("urban_roads") # Get the resulting messages and print them # print clipResult.getMessages() print countResult.getMessages()
As with geoprocessing tools, server tool messages are classified as either information, a warning, or an error. A message's type is indicated by its severity property, which is a numeric value. The following sample shows how to get the messages from a server tool after it has completed.
import arcpy import time # Add the server toolbox # arcpy.ImportToolbox("http://lab13/arcgis/services;BufferByVal", "mytools") featset = arcpy.FeatureSet() featset.load("//flames/gpqa/coredata/global/redlands/control.shp") # Run a server tool named BufferPoints # result = arcpy.BufferPoints_mytools(featset, "1000 feet") # Wait until the tool completes # while result.status < 4: time.sleep(0.2) # Print all messages from the result object # print result.getMessages()
Related Topics Error handling with Python Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Accessing tools
Errors happen. Writing scripts that expect and handle errors can save you a lot of time and frustration. When a tool returns an error message, ArcPy generates a system error, or exception. In Python, you can provide a variety of structures and methods that can handle exceptions. Of course, a script can fail for many other reasons that are not specifically related to a geoprocessing tool; these too need to be caught and dealt with in an appropriate manner. The following sections offer a few techniques that introduce the basics of Python exception handling. When a tool writes an error message, ArcPy generates a system error, or an exception. Python allows you to write a routine that is automatically run whenever a system error is generated. Within this errorhandling routine, you can retrieve the error message from ArcPy and react accordingly. If a script does not have an error-handling routine, it fails immediately, which decreases its robustness. Use errorhandling routines to manage errors and improve a script's usability. Geoprocessing tool error messages are accompanied by a six-digit code. These ID codes have been documented to provide additional information on their cause and how they can be dealt with. Learn more about creating and debugging geoprocessing scriptsLearn more about script tools
try-except statement A try-except statement can be used to wrap entire programs or just particular portions of code to trap and identify errors. If an error occurs within the try statement, an exception is raised, and the code under the except statement is then executed. Using a simple except statement is the most basic form of error handling. In the following code, Buffer fails because the required Distance parameter has not been used. Instead of failing without explanation, the except statement is used to trap the error, then fetch and print the error message generated by Buffer. Note that the except block is only executed if Buffer returns an error.
import arcpy try: # Execute the Buffer tool # arcpy.Buffer_analysis("c:/transport/roads.shp", "c:/transport/roads_buffer.shp") except Exception as e: print e.message # If using this code within a script tool, AddError can be used to return messages # back to a script tool. If not, AddError will have no effect. arcpy.AddError(e.message)
The try statement has an optional finally clause that can be used for tasks that should be always be executed, whether an exception has occurred or not. In the following example, the 3D Analyst extension is checked back in under a finally clause, ensuring that the extension is always checked back in.
class LicenseError(Exception): pass import arcpy from arcpy import env try: if arcpy.CheckExtension("3D") == "Available": arcpy.CheckOutExtension("3D") else: # Raise a custom exception # raise LicenseError env.workspace = "D:/GrosMorne" arcpy.HillShade_3d("WesternBrook", "westbrook_hill", 300) arcpy.Aspect_3d("WesternBrook", "westbrook_aspect") except LicenseError: print "3D Analyst license is unavailable" except: print arcpy.GetMessages(2) finally: # Check in the 3D Analyst extension # arcpy.CheckInExtension("3D")
raise statement The previous example dealt with handling an exception that occurred in the code; in some cases, it may be necessary to create custom exceptions. A raise statement can be used for this purpose. In the following code, a raise statement is used when an input feature class has been identified as having no features. This is not strictly an error but a condition that the code can be used to guard against.
class NoFeatures(Exception): pass import arcpy import os
arcpy.env.overwriteOutput = 1 fc = arcpy.GetParameterAsText(0) try: # Check that the input has features # result = arcpy.GetCount_management(fc) if int(result.getOutput(0)) > 0: arcpy.FeatureToPolygon_management(fc, os.path.dirname(fc) + os.sep + "out_poly.shp") else: # Raise custom exception # raise NoFeatures(result) except NoFeatures: # The input has no features # print fc + " has no features." except: # By default any other errors will be caught here # print arcpy.GetMessages(2)
ExecuteError class When a geoprocessing tool fails, it throws an ExecuteError exception class. What this means is that you can divide errors into two groups, geoprocessing errors (those that throw the ExecuteError exception) and everything else. You can then handle the errors differently, as demonstrated in the code below:
import arcpy try: result = arcpy.GetCount_management("C:/invalid.shp") # Return geoprocessing specific errors # except arcpy.ExecuteError: arcpy.AddError(arcpy.GetMessages(2)) # Return any other type of error except: arcpy.AddError("Non-tool error occurred")
traceback
In larger, more complex scripts, it can be difficult to determine the precise location of an error. Python's sys and traceback modules can be used together to isolate the exact location and cause of the error, identifying the cause of an error more accurately and saving you valuable debugging time.
# Import the required modules # import arcpy import sys import traceback arcpy.env.workspace = "C:/Data/myData.gdb" try: arcpy.CreateSpatialReference_management() #-------------------------# Your code goes here # # See the table below for examples #-------------------------except arcpy.ExecuteError: # Get the tool error messages # msgs = arcpy.GetMessages(2) # Return tool error messages for use with a script tool # arcpy.AddError(msgs) # Print tool error messages for use in Python/PythonWin # print msgs except: # Get the traceback object # tb = sys.exc_info()[2] tbinfo = traceback.format_tb(tb)[0] # Concatenate information together concerning the error into a message string # pymsg = "PYTHON ERRORS:\nTraceback info:\n" + tbinfo + "\nError Info:\n" + str(sys.exc_info()[1]) msgs = "ArcPy ERRORS:\n" + arcpy.GetMessages(2) + "\n" # Return python error messages for use in script tool or Python Window # arcpy.AddError(pymsg) arcpy.AddError(msgs) # Print Python error messages for use in Python / Python Window #
print pymsg + "\n" print msgs
If the above code was used and a geoprocessing tool error occurred, such an invalid input, this would raise ExecuteError, and the first except statement would be used. This statement would print out the error messages using the GetMessages function. If the same code was used, but a different type of error occurred, the second except statement would be used. Instead of printing geoprocessing messages, it would get a traceback object and print out the appropriate system error messages. The table below shows the expected errors that result from three different lines of codes that could be substituted into the code above. The first is a geoprocessing tool error, which prints out the traceback information and the geoprocessing error messages. The second and third examples are not specifically caught and print out only the traceback information. Your code arcpy.GetCount_management("")
Resulting error
PYTHON ERRORS: Traceback info: File "c:\temp\errortest.py", line 10, in arcpy.GetCount_management("") Error Info: Failed to execute. Parameters are not valid. ERROR 000735: Input Rows: value is required Failed to execute (GetCount). ArcPy ERRORS: Failed to execute. Parameters are not valid. ERROR 000735: Input Rows: value is required Failed to execute (GetCount).
x = "a" + 1
PYTHON ERRORS: Traceback info: File "c:\temp\errortest.py", line 10, in x = "a" + 1 Error Info: cannot concatenate 'str' and 'int' objects
float("a text string")
PYTHON ERRORS: Traceback info: File "c:\temp\errortest.py", line 10, in
float("a text string") Error Info: invalid literal for float(): a text string
Error results
Related Topics Setting paths to data in Python Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Accessing tools
Programming languages, such as Python, treat a backslash (\) as an escape character. For instance, \n represents a line feed, and \t represents a tab. When specifying a path, a forward slash (/) can be used in place of a backslash. Two backslashes can be used instead of one to avoid a syntax error. A string literal can also be used by placing the letter r before a string containing a backslash so it is interpreted correctly. Example 1: Valid use of paths in Python
import arcpy arcpy.GetCount_management("c:/temp/streams.shp") arcpy.GetCount_management("c:\\temp\\streams.shp") arcpy.GetCount_management(r"c:\temp\streams.shp")
Example 2: Invalid use of paths in Python In the following sample, backslashes are used by mistake, and \t is interpreted as a tab by Python. GetCount will fail, as the path is interpreted differently than it was intended.
import arcpy arcpy.GetCount_management("c:\temp\streams.shp") # ExecuteError: Failed to execute. Parameters are not valid. # ERROR 000732: Input Rows: Dataset c: em\streams.shp does not exist or is not supported # Failed to execute (GetCount) Tip: It is possible to have a feature class and a feature dataset with the same name contained within a geodatabase. In such a case, the feature class and feature dataset will have the same ArcCatalog path. Most tools work with one or the other. However, for those tools that can work with either, such as the Copy tool, the data type can be specified to avoid ambiguity.
Related Topics Paths explained: Absolute, relative, UNC, and URL
Listing tools, toolboxes, and environment settings Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Accessing tools
Depending on which toolboxes are available, ArcPy might have access to several toolboxes, dozens of environment settings, and hundreds of tools. ArcPy has several appropriately named functions to return a list of tools (ListTools), environment settings (ListEnvironments), or toolboxes (ListToolboxes). Learn more about the ListEnvironments functionLearn more about the ListToolboxes functionLearn more about the ListTools function Each function has a wild card option and returns a list of name strings that can be looped through. The example below shows how to access available tools and print out their usage.
import arcpy # Create a list of the conversion tools # tools = arcpy.ListTools("*_conversion") # Loop through the list and print each tool's usage # e.g., 'Usage: merge {field_mappings}' # for tool in tools: print arcpy.Usage(tool)
The following sample provides an approach for viewing environment settings in Python.
import arcpy environments = arcpy.ListEnvironments() # Sort the environment list, disregarding capitalization # environments.sort(key=string.lower) for environment in environments: # Use Python's eval function to evaluate an environment's value # envSetting = eval("arcpy.env." + environment) # Format and print each environment and its current setting # print "%-30s: %s" % (environment, envSetting)
The following sample provides an approach for viewing current toolboxes in Python.
import arcpy
# Print all current toolboxes # for toolbox in arcpy.ListToolboxes(): # Toolboxes are printed in the form of "toolbox_name(toolbox_alias)" print toolbox
Related Topics Listing data
Accessing licenses and extensions in Python Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Accessing tools
Whenever a tool is executed in a script, an ArcGIS Desktop license is required. Tools from ArcGIS extensions, such as ArcGIS Spatial Analyst, require an additional license for that extension. If the necessary licenses are not available, a tool fails and returns error messages. For example, if you install with an ArcView license, and you attempt to execute a tool set for an ArcEditor or ArcInfo license, the tool will fail. When using an ArcView or ArcEditor license, a script should set the product to ArcView or ArcEditor. Likewise, when using an Engine or EngineGeoDB license, a script should set the product to Engine or EngineGeoDB. If a license is not explicitly set, the license will be initialized based on the highest available license level the first time an ArcPy tool, function, or class is accessed. Every tool checks to ensure it has the appropriate license. If it doesn't have what's required, it fails. To guard against the situation of executing part way through and failing, you can perform a check at the top of your script and fail immediately. Tip: The setting of the product and extensions is only necessary within stand-alone scripts. If you are running tools from the Python window or using script tools, the product is already set from within the application, and the active extensions are based on the Extensions dialog box.
Desktop, Engine/Server licenses Product modules are imported prior to the import of arcpy to define the desktop license used by a script. The CheckProduct function can be used to the check the availability of desktop licenses, while the ProductInfo function reports what the current product license is. Legacy: The product level should be set by importing the appropriate product module (arcinfo, arceditor, arcview, arcserver, arcenginegeodb, arcengine) prior to importing arcpy. The SetProduct function is a legacy function and cannot set the product once arcpy has been imported.
Extension licenses
Licenses for extensions can be retrieved from a license manager and returned once they are no longer needed. CheckExtension is used to see if a license is available to be checked out for a specific type of extension, while CheckOutExtension actually retrieves the license. Once the extension license has been retrieved by the script, extension tools can be executed. Once a script is done using tools from a particular extension, the CheckInExtension function should be used to return the license to the license manager so other applications can use it. All checked-out extension licenses and set product licenses are returned to the license manager when a script completes. The following example executes some ArcGIS 3D Analyst tools and sets the desktop product license to ArcView, since an ArcInfo license is not required to execute tools from an extension. The script will fail if the ArcView license is not explicitly set and no ArcInfo license is available, since a desktop license is required to execute extension tools.
class LicenseError(Exception): pass # Set desktop license used to ArcView # import arcview import arcpy from arcpy import env try: if arcpy.CheckExtension("3D") == "Available": arcpy.CheckOutExtension("3D") else: # Raise a custom exception # raise LicenseError env.workspace = "D:/GrosMorne" arcpy.HillShade_3d("WesternBrook", "westbrook_hill", 300) arcpy.Aspect_3d("WesternBrook", "westbrook_aspect") except LicenseError: print "3D Analyst license is unavailable" except: print arcpy.GetMessages(2) finally: # Check in the 3D Analyst extension # arcpy.CheckInExtension("3D")
In the above example, the 3D Analyst extension is checked in under a finally clause, ensuring that the extension is always checked back in, whether an exception has occurred or not. A returned value of Failed, Unavailable or NotLicensed indicates that the extension could not be successfully checked out.
Below are the extension names and their extension code names: Extension
Extension Code
3D Analyst
3D
ArcGIS Schematics
Schematics
ArcScan
ArcScan
Business Analyst
Business
Data Interoperability
DataInteroperability
Geostatistical Analyst
GeoStats
ArcGIS Workflow Manager
JTX
Network Analyst
Network
Esri Aeronautical Solution
Aeronautical
Esri Defense Mapping
Defense
Esri Production Mapping
Foundation
ArcGIS Data Reviewer
Datareviewer
Esri Nautical Solution
Nautical
Spatial Analyst
Spatial
StreetMap
StreetMap
Tracking Analyst
Tracking
Product code names Product Codes ArcInfo ArcEditor ArcView Engine
EngineGeoDB ArcServer
Licensing functions Function
Explanation
CheckExtension(extension)
Checks to see if a license is available to be checked out for a specific type of extension. Return Value Available
Meaning
The requested license is available to be set.
Unavailable
The requested license is unavailable to be set.
NotLicensed
The requested license is not valid.
Failed
A system failure occurred during the request.
CheckInExtension(extension)
Returns the license so other applications can use it. Return Value
Meaning
NotInitialized
No desktop license has been set.
Failed
A system failure occurred during the request.
CheckedIn
The license has been returned successfully.
CheckOutExtension(extension)
Retrieves the license. Return Value
Meaning
NotInitialized
No desktop license has been set.
Unavailable
The requested license is unavailable to be set.
CheckedOut CheckProduct(code)
Successfully set the license.
Checks to see if the requested license is available. Return Value
Meaning
AlreadyInitialized
License has already been set in the script.
Available
The requested license is available to be set.
Unavailable
The requested license is unavailable to be set.
NotLicensed
The requested license is not valid.
Failed
A system failure occurred during the request.
ProductInfo()
Returns the current product license. Return Value
Meaning
NotInitialized
No license has been set.
ArcInfo
An ArcInfo license has been set.
ArcEditor
An ArcEditor license has been set.
ArcView
An ArcView license has been set.
ArcServer
An ArcGIS Server license has been set.
EngineGeoDB
An EngineGeoDB license has been set.
Engine SetProduct(code)
An Engine license has been set.
Defines the desktop license. Return Value
Meaning
CheckedOut
Successfully set the license.
AlreadyInitialized
License has already been set in
the script. NotLicensed
The requested license is not valid.
Failed
A system failure occurred during the request.
Listing data Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Working with sets of data in Python
One of the foremost tasks in a batch processing script is cataloging the available data so it can iterate through the data during processing. ArcPy has a number of functions built specifically for creating such lists. ListFields(dataset, wild_card, field_type)
Returns a list of fields found in the input value
ListIndexes(dataset, wild_card)
Returns a list of attribute indexes found in the input value
ListDatasets(wild_card, feature_type)
Returns the datasets in the current workspace
ListFeatureClasses(wild_card,
Returns the feature classes in the current workspace
feature_type) ListFiles(wild_card)
Returns the files in the current workspace
ListRasters(wild_card, raster_type)
Returns a list of rasters found in the current workspace
ListTables(wild_card, table_type)
Returns a list of tables found in the current workspace
ListWorkspaces(wild_card,
Returns a list of workspaces found in the current
workspace_type)
workspace
ListVersions(sde_workspace)
Returns a list of versions the connected user has permission to use
List functions
The result of each of these functions is a Python list, which is a list of values. A list in scripting can contain any type of data, such as a string, which could be, for example, a path to a dataset, field, or row from a table. Once the list has been created with the values you want, you can loop through it in your script to work with each individual value. Learn more about listing tools, toolboxes, and environment settings
List function parameters
The parameters of these functions are similar. A few, such as ListFields, require an input dataset value, since the items the functions are listing reside within a certain object or dataset. Other functions do not require an input dataset, because they list types of data in the current workspace that are defined in the environment settings. All functions have a wildcard parameter, which is used to restrict the objects or datasets listed by name. A wildcard defines a name filter, and all the contents in the newly created list must pass that filter. For example, you may want to list all the feature classes in a workspace that start with the letter G. The following example shows how this is done:
import arcpy from arcpy import env # Set the workspace. List all of the feature classes that start with 'G' # env.workspace = "D:/St_Johns/data.gdb" fcs = arcpy.ListFeatureClasses("G*")
The list can also be restricted to match certain data properties, such as only polygon feature classes, integer fields, or coverage datasets. This is what the Type parameter is used for in all the functions. In the next example, the feature classes in a workspace are filtered using a wild card and a data type, so only polygon feature classes that start with the letter G are in the resulting list:
# Set the workspace. List all of the polygon feature classes that # start with 'G' # env.workspace = "D:/St_Johns/data.gdb" fcs = arcpy.ListFeatureClasses("G*", "polygon")
Using your list ArcPy uses a Python list type as the returned type for all its list function results, since lists support the flexibility required for simple data access and multiple data types. A For loop is ideal for working with a Python list because it can be used to step through the list one item at a time. A For loop iterates through each item in the list. Below is an example of a For loop used to iterate through the list generated in the previous example:
# For each feature class in the list of feature classes # for fc in fcs: # Copy the features from the workspace to a folder # arcpy.CopyFeatures_management(fc, "D:/St_Johns/Shapefiles/” + fc)
Following is another example of how to use a List function. The script is used to create raster pyramids for all rasters that are Tagged Image File Format (TIFF) images within a folder.
# Set the workspace. List all of the TIFF files # env.workspace= "D:/St_Johns/images" # For each raster in the list of rasters # for tiff in arcpy.ListRasters("*", "TIF"): # Create pyramids # arcpy.BuildPyramids_management(tiff)
A Python list provides the opportunity to use and manage the results of a list function in variety of ways. Lists are a versatile Python type and provide a number of methods (append, count, extend, index, insert, pop, remove, reverse, sort) that can be used to manipulate and extract information. For instance, if you want to know how many feature classes you have in a workspace, you can use Python's built-in len function to provide that number.
import arcpy from arcpy import env env.workspace = "c:/St_Johns/Shapefiles" fcs = arcpy.ListFeatureClasses() # Use Python's built-in function len to reveal the number of feature classes # in the workspace # fcCount = len(fcs) print fcCount Tip: A Python list can show its contents easily. Python lists can be manipulated with a number of methods, including sort, append, and reverse.
>>> import arcpy >>> from arcpy import env >>> env.workspace = "c:/data/water.gdb" >>> fcs = arcpy.ListFeatureClasses() >>> print fcs [u'water_pipes', u'water_services', u'water_stations'] >>> fcs.sort(reverse=True) >>> print fcs [u'water_stations', u'water_services', u'water_pipes']
As lists are an ordered collection, they also permit indexing and slicing.
>>> print fcs[0] water_stations >>> print fcs[1:] [u'water_services', u'water_pipes']
List function type keywords The default behavior for all list functions is to list all supported types. A keyword is used to restrict the returned list to a specific type. The type keywords for each function are listed in the table below. Function
Type keywords
ListDatasets
All, Feature, Coverage, RasterCatalog, CAD, VPF, TIN, Topology
ListFeatureClasses
All, Point, Label, Node, Line, Arc, Route, Polygon, Region
ListFields
All, SmallInteger, Integer, Single, Double, String, Date, OID, Geometry, BLOB
ListTables
All, dBASE, INFO
ListRasters
All, ADRG, BIL, BIP, BSQ, BMP, CADRG, CIB, ERS, GIF, GIS, GRID, STACK, IMG, JPEG, LAN, SID, SDE, TIFF, RAW, PNG, NITF
ListWorkspaces
All, Coverage, Access, SDE, Folder
Type keywords for List functions
Example: Using list functions to migrate from personal to file geodatabases A common conversion task is the large-scale transfer of data from one format to another. The following script takes advantage of ListWorkspaces, ListFeatureClasses, ListTables, and ListDatasets to identify all personal geodatabases in a folder and converts the feature datasets, feature classes, and tables of each to file geodatabases.
import arcpy from arcpy import env import os # Allow for the overwriting of file geodatabases, if they already exist # env.overwriteOutput = True # Set workspace to folder containing personal geodatabases
# env.workspace = arcpy.GetParameterAsText(0) # Identify personal geodatabases # for pgdb in arcpy.ListWorkspaces("", "Access"): # Set workspace to current personal geodatabase # env.workspace = pgdb # Create file geodatabase based on personal geodatabase # fgdb = pgdb[:-4] + ".gdb" arcpy.CreateFileGDB_management(os.path.dirname(fgdb), os.path.basename(fgdb)) # Identify feature classes and copy to file gdb # for fc in arcpy.ListFeatureClasses(): print "Copying feature class " + fc + " to " + fgdb arcpy.Copy_management(fc, fgdb + os.sep + fc) # Identify tables and copy to file gdb # for table in arcpy.ListTables(): print "Copying table " + table + " to " + fgdb arcpy.Copy_management(table, fgdb + os.sep + table) # Identify datasets and copy to file gdb # Copy will include contents of datasets # for dataset in arcpy.ListDatasets(): print "Copying dataset " + dataset + " to " + fgdb arcpy.Copy_management(dataset, fgdb + os.sep + dataset)
Related Topics Listing tools, toolboxes, and environment settings
Working with multivalue inputs Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Working with sets of data in Python
Many geoprocessing tools have input parameters that accept multiple values. When you view the tool's reference page or its usage in the Python window, whenever you see the parameter enclosed in brackets [ ], you know it can take a list of values. For example, the Delete Field tool takes a list of fields to delete and the parameter usage is displayed as [drop_field, ...]. Some parameters, such as the input_features parameter of the Union tool, take a list-of-lists; its usage is displayed as [[in_features, {Rank}], ...].
Any parameter that accepts a list of values (or a list of list of values) is a multivalue parameter—it accepts one or more values. There are three ways to specify a multivalue parameter: 1. As a Python list, where each value is an element in the list 2. As a string, where values are separated by semicolons 3. As a ValueTable, where values are stored in a virtual table of rows and columns Below are examples of each.
As a Python list In a script, multivalue inputs can be passed as a Python list. A list is enclosed in brackets and is a flexible Python type. DeleteFields using a Python list for the drop_field parameter
import arcpy from arcpy import env env.workspace = "C:/base/county.gdb" arcpy.DeleteField_management("roads", ["STREET_NAM", "LABEL", "CLASS"])
Union using a Python list for the in_features parameter
import arcpy from arcpy import env env.workspace = "C:/base/data/gdb" arcpy.Union_analysis([["counties", 2],["parcels", 1]], "state_landinfo")
As a string Your script may have to use a multivalue string in some cases, because one may be returned as an output value of a tool or passed as an input parameter for your script. DeleteFields using a multivalue string for the drop_field parameter.
import arcpy from arcpy import env env.workspace = "C:/base/county.gdb" arcpy.DeleteField_management("roads", "STREET_NAM;LABEL;CLASS")
Union using a multivalue string for the in_features parameter
import arcpy from arcpy import env env.workspace = "C:/base/data/gdb" arcpy.Union_analysis("counties 2;parcels 1", "state_landinfo")
With ValueTable A ValueTable allows you to organize values into a virtual table of rows and columns. You specify the number of columns when you create a value table. The default is a single column. DeleteFields using a ValueTable for the drop_field parameter
import arcpy from arcpy import env env.workspace = "C:/base/county.gdb" vt = arcpy.ValueTable() vt.addRow("STREET_NAM") vt.addRow("LABEL") vt.addRow("CLASS") arcpy.DeleteField_management("roads", vt)
Union using a ValueTable for the in_features parameter
import arcpy from arcpy import env env.workspace = "C:/base/data/gdb" vt = arcpy.ValueTable(2) vt.addRow("counties 2") vt.addRow("parcels 1") arcpy.Union_analysis(vt, "state_landinfo")
Related Topics Using the multivalue parameter control
Mapping input fields to output fields Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Working with sets of data in Python
A common geoprocessing task is to merge many datasets into a new or existing dataset to create a single dataset covering a larger area or a table containing a greater number of records. Often, the attributes, or fields, are the same for all the inputs that are used in a merge or append operation; sometimes, however, they do not match, and the relationships between fields of different names and types have to be mapped. For an example of field mappings, see the Merge tool in the Data Management toolbox; it facilitates this mapping of relationships so data is placed in the desired output fields with the correct values. The FieldMap object provides a field definition and a list of input fields from a set of tables or feature classes that provide its values.
The properties of the FieldMap object include the start and end position of an input text value, so a new output value can be created using a slice of an input value. If a FieldMap object contains multiple input fields from the same table or feature class, each record's values are merged using the mergeRule property. This is a convenient way to join values, such as a street name that is held in one field and a street type that is held in another, for example, Eureka and Street. The joinDelimiter property of FieldMap is used if the mergeRule value Join is specified. Any set of characters, such as a space, can be used as a delimiter. In the above example, this would create a value of Eureka Street. FieldMap properties Property
Explanation
inputFieldCount The number of defined input fields. joinDelimiter
A string value used to separate input values from the same table if the output field type is string and the mergeRule is Join.
mergeRule
Defines how values from two or more fields from the same input table are merged into a single output value. Valid choices are as follows:
First: The first input value is used.
Last: The last input value is used.
Join: Merge the values together using the delimiter value to separate the values (only valid if the output field type is text.
Min: The smallest input value is used (only valid if the output field type is numeric.
Max: The largest input value is used (only valid if the output field type is numeric).
Mean: The mean is calculated using the input values (only valid if the output field type is numeric).
Median: The median is calculated using the input values (only valid if the output field type is numeric).
Sum: The sum is calculated using the input values (only valid if the output field type is numeric).
StdDev: The standard deviation is calculated using the input values (only valid if the output field type is numeric).
Count: The number of values included in statistical calculations. This counts each value except null values.
outputField
The properties of the output field are either set or returned in a field object.
FieldMap methods Method
Explanation
addInputField(table_dataset,
Adds a field to the list of input fields by specifying the
field_name, {start_position},
name, including the path to the field's input table or
{end_position})
feature class and the name of the field, as well as the start and end position of the field value, if the input value is from a text field.
findInputFieldIndex (table_dataset,
Returns the index position of a specific field within the
field_name)
FieldMap's list of input fields.
getEndTextPosition(index)
Returns the position within the input field value that will be used to end the new output value. This property is only used when the input field type is text.
getInputFieldName(index)
Returns the field name for a specific input field.
getInputTableName(index)
Returns the table name for a specific input field.
getStartTextPosition(index)
Returns the position within the input field value that will be used to start the new output value. This property is only used when the input field type is text.
removeAll()
Deletes the contents of the FieldMap's list of input fields.
removeInputField(index)
Removes an input field from the FieldMap's list of input fields.
setEndTextPosition(index,
Defines the value indicating the last character position of
end_position)
the input value used to define the new output value. This property is only used when the input field type is text.
setStartTextPosition(index,
Defines the value indicating the first character position of
start_position)
the input value used to define the new output value. This property is only used when the input field type is text.
The FieldMappings object is a collection of FieldMap objects, and it is used as the parameter value for tools that perform field mapping, such as Merge. The easiest way to work with these objects is to first create a FieldMappings object, then initialize its FieldMap objects by adding the input feature classes or tables that are to be combined. Once all inputs are provided, the FieldMappings object will contain one FieldMap object, or output field, for each unique field name from all the inputs. This list can be modified by adding new fields, altering the properties and/or contents of an output field, or removing any unwanted output fields. FieldMappings properties Property
Explanation
fieldCount
The number of output fields.
fieldValidationWorkspace The workspace type defines the rules for attribute field naming. These rules are used when determining the output field names, which are based on the names of the input fields from the input tables or feature classes. For example, a file system workspace that contains shapefiles may only have field names with a maximum length of 10 characters. fields
A list of field objects. Each field object represents the properties of each output field.
FieldMappings methods Method
Explanation
addFieldMap(field_map)
Adds a new FieldMap object that will define a new output field
addTable(table_dataset)
Specifies a table or feature class whose fields will be used to define the output fields
exportToString()
Saves the contents of the FieldMappings objects to a string value
findFieldMapIndex(field_map_name) Using the name of the output field, returns the position of the FieldMap object for the field within the list of FieldMap objects that define the output fields getFieldMap(index)
Returns a FieldMap object from the list of output fields using the index position of the FieldMap within that list
loadFromString()
Populates the contents of the FieldMappings object using a string definition of a FieldMappings object
removeAll()
Deletes the contents of the FieldMap list so that no output fields are defined
removeFieldMap(index)
Removes an output field in the list of FieldMap objects that define the output fields
replaceFieldMap(index, value)
Replaces an existing output field in the list of FieldMap objects that define the output fields using a new FieldMap object
In the following example, a number of feature classes containing U.S. census data will be merged to form a new feature class. One of the input attributes found in all the inputs is a numeric field, STFID. This 15-digit value is a unique identifier for all census blocks for the United States. The value can be broken into four components. The first two digits provide the state code, the next three indicate the county, the following six identify the census tract, and the last four identify the census block. The value
360899912001006 represents the census block (1006) containing the State University of New York at Potsdam in upstate New York (36), within census tract 991200 of the county of St. Lawrence (089). The script sample will merge these feature classes together and also create two new fields, TRACTID and BLOCKID, because the input data only has the STFID attribute. To do this, the FieldMappings object is initialized using the addTable method to enter each input. Then the default FieldMappings object is modified by creating two new FieldMap objects, populating their properties, and adding them to the FieldMappings object.
import arcpy from arcpy import env env.workspace = "C:/Data/CityBlocks.gdb" outfc = "C:/Data/CityBlocks.gdb/AllBlocks" # Each of the input Feature classes has an STFID, which is the # combination of the Tract ID and Block ID for each block. # Separate these values out from this field into two new # fields, TRACTID and BLOCKID. # # Create a fieldmappings and two new fieldmaps. # fieldmappings = arcpy.FieldMappings() fldmap_TRACTID = arcpy.FieldMap() fldmap_BLOCKID = arcpy.FieldMap() # List all the feature classes in the workspace that start with # 'block' in their name and are of polygon feature type. # fcs = arcpy.ListFeatureClasses("block*", "Polygon") # Create a value table that will hold the input feature classes to Merge # vTab = arcpy.ValueTable() for fc in fcs: # Adding a table is the fast way to load all the fields from the # input into fieldmaps held by the fieldmappings object. # fieldmappings.addTable(fc) # In this example also create two fieldmaps by 'chopping up' # an input field. Feed the chopped field into the new fieldmaps. # fldmap_TRACTID.addInputField(fc, "STFID") fldmap_BLOCKID.addInputField(fc, "STFID") # Populate the input value table with feature classes # vTab.addRow(fc)
# Set the starting and ending position of the fields going into the # TractID fieldmap. This is the location in the STFID field where the # TractID falls. # for x in range(0, fldmap_TRACTID.inputFieldCount): fldmap_TRACTID.setStartTextPosition(x, 5) fldmap_TRACTID.setEndTextPosition(x, 10) # Set the Name of the Field output from this field map. # fld_TRACTID = fldmap_TRACTID.outputField fld_TRACTID.name = "TRACTID" fldmap_TRACTID.outputField = fld_TRACTID # Set the starting and ending position of the fields going into the # BlockID fieldmap. This is the location in the STFID field where the # blockID falls. # for x in range(0, fldmap_BLOCKID.inputFieldCount): fldmap_BLOCKID.setStartTextPosition(x, 11) fldmap_BLOCKID.setEndTextPosition(x, 16) # Set the Name of the Field output from this field map. # fld_BLOCKID = fldmap_BLOCKID.outputField fld_BLOCKID.name = "BLOCKID" fldmap_BLOCKID.outputField = fld_BLOCKID # Add the custom fieldmaps into the fieldmappings object. # fieldmappings.addFieldMap(fldmap_TRACTID) fieldmappings.addFieldMap(fldmap_BLOCKID) # Run the Merge tool. # arcpy.Merge_management(vTab, outfc, fieldmappings)
The next example shows how to modify a FieldMap object after it has been created using the addTable method of the FieldMappings object. This is important when the inputs have fields with different names but logically contain the same values.
import arcpy outfc = "C:/data/CityData.gdb/AllBlocks" # Want to merge these two feature classes together. Have a field # that has the same content but the names are slightly different: # Blocks1 has TRACT2000 and Blocks2 TRACTCODE. Name the output # the same as Blocks1.
# fc1 = "C:/data/CityData.gdb/Blocks1" fc2 = "C:/data/CityData.gdb/Blocks2" # Create a new fieldmappings and add the two input feature classes. # fieldmappings = arcpy.FieldMappings() fieldmappings.addTable(fc1) fieldmappings.addTable(fc2) # First get the TRACT2000 fieldmap. Then add the TRACTCODE field # from Blocks2 as an input field. Then replace the fieldmap within # the fieldmappings object. # fieldmap = fieldmappings.getFieldMap(fieldmappings.findFieldMapIndex("TRACT2000")) fieldmap.addInputField(fc2, "TRACTCODE") fieldmappings.replaceFieldMap(fieldmappings.findFieldMapIndex("TRACT2000"), fieldmap) # Remove the TRACTCODE fieldmap. # fieldmappings.removeFieldMap(fieldmappings.findFieldMapIndex("TRACTCODE")) # Create a value table that will hold the inputs for Merge. # vTab = arcpy.ValueTable() vTab.addRow(fc1) vTab.addRow(fc2) # Run the Merge tool. # arcpy.Merge_management(vTab, outfc, fieldmappings)
Related Topics FieldMap FieldMappings Using the field mapping control
Scheduling a Python script to run at prescribed times Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Working with sets of data in Python
How to schedule a geoprocessing script to run at prescribed times Scheduled Tasks Steps:
1. The method to schedule a script depends on your system.
For Windows XP: a. Click the Windows Start menu, point to Control Panel, then double-click Scheduled Tasks.
b. If the control panel is in category view, click Performance and Maintenance and click Scheduled Tasks.
For Windows 2000 and NT: a. Click the Windows Start menu, point to Settings, point to Control Panel, then click Scheduled Tasks.
For Windows Vista: a. Click the Windows Start menu, click Settings, point to Control Panel, then click System and Maintenance. Click Administrative Tools and click Schedule tasks.
2. Double-click Add Scheduled Task. 3. Complete the options on the wizard. a. When asked to click the program you want Windows to run, click the Browse button and the Python script.
If the program you want to run is a Python script with arguments For more information about scheduled tasks, see the Windows Help. Steps: 1. On the last pane of Schedule Task Wizard, check the Open advanced properties check box. 2. On the Task Properties dialog box, change Run to contain the Python executable, your script, and the arguments you want the script to run, as shown in the following example. c:\python26\python.exe c:\gisWork\myscript.py c:\gisWork\gdb.mdb\counties 10
Describing data Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Accessing geographic data in Python
Geoprocessing tools work with all types of data, such as geodatabase feature classes, shapefiles, rasters, tables, topologies, and networks. Each piece of data has particular properties that can be accessed and used to control the flow of a script or used as the parameters of a tool. For example, the output feature type of the Intersect tool is dependent on the shape type of the data being intersected— point, line, or polygon. When the Intersect tool is run within a script on a list of input datasets, you must be able to determine the shape types of the input datasets so the correct output shape type can be set. You can use the Describe function to determine the shape types of all the input datasets. Using the Describe function, a dataset's properties can be determined and used to make decisions. For instance, in the following example, the script uses Describe to evaluate the shape type (polyline, polygon, point, and so on) of input data and determine which geoprocessing tool is appropriate.
import arcpy inFC = arcpy.GetParameterAsText(0) outFC = arcpy.GetParameterAsText(1) # Describe a feature class # desc = arcpy.Describe(inFC) # Get the shape type (Polygon, Polyline) of the feature class # type = desc.shapeType # If the shapeType is Polygon convert the data to polylines using the FeatureToLine tool, # otherwise just copy the data using the CopyFeatures tool. # if type == "Polygon": arcpy.FeatureToLine_management(inFC, outFC) else: arcpy.CopyFeatures_management(inFC, outFC)
The Describe function returns a Describe object, with multiple properties, such as data type, fields, indexes, and many others. Its properties are dynamic, meaning that depending on what data type is described, different describe properties will be available for use. Describe properties are organized into a series of property groups. Any particular dataset will acquire the properties of at least one of these groups. For instance, if describing a geodatabase feature class, you could access properties from the GDB FeatureClass, FeatureClass, Table, and Dataset property groups. All data, regardless of the data type, will always acquire the generic Describe Object properties. Describe Object PropertiesArcInfo Item PropertiesArcInfo Table PropertiesCAD Drawing Dataset PropertiesCAD FeatureClass PropertiesCoverage FeatureClass PropertiesCoverage PropertiesDataset PropertiesdBase Table PropertiesFeatureClass PropertiesFile PropertiesFolder PropertiesGDB FeatureClass PropertiesGDB Table PropertiesGeometric Network PropertiesLayer PropertiesMap Document PropertiesMosaic Dataset PropertiesNetwork Analyst Layer PropertiesNetwork Dataset PropertiesPrj File PropertiesRaster Band PropertiesRaster Catalog PropertiesRaster Dataset PropertiesRelationshipClass PropertiesRepresentationClass PropertiesSchematic Dataset PropertiesSchematic Diagram PropertiesSchematic Folder PropertiesSDC FeatureClass PropertiesShapefile FeatureClass PropertiesTable PropertiesTableView PropertiesText File PropertiesTin PropertiesTool PropertiesToolbox PropertiesTopology PropertiesVPF Coverage PropertiesVPF FeatureClass PropertiesVPF Table PropertiesWorkspace Properties
Working with property sets
Some properties are members of a Property set. For example, the tolerances of a coverage or the connection properties of a workspace are returned as Property sets. Property sets have named properties that can be called from the property set itself. In the example below, the tolerances of a coverage (Fuzzy, Dangle, TicMatch, Edit, NodeSnap, Weed, Grain, and Snap) are printed to the standard output:
import arcpy # Create a describe object from a coverage feature class # desc = arcpy.Describe("D:/St_Johns/covs/freshwater") # Create a property set of coverage tolerances # covTols = desc.tolerances # Print each coverage tolerance # print covTols.fuzzy print covTols.dangle print covTols.ticMatch print covTols.edit print covTols.nodeSnap print covTols.weed print covTols.grain print covTols.snap
Property sets are typically used when the properties of the object being described vary. The connection properties (server, instance, database, user, and version) of an enterprise geodatabase workspace vary depending on the type of ArcSDE database that is being used, so it is well suited to a property set that has no predefined set of values.
Related Topics Describe
Using fields and indexes Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Accessing geographic data in Python
When described, feature classes and tables have a fields property that returns a Python list of field objects, and an indexes property that returns a Python list of index objects. Each field or index object has a number of properties that can be used to explore the object. Alternatively, the ListFields and ListIndexes functions can be used to create the same lists. The following example shows how to create a field list and loop through the contents to find a specific field.
import arcpy fc = "D:/St_Johns/data.gdb/roads"
# Describe a feature class # desc = arcpy.Describe(fc) # Get a list of field objects from the describe object # fields = desc.fields for field in fields: # Check the field name, perform a calculation when finding the field 'Flag' # if field.name == "Flag": # Set the value for the field and exit loop # arcpy.CalculateField_management(fc, "Flag", "1") break
The properties of the field and index objects are listed below: Property
Explanation
Name
The name of the field.
AliasName
The alias name of the field.
Domain
The name of the associated domain.
Editable
True if the field is editable.
IsNullable
True if the field is nullable.
Required
True if the field is required.
Length
The field's length.
Type
SmallInteger, Integer, Single, Double, String, Date, OID, Geometry, BLOB.
Scale
The field's scale.
Precision
The field's precision.
Field properties
Property
Explanation
Name
The name of the index.
IsAscending
True if the index is sorted in ascending order.
IsUnique
True if the index is unique.
Fields
A Python list of field objects. This is the same as using Describe's field property.
Index properties
Tip: ListFields and ListIndexes can be used to limit the results based on name and type.
Related Topics ListFields ListIndexes Listing data
Using the spatial reference class Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Accessing geographic data in Python
Geographic datasets, such as feature classes, coverages, and rasters, have a spatial reference that defines a dataset's coordinate system, x,y domain, m-domain, and z-domain. Each part of the spatial reference has a number of properties, especially the coordinate system, which defines what map projection options are used to define horizontal coordinates. All this information is available from the spatial reference property, which is actually another object containing a number of properties.
import arcpy # Describe a feature class # fc = "D:/St_Johns/data.gdb/roads" desc = arcpy.Describe(fc) # Get the spatial reference # sr = desc.spatialReference # Check if the feature class is in projected space # if sr.type == "Projected": arcpy.Copy_management(fc,"D:/St_Johns/data.gdb/roads_UTM")
Creating a spatial reference using a projection (.prj) file It is not often practical to keep all details of a spatial reference inside a Python script. By using a projection file as an argument to the SpatialReference class, you can quickly complete the properties of a spatial reference and use the object as input to a geoprocessing tool. In the following example, the spatial reference is constructed using a projection file supplied as an input argument.
import arcpy
inputWorkspace = "c:/temp" outputName = "rivers.shp" # Get the input workspace, the output name for the new feature class # and path to an input projection file # inputWorkspace = arcpy.GetParameterAsText(0) outputName = arcpy.GetParameterAsText(1) prjFile = arcpy.GetParameterAsText(2) # Use the the projection file as input to the SpatialReference class # spatialRef = arcpy.SpatialReference(prjFile) # Use the SpatialReference object to create a new feature class with a # specific coordinate system # arcpy.CreateFeatureClass_management(inputWorkspace, outputName, "POLYLINE", "", "", "", spatialRef) Note: For a full list of properties and methods, see SpatialReference class. Note: Spatial references are sometimes referred to as Projection Engine strings. The Projection Engine (PE) is a library of code that all of ArcGIS uses for defining map projections and transforming from one projection to another.
Related Topics SpatialReference
How to use feature sets and record sets Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Accessing geographic data in Python
FeatureSet objects are lightweight representations of a feature class. They are a special data element that contains not only schema (geometry type, fields, spatial reference) but also the data, including the geometry itself. RecordSet objects are similar but comparable to a table. When used in a script tool, feature sets and record sets can be used to interactively define features and records. Note: Server tools communicate using feature sets and record sets, meaning data must be created using or loaded into these objects when using server tools. The FeatureSet and RecordSet classes have the same two methods. Property
Explanation
load
Import a feature class into the FeatureSet object.
save
Export to a geodatabase feature class or shapefile.
FeatureSet class
Property
Explanation
load
Import a feature class into the RecordSet object.
save
Export to a geodatabase table or dBASE file.
RecordSet class
Creating and using FeatureSet and RecordSet objects FeatureSet and RecordSet objects can be created in a number of ways depending on need and application. The load method can be used to add new features or rows to the object, and the save method can be used to preserve the features or rows on disk. In addition, the input feature class or table can also be supplied as argument to the class. Both FeatureSet and RecordSet objects can also be used directly as input to a geoprocessing tool. Create an empty feature set.
import arcpy # Create an empty FeatureSet object # featSet = arcpy.FeatureSet()
Construct a feature set from an input feature class
import arcpy # Construct a FeatureSet from a feature class # featSet = arcpy.FeatureSet("c:/base/roads.shp")
GetParameterValue function If you want to create a feature set or record set with the specific schema of a tool's input, use GetParameterValue() to create an empty FeatureSet or RecordSet object with the appropriate schema.
import arcpy # Add a custom server toolbox # arcpy.ImportToolbox("http://flame7/arcgis/services;BufferByVal", "servertools")
# Get the default input from a tool # inRecSet = arcpy.GetParameterValue("bufferpoints", 0)
Learn more about the GetParameterValue function Using the GetParameter function When working with script tools, FeatureSet and RecordSet objects can be acquired from the tool using the GetParameter function.
import arcpy # Get the RecordSet from a script tool # inRecSet = arcpy.GetParameter(0)
Learn more about the GetParameter function Result class' getInput/getOutput methods When using a server tool, you must explicitly ask for its output. When the output is a feature set or record set, the Result class' getOutput() method can be used to return the tool's output in a FeatureSet or RecordSet object. As well, the Result object's getInput method can be used to get an input FeatureSet or RecordSet object. Learn more about getting results from a geoprocessing tool
import arcpy import time # Add a toolbox from a server # arcpy.ImportToolbox("http://flame7/arcgis/services;GP/BufferByVal", "servertools") # Use GetParameterValue to get a featureset object with the default schema of the # first parameter of the tool 'bufferpoints' # inFeatureSet = arcpy.GetParameterValue("bufferpoints", 0) # Load a shapefile into the featureset # inFeatureSet.load("c:/base/roads.shp") # Run a server tool named BufferPoints with featureset created above # result = arcpy.BufferPoints_servertools(inFeatureSet, "5 feet")
# Check the status of the result object every 0.2 seconds until it has a value # of 4 (succeeded) or greater # while result.status < 4: time.sleep(0.2) # Get the output FeatureSet back from the server and save to a local geodatabase # outFeatSet = result.getOutput(0) outFeatSet.save("c:/temp/base.gdb/towers_buffer")
Learn more about the Result class
Example: Loading data to a feature set using cursors and an in-memory feature class import arcpy from arcpy import env env.overwriteOutput = True arcpy.ImportToolbox("http://flame7/arcgis/services;BufferByVal", "server") # List of coordinates # coordinateL = ["-117.196717216;34.046944853","-117.186226483;34.046498438",\ "-117.179530271;34.038016569","-117.187454122;34.039132605",\ "-117.177744614;34.056765964","-117.156205131;34.064466609",\ "-117.145491191;34.068261129","-117.170825195;34.073618099",\ "-117.186784501;34.068149525","-117.158325598;34.03489167"] # Create an in_memory feature class to initially contain the coordinate pairs # fc = arcpy.CreateFeatureClass_management("in_memory", "tempfc", "POINT") # Open an insert cursor # cur = arcpy.InsertCursor(fc) pointArray = arcpy.Array() pnt = arcpy.Point() # Iterate through list of coordinates and add to cursor # for coords in coordinateL: x,y = coords.split(';')
pnt.ID = coordinateL.index(coords) + 1 pnt.X = x pnt.Y = y feat = cur.newRow() feat.shape = pnt cur.InsertRow(feat) pointArray.add(pnt) # Delete the cursor del cur # Create a FeatureSet object and load in_memory feature class # featSet = arcpy.FeatureSet() featSet.load(fc) results = arcpy.BufferPoints_servertools(featSet)
Related Topics A quick tour of using Feature Set and Record Set
Checking for the existence of data Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Accessing geographic data in Python
To check for the existence of data in a script, use the Exists function. Exists(dataset) Tests for the existence of feature classes, tables, datasets, shapefiles, workspaces, layers, and other files in the current workspace at the time of execution. The function returns a Boolean indicating whether the element exists. Exists function
When checking for the existence of geographic data, you must use the Exists function, since it recognizes catalog paths. A catalog path is a pathname that only ArcGIS recognizes. For example: D:\Data\Final\Infrastructure.gdb\EastValley\powerlines refers to the powerlines feature class found in the EastValley feature dataset in the file geodatabase Infrastructure. This is not a valid system path as far as the Windows operating system is concerned, since Infrastructure.gdb (a folder) does not contain a file named Infrastructure. In short, Windows doesn't know about feature datasets or feature classes, so you cannot use Python existence functions like os.path.exists. Of course, everything in ArcGIS knows how to deal with catalog paths. UNC (Universal Naming Convention) paths can also be used.
import arcpy from arcpy import env env.workspace = "d:/St_Johns/data.gdb"
fc = "roads" # Clip a roads feature class if it exists # if arcpy.Exists(fc): arcpy.Clip_analysis(fc,"urban_area","urban_roads") Tip: The Exists function honors the geoprocessing workspace environment allowing you to just specify the base name. If the data resides in an enterprise geodatabase, the name must be fully qualified.
import arcpy from arcpy import env env.workspace = "Database Connections/Bluestar.sde" fc = "ORASPATIAL.Rivers" # Confirm that the feature class exists # if arcpy.Exists(fc): print "Verified %s exists" % fc
In scripting, the default behavior for all tools is to not overwrite any output that already exists. This behavior can be changed by setting the overwriteOutput property to True (arcpy.env.overwriteOutput = True). Attempting to overwrite when the overwriteOutput is False will cause a tool to fail.
Related Topics Exists Paths explained: Absolute, relative, UNC, and URL Setting paths to data in Python
Accessing data using cursors Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Accessing geographic data in Python
A cursor is a data access object that can be used to either iterate over the set of rows in a table or insert new rows into a table. Cursors have three forms: search, insert, or update. Cursors are commonly used to read existing geometries and write new geometries. Each type of cursor is created by a corresponding ArcPy function (SearchCursor, InsertCursor, or UpdateCursor) on a table, table view, feature class, or feature layer. A search cursor can be used to retrieve rows. An update cursor can be used to positionally update and delete rows, while an insert cursor is used to insert rows into a table or feature class. Cursor
Explanation
InsertCursor(dataset, {spatial_reference})
Inserts rows
SearchCursor(dataset, {where_clause}, {spatial_reference}, {fields},
Read-only access
{sort_fields}) UpdateCursor(dataset, {where_clause}, {spatial_reference}, {fields},
Updates or deletes
{sort_fields})
rows
Cursor functions
Caution: All updates or insertions to a table are done outside an edit session in ArcGIS. Changes made are permanent and cannot be undone. Note: Cursors honor layer/table view definition queries and selections. The cursor object only contains the rows that would be used by any geoprocessing tool during an operation. All three cursor functions create a cursor object that can be used to access row objects. The methods supported by the row object depend on the type of cursor created. Cursors can only be navigated in a forward direction; they do not support backing up and retrieving rows that have already been retrieved or making multiple passes over data. If a script needs to make multiple passes over the data, the application must reexecute the cursor function. If both executions are made within the same edit session (or database transaction with the appropriate level of isolation), the application is guaranteed not to see any changes made to the data by other concurrently executing applications. Search or update cursors are able to be iterated with a For loop or in a While loop using the cursor's next method to return the next row. When using the next method on a cursor to retrieve all rows in a table containing N rows, the script must make N calls to next. A call to next after the last row in the result set has been retrieved returns None, which is a Python data type that acts here as a placeholder. This example shows a simple cursor operation. It prints out name and value of each string field for each row in a feature class.
import arcpy fc = "D:/st_johns/roads.shp" # Create a search cursor # rows = arcpy.SearchCursor(fc) # Create a list of string fields fields = arcpy.ListFields(fc, "", "String") for row in rows: for field in fields: if field.type != "Geometry":
print "%s: Value = %s" % (field.name, row.getValue(field.name))
All row objects retrieved from a table logically contain the same ordered set of fields. In particular, the order of fields in a row of a table is the same as the order of fields returned by the ListFields function. The row will only contain the visible fields of the table used to create the cursor, with each field name being a property of the object.
The cursor object SearchCursor, UpdateCursor, and InsertCursor functions create a cursor object (sometimes referred to as an enumeration object) that can be used to iterate through the records. The methods of the cursor object created by the various cursor functions vary depending on the type of cursor created. The following chart shows the methods supported for each cursor type: Cursor type
Method
Effect on position
Search
next
Retrieves the next row object
Insert
newRow
Creates an empty row object
insertRow
Inserts a row object into the table
next
Retrieves the next row object
updateRow
Updates the current row with a modified row object
deleteRow
Removes the row from the table
next
Retrieves the next row object
Update
insertRow The insert cursor is used to create new rows and insert them. The basic flow of processing is to use the newRow method on the cursor object in which rows are to be inserted. This new row object contains all the fields found on the table, and you can assign values to the fields on the row before inserting the row using insertRow.
import arcpy # Create insert cursor for table # rows = arcpy.InsertCursor("D:/St_Johns/data.gdb/roads_lut") x = 1 # Create 25 new rows. Set the initial row ID and distance values # while x 0 and \ len(arcpy.ListFields(input,"Shape_length")) > 0: # Add the new field and calculate the value # arcpy.AddField_management(input, fieldname, "double") arcpy.CalculateField_management(input,fieldname, "[Shape_area] / [Shape_length]") else: raise FieldError except ShapeError: print "Input does not contain polygons"
except FieldError: print "Input does not contain shape area and length fields" except: print arcpy.GetMessages(2)
Whenever a script is updating a dataset, such as a feature class or table, be careful to avoid situations in which the dataset is locked. If you have opened a personal or file geodatabase in ArcCatalog, a script will not be able to update any of the geodatabase's contents until it is deselected and the folder is refreshed or ArcCatalog is closed. This includes script tools.
Parsing table and field names Scripts should use the ParseTableName() and ParseFieldName() functions to split the fully qualified names for a dataset or for a column in a table into its components (database, owner, table, and column). Scripts that need to be RDBMS independent should not assume that the period (.) is the delimiter used to separate the components of a fully qualified dataset name. ArcGIS applications always use fully qualified names, so if your script is being used as the source of a script tool, any feature class name, for example, must be parsed if the script needs to determine the name of the feature class without the user and database names. In the example below, the script is checking the input feature class for specific user names. The script could use the parsing functions of Python to split the qualified name, but it would then assume a specific syntax, which may change if another database type is used. ParseTableName() returns a single string with the database name, owner name, and table name separated by commas. ParseFieldName() returns the table name and the field name, also separated by commas. A script can then reliably parse the returned string, since these functions always return the same formatted string. A string in Python has a number of native methods for manipulation. In this example, the split method is used to create a Python list, using the comma as the delimiter. Function
Explanation
ParseFieldName(name,
Parses a fully qualified field name into its components
{workspace})
(database, owner name, table name, field name) depending on the workspace
ParseTableName(name,
Parses a table name into its components (database, owner,
{workspace})
table) depending on the workspace
Parse functions
# Append input feature class to another feature class and update field # import arcpy from arcpy import env import sys # Get the name of the input feature class and parse it.
# env.workspace = os.path.dirname(arcpy.GetParameterAsText(0)) # Split ParseTableName's returned value to determine database, owner, and # featureclass # fullname = arcpy.ParseTableName(os.path.basename(arcpy.GetParameterAsText(0))) database, owner, featureclass = fullname.split(",") # Validate the name of the feature class that will be appended to and set # the workspace using the administrator's connection # env.workspace = "Database Connections/Trans_admin.sde" appendFC = arcpy.ValidateTableName("common", "roads") try: if owner == "TJohnson": arcpy.CalculateField_management(fullname, "AppendedBy", owner) arcpy.Append_management(fullname, appendFC) elif owner == "RSmith": arcpy.CalculateField_management(fullname, "AppendedBy", owner) arcpy.Append_management(fullname, appendFC) else: arcpy.AddError("Unknown user of input feature class") except: arcpy.AddError(arcpy.GetMessages(2))
A Python list is an ordered collection of any type of object, such as strings or numbers. Lists are zero based and can be used to effectively handle arrays of values when the order of the list's contents is known. Scripts that are used as the source of script tools can make some assumptions about their input argument values. Paths to data are always fully qualified by the geoprocessing framework. Scripts that may be run outside an ArcGIS application should not make the same assumption.
Related Topics A quick tour of the geodatabase Specifying a query in Python Table basics
Executing SQL using an ArcSDE connection Resource Center » Professional Library » Geoprocessing » Geoprocessing with Python » Accessing geographic data in Python
Sometimes when working with tables that are not versioned, it may seem easier to query a table in a database using Structured Query Language (SQL) rather than using one of the geoprocessing tools. The ArcSDESQLExecute object supports the execution of most SQL statements and will return to the user the results of those statements. The object will return a list of lists in the case where the statement returns
rows from a table; for statements that do not return rows, it will return an indication of the success or failure of the statement (True for success, None for failure). Caution:
ArcSDE and GDB system tables should not be altered using anything other than ArcGIS software. Corruption can occur if these system tables are edited directly using SQL.
Edits on versioned data performed using SQL should only be done through multiversioned views.
For geodatabases implemented in a relational database management system (DBMS) using DBMS data types and table formats, the DBMS's own SQL may be used to work with the information stored in the database.
Accessing the information in a geodatabase via SQL allows external applications to access the tabular data managed by the geodatabase. These external applications may be nonspatial database applications or custom spatial applications developed in an environment other than ArcObjects. Be aware, though, that SQL access to the geodatabase bypasses geodatabase functionality, such as topology, networks, terrains, or other class or workspace extensions.
It may be possible to use DBMS features such as triggers and stored procedures to maintain the relationships between tables needed for certain geodatabase functionality. However, executing SQL commands against the database without taking this extra functionality into account—for example, issuing INSERT statements to add records to a business table—will circumvent geodatabase functionality and possibly corrupt the relationships between data in your geodatabase.
Before attempting to access or modify any ArcSDE or GDB objects, read all ArcSDE and geodatabase documentation about using SQL against ArcSDE or GDB objects in the DBMS.
Property transactionAutoCommit The autocommit interval. This can be used to force intermediate commits after a specified number of features have been modified. ArcSDESQLExecute properties
Methods commitTransaction()
No DML statements will be committed until the commitTransaction method is called. Note: A commit may also occur when the connection to ArcSDE is terminated (check specific DBMS documentation to see how each DBMS deals with a disconnect while in a transaction).
execute(sql_statement) Sends the SQL statement to the database via an ArcSDE connection. If execute is run outside of a transaction, a commit will automatically take place once the SQL DML (INSERT, UPDATE, DELETE) statement has been executed.
rollbackTransaction()
Rollback any DML operations to the previous commit.
startTransaction()
To control when your changes are committed to the database, call the startTransaction method before calling execute. This starts a transaction, and no DML statements will be committed until the commitTransaction method is called.
ArcSDESQLExecute methods
The execute method sends the SQL statement to the database via an ArcSDE connection. If execute is run outside a transaction, a commit will automatically take place once the SQL DML (INSERT, UPDATE, DELETE) statement has been executed. ArcSDESQLExecute supports the ArcSDE Transaction model. Transactions are a property of an ArcSDE connection and bind operations so that an entire set of changes is either recorded or rejected. For example, if a set of parcels is being updated in a particular order, you can use a transaction to define the beginning and end of the changes so that all changes are posted together. If a set of changes can't be successfully inserted, the entire transaction is rejected. All transactions end when a user disconnects. ArcSDESQLExecute uses the provided ArcSDE API functions to start, commit, and rollback transactions. If you want to control when your changes are committed to the database, call the startTransaction method before calling execute. This starts a transaction, and no DML statements will be committed until the commitTransaction method is called. A commit may also occur when the connection to ArcSDE is terminated (check specific DBMS documentation to see how each DBMS deals with a disconnect while in a transaction). Within a transaction, it is also possible to rollback any DML operations to the previous commit. An autocommit interval property, transactionAutoCommit, is available. This can be used to force intermediate commits after a specified number of features have been modified. See your specific DBMS SQL Reference guide for help writing SQL statements.
Examples Execute a list of SQL statements
import arcpy from arcpy import env import sys try: # Make data path relative # env.workspace = sys.path[0] # Two ways to create the object, which also creates the connection to ArcSDE. # Using the first method, pass a set of strings containing the connection properties: # ,,,,
# sdeConn = arcpy.ArcSDESQLExecute("gpserver3","5151","#","toolbox","toolbox") # Using the second method pass the path to a valid ArcSDE connection file # sdeConn = arcpy.ArcSDESQLExecute("data\Connection to GPSERVER3.sde") # Get the SQL statements, separated by ; from a text string. # SQLStatement = arcpy.GetParameterAsText(0) SQLStatementList = SQLStatement.split(";") print "+++++++++++++++++++++++++++++++++++++++++++++\n" # For each SQL statement passed in, execute it. # for sql in SQLStatementList: print "Execute SQL Statement: " + sql try: # Pass the SQL statement to the database. # sdeReturn = sdeConn.execute(sql) except Exception, ErrorDesc: print ErrorDesc sdeReturn = False # If the return value is a list (a list of lists), display each list as a row from the # table being queried. if isinstance(sdeReturn, list): print "Number of rows returned by query: " + len(sdeReturn), "rows" for row in sdeReturn: print row print "+++++++++++++++++++++++++++++++++++++++++++++\n" else: # If the return value was not a list, the statement was most likely a DDL statment. # Check its status. if sdeReturn == True: print "SQL statement: " + sql + " ran sucessfully." print "+++++++++++++++++++++++++++++++++++++++++++++\n" else: print "SQL statement: " + sql + " FAILED." print "+++++++++++++++++++++++++++++++++++++++++++++\n" except Exception, ErrorDesc: print Exception, ErrorDesc except: print "Problem executing SQL."
Conditional update using a transaction
# WARNING - DO NOT USE ON VERSIONED TABLES OR FEATURE CLASSES. # DO NOT USE ON ANY ArcSDE or GDB SYSTEM TABLES. # DOING SO MAY RESULT IN DATA CORRUPTION. import arcpy from arcpy import env import sys try: # Make data path relative (not relevant unless data is moved here and paths modified) # env.workspace = sys.path[0] #Column name:value that should be in the record. # SQLvalues = {"STREET_NAM":"'EUREKA'"} #Value that is incorrect if found in the above column. # badVal = "'EREKA'" #List of tables to look in for the bad value. # tableList = ["streetaddresses_blkA","streetaddresses_blkB", "streetaddresses_blkC"] # Two ways to create the object, which also creates the connection to ArcSDE. # Using the first method, pass a set of strings containing the connection properties: # ,,,, # sdeConn = arcpy.ArcSDESQLExecute("gpserver3","5151","#","toolbox","toolbox") # Using the second method pass the path to a valid ArcSDE connection file # sdeConn = arcpy.ArcSDESQLExecute("data\Connection to GPSERVER3.sde") for tbl in tableList: print "++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++" for col, val in SQLvalues.items(): print "++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++"
#Check for the incorrect value in the column for the specific rows. If the table contains the #incorrect value, correct it using the update SQL statement. # print "Analyzing table " + tbl + " for bad data: Column:" + col + " Value: " + badVal try: sql = "select OBJECTID," + col + " from " + tbl + " where " + col + " = " + badVal print "Attempt to execute SQL Statement: " + sql sdeReturn = sdeConn.execute(sql) except Exception, ErrorDesc: print ErrorDesc sdeReturn = False if isinstance(sdeReturn, list): if len(sdeReturn) > 0: print "Identified " + str(len(sdeReturn)) + " rows with incorrect data. Starting transaction for update." # Start the transaction # sdeConn.startTransaction() print "Transaction started....." # Perform the update # try: sql = "update " + tbl + " set " + col + "=" + str(val) + " where " + col + " = " + badVal print "Changing bad value: " + badVal + " to the good value: " + val + " using update statement:\n " + sql sdeReturn = sdeConn.execute(sql) except Exception, ErrorDesc: print ErrorDesc sdeReturn = False # If the update completed sucessfully, commit the changes. If not, rollback. # if sdeReturn == True: print "Update statement: \n" + sql + " ran successfully." # Commit the changes # sdeConn.commitTransaction() print "Commited Transaction" # List the changes. # try: print "Displaying updated rows for visual inspection."
sql = "select OBJECTID," + col + " from " + tbl + " where " + col + " = " + val print "Executing SQL Statement: \n" + sql sdeReturn = sdeConn.execute(sql) except Exception, ErrorDesc: print ErrorDesc sdeReturn = False if isinstance(sdeReturn, list): print len(sdeReturn), "rows" for row in sdeReturn: print row print "+++++++++++++++++++++++++++++++++++++++++++++\n" else: if sdeReturn == True: print "SQL statement: \n" + sql + "\nran successfully." print "+++++++++++++++++++++++++++++++++++++++++++++\n" else: print "SQL statement: \n" + sql + "\nFAILED." print "+++++++++++++++++++++++++++++++++++++++++++++\n" print "+++++++++++++++++++++++++++++++++++++++++++++\n" else: print "SQL statement: \n" + sql + "\nFAILED. back all changes." # Rollback changes # sdeConn.rollbackTransaction() print "Rolled back any changes." print "+++++++++++++++++++++++++++++++++++++++++++++\n" else: print "No records required updating."
Rolling
# Disconnect and exit del sdeConn print "++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++" except Exception, ErrorDesc: print Exception, ErrorDesc except: print "Problem executing SQL."
Related Topics ArcSDESQLExecute
