ArcGIS 10 introduced 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 toolbox
- Cartography toolbox
- Conversion toolbox
- Data Management toolbox
- Editing toolbox
- Geocoding toolbox
- Linear Referencing toolbox
- Multidimension toolbox
- Spatial 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 data access module (arcpy.da), mapping module (arcpy.mapping), an ArcGIS Spatial Analyst extension module (arcpy.sa), and an ArcGIS Network Analyst extension module (arcpy.na).
To import an entire module, use the import module:
# Import only arcpy.mapping
#
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.
# Import arcpy and the sa module as *
#
import arcpy
from arcpy.sa import *
arcpy.CheckOutExtension("spatial")
# Get input parameters
#
inRaster1 = arcpy.GetParameterAsText(0)
inRaster2 = arcpy.GetParameterAsText(1)
inRaster3 = 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 parameters
#
inRaster1 = arcpy.GetParameterAsText(0)
inRaster2 = arcpy.GetParameterAsText(1)
inRaster3 = 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):
- Paths specified in the PYTHONPATH system environment variable
- A set of standard Python folders (the current folder, c:\python2x\lib, c:\python2x\Lib\site-packages, and so on)
- 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.3.1 products will install Python 2.7 if it isn't already installed. The installation will also add the file Desktop10.3.pth (or Engine10.3.pth or Server10.3.pth) into python27\Lib\site-packages. The contents of this file include two lines containing the paths to your system's ArcGIS installation's arcpy and bin folders. These two paths are required to import ArcPy successfully in Python version 2.7.
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.