ArcPy is a Python module that is used to perform geographic data analysis, conversion and management in Python. It is imported during the installation of ArcGIS.
The ArcPy module contains functions that are necessary to perform scripting tasks such as listing data, describing data, and validating table and field names.
ArcPy can be used to run a tool, for example, by typing in arcpy plus a dot at the prompt. The console has autocomplete, so typing arcpy. Displays possible choices.
Figure 1: Autocomplete Feature
Typing text into the window helps narrow down what is shown on the list. When an item is chosen and a parenthesis added, the help context for that command will be displayed.
Figure 2: Invoking Help
This is a great way to check all of the inputs to a function, for example, especially if you find it is not working properly in your script. Each of the inputs is highlighted as it is typed, as shown in Figure 3.
Additional information about each input appears at the bottom of the window. Other options may also pop up, such as layers currently on the map, and inputs that only take several different choices.
ESRI’s help files can be useful as well; they are easy to read and provide examples. Within Python, there is also a help command. Type in help (arcpy.Buffer_analysis) to get a description of the function in the Python command window as shown in Figure 3.
Figure 3: Command line Help
Watch the video, The Dot Operator in Python and ArcPy (10:53), for a demonstration on how to use the dot operator in ArcPy and Python.
Understanding a Module
A module is a group of related functions that Python can import into a script. Modules may contain many different functions, so keeping only those modules used by your code will help keep the program running faster and avoid calling the wrong function.
Above is a command line that will appear in almost any script that relates to ArcMap. This command line allows Python to use all of the functions that ESRI has made available through toolboxes and data sources. Without this line at the top, you will get an error when trying to run any of these functions.
With the above line, to create a feature class, you would need to type something like:
|arcpy.CreateFeatureclass_management(“C:/output”, “habitatareas.shp”, “POLYGON”, “study_quads.shp”, “DISABLED”, “DISABLED”, “C:/workspace/landuse.shp”)|
In examples or other scripts you may also see something like this:
|from arcpy import CreateFeatureclass_management|
This tells Python to let you use exactly one function from arcpy without needing to call arcpy anymore and allows you to shorten the function call slightly:
|CreateFeatureclass_management(“C:/output”, “habitatareas.shp”, “POLYGON”, “study_quads.shp”, “DISABLED”, “DISABLED”, “C:/workspace/landuse.shp”)|
You can also use a wildcard to import all of the functions from arcpy, like this:
|from arcpy import|
This imports all of the functions and variables within arcpy and allows Python to use them directly without differentiating them as being part of arcpy.
Different libraries may have functions with the same name, and so importing * on every library could cause confusion and can also slow down the code as Python has more function and variable names to compare with every instruction line. Importing specific functions can be useful and save some typing, but only use it on those functions that are called the most in your code.
If you are using functions from within ArcGIS Desktop, you will not need to import arcpy since it is already imported into the GIS program.
To open the console within ArcMap, go to Windows->Console. The window that opens is a good place to test out commands for the right syntax or inputs. This window will auto-complete tool names and show information on the right about the inputs required to run arcpy commands. This window has access to the currently open map by using the special keyword “CURRENT” as an input whenever a map is required for a tool. This keyword only works within ArcMap, so it must be used as a tool running a script or within the console window. Using the “CURRENT” keyword doesn’t work in other IDEs or when running a script from regular windows command line.
To read more about importing ArcPy and other modules, browse to the ArcGIS Resource Center.
- Click on Desktop > Geoprocessing > ArcPy > Introduction > What is ArcPy? in the left column.
- Select Importing ArcPy from the Related Topics list.
This document provides examples of importing modules and also lists all of the geoprocessing tools that can be run once ArcPy is imported.
A Python core module that is very useful is sys, which must be used if any arguments or parameters are required to run the tool or script.
sys.argv is always the script name that is running.
sys.argv is the first argument sent to the script.
There are other, more advanced functions within sys that can modify input and output and some functions to find the path of python or the version. These may not be important until more advanced scripts are being written, but it is mentioned here.
Another very useful module is os, which helps maintain cross-platform scripting, so the scripts can be run on MacOS, Windows, or Linux. Some of the more useful functions include:
os.path has functions related to files and folders.
os.path.isdir checks to see if a path leads to a folder.
#Do Some work on ‘C:/Some/Path’
os.path.join will concatenate multiple parts of a path together, such as a folder and filename.
|fullpath = os.path.join(my_path_variable, my_extra_folder, my_file_name)|
os.sep is the file system separator, such as the backslash (\) in Windows.
|fullpath = my_path + os.sep + my_filename|
os.listdir gives a list of everything in a specific folder.
|dir_list = os.listdir(input_folder)|
os.walk will return three things, the root folder, all the directories, and all the files
|for root, dirs, files in os.walk(‘C:/Some/Path’)|
The library zipfile is useful for automating tasks where a file needs to be unzipped from an archived or zipped into an archive.
A function performs a particular task within a program. All geoprocessing tools are functions within ArcyPy. There are also some functions incorporated into ArcPy which are only available through a Python script. Functions can be used to list certain datasets or to retrieve a dataset’s properties, for example. Browse to the ArcGIS Resources website.
- Click Desktop > Geoprocessing > ArcPy> ArcPy functions.
- Click on the link to see the Alphabetical list of ArcPy functions.
A function contains one focused piece of functionality in a reusable section of code. The idea is that you write the function once, then use, or call, it throughout your code whenever you need to. You can put a group of related functions in a module so you can use them in many different scripts. When used appropriately, functions eliminate code repetition and make the main body of your script shorter and more readable.
Functions exist in many programming languages, and each has its way of defining a function. In Python, you define a function using the def statement. Each line in the function that follows the def is indented.
Here’s a simple function that reads the radius of a circle and reports the circle’s approximate area. (Remember that the area is equal to pi [3.14159…] multiplied by the square [** 2] of the radius.)
|>>> def findArea(radius):
… area = 3.14159 * radius ** 2
… return area
Notice from the above example that functions can take parameters or arguments. When you call the above function, you supply the radius of the circle in parentheses. The function returns the area (notice the return statement, which is new to you).
Thus, to find the area of a circle with a radius of 3 inches, you could make the function call findArea(3) and get the return value 28.27431 (inches).
It’s common to assign the returned value to a variable and use it later in your code. For example, you could add these lines in the Interactive Window:
|>>> aLargerCircle = findArea(4)
>>> print a larger circle
A function is not required to return any value. For example, you may have a function that takes the path of a text file as a parameter, reads the first line of the file, and prints that line to the Interactive Window. Since all the printing logic is performed inside the function, there is really no return value.
Neither is a function required to take a parameter. For example, you might write a function that retrieves or calculates some static value. Try this in the Interactive Window:
|>>> def getCurrentPresident():
… return “Barack Obama”
>>> president = getCurrentPresident()
>>> print president
The function getCurrentPresident() doesn’t take any user-supplied parameters. Its only “purpose in life” is to return the name of the current president. It cannot be asked to do anything else.
Functions and Modules
You may be wondering what advantage you gain by putting the above getCurrentPresident() logic in a function. Why couldn’t you just define a string currentPresident and set it equal to “Barack Obama?” The big reason is reusability.
Suppose you maintain 20 different scripts, each of which works with the name of the current President in some way. You know that the name of the current President will eventually change. Therefore, you could put this function in what’s known as a module file and reference that file inside your 20 different scripts. When the name of the President changes, you don’t have to open 20 scripts and change them. Instead, you just open the module file and make the change once.
As you use Python in your GIS work, you’ll probably write functions that are useful in many types of scripts. These functions might convert a coordinate from one projection to another, or create a polygon from a list of coordinates. These functions are perfect candidates for modules. If you ever want to improve your code, you can make the change once in your module instead of finding each script where you duplicated the code.
Creating a module
To create a module, create a new script in PythonWin and save it with the standard .py extension; but instead of writing start-to-finish scripting logic, just write some functions. Here’s what a simple module file might look like. This module only contains one function, which adds a set of points to a feature class given a Python list of coordinates.
|# This module is saved as practiceModule1.py
# The function below creates points from a list of coordinates
# Example list: [[-113,23][-120,36][-116,-2]]
def createPoints(coordinateList, featureClass):
# Import arcpy and create an insert cursor
with arcpy.da.InsertCursor(featureClass, (“SHAPE@”,)) as rowInserter:
# Loop through each coordinate in the list and make a point
for coordinate in coordinateList:
point = arcpy.Point(coordinate,coordinate)
The above function createPoints could be useful in various scripts, so it’s very appropriate for putting in a module. Notice that this script has to work with insert cursors and point objects, so it requires arcpy. It’s legal to import a site package or module within a module.
Also notice that arcpy is imported within the function, not at the very top of the module like you are accustomed to seeing. This is done for performance reasons. You may add more functions to this module later that do not require arcpy. You should only do the work of importing arcpy when necessary, that is, if a function is called that requires it.
The arcpy site package is only available within the scope of this function. If other functions in your practice module were called, the arcpy module would not be available to those functions. Scope applies also to variables that you create in this function, such as rowInserter.
The scope can be further limited by loops that you put in your function. The variable pointGeometry is only valid inside the for loop inside this particular function. If you tried to use it elsewhere, it would be out of scope and unavailable.
Using a module
So how could you use the above module in a script? Imagine that the module above is saved on its own as practiceModule1.py. Below is an example of a separate script that imports practiceModule1.
|# This script is saved as add_my_points.py
# Import the module containing a function we want to call
# Define point list and shapefile to edit
myWorldLocations = [[-123.9,47.0],[-118.2,34.1],[-112.7,40.2],[-63.2,-38.7]]
myWorldFeatureClass = “c:\\Data\\WorldPoints.shp”
# Call the createPoints function from practiceModule1
The above script is simple and easy to read because you didn’t have to include all the logic for creating the points. That is taken care of by the createPoints function in the module you imported, practiceModule1. Notice that to call a function from a module, you need to use the syntax module.function().