ArcPy is a Python site package that provides a useful and productive way to perform geographic data analysis, data conversion, data management, and map automation with Python.
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.
ArcPy provides access to geoprocessing tools as well as additional functions, classes, and modules that allow you to create simple or complex workflows. Broadly speaking, ArcPy is organized in tools, functions, classes, and modules.
Technically speaking, geoprocessing tools are functions available from arcpy—that is, they are accessed like any other Python function. However, to avoid confusion, a distinction is always made between tool and nontool functions (such as utility functions like ListFeatureClasses()).
- Tools are documented differently than functions. Every tool has its own tool reference page in the help system. Functions are documented in the ArcPy documentation.
- Tools return a Result object; functions do not.
- Tools produce messages, accessed through a variety of functions such as GetMessages(). Functions do not produce messages.
Running a tool
This next example shows how to execute the Buffer tool. When run in the Python window, the code will be transferred into the transcript section of the window along with the result.
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 enterprise geodatabase.
import arcpy
arcpy.AddField_management("c:/data/Portland.gdb/streets", "LENGTH_MILES", "FLOAT")
arcpy.CalculateField_management("c:/data/Portland.gdb/streets", "LENGTH_MILES", "!shape.length@miles!", "PYTHON3")
arcpy.FeatureClassToFeatureClass_conversion("c:/data/Portland.gdb/streets", "Database Connections/MySDE.sde/PortlandDataset", "streets")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 includes the path to the output dataset produced or updated by the tool. In other cases, it may contain other values, such as a number or Boolean.
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")
# prints C:\Portland\Portland_OR.gdb\riverBuf
print(result)
arcpy.Clip_analysis("streets", result, "streets_50m_of_rivers")Return the number of features.
result = arcpy.GetCount_management("streets_50m_of_rivers")
# prints 54
print(result[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")[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 = 30Using 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:
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)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
spatial_ref = arcpy.SpatialReference("Hawaii Albers Equal Area Conic")Working with modules
ArcPy includes modules covering other areas of ArcGIS. ArcPy is supported by a series of modules, including the following:
- Charts (arcpy.charts)
- Data Access (arcpy.da)
- Geocoding (arcpy.geocoding)
- Image Analysis (arcpy.ia)
- Mapping (arcpy.mp)
- Metadata (arcpy.metadata)
- Network Analyst (arcpy.nax and arcpy.na)
- Sharing (arcpy.sharing)
- Spatial Analyst (arcpy.sa)
- Workflow Manager (arcpy.wmx)
For example, the tools of the arcpy.sa and arcpy.ia module use tools from the Spatial Analyst and Image Analyst toolboxes 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.