apostila_arcpy

Prévia do material em texto

Creating Python® Scripts
for ArcGIS®
Creating Python® Scripts
for ArcGIS®
STUDENT EDITION
Copyright © 2022 Esri
All rights reserved.
Course version 8.0. Version release date August 2022.
Printed in the United States of America.
The information contained in this document is the exclusive property of Esri. This work is
protected under United States copyright law and other international copyright treaties and
conventions. No part of this work may be reproduced or transmitted in any form or by any
means, electronic or mechanical, including photocopying and recording, or by any information
storage or retrieval system, except as expressly permitted in writing by Esri. All requests should
be sent to Attention: Director, Contracts and Legal, Esri, 380 New York Street, Redlands, CA
92373-8100, USA.
Export Notice: Use of these Materials is subject to U.S. export control laws and regulations
including the U.S. Department of Commerce Export Administration Regulations (EAR).
Diversion of these Materials contrary to U.S. law is prohibited.
The information contained in this document is subject to change without notice.
Commercial Training Course Agreement Terms: The Training Course and any software,
documentation, course materials or data delivered with the Training Course is subject to
the terms of the Master Agreement for Products and Services, which is available at
https://www.esri.com/~/media/Files/Pdfs/legal/pdfs/ma-full/ma-full.pdf. The license
rights in the Master Agreement strictly govern Licensee's use, reproduction, or disclosure
of the software, documentation, course materials and data. Training Course students may
use the course materials for their personal use and may not copy or redistribute for any
purpose. Contractor/Manufacturer is Esri, 380 New York Street, Redlands, CA
92373-8100, USA.
Esri Trademarks: Esri trademarks and product names mentioned herein are subject to the
terms of use found at the following website: https://www.esri.com/legal/copyright-
trademarks.html.
Other companies and products or services mentioned herein may be trademarks, service
marks or registered marks of their respective mark owners.
https://www.esri.com/~/media/Files/Pdfs/legal/pdfs/ma-full/ma-full.pdf
https://www.esri.com/legal/copyright-trademarks.html
https://www.esri.com/legal/copyright-trademarks.html
1 Python automation for your organization
2 Using Python to access geoprocessing tools
Table of Contents
Esri resources for your organization...................................................................................... vii
Course introduction
Course introduction ...............................................................................................................1
Course goals ..........................................................................................................................1
Installing the course data .......................................................................................................1
Icons used in this workbook ..................................................................................................2
Lesson introduction .............................................................................................................1-1
Benefits of Python automation ............................................................................................1-2
The Python script creation workflow....................................................................................1-5
Integrating Python in ArcGIS Pro.........................................................................................1-7
Python development and run environments .......................................................................1-8
Accessing Python...............................................................................................................1-10
Lesson review.....................................................................................................................1-11
Answers to Lesson 1 questions..........................................................................................1-12
Lesson introduction .............................................................................................................2-1
Viewing parameters in a geoprocessing tool ......................................................................2-2
Explore the syntax of a geoprocessing tool ........................................................................2-3
Ways to use variables in a script ..........................................................................................2-5
Using variables in a script ....................................................................................................2-7
Exercise 2A: Create a simple script with variables...............................................................2-9
Create a new ArcGIS Pro project .................................................................................2-10
Add data for the affected area.....................................................................................2-10
Evaluate the syntax of the Copy Features tool ............................................................2-12
Evaluate the syntax of the Buffer tool ..........................................................................2-13
Combine the geoprocessing tools in a script ..............................................................2-15
Verify the script in PyCharm .........................................................................................2-16
Python troubleshooting techniques...................................................................................2-18
Troubleshooting errors in a script ......................................................................................2-20
Exercise 2B: Add troubleshooting techniques to a Python script .....................................2-22
Add informative comments..........................................................................................2-23
Add print functions ......................................................................................................2-24
Comment existing code...............................................................................................2-25
Create a variable ..........................................................................................................2-27
Use debugging tools in PyCharm ................................................................................2-28
Lesson review.....................................................................................................................2-29
i
3 Using Describe properties in geoprocessing tools
4 Automating Python scripts with lists
5 Working with cursors
Answers to Lesson 2 questions..........................................................................................2-30
Lesson introduction .............................................................................................................3-1
Accessing properties with a Describe function....................................................................3-2
Identify available Describe function properties ...................................................................3-4
Describe syntax and usage ..................................................................................................3-7
Accessing Describe properties ............................................................................................3-8
Exercise 3: Use the Describe function in a geoprocessing script ........................................3-9
Create a new map........................................................................................................3-10
Examine the properties of a feature class ....................................................................3-10
Use the Describe function to examine properties........................................................3-11
Create a new Pythonvalues as
the script runs.
Watching the values of the variables will help as you troubleshoot issues.
d In the Debug window, click the Resume Program button to finish running the script.
The script now runs successfully.
e After your script has finished running, close any open Python files.
f Exit PyCharm.
In this exercise, you have learned about troubleshooting techniques to plan and debug
existing code: informative comments, print functions, and commenting. You will use these
techniques in other exercises throughout this course.
Lesson 2
2-28
1. The syntax of a geoprocessing tool includes parameters that are both ____________ and
___________.
a. temporary, permanent
b. required, optional
c. subjective, topical
d. alpha, numeric
2. Informative comments can only be added to a script before the script has been
executed.
a. True
b. False
3. What should you remember about variables when you create them?
a. They are always set at the beginning of a script and need to have their data type
defined explicitly.
b. They are set once in the script and are unchangeable.
c. They are dynamic and capable of holding different data types.
d. They are not case-specific and have to be set at the end of the script.
Lesson review
Using Python to access geoprocessing tools
2-29
Explore the syntax of a geoprocessing tool (page 2-3)
1. Clip (Analysis)
Clip(in_features, clip_features, out_feature_class, {cluster_tolerance})
2. Copy Features
CopyFeatures(in_features, out_feature_class, {config_keyword}, {spatial_grid_1},
{spatial_grid_2}, {spatial_grid_3})
3. Intersect
Intersect(in_features, out_feature_class, {join_attributes}, {cluster_tolerance},
{output_type})
Using variables in a script (page 2-7)
Scenario 1: Identify the affected area
1. Which parameter can be converted into a variable and used in both tools?
Buffer - out_feature_class, Clip - clip_features
Scenario 2: Create new service areas
2. Which parameter can be converted into a variable and used in both tools?
• Dissolve - dissolve_field, Split - split_field
• Dissolve - out_feature_class, Split - in_features
• Dissolve - out_feature_class, Split - split_features
Exercise 2A: Create a simple script with variables (page 2-9)
1. Which parameters are required?
Input Features = "AffectedAreaApp" and Output Feature Class = r"C:\EsriTraining\
PYTS\Default.gdb\AffectedAreaAppCopy".
2. What value was placed in the code for the optional parameters?
'', None.
Answers to Lesson 2 questions
2-30
3. How many required parameters are there for Buffer?
Three (in_features, out_feature_class, buffer_distance_or_field)
Troubleshooting errors in a script (page 2-20)
1. Which lines of code use the commenting out troubleshooting technique?
Lines 15, 16, and 17 of the script use the commenting out troubleshooting technique.
2. Which lines of code use the print function troubleshooting technique?
Lines 9 and 13 of the script use the print function troubleshooting technique.
3. Which lines of code use the informative comments troubleshooting technique?
Lines 3 and 11 of the script use the informative comments troubleshooting technique.
Answers to Lesson 2 questions (continued)
2-31
To automate GIS tasks in Python, you must use information about the datasets that you
have. These data types will vary based on the project, so your script will need to be able to
handle these data changes. 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 within your script and can be added to variables. When automating
GIS tasks in Python, these variables can be used throughout your script. Variables not only
represent predefined values, but they can also reference the derivative of tools or
functions.
The Describe properties returned by the Describe function can be used in various ways,
such as the input of a geoprocessing tool or employed in decision-making processes. In
this lesson, you will learn about the Describe function, how to access Describe object
properties, and how these properties can be used as geoprocessing inputs and flow
control elements.
Topics covered
Using the Describe function to access properties
Exploring the available Describe object properties
3 Using Describe properties in geoprocessing tools
3-1
The Describe function returns a Describe object with property information about the data
being evaluated. The Describe function in the ArcPy site package returns an object that
contains various properties based on the data element being described. Types of data that can
be described include the following:
• Geodatabases
• Feature classes
• Table
• Rasters
• Network datasets
• Shapefiles
• Toolboxes
• Folders
• Layer files
Describe properties can be used within a script to report the values, can make conditional
decisions that control the flow of a script, and can function as input parameters to
geoprocessing tools. For example, if you were describing a workspace, you might be
interested in knowing if the workspace is file-based, a local geodatabase, or a remote
geodatabase. If you were working with a feature class, you might need to know what type of
geometry it can store.
You can also use Describe properties as input to geoprocessing tools or environment settings.
For example, you can read the spatial reference property of a feature class and use it as the
create feature class spatial reference input.
Lesson 3
Accessing properties with a Describe function
3-2
Figure 3.1. The Describe function can report many properties.
For example, you can use these properties to help you write code that can make decisions
based on a property's value. Alternately, if you were tasked with writing a script that creates a
monthly inventory report on the contents of your organization's geodatabases, the Describe
function could be used to supply the values for the report. The Describe function is dynamic,
so the properties returned are for the data element being described. This could include the
geodatabase itself, feature classes, tables, rasters, network datasets, and more. The data
element being described is not limited to only geodatabase elements.
Accessing properties with a Describe function (continued)
Using Describe properties in geoprocessing tools
3-3
The Describe function accesses different properties based on the data type. While some of the
properties may be available in a few different data types, most data types have unique
properties. By evaluating the web help documentation about the various data types, you can
identify which properties are available for each one. In this activity, you will explore the help
documentation to learn about available properties within the Describe object for different data
types.
Figure 3.2. The properties in the Describe object differ based on data type.
Instructions
a Open a web browser and go to ArcGIS Pro Help: ArcInfo Workstation Item properties.
b From the left-side menu, locate and click the link for each specified data type, and then
answer the following questions about different Describe properties.
c When you are finished, close the web browser.
Lesson 3
Identify available Describe function properties
3-4
https://pro.arcgis.com/en/pro-app/latest/arcpy/functions/arcinfo-item-properties.htm
FeatureClass properties
1. What does the shapeType property return?
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
2. Which property indicates if the geometry has 3D values?__________________________________________________________________________________
__________________________________________________________________________________
Raster Dataset properties
3. If you needed to find the number of bands in a raster dataset, which property would
you use?
__________________________________________________________________________________
__________________________________________________________________________________
4. What does the format property indicate?
__________________________________________________________________________________
__________________________________________________________________________________
Layer properties
5. What does the whereClause property indicate?
__________________________________________________________________________________
__________________________________________________________________________________
6. Which property indicates the name of the layer?
__________________________________________________________________________________
__________________________________________________________________________________
Identify available Describe function properties (continued)
Using Describe properties in geoprocessing tools
3-5
Lesson 3
Identify available Describe function properties (continued)
3-6
The Describe function requires a single input parameter, which is the value of the specific data
element that you want to describe. This is normally the file path of the data, but it can also be
a geoprocessing object. You can set the Describe function to a variable to make it easier to
access when calling properties. When you want to read the property of an object, you can
simply call the property from the variable. The property is returned to the Python window or
Run Console.
Figure 3.3. Describe function syntax.
The help documentation provides a list of properties that each object can return. However, in
some instances, an object may not have all of the documented properties.
To see if a Describe object has a particular property, you can use the hasattr()
function. In ArcGIS Notebooks, you can run a cell with the describe object and get a
list of available properties.
Describe syntax and usage
Using Describe properties in geoprocessing tools
3-7
The properties that you can view in the Describe object allow you to modify the geoprocessing
environment in your script and avoid having to rewrite your code if you use different data. This
flexible approach to coding has benefits when sharing your Python script and reusing your
script on different data. The Describe function allows you to identify properties of the data
within your Python script.
Figure 3.4. Describe function properties can be used in geoprocessing tools within a script.
The Describe function may return a generic object. For some geoprocessing tools,
this object is what is required, but if you want to print it, you may need to reference
the name within the object.
Lesson 3
Accessing Describe properties
3-8
As the GIS specialist for Cumberland County Power, you have received a request to create a
new feature class based on the properties of a previously created layer. The request indicates
that the new feature class should have the same coordinate system, geometry type, and file
path. Additionally, the request indicates that there will be many future requests. Based on this
requirement, you have decided to use Python to start developing an automated way of
processing this in the future.
In this exercise, you will use Python to examine the properties of datasets through the Describe
object and use those properties in your geoprocessing tasks.
In this exercise, you will perform the following tasks:
• Create a Describe object.
• Use the Python window to examine dataset properties.
• Use Describe object properties in a geoprocessing script.
Exercise 3
Use the Describe function in a geoprocessing script
30 minutes
3-9
Step 1: Create a new map
a If necessary, open the PowerOutage project in ArcGIS Pro.
The instructions in this box are only necessary if you did not already create the
PowerOutage project. If you are unsure, ask your instructor for assistance.
1. Start ArcGIS Pro and, if necessary, sign in to your organizational account.
2. To the right of Recent Projects, click Open Another Project.
3. Browse to ..\EsriTraining\PYTS\Results\Exercise02A\PowerOutage, select
PowerOutage.aprx, and then click OK.
b On the Insert tab, click New Map .
c In the Catalog pane, expand Maps, right-click Map, and choose Rename.
d Type DescribeProperties and press Enter.
Step 2: Examine the properties of a feature class
In this step, you will add the data that you will be using to harvest the properties from. You will
also use the Python window to learn about the dataset.
a In the Catalog pane, expand Folders, expand the Data folder, and then expand
CountyData.gdb.
b Right-click the ParcelPts feature class and choose Add To Current Map .
c In the Contents pane, right-click the ParcelPts feature class and choose Properties.
d In the Layer Properties dialog box, click the Source tab.
1. What is the geometry type for the layer?
__________________________________________________________________________________
__________________________________________________________________________________
e On the Source tab, expand the Spatial Reference section.
2. What is the coordinate system reported in the section?
Lesson 3
3-10
__________________________________________________________________________________
__________________________________________________________________________________
f Click OK to close the layer properties.
Step 3: Use the Describe function to examine properties
Now that you have examined the properties using the ArcGIS Pro user interface, you will
examine the properties using the Describe function.
You will first run the Describe function to access the Feature Class properties.
a On the View tab, in the Windows group, click Python Window to open the Python
window.
b If the Python window still has information from the previous exercise, right-click in the
Python window and choose Clear Transcript.
c In the Python window, type desc = arcpy.Describe("ParcelPts") and press Enter.
Hint:Hint: Recall that all the properties of the Describe object are available to be read by
referencing the name of the property. Be sure to type a period (.) after the name of
the Describe object.
d Type desc.path and press Enter.
3. What is the path that is returned?
__________________________________________________________________________________
__________________________________________________________________________________
e Type desc.baseName and press Enter.
4. Which property does this reference, and what value is returned?
__________________________________________________________________________________
__________________________________________________________________________________
This property is obvious when you have added the data to the map. However, this
property will be important when writing a script that will run in an IDE or when
combined with other code to loop through a series of datasets.
f Type desc.spatialReference and press Enter.
Using Describe properties in geoprocessing tools
3-11
5. What value is returned?
__________________________________________________________________________________
__________________________________________________________________________________
The object returned contains all the properties of the spatial reference in which this dataset has
been projected, and it can be used within the geoprocessing script, but to determine the
name of the coordinate system, you must return the name property of the resulting object.
g Type desc.spatialReference.name and press Enter.
6. What is returned for the spatial reference now?
__________________________________________________________________________________
__________________________________________________________________________________h Save the project and leave ArcGIS Pro open.
Step 4: Create a new Python script in PyCharm
In this step, you will use PyCharm to create the script using the Describe function.
a Start PyCharm.
b In the Project pane, select Scripts C:\EsriTraining\PYTS\Scripts.
c From the File menu, choose New, and then choose Python File.
d In the New Python File dialog box, for Name, type CreateFeatureClass and press Enter.
Step 5: Create a Describe object
Now that you have set up your Python document, you will add lines of code to read the
properties of a feature class. You will begin by importing the ArcPy site package.
a On line 1, type # import site package and press Enter.
b On line 2, type import arcpy and press Enter to accept the code completion.
c Press Enter again to move to line 4.
Next, you will set the Describe object to a variable.
d On line 4, type # Access describe object and press Enter.
e On line 5, type desc = arcpy.Describe(r"C:\EsriTraining\PYTS\Data\CountyData.gdb\
ParcelPts") and press Enter.
Lesson 3
3-12
f On line 6, type # Variable for properties and press Enter.
g On line 7, type dPath = desc.path and press Enter.
Now you will add a print function and run the script to verify that the Describe function is set
up properly.
h On line 8, type print(dPath).
i Right-click in the script window and choose Run 'CreateFeatureClass'.
7. What value is printed to the Run window?
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
Step 6: Use Describe properties to create a new feature class
In this step, you will use the information obtained from the ParcelPts feature layer to create a
new feature class.
a On lines 9-11, type the following code:
dName = desc.baseName
dGeometry = desc.shapeType
dCoord = desc.spatialReference
b Press Enter.
Now that the variables are defined, you will use the name of the data element to create the
name for the new feature class.
c On line 12, type # Modify output feature class name and press Enter.
The next line uses the f-string method, which is used to format string data elements.
String operations are powerful operations that can maintain naming conventions for
Python automation.
d On line 13, type newName = f"{dName}_new" and press Enter.
e On line 14, type print(newName) and press Enter.
Using Describe properties in geoprocessing tools
3-13
Now you will use the variables in a geoprocessing tool to create a new feature class.
f On line 15, type # Create new feature class and press Enter.
g On line 16, type arcpy.CreateFeatureclass_management(dPath, newName, dGeometry,
None, "", "", dCoord) and press Enter.
PyCharm provides the syntax to the geoprocessing tool as you type it. This feature can help
when you are unfamiliar with the syntax of the tool, giving you a reminder of the variables that
you have created within the script.
h On line 17, type print("Script complete").
You have completed the script and are ready to run it. Because you have already run the script,
you can run it from the Run menu without having to go through the extra dialog box.
i From the Run menu, choose Run 'CreateFeatureClass'.
j Notice the print statements in the Run window, which show that your script has completed.
C:\EsriTraining\PYTS\Data\CountyData.gdb
ParcelPts_New
Script complete
Process finished with exit code 0
The completed script should look like the following code block. If you received an error
message, check your code for mistakes.
# import site package
import arcpy
# Access describe object
desc = arcpy.Describe(r"C:\EsriTraining\PYTS\Data\CountyData.gdb\
ParcelPts")
# Variable for properties
dPath = desc.path
print(dPath)
dName = desc.baseName
dGeometry = desc.shapeType
dCoord = desc.spatialReference
Lesson 3
3-14
# Modify output feature class name
newName = f"{dName}_new"
print(newName)
# Create new feature class
arcpy.CreateFeatureclass_management(dPath, newName, dGeometry, None,
"", "", dCoord)
print("Script complete")
k Close any open Python files.
l Minimize PyCharm, as you will use it again in later lessons.
Step 7: Verify the new feature class
a In ArcGIS Pro, in the Catalog pane, right-click CountyData.gdb and choose Refresh.
The geodatabase contains a new ParcelPts_new feature class.
b Right-click the ParcelPts_new feature class and choose Add To Current Map .
c Notice that there are not any points added to the new feature class.
d In the Contents pane, right-click the ParcelPts_new feature class and choose Properties.
e In the Layer Properties dialog box, on the Source tab, expand the Spatial Reference
section.
f Confirm that the coordinate system is NAD 1983 (CORS96) StatePlane North Carolina FIPS
3200 (US Feet).
g Click OK to close the layer properties.
h Close any open maps.
i From the View tab, click Reset Panes and choose Reset Panes For Mapping (Default).
j Save the project, and then exit ArcGIS Pro.
You created a Python script that used the Describe function to access the properties of a
feature class. You will use this technique in the upcoming lessons to create your Python script
tool.
Using Describe properties in geoprocessing tools
3-15
The da.Describe object is similar to the Describe object, but it returns the information as a
dictionary. This output may be particularly beneficial to certain scripts because all the
properties will be gathered at once. The properties found in the da.Describe object can be
accessed just as you would access information from any other Python dictionary.
Figure 3.5. Properties from the da.Describe object in a dictionary.
Lesson 3
Using the da.Describe object in a geoprocessing script
3-16
1. How do describe functions assist in geoprocessing scripts?
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
2. Describe properties can be used to set the environment variables of a geoprocessing
tool.
a. True
b. False
3. Which Describe object property would return the value of 'Polyline'?
a. featureType
b. shapeType
c. shapeFieldName
d. hasM
Lesson review
Using Describe properties in geoprocessing tools
3-17
Identify available Describe function properties (page 3-4)
1. What does the shapeType property return?
• Polygon
• Polyline
• Point
• Multipoint
• MultiPatch
2. Which property indicates if the geometry has 3D values?
hasZ
3. If you needed to find the number of bands in a raster dataset, which property would you
use?
bandCount
4. What does the format property indicate?
The raster format of the raster
5. What does the whereClause property indicate?
The layer's definition query where clause
6. Which property indicates the name of the layer?
nameString
Exercise 3: Use the Describe function in a geoprocessing script (page 3-9)
1. What is the geometry type for the layer?
Point
2. What is the coordinate system reported in the section?
NAD 1983 (CORS96) StatePlane North Carolina FIPS 3200 (US Feet)
3. What is the path that is returned?
'C:\\EsriTraining\\PYTS\\Data\\CountyData.gdb'
Answers to Lesson 3 questions
3-18
4. Which property does this reference, and what value is returned?
It indicates the name of the feature class, and it returns 'ParcelPts'.
5. What value is returned?
A geoprocessing object
6. What is returned for the spatial reference now?
'NAD_1983_CORS96_StatePlane_North_Carolina_FIPS_3200_Ft_US'
7. What value is printed to the Run window?
C:\EsriTraining\PYTS\Data\CountyData.gdb
Process finished with exit code 0
Answersto Lesson 3 questions (continued)
3-19
One of the primary benefits of using Python in ArcGIS Pro is the ability to automate GIS
tasks. Your decision to automate a task or process is often based on the frequency that is
necessary to repeat it. Using lists, a Python script can evaluate datasets and then
determine how many times a process should be run. Lists eliminate the need to specify a
range as its items define the number of times a process must be repeated. The ArcPy site
package has many List functions that are built to return Python lists for different types of
data. In this lesson, you will explore these ArcPy List functions and start automating GIS
tasks.
Topics covered
List creation based on GIS data
Create a loop to iterate over a list
Integrating lists into a Python script to handle different datasets
4 Automating Python scripts with lists
4-1
The ArcPy site package provides a number of List functions that return a list of values. These
List functions can provide you with lists of feature class names in a geodatabase, geodatabase
names in a folder, rasters in a folder, field objects in a table, and many other items. You can use
the lists to iterate through each item and perform defined tasks. This means that the task will
be performed on each item in the list.
Figure 4.1. Using List functions to create lists.
ArcPy List functions for listing data
List function Content of list
ListDatasets All the datasets in a workspace
ListFeatureClasses All the feature classes in a workspace
ListFields All the fields in a feature class, shapefile, or table
ListFiles All the files in a workspace
ListIndexes The indexes in a feature class, shapefile, or table
ListRasters All the rasters in a workspace
Lesson 4
List functions in Python
4-2
List function Content of list
ListTables All the tables in a workspace
ListVersions All the versions a connected user has permissions to use
ListWorkspaces All the workspaces within a workspace
Syntax
The syntax of all the List functions includes parameters to limit the results to specific values, or
types of data. The general syntax for creating a list is to set a workspace that will be used in
the List function. This workspace could be the current workspace or another specific
workspace.
For example, if you were looking to create a list of all the feature classes in a geodatabase,
then you would type the following code:
# Set the workspace
arcpy.env.workspace = r'C:\EsriTraining\PYTS\Default.gdb'
# Create a list of feature classes in the current workspace
fcList = arcpy.ListFeatureClasses()
All the List functions include a wildcard parameter to limit the values returned. If no
wildcard parameter is used, then all the values will be returned.
List functions in Python (continued)
Automating Python scripts with lists
4-3
As you have learned, ArcPy has several different List functions. One commonly used List
function is ListFiles. ListFiles creates a Python list of all the files in a workspace. A condition can
be added to the search to limit the results based on name. You will explore a help topic that
discusses the ListFiles function and answer some questions.
Instructions
a Open a web browser and go to the ListFiles ArcGIS Pro Help topic (https://pro.arcgis.com
/en/pro-app/latest/arcpy/functions/listfiles.htm).
b Under the Syntax section, review each parameter of the ListFiles function.
c Under the Code Sample section, examine the ListFiles example.
d When you are finished, close the web browser.
1. Which environment must be set before using the ListFiles function?
__________________________________________________________________________________
__________________________________________________________________________________
2. What text string would you use to return only CSV files?
__________________________________________________________________________________
__________________________________________________________________________________
3. What is returned from the ListFiles function?
__________________________________________________________________________________
__________________________________________________________________________________
Lesson 4
Examine the ListFiles function
4-4
https://pro.arcgis.com/en/pro-app/latest/arcpy/functions/listfiles.htm
Using the script comments, fill in the code that is missing in the three incomplete scripts. Use
the workbook and ArcGIS documentation resources to complete the activity.
Scenario 1: List of feature datasets
# Create a Python list of feature datasets from the Default.gdb
# Geodatabase is located in C:\EsriTraining\PYTS folder
# Import modules
import arcpy
# Set workspace environment
arcpy.env.workspace = r"C:\EsriTraining\PYTS\______"
# Create Python list
datasetList = arcpy.______("", "Feature")
Fill in the blanks with the correct syntax.
1. arcpy.env.workspace=r"C:\EsriTraining\PYTS\______"
__________________________________________________________________________________
__________________________________________________________________________________
2. datasetList = arcpy.______("", "Feature")
__________________________________________________________________________________
__________________________________________________________________________________
Finishing the List function syntax
Automating Python scripts with lists
4-5
Scenario 2: List of field names
# Create a Python list of field objects from the MajorAttractions
feature class
# Print the name of the third field
# Import modules
import arcpy
# Set workspace environment
arcpy.env.workspace = r"C:\EsriTraining\PYTS\Default.gdb"
# Create Python list
fieldsList = arcpy.______('MajorAttractions')
print(_____[2].name)
Fill in the blanks with the correct syntax.
3. fieldsList = arcpy.______('MajorAttractions')
__________________________________________________________________________________
4. print(_____[2].name)
__________________________________________________________________________________
Lesson 4
Finishing the List function syntax (continued)
4-6
Scenario 3: List of raster names
# Create a Python list of raster names from Default geodatabase
# Only rasters that start with the letter 'e'
# Print the name of the raster
# Import modules
import arcpy
# Set workspace environment
arcpy.env.workspace = r"C:\EsriTraining\PYTS\Default.gdb"
# Create Python list
_______ = arcpy.________("e*")
print(rasterList)
Fill in the blanks with the correct syntax.
5. _______ = arcpy.________("e*")
__________________________________________________________________________________
Finishing the List function syntax (continued)
Automating Python scripts with lists
4-7
As the GIS specialist for Cumberland County Power, you are working on automating a process
that will evaluate the incoming data to ensure that it matches the current data. While you
determine the exact tests that you must perform to survey the incoming data, you will need to
survey the data that you currently have. In this exercise, you will examine the existing data you
have to create a list that you will use for automation in the future.
In this exercise, you will perform the following tasks:
• Use List functions to create Python lists.
• Explore the values returned in lists.
Exercise 4A
Prepare to automate with Python lists
25 minutes
4-8
Step 1: Create a new map
a Start ArcGIS Pro.
b Under Recent Projects, open the PowerOutage project in ArcGIS Pro.
The instructions in this box are only necessary if you did not already create the
PowerOutage project. If you are unsure, ask your instructor for assistance.
1. Start ArcGIS Pro and, if necessary, sign in to your organizational account.
2. To the right of Recent Projects, click Open Another Project.
3. Browse to ..\EsriTraining\PYTS\Results\Exercise02A\PowerOutage, select
PowerOutage.aprx, and then click OK.
c On the Insert tab, click New Map .
d In the Catalog pane, expand Maps, right-click Map, and chooseRename.
e Type CreatingLists and press Enter.
Step 2: Create a list of workspaces
To begin your survey of existing data, you will create a list of the geodatabases that you have
currently.
a Open the Python window and, if necessary, clear the transcript.
The first step is to establish the working directory.
b In the Python window, type arcpy.env.workspace = r"C:\EsriTraining\PYTS\Data" and press
Enter.
The next step is to create the Python list with a variable.
c Type gdbList = arcpy.ListWorkspaces("", "FileGDB") and press Enter.
Now that you have created the list, you will print it to see it.
d Type print(gdbList) and press Enter.
e Notice the list of geodatabases that appears in the Python window.
1. How many geodatabases are reported?
Automating Python scripts with lists
4-9
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
Step 3: Create a list of features
In this step, you will create a list of the feature classes within the CountyData geodatabase.
a In the Python window, set the workspace to the CountyData.gdb.
Hint:Hint: The code should be
arcpy.env.workspace = r"C:\EsriTraining\PYTS\Data\CountyData.gdb".
b Type fcList = arcpy.ListFeatureClasses() and press Enter.
c Type print(fcList) and press Enter.
d Notice the feature classes that are reported.
2. How many feature classes are reported?
_______________________________________________________________________________
Now you will consider how many of these feature classes are point feature classes.
e Type fcList2 = arcpy.ListFeatureClasses("", "Point") and press Enter.
f Type print(fcList2) and press Enter.
3. How many point feature classes are listed?
_______________________________________________________________________________
Step 4: Create a list of fields
Now you will create a list of fields from the parcel points.
a In the Catalog pane, expand Folders, expand the Data folder, and then expand
CountyData.gdb.
b Right-click ParcelPts and choose Add To Current Map .
c In the Python window, type fieldList = arcpy.ListFields("ParcelPts") and press Enter.
d Type print(fieldList[8].name) and press Enter.
4. Which field name is printed in the window?
Lesson 4
4-10
__________________________________________________________________________________
__________________________________________________________________________________
5. Why did you have to include '.name' to the code?
__________________________________________________________________________________
__________________________________________________________________________________
e Close any open map views.
f From the View tab, click Reset Panes and choose Reset Panes For Mapping (Default).
g Save the project and leave ArcGIS Pro open.
Automating Python scripts with lists
4-11
For loops are important for controlling the flow of your script and are mostly used in
conjunction with a list. Each item in the list is used within the indented code block beneath the
for loop. After all of the items from the list have been used, the program exits the for loop. For
example, each field from a list of fields created using the ListFields function is inserted into a
print statement. When all of the fields in the list have been printed, the program exits the for
loop and moves on to the next block of code.
arcpy.env.workspace = r"C:\Data\Cumberland.gdb"
fieldList = arcpy.ListFields("Outages")
for field in fieldList:
print(field.name)
Figure 4.2. For loop statement.
An if-then statement can be nested within a for loop statement. As the for loop statement
iterates over each item from the list, the item can be evaluated against the condition of the if
statement. For example, each number from a list of numbers can be evaluated against a set of
if statement conditions.
Lesson 4
Using a for loop
4-12
arcpy.env.workspace = r"C:\Data\Cumberland.gdb"
fieldList = arcpy.ListFields("Outages")
for field in fieldList:
if field.type == "String":
print(f"{field.name} is a string")
elif field.type == "Double":
print(f"{field.name} is a double")
else:
print(f"{field.name} is not a string or double")
Using a for loop (continued)
Automating Python scripts with lists
4-13
Loops can be used to pass each item in a list through processes to create unique sets of
output. A for loop is ideal for iterating through a list because it can be used to step through
the list one item at a time.
Figure 4.3. Using a loop to iterate over lists of data.
Considerations when working with lists and for loops
• For loops can also be nested within another for loop. Nesting allows you to process all
the fields within a feature class as you process each feature class.
• Remember that you can maintain the number of iterations performed by adding a counter
within your for loop.
• Within each list, the sequence of the elements can be accessed by their index number.
Python lists can be manipulated so that the data elements can be changed, reordered,
removed, or sorted.
Lesson 4
Using a for loop to iterate over lists
4-14
As the GIS specialist for Cumberland County Power, you will continue working with the List
function that you used in the previous exercise. To help prepare and organize data that you
have received from another agency, you will create copies of each point feature class and put
them into an existing geodatabase. In this exercise, you will use the ListFeatureClasses
function and a for loop to iterate over a list of feature classes, passing each point feature class
to the Copy Features tool.
In this exercise, you will perform the following tasks:
• Create a new Python file in PyCharm.
• Use the ListFeatureClasses function to create a list of feature classes.
• Use a for loop statement on a list to copy feature classes.
• Verify the feature classes in the destination geodatabase.
Exercise 4B
Automate a geoprocessing workflow using loops
20 minutes
4-15
Step 1: Create a new Python script in PyCharm
In this step, you will use PyCharm to create a script using lists.
a If necessary, start PyCharm.
b In the Project pane, select the Scripts project.
c From the File menu, choose New, and then choose Python File.
d In the New Python File dialog box, for Name, type FeatureClassLoop and press Enter.
Step 2: Copy feature classes from a workspace
Now that you have set up your Python document, you will add lines of code to loop over a list
of feature classes and copy all the point feature classes to a new geodatabase.
a Begin by importing arcpy.
Hint:Hint: Type import arcpy, and then press Enter twice.
Next, you will set the current workspace and the output workspace.
b Beneath the arcpy import, type the following code:
# Set the workspaces
arcpy.env.workspace = r"C:\EsriTraining\PYTS\Data\CountyData.gdb"
outWorkspace = r"C:\EsriTraining\PYTS\Default.gdb"
c Press Enter.
Now you will create the point feature class list and loop through the list.
d Type fcList = arcpy.ListFeatureClasses("", "Point") and press Enter.
e Type for fc in fcList: and press Enter.
The next lines will be indented under the for loop statement.
f Type outputFC = f"{outWorkspace}\\{fc}" and press Enter.
g Type arcpy.CopyFeatures_management(fc, outputFC) and press Enter.
Now you will add a print statement to indicate which feature class has been copied.
Lesson 4
4-16
h Type print(f"{fc} copied") and press Enter.
Your code should look like the following code block:
import arcpy
# Set the workspaces
arcpy.env.workspace = r"C:\EsriTraining\PYTS\Data\CountyData.gdb"
outWorkspace = r"C:\EsriTraining\PYTS\Default.gdb"
fcList = arcpy.ListFeatureClasses("", "Point")
for fc in fcList:
outputFC = f"{outWorkspace}\\{fc}"
arcpy.CopyFeatures_management(fc, outputFC)
print(f"{fc} copied")
With your script completed, it is ready to be run.
i Right-clickin the script window and choose Run 'FeatureClassLoop'.
j Notice that a print statement is added to the PyCharm Run window for each feature class
copied.
k Close any open Python files and exit PyCharm.
Step 3: Verify the new feature classes
a If necessary, open the PowerOutage project in ArcGIS Pro.
The instructions in this box are only necessary if you did not already create the
PowerOutage project. If you are unsure, ask your instructor for assistance.
1. Start ArcGIS Pro and, if necessary, sign in to your organizational account.
2. To the right of Recent Projects, click Open Another Project.
3. Browse to ..\EsriTraining\PYTS\Results\Exercise02A\PowerOutage, select
PowerOutage.aprx, and then click OK.
b In ArcGIS Pro, in the Catalog pane, expand Databases, right-click Default.gdb, and choose
Refresh.
c Expand Default.gdb, if necessary, and notice the new feature classes.
Automating Python scripts with lists
4-17
1. The feature classes use the same name as in the CountyData.gdb. How could you
modify the name of the feature classes to add "_copy" to the end of the name?
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
d Save the project, and then exit ArcGIS Pro.
Now you have created a Python script that loops through a list of feature classes and copies
each one to a new database.
Lesson 4
4-18
1. List __________ are used to create Python lists from GIS data.
a. operations
b. properties
c. functions
d. methods
2. Which type of loop will perform a task based on items within a list?
a. If-then loop
b. For loop
c. Count loop
d. While loop
3. An if-then statement can be nested within a for loop statement.
a. True
b. False
4. When using List functions, a __________ parameter can be used to limit the values
returned.
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
Lesson review
Automating Python scripts with lists
4-19
Examine the ListFiles function (page 4-4)
1. Which environment must be set before using the ListFiles function?
Workspace
2. What text string would you use to return only CSV files?
"*.csv"
3. What is returned from the ListFiles function?
A list containing file names
Finishing the List function syntax (page 4-5)
Scenario 1: List of feature datasets
1. arcpy.env.workspace=r"C:\EsriTraining\PYTS\______"
"Default.gdb"
2. datasetList = arcpy.______("", "Feature")
ListDatasets
Scenario 2: List of field names
3. fieldsList = arcpy.______('MajorAttractions')
ListFields
4. print(_____[2].name)
fieldsList
Scenario 3: List of raster names
5. _______ = arcpy.________("e*")
rasterList, ListRasters
Answers to Lesson 4 questions
4-20
Exercise 4A: Prepare to automate with Python lists (page 4-8)
1. How many geodatabases are reported?
Two geodatabases ( 'C:\\EsriTraining\\PYTS\\Data\\CountyData.gdb', 'C:\\EsriTraining\
\PYTS\\Data\\Outages.gdb') are reported.
2. How many feature classes are reported?
Four feature classes are reported: 'ParcelPts', 'ServiceAreas', 'ParcelPoly',
'ParcelPts_New'.
3. How many point feature classes are listed?
Two ('ParcelPts', 'ParcelPts_New')
4. Which field name is printed in the window?
Owner_Name
5. Why did you have to include '.name' to the code?
To print the name property of the field object
Exercise 4B: Automate a geoprocessing workflow using loops (page 4-15)
1. The feature classes use the same name as in the CountyData.gdb. How could you modify
the name of the feature classes to add "_copy" to the end of the name?
Modify the output feature class string by adding "_copy" within the quotes.
outputFC = f"{outWorkspace}\\{fc}_copy"
Answers to Lesson 4 questions (continued)
4-21
Accessing data in feature classes and tables is the starting point for many data
management and analysis workflows. A cursor is a data access object that can be used to
iterate over a set of data in a table. It can process the data more efficiently through the use
of built-in functions that allow you to limit your data to the necessary fields. During the
iteration, the cursor can search the data, insert new data, or update existing data. The
cursor allows you to script and automate data access tasks. Compared to similar tasks
using geoprocessing tools, cursors can provide better performance.
In this lesson, you will learn how you can use cursors to manipulate data within your Python
script.
Topics covered
Types of cursors
Using cursors to manipulate data
5 Working with cursors
5-1
Cursors are data access objects that can be used to iterate over a set of rows in a table and
search, insert, or update the data in the rows. One of the more common uses is to read
existing geometries and write new geometries in feature data. You can use the cursors to
correct data in existing datasets or update the data with new information. There are many
situations where the data to be used in a Python script must be adjusted prior to performing a
task.
Here are some examples of how cursor functionality can be used:
• Data migration automation
• Data management tasks like adding new fields and calculating values
• Batch insert of captured field data
• Summary reporting of field values
• Updating large numbers of records
Cursor Type of
access
Types of data manipulation Available
methods
SearchCursor Read
only
• Read field values of tables
• Read geometry of features
• reset()
UpdateCursor Read
/write
• Read and update field
values of tables
• Delete table rows
• updateRow()
• deleteRow()
• reset()
InsertCursor Write
only
• Add rows to table
• Create feature geometry
• insertRow()
There are also cursors that are part of the ArcPy module. These cursors do not
perform as well as the data access module cursors and are considered legacy
functionality. For more information about these cursors, please see ArcGIS Pro Help:
Accessing data using cursors.
Lesson 5
Types of cursors
5-2
SearchCursor
The arcpy.da.SearchCursor provides read-only access to field values in a feature class or table
and a feature layer or table view. It can be run by using a for loop statement or a with
statement that resets iteration and removes data locks. The cursor object can be filtered to
match an attribute field where clause and an SQL clause when working with a geodatabase
data source like a feature class or table.
Figure 5.1. A Search cursor.
arcpy.da.SearchCursor (in_table, field_names, {where_clause},
{spatial_reference}, {explode_to_points}, {sql_clause},
{datum_transformation})
Figure 5.2. Syntax components of the SearchCursor.
arcpy.da SearchCursor parameters
Parameter Description
in_table A feature class, table, feature layer, or table view
field_names A tuple or list of field names; SHAPE@tokens also supported
Types of cursors (continued)
Working with cursors
5-3
Parameter Description
where_clause Attribute field SQL expression
spatial_reference The spatial reference of the feature class
explode_to_points Deconstructs a feature into its vertices or points
sql_clause SQL prefix and postfix clauses
datum_transformation Used to project features from one spatial reference to
another
UpdateCursor
The arcpy.da.UpdateCursor provides read-write access to field values in a feature class or
table, as well as a feature layer or table view. Update cursors can be iterated by using a for
loop or a with statement.
You can filter the Update cursor records to match an attribute field value using an SQL clause
when working with a geodatabase data source, such as a feature class or table.
Figure 5.3. An Update cursor.
arcpy.da.UpdateCursor(in_table,field_names, {where_clause},
{spatial_reference}, {explode_to_points}, {sql_clause},
{datum_transformation})
Lesson 5
Types of cursors (continued)
5-4
Figure 5.4. Syntax components of the UpdateCursor.
arcpy.da UpdateCursor parameters
Parameter Description
in_table A feature class, table, feature layer, or table view
field_names A tuple or list of field names; SHAPE@tokens also supported
where_clause Attribute field SQL expression
spatial_reference The spatial reference of the feature class
explode_to_points Deconstructs a feature into its vertices or points
sql_clause SQL prefix and postfix clauses
datum_transformation Used to project features from one spatial reference to
another
InsertCursor
The arcpy.da.InsertCursor creates a write-only cursor to create new rows with field values and
insert them into a feature class or table, as well as a feature layer or table view. An Insert cursor
uses exclusive locks in a Python IDE, similar to when you are saving edits to a feature class or
changing the schema in ArcGIS Desktop.
Types of cursors (continued)
Working with cursors
5-5
Figure 5.5. An Insert cursor.
arcpy.da.InsertCursor(in_table, field_names, {datum_transformation})
Figure 5.6. Syntax components of the InsertCursor.
arcpy.da InsertCursor parameters
Parameter Description
in_table A feature class, table, feature layer, or table view
field_names A tuple or list of field names; SHAPE@tokens also supported
datum_transformation Used to project features from one spatial reference to
another
Within the syntax of each cursor, there is additional functionality that can be used in
a Python script. Depending on the Python script, you can change properties of the
data while you access the data. The Search and Update cursors also allow you to
limit the results through where clauses, change the spatial reference, or deconstruct
a feature into its vertices or points. Carefully consider this additional functionality to
improve performance when you use cursors in your Python script.
Lesson 5
Types of cursors (continued)
5-6
Cursors provide a way to read table rows, update table row values, and insert new table rows
with values and geometries. Each cursor has properties and methods that allow them to
accomplish each process. You will explore help topics about cursors and then answer some
questions.
Instructions
a Open a web browser and go to ArcGIS Pro Help: What Is The Data Access Module.
b Under the Data Access Classes section, click InsertCursor.
c Review the Syntax, Properties, Method Overview, and Code Sample sections, and then
answer the following question for InsertCursor.
d After you have answered the question for InsertCursor, repeat the process for SearchCursor
and UpdateCursor.
e When you are finished, close the web browser.
InsertCursor
1. Which token can be used with the InsertCursor to add point features to a point feature
class?
__________________________________________________________________________________
__________________________________________________________________________________
SearchCursor
2. Why is using an asterisk (*) for the field_names parameter to access all fields
discouraged?
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
UpdateCursor
3. What methods does the UpdateCursor class provide?
__________________________________________________________________________________
__________________________________________________________________________________
Examine cursors
Working with cursors
5-7
https://pro.arcgis.com/en/pro-app/latest/arcpy/data-access/what-is-the-data-access-module-.htm
Lesson 5
Examine cursors (continued)
5-8
Cursors can be powerful data tools, but determining when to use each cursor requires
information about the task that you are attempting to accomplish. After carefully considering
the task, you can determine the proper cursor.
Match the following scenario to the proper cursor. The following cursors apply the scenarios:
• SearchCursor
• UpdateCursor
• InsertCursor
Scenario Cursor
Add five new employees to an employee database.
Compile a list of the current addresses of all your store locations.
Change district designation for your stores.
Add contact information for a neighborhood sports team.
Identify which students live in a particular county.
Modify addresses on a mailing list.
Determine which cursor to use
Working with cursors
5-9
Although cursors are simple in concept, writing code to use a cursor in a script can be
challenging. You can look at the code examples of each cursor to get a better understanding
of its syntax.
Tips and best practices for accessing data using cursors
• When accessing the Shape field, use the Shape field tokens for the best cursor
performance.
• To return a sorted list of values from a cursor or a list, use the sorted() built-in function.
• The SearchCursor, UpdateCursor, and InsertCursor objects have a fields property that can
be used to conform the order of field values in the tuple that is returned by the row
object.
• Cursors are navigated in a forward direction only.
• Rows may be retrieved only once.
• When looping through rows with a cursor, a block that uses the reset() method can be
used to return the cursor to the first row.
• To reset iteration and aid in removal of database lock, use the with statement on the
Search cursor and Update cursors.
• To have the cursor object go out of scope to guard against all locking cases, use the del
statement to delete the object or wrapping the cursor in a function.
Lesson 5
Exploring cursor syntax
5-10
When using cursors in a Python script, it is important to follow this workflow to ensure that your
script uses the cursor effectively.
Figure 5.7. Workflow for using cursors in a Python script.
Identify task
Before using a cursor, consider what you want the cursor to accomplish. This will define which
cursor you will use. Depending on the input data, a combination of cursors may be necessary
to complete the task.
Consider placement
After you have identified the task that will be performed and the type of cursor to use, you
must consider where the cursor should be placed. Perhaps you need to iterate over many
records, so the cursor will need to be nested within a loop or outside the loop. Will the task be
performed on a single feature class or a workspace? Will you need to recreate the cursor within
the loop?
Create cursor
In this step, you create a cursor to perform the designated task within your script. Before
writing the script, carefully consider the syntax necessary for the selected cursor. There are
slight differences with each of the cursors, so be sure to create the cursor correctly.
Perform task
This is the action step when the cursor will manipulate the data. Depending on the task, the
Using cursors in a workflow
Working with cursors
5-11
output from the process can be different. In this step, you will read, insert, or update the data.
Delete cursor
After the cursor has finished the task, it is important to delete the cursor to free up memory
and prevent schema locks. The With statement can be used to reset iteration and aid in the
removal of locks; however, using the del statement to delete the cursor or wrapping the cursor
in a function to have the cursor object go outside of scope should be considered to guard
against all locking cases. The desired goal is to free up the data after the script completes.
Deleting the cursor will ensure that the data and memory are released.
Lesson 5
Using cursors in a workflow (continued)
5-12
Cumberland County Power is considering a new energy product for specific customers. Their
initial research shows that customers with home values of $90 per square foot or less meet the
desired profile. You have been taskedto use GIS parcel data to determine which homes are in
this value range.
In this activity, you will use ArcGIS Pro to examine the provided GIS data, consider the desired
output, and apply the cursor workflow.
Instructions
a If necessary, start ArcGIS Pro and sign in.
b Open the PowerOutage project.
c Open the DescribeProperties map.
If you did not already create the CreatingLists map in the PowerOutage project, you
can open the PowerOutage project in ..\EsriTraining\PYTS\Results\Exercise03\
PowerOutage.
d For ParcelPts, open the attribute table.
e Examine the fields in the attribute table.
f After the activity is complete, exit ArcGIS Pro without saving changes.
Now that you have evaluated the ParcelPts feature class, fill in the following table about the
cursor workflow.
Consider which cursors will accomplish the desired output. Will one work or perhaps more
than one?
Step Action
Which task needs to be accomplished?
Which dataset needs to be manipulated?
Which cursor or cursors need to be used?
List the cursor or cursors used and what they will do.
Apply the cursor workflow
Working with cursors
5-13
You have already learned how to apply the cursor workflow to consider the new energy
product for specific Cumberland County Power customers. Now, you will create the Python
script to use GIS parcel data to determine which homes are in this value range. You will use an
Update cursor to calculate the value per square foot from home values in the parcel data. After
you have calculated that value, you will use a Search cursor to create a subset of the data.
These values will allow the power company to solicit these customers before their tax value is
updated.
In this exercise, you will perform the following tasks:
• Create an Update cursor to update field values.
• Create a Search cursor to read field values.
• Create a CSV file from a list of values.
• Verify the script output.
Exercise 5
Read and update values in a feature class
45 minutes
5-14
Step 1: Create a new Python script in PyCharm
In this step, you will use PyCharm to create a script using lists.
a Start PyCharm.
b In the Project pane, select the Scripts project.
c From the File menu, choose New, and then choose Python File.
d In the New Python File dialog box, for Name, type CursorCreation and press Enter.
Step 2: Set up the Python script
In this step, you will set up the Python script by importing the proper module and setting the
variable for the target feature class.
a In the CursorCreation file, set up your script by importing the ArcPy module and creating
an fc variable, which will indicate the path to the ParcelPts feature class in the CountyData
geodatabase.
Be sure to use informative comments to explain which action each section of code is
doing.
Hint:Hint: There is also a ParcelPoints feature class in the default geodatabase. Make sure that
you use the feature class in the CountyData geodatabase.
Now that you have set up the Python script, you are ready to create the first cursor to look
through the features.
Step 3: Create an Update cursor
In this step, you will create the Update cursor, which will update the values of the price per
square foot field.
a In the CursorCreation file, create a list of fields named uFields, including the following
fields:
• SquFoot
• TaxValue
• PriceSquFt
Hint:Hint: A list is made up of values within []s and separated by commas.
Hint:Hint: Because the field names are string values, be sure to use quotes around each field.
You will need to create a list to ensure that all the fields that you are using for the calculation
Working with cursors
5-15
are found.
b Type the following code to create the Update cursor in a with statement:
with arcpy.da.UpdateCursor(fc, uFields) as uCursor:
c Press Enter.
This line will create the Update cursor and reference the feature class and list of fields that you
created earlier.
d Type the following code to create a for loop to loop through the feature class.
Hint:Hint: Verify that the line is indented before entering the code.
for row in uCursor:
row[2] = row[1] / row[0]
uCursor.updateRow(row)
del uCursor
The [] values are the index position of the fields in the created list used for the calculation. The
calculation to determine the value per square foot is the TaxValue divided by the SquFoot
fields.
e Press Enter.
f Check your code against the following code to ensure that you have entered the code
correctly:
# import site packages
import arcpy
# Set variables
fc = r"C:\EsriTraining\PYTS\Data\CountyData.gdb\ParcelPts"
# Update value per square foot with update cursor
uFields = ["SquFoot", "TaxValue", "PriceSquFt"]
with arcpy.da.UpdateCursor(fc, uFields) as uCursor:
for row in uCursor:
Lesson 5
5-16
row[2] = row[1] / row[0]
uCursor.updateRow(row)
del uCursor
g Correct any syntax errors in your script.
Step 4: Create a Search cursor
In this step, you will create the Search cursor, which will read the values of the ParcelPts feature
class and add them to a list. The list of values will be written to a CSV file in the next step.
Be sure that you are starting outside of the with loop from the previous step. If
you are within the with loop, the code will not work properly.
a In the CursorCreation file, create a list of fields named sFields, including the following
fields:
• Parcel_ID
• Owner_Name
• Phone_Number
• PriceSquFt
b Type the following code that will define a search query to limit the results to parcels that
have a price per square foot price of less than or equal to 90:
exp = '"PriceSquFt"mode. After the file
object is open, you will use the write method to write the text to the file. After that is finished,
you will close the CSV file.
c Type the following code to use the open function in the writing mode:
csvFile = open(r"C:\EsriTraining\PYTS\AssessmentParcels.csv", "w")
csvFile.write(textBody)
csvFile.close()
print("Script Complete")
d Press Enter.
e Check your code against the following code to be sure that you have entered the code
correctly:
# Write messages to a CSV file
textBody = '\n'.join(parcelList)
csvFile = open(r"C:\EsriTraining\PYTS\AssessmentParcels.csv", "w")
csvFile.write(textBody)
Working with cursors
5-19
csvFile.close()
print("Script Complete")
Now that you have completed the script, you are ready to run the script and generate the list
of properties that meet your criteria.
Step 6: Run the script in PyCharm
Now that you have completed the script, it is ready to run.
a Right-click in the script window and choose Run 'CursorCreation'.
After the script has finished running, it will print "Script Complete" to the Python Console.
b Close any open Python files and exit PyCharm.
Step 7: Create a new map
You have run the CursorCreation script and are now ready to check the results.
a If necessary, open the PowerOutage project in ArcGIS Pro.
The instructions in this box are only necessary if you did not already create the
PowerOutage project. If you are unsure, ask your instructor for assistance.
1. Start ArcGIS Pro and, if necessary, sign in to your organizational account.
2. To the right of Recent Projects, click Open Another Project.
3. Browse to ..\EsriTraining\PYTS\Results\Exercise02A\PowerOutage, select
PowerOutage.aprx, and then click OK.
b Close any open map views.
c On the Insert tab, click New Map .
d In the Catalog pane, expand Maps, right-click Map, and choose Rename.
e Type Cursors and press Enter.
Step 8: Verify the script results
a In the Catalog pane, expand Folders, expand the Data folder, and then expand
CountyData.gdb.
b Right-click ParcelPts and choose Add To Current Map .
Lesson 5
5-20
c In the Contents pane, right-click the ParcelPts feature class and choose Attribute Table.
The Price Per Square Foot field has been updated with the correct values.
d Close the attribute table.
e Close any open maps.
f Save the project, and then exit ArcGIS Pro.
Now you will check the CSV file.
g In File Explorer, browse to ..\EsriTraining\PYTS.
h Open the AssessmentParcels.csv file in Notepad.
i Verify that the first row of data contains your field names.
All the parcels with a price per square foot less than or equal to 90 are listed in the table.
j Exit Notepad without saving your changes.
Working with cursors
5-21
1. Which cursor provides read-write access to field values in a feature class or table?
a. SearchCursor
b. UpdateCursor
c. InsertCursor
d. ReadCursor
2. In addition to reading data within a table, the Search cursor allows you to delete data
rows.
a. True
b. False
3. When you work with cursors, how do you free up memory and prevent schema locks?
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
Lesson 5
Lesson review
5-22
4. What will the following Python code accomplish?
fc = 'C:\EsriTraining\Default.gdb\Roads'
fields = ['ROAD_ID', 'ROAD_TYPE']
exp = " ROAD_TYPE = 'HWY' "
for row in arcpy.da.SearchCursor(fc, fields, exp):
print(f"For {row[0]} the type of highway is {row[1]}.")
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
Lesson review (continued)
Working with cursors
5-23
Examine cursors (page 5-7)
1. Which token can be used with the InsertCursor to add point features to a point feature class?
SHAPE@XY
2. Why is using an asterisk (*) for the field_names parameter to access all fields discouraged?
It impacts cursor performance, and the field order may not be reliable. It is
recommended that the list of fields be narrowed to only those that you need.
3. What methods does the UpdateCursor class provide?
deleteRow (), reset (), and updateRow (row)
Determine which cursor to use (page 5-9)
Scenario Cursor
Add five new employees to an employee database. InsertCursor
Compile a list of the current addresses of all your store
locations.
SearchCursor
Change district designation for your stores. UpdateCursor
Answers to Lesson 5 questions
5-24
Scenario Cursor
Add contact information for a neighborhood sports
team.
UpdateCursor
Identify which students live in a particular county. SearchCursor
Modify addresses on a mailing list. UpdateCursor
Apply the cursor workflow (page 5-13)
Step Action
Which task needs to be
accomplished?
You need to update the price per square foot and
select the parcels that meet the criteria.
Which dataset needs to be
manipulated?
The target feature class is ParcelPts.
Which cursor or cursors
need to be used?
The Search cursor and the Update cursor are
needed to accomplish the task.
Answers to Lesson 5 questions (continued)
5-25
Step Action
List the cursor or cursors
used and what they will do.
• The Update cursor will calculate the price per
square foot.
• The Search cursor will determine which parcels
meet the criteria.
Answers to Lesson 5 questions (continued)
5-26
In many geoprocessing workflows, you run tools that work with coordinate and geometry
information. The geoprocessing tools that you use may accept features from a feature layer
or a feature class as input to the tool. These same tools will also accept geometry objects
as input in place of features.
Geometry objects that can be created in memory include Geometry, Multipoint,
PointGeometry, Polyline, and Polygon. These can be empty geometry objects, or they can
be populated with coordinate pairs of x,y values.
Topics covered
Creating geometry objects
Accessing and updating geometry
Using geometry objects in a geoprocessing tool
6 Geoprocessing with geometry objects
6-1
When performing geoprocessing tasks, you may need to run a tool that uses coordinate or
geometry information for input. In a normal workflow, you might create a temporary feature
class to hold the geometry, populate the feature class with an Insert cursor, and then use the
feature class for input to the geoprocessing tool. Geometry objects are created in your
computer's memory and can be used in place of permanent feature classes for intermediate
data. These objects help reduce the amount of time reading and writing from disk.
An alternative to storing the geometry in a temporary feature class is to use the ArcPy
Geometry classes.
Figure 6.1. You can use geometry objects in geoprocessing tools.
Geometry objects can be created in memory from the Geometry, Multipoint, PointGeometry,
Polyline, and Polygon ArcPy classes. The geometry object can be populated to represent a
shape and then used for input in a geoprocessing tool, removing the need to store the
geometry in a temporary feature class. Using a geometry object can make your workflows
simpler than they would be if you were to use a feature layer or feature class as input.
Lesson 6
Benefits of geometry objects
6-2
The geometry object defines all the properties of data passed between processes and tools.They can be created from scratch using Geometry, Multipoint, PointGeometry, Polygon, or
Polyline classes or by setting the output of a geoprocessing tool to an empty geometry object.
There are different workflows that create geometry objects from scratch, including the
PointGeometry object, Polygon/Polyline geometry object, and cursor workflows. You can use
each workflow within a Python script.
PointGeometry object
The PointGeometry object is a shape that has no area or length. It supports all geometry
object properties, including a spatial reference. It is constructed from a Point object. A typical
workflow for creating a PointGeometry object is to create and populate a Point object, then
pass the Point object to the arcpy.PointGeometry() as the input parameter.
Figure 6.2. Workflow to create a PointGeometry object.
Polygon/Polyline/Multipoint geometry object
The Polygon, Polyline, and Multipoint geometry workflows are similar. Each workflow starts
with creating arrays. An array contains the points (vertices) used to create the geometry object.
The difference between the polygon and polyline geometry objects is whether the vector line
connecting the points joins the origin point. After the array is populated, the geometry object
will be created.
Figure 6.3. Workflows to create a Polygon, Polyline, and Multipoint geometry object.
Workflows to create geometry objects
Geoprocessing with geometry objects
6-3
Cursor
You can also use cursors to create or update the geometry of feature classes through geometry
objects. Updating features in an existing feature class or inserting new features into a feature
class is accomplished using the arcpy.da cursors. The cursor can access the feature geometry
by working with the Shape field in the current cursor row. When accessing feature geometry or
passing a new geometry object to the Shape field, use the SHAPE@ tokens in the cursor field
list for more efficient cursor performance.
Figure 6.4. Workflow to create a geometry object with a cursor.
Lesson 6
Workflows to create geometry objects (continued)
6-4
Within each geometry object, there are different properties that can be obtained and used to
create new geometries. For example, you can use Polyline geometry objects for many
applications, including harvesting the vertices to form new geometries or calculating the
distance for portions of an existing geometry object.
Figure 6.5. Geometry object properties.
Discovering polyline geometry objects
Geoprocessing with geometry objects
6-5
Geometry objects define a geometric shape and spatial location. You can create a geometry
object using the arcpy.Geometry class constructor or by using the Multipoint, PointGeometry,
Polyline, or Polygon class constructors.
Syntax
arcpy.Geometry(geometry, inputs, {spatial_reference}, {has_z}, {has_m})
arcpy.Geometry parameters
Parameter Description
geometry The geometry object type:
• Point
• Multipoint
• Polyline
• Polygon
inputs The coordinate pairs used to create the geometry object; the data
type can be either Point or Array.
spatial_reference The spatial reference of the new geometry; the data type is a
SpatialReference object. Use arcpy.SpatialReference to create a
new object or arcpy.Describe to obtain an existing spatial
reference.
has_z True if Z is enabled for the geometry; false if not enabled.
has_m True if M is enabled for the geometry; false if not enabled.
If the geometry parameter is set to Point, the arcpy.Geometry class constructor will
ignore the spatial_reference parameter.
ArcGIS Pro Help: Geometry
Lesson 6
Components of a geometry object
6-6
In Python, methods are functions that belong to an object and are defined inside of a class.
For geometry objects, there are different methods available that increase processing efficiency
for basic spatial analysis and allow for custom geometries to be created.
Instructions
a Open a web browser and go to the Geometry ArcGIS Pro Help topic (https:/
/pro.arcgis.com/en/pro-app/latest/arcpy/classes/geometry.htm).
b Browse to the specified method, and then answer the following questions about different
geometry object methods.
c When you are finished, close the web browser.
1. Which method will construct a geometry that is the minimal bounding polygon such that
all outer angles are convex?
__________________________________________________________________________________
__________________________________________________________________________________
2. The difference(other) method will construct a geometry that __________________.
__________________________________________________________________________________
__________________________________________________________________________________
3. Which method will construct a polygon at a specified distance from the geometry?
__________________________________________________________________________________
__________________________________________________________________________________
4. What output is returned from the within(second_geometry,{relation}) method?
__________________________________________________________________________________
__________________________________________________________________________________
Discover geometry object methods
Geoprocessing with geometry objects
6-7
https://pro.arcgis.com/en/pro-app/latest/arcpy/classes/geometry.htm
You have received a CSV file with the coordinates of a power outage. You have been tasked
with creating a polygon boundary of the outages and determining the service areas that
intersect the power outage points. To accomplish this task, you will create a multipoint
geometry object from the x,y coordinates and use the convexHull() method to create the
boundary. The multipoint geometry will then be used as input for the Spatial Join tool to
determine which service areas are affected.
In this exercise, you will perform the following task:
• Create a Python script that uses geometry objects as input to an ArcGIS geoprocessing
tool.
Exercise 6
Convert coordinates into affected area polygons
15 minutes
6-8
Step 1: Open a Python script in PyCharm
In this step, you will use PyCharm to create a script using lists.
a Start PyCharm.
b In the Project pane, under the Scripts folder, double-click OutageGeometry.py.
Step 2: Evaluate the Python script
The Python script contains many of the steps needed to determine the service area provided,
including variables and geoprocessing tools to process the data.
a Evaluate the Python script, and then consider the following questions.
1. Which module has been imported to read the OutageXY table?
_______________________________________________________________________________
2. Which loop is used to examine each row in the table?
_______________________________________________________________________________
3. Which cursor is used to determine which service area covers the new geometry?
_______________________________________________________________________________
Now that you have evaluated the Python script, you are ready to add the code to generate the
geometry object.
Step 3: Create the geometry object from a list
The script will read all the outage coordinates and create a list of the coordinates. You will use
that list to create the multipoint geometry and the outage boundaries.
a Find the section of the code with the comment
# Create a multipoint geometry object from list of coordinates.
b Type the following code to create point geometry from the coordinates, place the points
into an array, and then use the array to create the multipoint geometry:
pntLst = []
for coords in outageCoords:
pnt = arcpy.Point(coords[0], coords[1])
Geoprocessing with geometry objects
6-9
pntLst.append(pnt)
pntAry = arcpy.Array(pntLst)
outagePoints = arcpy.Multipoint(pntAry)
print("Geometry object created.")
An alternative technique for creating multipoint geometry is to use a Python List
Comprehension like the following example, which is modifiedscript in PyCharm.......................................................................3-12
Create a Describe object .............................................................................................3-12
Use Describe properties to create a new feature class ................................................3-13
Verify the new feature class..........................................................................................3-15
Using the da.Describe object in a geoprocessing script ...................................................3-16
Lesson review.....................................................................................................................3-17
Answers to Lesson 3 questions..........................................................................................3-18
Lesson introduction .............................................................................................................4-1
List functions in Python ........................................................................................................4-2
Examine the ListFiles function .............................................................................................4-4
Finishing the List function syntax .........................................................................................4-5
Exercise 4A: Prepare to automate with Python lists ............................................................4-8
Create a new map..........................................................................................................4-9
Create a list of workspaces ............................................................................................4-9
Create a list of features ................................................................................................4-10
Create a list of fields ....................................................................................................4-10
Using a for loop .................................................................................................................4-12
Using a for loop to iterate over lists...................................................................................4-14
Exercise 4B: Automate a geoprocessing workflow using loops ........................................4-15
Create a new Python script in PyCharm.......................................................................4-16
Copy feature classes from a workspace .......................................................................4-16
Verify the new feature classes ......................................................................................4-17
Lesson review.....................................................................................................................4-19
Answers to Lesson 4 questions..........................................................................................4-20
Lesson introduction .............................................................................................................5-1
Types of cursors ...................................................................................................................5-2
Examine cursors ...................................................................................................................5-7
Determine which cursor to use ............................................................................................5-9
Exploring cursor syntax......................................................................................................5-10
ii
6 Geoprocessing with geometry objects
7 Using ArcGIS Notebooks
Using cursors in a workflow ...............................................................................................5-11
Apply the cursor workflow .................................................................................................5-13
Exercise 5: Read and update values in a feature class.......................................................5-14
Create a new Python script in PyCharm.......................................................................5-15
Set up the Python script...............................................................................................5-15
Create an Update cursor ..............................................................................................5-15
Create a Search cursor .................................................................................................5-17
Write values to a CSV file .............................................................................................5-19
Run the script in PyCharm............................................................................................5-20
Create a new map........................................................................................................5-20
Verify the script results .................................................................................................5-20
Lesson review.....................................................................................................................5-22
Answers to Lesson 5 questions..........................................................................................5-24
Lesson introduction .............................................................................................................6-1
Benefits of geometry objects...............................................................................................6-2
Workflows to create geometry objects................................................................................6-3
Discovering polyline geometry objects ...............................................................................6-5
Components of a geometry object .....................................................................................6-6
Discover geometry object methods ....................................................................................6-7
Exercise 6: Convert coordinates into affected area polygons .............................................6-8
Open a Python script in PyCharm..................................................................................6-9
Evaluate the Python script..............................................................................................6-9
Create the geometry object from a list ..........................................................................6-9
Run the script in PyCharm............................................................................................6-11
Create a new map........................................................................................................6-12
Verify the script output feature classes ........................................................................6-12
Lesson review.....................................................................................................................6-14
Answers to Lesson 6 questions..........................................................................................6-15
Lesson introduction .............................................................................................................7-1
Benefits of ArcGIS Notebooks.............................................................................................7-2
Cell types in ArcGIS Notebooks ..........................................................................................7-4
Explore a sample notebook.................................................................................................7-6
Impact of data engineering on analysis results....................................................................7-7
Evaluate data changes in a notebook in ArcGIS Pro ...........................................................7-8
Exercise 7: Create a notebook in ArcGIS Pro ......................................................................7-9
Create a new map........................................................................................................7-10to appear in the
workbook (the code will appear as one line):
outagePoints = (arcpy.Multipoint(arcpy.Array([arcpy.Point(*coords) for
coords in outageCoords])))
This code will create a multipoint geometry object that will show all the outage areas
individually. Although this geometry object will effectively show the outage areas specifically,
your manager would like to see the whole area that is affected in case some areas did not
report the outage.
c Find the section of the code with the comment
#Create outage boundary using convex hull.
d Type the following code to use the convexHull() geometry method:
convexHull = outagePoints.convexHull()
arcpy.CopyFeatures_management(convexHull, outConvexHull)
print("Outage boundary created."
The Copy Features tool is used to create a permanent feature class.
e Check your code against the following code to be sure that you have entered the code
correctly:
# Create a multipoint geometry object from list of coordinates
pntLst = []
for coords in outageCoords:
Lesson 6
6-10
pnt = arcpy.Point(coords[0], coords[1])
pntLst.append(pnt)
pntAry = arcpy.Array(pntLst)
outagePoints = arcpy.Multipoint(pntAry)
print("Geometry object created.")
# Create outage boundary using convex hull
convexHull = outagePoints.convexHull()
arcpy.CopyFeatures_management(convexHull, outConvexHull)
print("Outage boundary created.")
Step 4: Run the script in PyCharm
Now that you have completed the script, it is ready to run.
a Review the completed script.
b Right-click in the script window and choose Run 'OutageGeometry'.
4. Which service area crews should be alerted to respond to the power outage?
__________________________________________________________________________________
__________________________________________________________________________________
After the script finishes running, it will print the following information to the Python Console:
Modules imported and environments set.
Variables are set.
Geometry object created.
Outage boundary created.
Spatial join finished.
Affected service areas
Service Area: 8
Service Area: 9
Service Area: 1
Analysis complete.
Process finished with exit code 0
Geoprocessing with geometry objects
6-11
c Close any open Python files and exit PyCharm.
Step 5: Create a new map
a If necessary, open the PowerOutage project in ArcGIS Pro.
The instructions in this box are only necessary if you did not already create the
PowerOutage project. If you are unsure, ask your instructor for assistance.
1. Start ArcGIS Pro and, if necessary, sign in to your organizational account.
2. To the right of Recent Projects, click Open Another Project.
3. Browse to ..\EsriTraining\PYTS\Results\Exercise02A\PowerOutage, select
PowerOutage.aprx, and then click OK.
b On the Insert tab, click New Map .
c In the Catalog pane, expand Maps, right-click Map, and choose Rename.
d Type GeometryObjects and press Enter.
Step 6: Verify the script output feature classes
a In the Catalog pane, expand Folders, expand the Data folder, and then expand
CountyData.gdb.
b Right-click the ParcelPoly feature class and choose Add To Current Map .
c In the Catalog pane, expand Outages.gdb.
d Notice the new CurrentAffectedArea feature class.
Hint:Hint: If the new feature class does not appear, refresh the folder.
e Right-click the CurrentAffectedArea feature class and choose Add To Current Map .
The CurrentAffectedArea layer overlaps the ParcelPoly layer.
Lesson 6
6-12
f Close any open maps.
g Save the project, and then exit ArcGIS Pro.
Now you have created a Python script that uses geometry objects as input to geoprocessing
tools. You will use geometry objects later in your final script tool.
Geoprocessing with geometry objects
6-13
1. To use a geometry object, it must persist within a geodatabase.
a. True
b. False
2. To create a Polyline or Polygon geometry object, which two objects must first be
created?
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
3. What is one of the primary benefits of using a geometry object in your script?
a. Geometry objects all have the same coordinate system.
b. Geometry objects are temporary and contained in memory.
c. Geometry objects have a default file size of a TB.
d. Geometry objects are always named the same way, allowing for easier coding.
Lesson 6
Lesson review
6-14
Discover geometry object methods (page 6-7)
1. Which method will construct a geometry that is the minimal bounding polygon such that all
outer angles are convex?
convexHull()
2. The difference(other) method will construct a geometry that __________________.
Is composed of only the region unique to the base geometry but not part of the other
geometry.
3. Which method will construct a polygon at a specified distance from the geometry?
buffer(distance)
4. What output is returned from the within(second_geometry,{relation}) method?
A Boolean True or False output is given based on whether the output of the base
geometry is within the comparison geometry.
Exercise 6: Convert coordinates into affected area polygons (page 6-8)
1. Which module has been imported to read the OutageXY table?
CSV module
2. Which loop is used to examine each row in the table?
for loop
3. Which cursor is used to determine which service area covers the new geometry?
Search cursor
4. Which service area crews should be alerted to respond to the power outage?
Crews for service areas 8, 9, and 1 should be alerted.
Answers to Lesson 6 questions
6-15
ArcGIS Notebooks gives you access to the functionality of open-source Jupyter Notebooks
within ArcGIS Pro. Your notebooks can include Python code, data charts, narrative text,
and images. You can run and rerun the notebooks as you modify your Python code and
data input. You can also collaborate with other teams across your organization by sharing
notebooks. In this lesson, you will learn about the capabilities and benefits of ArcGIS
Notebooks, evaluate data changes in ArcGIS Notebooks, and create a notebook in ArcGIS
Pro.
Topics covered
Benefits of using ArcGIS Notebooks
Data engineering using ArcGIS Notebooks
Creating notebooks in ArcGIS Pro
7 Using ArcGIS Notebooks
7-1
ArcGIS Notebooks integrates open-source Python with the ArcGIS system to support data
engineering and spatial analysis workflows. Using ArcGIS Notebooks as a Python development
environment in ArcGIS Pro provides many benefits, as described in the following table.
Benefit Description
Connectivity
with Jupyter
Notebooks
Notebooks can be stored directly within ArcGIS Pro instead of having
your analysis in a separate Jupyter environment. This connectivity
between ArcGIS Pro and Jupyter Notebooks offers easy access to
your notebook while working in your ArcGIS Pro project.
Cross-team
collaboration
Notebooks combines Python with interactive visualizations and
descriptions of your workflow in a shareable medium familiar to data
scientists. You can import shared notebooks (.ipynb files) from across
an organization into ArcGIS Pro, and open-source Jupyter Notebooks
can run any notebook created in ArcGIS Pro. These capabilities allow
better collaboration between GIS and data science teams.
Open-source
Python
integration
Although ArcGIS Pro gives access to open-source Python integration
through the Python Package Manager, ArcGIS Notebooks provides a
more accessible way to explore the vast functionality of open-source
integration. Within ArcGIS Notebooks, you can use Pandas to create
data frames, matplotlib libraries to visualize data, or h5py to slice into
multi-terabyte datasets stored on disk.
Storytelling
with code
Notebooks provides contextual narration along with results that you
visualize using return tables, charts, and maps to help drive insight
and action for real-world problem-solving.Lesson 7
Benefits of ArcGIS Notebooks
7-2
Benefit Description
Data
engineering
Notebooks helps prepare raw data by improving your ability to
visualize data, explore tabular data, and even quickly add data to a
map for inspection.
Spatial
analysis
Notebooks gives access to ArcGIS Pro geoprocessing tools and
allows you to utilize statistical, open-source Python libraries side by
side with your maps. ArcGIS Notebooks can access layers in your map
by name and add the output of a geoprocessing tool to the map by
default. When running a geoprocessing tool in ArcGIS Notebooks,
the tool results log appears in the geoprocessing history.
Automation Notebooks provides an environment within ArcGIS Pro to automate
repetitive administrative tasks in your GIS by using the built-in ArcGIS
Python libraries.
Reproducible
research
Using Markdown, you can contextualize your analyses by combining
text and images with your code to communicate your desired intent.
By adding this information, your work can be reproducible beyond
just sharing the code.
Benefits of ArcGIS Notebooks (continued)
Using ArcGIS Notebooks
7-3
There are two types of cells in ArcGIS Notebooks: markdown and code.
Markdown cells
The notebook will interpret all content in a markdown cell in the Markdown language, which
converts plain text into formatted text and images. For example, the Markdown language can
be used to format headings by adding one or more number signs to the beginning of a line.
When a markdown cell is run, any headings and body text are converted to rich text. To edit
the contents of a markdown cell, double-click the cell, make the change, and then run the cell
to view the updates.
Figure 7.1. An example of a markdown cell is shown before and after the cell is run in the notebook.
Code cells
The notebook will interpret all content in a code cell in the Python language. When a code cell
is run, the Python commands that are contained in the cell will be executed.
Lesson 7
Cell types in ArcGIS Notebooks
7-4
Figure 7.2. This example code cell contains a comment and a Python command.
Cell types in ArcGIS Notebooks (continued)
Using ArcGIS Notebooks
7-5
Notebooks allow you to create rich Python environments using elements such as text, lists,
charts, images, and links. You will explore the historical wildfire analysis notebook that shows a
few of these elements, and then you will answer some questions about the notebook.
Instructions
a Start ArcGIS Pro.
b Click Open Another Project.
c Browse to C:\EsriTraining\PYTS\Projects\WildfireAnalysis and open WildfireAnalysis.aprx.
d Browse the Historic Wildfire Analysis notebook, and then answer the following questions
about the elements of the notebook.
e When you are finished, exit ArcGIS Pro without saving changes.
1. Select the first cell in the notebook and review the drop-down list on the toolbar. Which
cell type is used to provide a background to the wildfire analysis project?
__________________________________________________________________________________
__________________________________________________________________________________
2. What elements are part of the Markdown cell?
__________________________________________________________________________________
__________________________________________________________________________________
3. Which Python modules are imported in the historical wildfire analysis notebook?
__________________________________________________________________________________
__________________________________________________________________________________
4. The matplotlib module is used to add charts to the historical wildfire analysis notebook.
What types of charts are used to display wildfire frequency and causes?
__________________________________________________________________________________
__________________________________________________________________________________
Lesson 7
Explore a sample notebook
7-6
Data engineering is the means for cleaning, preparing, and processing raw data into
something ready to be used in the analysis. It can turn data tables into location-enabled data
for visualization on maps. Data engineering can also mean enriching data with demographic,
psychographic, and socioeconomic data using Esri tools.
1. What are some ways that raw data can be cleaned and prepared for use in analysis?
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
2. What types of outside data could ArcGIS Notebooks allow you to access and add to
your data?
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
3. How might data engineering in ArcGIS Notebooks impact your analysis results?
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
Impact of data engineering on analysis results
Using ArcGIS Notebooks
7-7
Input data can be changed, either through editing or by using a different dataset. Having the
ability to rerun existing code for other datasets without going through each processing step is
more efficient. You can rerun the Python code within a notebook cell on modified data to
produce a different output. Additionally, you can use a different dataset in the notebook code
and then rerun the cell to see the changes. You can follow these steps to evaluate data:
1. Update the input data.
2. Rerun the notebook.
3. Evaluate the output in the map and the notebook.
Figure 7.3. Evaluating data changes in ArcGIS Notebook
Lesson 7
Evaluate data changes in a notebook in ArcGIS Pro
7-8
You are creating a notebook for use during your presentation at the daily power outage
meeting. Each hour, you receive an updated file of all the power outages. Your team wants to
know quickly how the outages are being reported (app, phone, or social media) and where the
power outages occur. You will leverage pandas to evaluate the data and matplotlib to chart the
data. Then, you will run the kernel density tool to visualize where the outages are on your map.
In this exercise, you will perform the following tasks:
• Create a new notebook.
• Add Markdown.
• Use Python to query data.
• Use Python to create a chart.
• Use Python to perform analysis.
Exercise 7
Create a notebook in ArcGIS Pro
25 minutes
7-9
Step 1: Create a new map
You will begin by creating a new map that will be used to add the output from the notebook.
a If necessary, open the PowerOutage project in ArcGIS Pro.
The instructions in this box are only necessary if you did not already create the
PowerOutage project. If you are unsure, ask your instructor for assistance.
1. Start ArcGIS Pro and, if necessary, sign in to your organizational account.
2. To the right of Recent Projects, click Open Another Project.
3. Browse to ..\EsriTraining\PYTS\Results\Exercise02A\PowerOutage, select
PowerOutage.aprx, and then click OK.
b On the Insert tab, click New Map .
c Rename the new map Notebook.
Hint:Hint: Catalog > Maps > Rename
Step 2: Create a new notebook
Next, you will create a new notebook that will use a feature class containing all the outage
analysis data.
a On the Insert tab, click New Notebook .
b In the Catalog pane, expand Notebooks, right-click New Notebook.ipynb, and choose
Rename.
c Type PowerOutage and press Enter.
d Drag the PowerOutage notebook tab and dock it to the right side of your display.
Step 3: Add Markdown to the notebook
In this step, you will use Markdown to add narration and an image aboutthe purpose of the
notebook.
a Verify that the PowerOutage notebook is enabled.
b With the first cell selected, on the notebook toolbar, click the drop-down list and choose
Markdown.
Lesson 7
7-10
c In the first cell, type # Power Outage Analysis and press Enter.
Heading levels are set by using one or more # characters followed by a space before the text.
d Type *** and press Enter to create a horizontal rule.
e Type The purpose of this notebook is to explore the power outage data., and then
press Enter twice.
From the toolbar, click Run .
Alternately, you can press Shift+Enter to run a cell. For more information about
keyboard shortcuts, open the Help menu and choose Keyboard Shortcuts.
When the cell runs, the text is formatted based on the Markdown syntax.
f Double-click the first cell to edit the Markdown text.
g At the bottom of the cell, type The following tasks will be performed in this notebook:
and press Enter.
A dash can be used to create an unordered list.
Be sure to add the space between the dash and the text.
h Type - Access data and press Enter.
i Type - Create chart and press Enter.
j Type - Perform analysis and press Enter.
Next, you will add an image to the Markdown cell.
k From the toolbar, click Edit and choose Insert Image.
Depending on your display settings, you may not see the Edit button. Instead, click
Menu, choose Edit, and then choose Insert Image.
l In the Select A File dialog box, click Choose File.
m Browse to C:\EsriTraining\PYTS\Data and select PowerOutages.jpeg.
n Click Open.
o Click OK.
p From the toolbar, click Run.
Using ArcGIS Notebooks
7-11
You have successfully added formatted text and an image to your notebook using Markdown.
Step 4: Import Python site packages
Now that you have added narration, you will import the Python packages needed for the
analysis. The pandas library is used for analyzing tabular data, and the matplotlib library is used
for data visualization.
a Click in the cell after the Markdown cell.
b Type the following code block, pressing Enter after each line:
import arcpy
import pandas as pd
import matplotlib
Lesson 7
7-12
import matplotlib.pyplot as plt
import arcgis
After importing ArcGIS API for Python, you will have access to a Python library for performing
GIS visualization and analysis, spatial data management, and GIS system administration tasks.
c Click Run.
Step 5: Add Python code to query the data
Next, you will add Python code to access and explore the power outage data.
a Click in the next cell and, from the toolbar, change the type to Markdown.
b Type ## Access data and press Enter.
c From the toolbar, click Run.
d In the next cell, type outages = r"C:\EsriTraining\PYTS\Data\Outages.gdb\AllOutages" and
press Enter.
You will create a spatially enabled pandas data frame from the AllOutages feature class, which
will let you use pandas' powerful data exploration and engineering methods.
e Type df = pd.DataFrame.spatial.from_featureclass(outages) and press Enter.
You will get a summary of the pandas DataFrame by using .info()
f Type df.info().
g From the toolbar, click Run.
1. Which fields are returned in the information?
Using ArcGIS Notebooks
7-13
__________________________________________________________________________________
__________________________________________________________________________________
You will specify the Source and Residents fields to use when querying the data. This will limit
the data being accessed to just those two fields.
h In the next cell, type outage_df = df[["Source","Residents"]] and press Enter.
i Type outage_df.head() and press Enter.
j From the toolbar, click Run.
The output shows a sample of the data that you can use to determine the type of summaries
and charts that you can create.
You will group the data by source and show the count of outages from each source.
k In the next cell, type outage_df.groupby("Source").agg({"Source":"count"}).
l From the toolbar, click Run.
2. How many outage reports came from social media?
__________________________________________________________________________________
__________________________________________________________________________________
Now that you have explored that data, you will create visuals of the data using a chart and a
map.
Step 6: Add Python code to create a chart
Now that you have grouped the power outage reports by source, you will create a chart using
the matplotlib site package.
a Click in the next cell and, from the toolbar, change the type to Markdown.
Lesson 7
7-14
b Type ## Create chart and press Enter.
c From the toolbar, click Run.
d In the next cell, type source = df["Source"].value_counts().
The .value_counts will return the counts of unique values from the DataFrame field. The pie
chart will use these values.
e From the toolbar, click Run.
f In the next cell, type %matplotlib inline and press Enter.
The %matplotlib inline line will display any outputs within the notebook instead of
opening a new window.
g Under the %matplotlib inline line, type the following block of code, pressing Enter
after each line:
plt.bar(source.index, source, color=['blue', 'orange', 'green'])
plt.show()
h From the toolbar, click Run.
You have created a bar chart of the power outage sources. The bar chart can be further
customized using additional matplotlib functions.
Step 7: Add Python code to perform analysis
In this step, you will run the Kernel Density tool on the AllOutages feature class. Because the
Using ArcGIS Notebooks
7-15
Kernel Density tool requires the ArcGIS Spatial Analyst extension, you will add an extension
check to the code.
a Click in the next cell and, from the toolbar, change the type to Markdown.
b Type ## Perform analysis and press Enter.
c From the toolbar, click Run.
d In the next cell, type
if arcpy.CheckExtension("Spatial") == "Available":
outage_density = arcpy.sa.KernelDensity(outages, "Residents", 100, None,
"SQUARE_MILES")
outage_density.save(r"C:\EsriTraining\PYTS\Default.gdb\
OutageDensityByResidents")
else:
msg = "ArcGIS Spatial Analyst extension is not available."
print(msg)
e From the toolbar, click Run.
Lesson 7
7-16
The outage_density layer is added to the Notebook map and provides a visual of where the
majority of the power outages are located.
f Close any open maps and notebooks.
g From the View tab, click Reset Panes and choose Reset Panes For Mapping (Default).
h Save the project, and then exit ArcGIS Pro.
In this exercise, you created a notebook that you can use in your presentations at the daily
power outage meeting. This notebook will allow you to have updated data, charts, and maps
ready each day for the meeting. You can also easily share the notebook with others who will
use the data in their analysis and decision-making.
Using ArcGIS Notebooks
7-17
1. The ability to import shared notebooks (.ipynb files) allows which benefit of ArcGIS
Notebooks?
a. Access open-source Python integration
b. Collaborate between GIS and data science teams
c. Perform spatial analysis
d. Build reproducible research
2. What open-source application is used to integrate ArcGIS Notebooks into ArcGIS Pro?
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
3. Which ArcGIS Notebooks cell type allows you to add images to your Python code?
a. Markdown
b. Code
c. Text
d. Raw
Lesson 7
Lesson review
7-18
Explore a sample notebook (page 7-6)
1. Select the first cell in the notebook and review the drop-down list on the toolbar. Which cell
type is used to provide a background to the wildfire analysis project?
Markdown cells allow you to add formatted text to a notebook.
2. What elements are part of the Markdown cell?
Headings, lists, images, plain text, and links are part of the Markdown cell.3. Which Python modules are imported in the historical wildfire analysis notebook?
The arcpy, pandas, NumPy, matplotlib, and ArcGIS modules are used in the notebook.
4. The matplotlib module is used to add charts to the historical wildfire analysis notebook.
What types of charts are used to display wildfire frequency and causes?
The wildfire frequency and causes are displayed using bar and pie charts.
Impact of data engineering on analysis results (page 7-7)
1. What are some ways that raw data can be cleaned and prepared for use in analysis?
Answers will vary based on personal experience.
2. What types of outside data could ArcGIS Notebooks allow you to access and add to your
data?
Answers will vary based on personal experience.
3. How might data engineering in ArcGIS Notebooks impact your analysis results?
Answers will vary based on personal experience.
Exercise 7: Create a notebook in ArcGIS Pro (page 7-9)
1. Which fields are returned in the information?
The OBJECTID, Source, Residents, and SHAPE fields are returned.
2. How many outage reports came from social media?
There are 153 outage reports that came from social media.
Answers to Lesson 7 questions
7-19
Python script tools provide a graphical user interface for your Python script. Through the
Python script tool, users of your script can input their own data and apply your process to
complete their analysis. You can also adjust the tool properties to create a Python script
tool that will accept the desired data and output the desired results.
In this lesson, you will learn how to accept user input in your script and use the Python tool
creation workflow to create a Python script tool.
Topics covered
Using ArcPy functions to receive user input
Customizing input and output parameters in a Python script tool
Creating a Python script tool
8 Creating a Python script tool
8-1
Python scripts allow you to automate your workflow through the use of geoprocessing tools
and Python functionality. Most scripts are created for a specific workflow, dataset, or analysis.
So, what can you do to preserve the scripted workflow that you created and reuse it on a
different dataset or share it with others in your organization?
Figure 8.1. Python script tools make a Python script more accessible by allowing the tool to be run on differing
input data.
One way to share your Python script is by adding it to a Python script tool. These
geoprocessing tools execute a script or an executable file within ArcGIS Pro. Script tools allow
you to run scripts from within ArcGIS Pro using a custom geoprocessing tool as the interface.
Many GIS users are comfortable and familiar with using the geoprocessing tool interface to
interact with their data. By converting your Python script to a Python script tool, you will allow
other users to perform your workflow with different data.
Lesson 8
Improving script accessibility
8-2
You can control the name, description, inputs, outputs, access, and behavior of your Python
script tool through properties.
These properties are divided into four sections:
• General
• Parameters
• Execution
• Validation
Figure 8.2. Properties of a Python script tool.
General
These properties control the name of the tool, the source of the Python script, and the security
of the script. The options to import the Python script into the tool are also available here.
Parameters
The parameters of a Python script tool define what input datasets, additional parameters, and
Components of a Python script tool
Creating a Python script tool
8-3
output datasets the script will display. The parameters will reference variables within the
Python script tool and will appear in the tool interface. For each parameter, you can specify a
label, indicate the data type, specify whether the parameter is input or output, and configure
many other properties.
For more information on the properties that you can set, see ArcGIS Pro Help: Create a script
tool.
Execution
The execution page properties allow you to access the execution code of the script tool. You
can paste the code directly within the editor or browse to path of the Python script. The
execution page provides functionality to embed and password-protect the script's code. There
is also the option to export the code to a new Python file.
Validation
The validation properties of a Python script tool allow you more control over the behavior,
appearance, and messaging within the script tool. Python script tool validation is handled
through functions that you create. These functions ensure that the proper data is used in the
parameters and provide more custom feedback before the tool is run. Tool validation will be
covered later in the course in more detail.
Lesson 8
Components of a Python script tool (continued)
8-4
You can increase the reusability and functionality of your Python script by accepting user input.
To allow for user input, you must remove the hard-coded paths to data in your script and
replace them with a function to gather user input. The choice of which function is based upon
the type of variable that you are replacing in the Python script.
These are the steps to follow in the workflow to accept user input:
• Identify variables
• Choose parameter data type
• Convert variable
• Reference in script tool
Figure 8.3. Workflow to accept user input in a Python script.
Identify variables
In this step, you will evaluate your Python script and determine which variables should be
converted to allow user input. Not all variables need user input. For instance, if you want to
Accepting user input
Creating a Python script tool
8-5
ensure that the name or location of output is consistent, you may not want to allow the users
to specify a new location or name.
Choose parameter data type
Depending on the analysis that you are performing, the variables could be text, a coordinate
system, or some other type of data. Some variables work better as objects in geoprocessing
tools (such as coordinate systems), whereas others work better as text.
Convert variable
After you have selected the parameter data type you will need in your Python script, you can
specify the function necessary to accept user input in that type. For most geoprocessing tools,
the function GetParameterAsText() will work to accept input as a string. However, there may
be some instances where GetParameter() is preferred.
For more information on the various functions your Python script may need, see ArcGIS Pro
Help: Setting script tool parameters.
Reference in script tool
Now that you have updated the Python script, the last step is to reference the new function in
the Python script tool interface. Remember to pay attention to the order of the parameter
functions in the script because they will be referenced in that order in the Python script tool
interface.
Lesson 8
Accepting user input (continued)
8-6
Python script tools reference portions of the Python code through parameters. Determining
which portions of the code can be used in parameters is an important skill to build.
Figure 8.4. Syntax of GetParameterAsText function.
Review the parameters in the script tool, and then fill in the value for each
GetParameterAsText(_) command in the Python script.
Remember that the index positions in Python begin with 0.
Parameter identification
Creating a Python script tool
8-7
Script tool Python script
Input polygon # Import site packages
import arcpy
# Define the variables
inPoly = arcpy.GetParameterAsText(__)
outPoly = arcpy.GetParameterAsText(__)
partSelect = arcpy.GetParameterAsText(__)
dField = arcpy.GetParameterAsText(__)
#Dissolve
arcpy.Dissolve_management(inPoly,
outPoly, dField, "", partSelect)
arcpy.GetMessages()
#Split
arcpy.analysis.SplitByAttributes(outPoly,
r"C:\Data", dField)
arcpy.GetMessages()
Output polygon
Dissolve field
Part definition
Lesson 8
Parameter identification (continued)
8-8
As the GIS specialist for Cumberland County Power, youhave a Python script that takes
multiple power outage data sources and creates a series of outputs for analysis. You have been
tasked with simplifying the workflow for users who may not know Python by creating a script
tool.
In this exercise, you will use the Python script tool interface to link the Python script to the
Python script tool interface. You will update the hard-coded inputs within the script with
GetParameterAsText() functions. Then, you will create the script tool and define its
parameters. After the parameters have been set, you will be ready to create the Python script
tool to share with other users.
In this exercise, you will perform the following tasks:
• Modify the variables in a Python script to accept user input.
• Use custom messaging to explain tool progress.
• Create a script tool in ArcGIS Pro.
Exercise 8
Create a Python script tool
20 minutes
8-9
Step 1: Prepare the Python script for user input
You have received a script with hard-coded values that need to be replaced with Python input
parameters. The Python script provides information to the power company outage team about
any reported power outages. The script uses information reported by three different mediums
(social media, the company app, and phone calls). It then generates an affected service area
polygon and a heat map indicating which areas are most affected to determine which service
areas should respond. You will use the arcpy.GetParameterAsText() function.
a Start PyCharm.
b In the Project pane, under the Scripts folder, double-click PowerOutage.py.
c In the script window, examine the script variables.
You will need to alter the paths of the input data. These paths include pNumFile, xyFile, and
ptFile.
Hint:Hint: The script variables reference parameters within the Python script. Look for the
section of code that refers to the parameters.
d Keeping the same variable name, replace the path values for the pNumFile, xyFile, and
ptFile input files with the arcpy.GetParameterAsText() function.
e Inside each GetParameterAsText() function parentheses, add incremental numbers
starting with 0.
Hint:Hint: You can comment out the file path at the end of each line as a point of reference.
f Check your code against the following code to ensure that you have entered the code
correctly:
pNumFile = arcpy.GetParameterAsText(0)
# r"C:\EsriTraining\PYTS\Data\PhoneReports.csv"
xyFile = arcpy.GetParameterAsText(1)
# r"C:\EsriTraining\PYTS\Data\SocialMediaReports.xlsx\SocialMediaXY$"
ptFile = arcpy.GetParameterAsText(2)
# r"C:\EsriTraining\PYTS\Data\AppReports.shp"
g Close any open Python scripts.
h Exit PyCharm.
Lesson 8
8-10
Step 2: Create a new map
a Open the PowerOutage project in ArcGIS Pro.
The instructions in this box are only necessary if you did not already create the
PowerOutage project. If you are unsure, ask your instructor for assistance.
1. Start ArcGIS Pro and, if necessary, sign in to your organizational account.
2. To the right of Recent Projects, click Open Another Project.
3. Browse to ..\EsriTraining\PYTS\Results\Exercise02A\PowerOutage, select
PowerOutage.aprx, and then click OK.
b On the Insert tab, click New Map .
c In the Catalog pane, expand Maps, right-click Map, and choose Rename.
d Type ScriptTool and press Enter.
e In the Catalog pane, expand Folders, and then expand the Data folder.
f Expand CountyData.gdb, right-click ServiceAreas, and choose Add To Current Map.
Creating a Python script tool
8-11
g In the Contents pane, right-click ServiceAreas and choose Symbology .
h In the Symbology pane, next to Symbol, click the current symbol, and then click the
Properties tab.
i Change the color of the layer fill to No Color and the outline color to a red color.
j Click Apply.
k Close the Symbology pane.
Step 3: Create a script tool in ArcGIS Pro
In this step, you will create a Python script tool in the project toolbox.
a In the Catalog pane, expand Toolboxes.
b Right-click the Default.atbx toolbox, point to New, and choose Script.
c In the New Script dialog box, on the General tab, for Name, type PowerOutage, and then
for Label, type Power Outage.
d On the Execution tab, for Script File, browse to ..\EsriTraining\PYTS\Scripts, select
PowerOutage.py, and click OK.
e Click the Parameters tab.
Each of the parameters appears in the order in which they are numbered in the Python script;
the order of entry determines the order in the tool that a user will see.
Using the Feature Layer data type allows users to browse to the file through the
Catalog pane or select from layers in the map through a drop-down list. In this
exercise, you will use the Feature Class data type, which only allows users to browse
to the file through the Catalog pane.
f Add the following parameters:
Label Data Type Direction Filter
Phone Reports Table Input
Social Media Reports Table Input
App Reports Points Feature Class Input Feature Type - Point
g Click OK to close the script tool properties.
Lesson 8
8-12
Now that you have created the Python script tool, you are ready to test it.
Step 4: Run the Python script tool
In this step, you will use some provided data about an outage to see if the tool processes it
correctly.
a In the Catalog pane, expand Default.atbx, if necessary, and double-click the Power Outage
script tool to open it.
b In the Geoprocessing pane, specify the following parameters:
• Phone Reports: ..\EsriTraining\PYTS\Data\PhoneReports.csv
• Social Media Reports: ..\EsriTraining\PYTS\Data\SocialMediaReports.xlsx\
SocialMediaXY$
• App Reports Points: ..\EsriTraining\PYTS\Data\AppReports.shp
You can browse directly to the Excel workbook sheet in the Open dialog box.
c Click Run to run the Power Outage script tool.
d Point to the successfully completed geoprocessing message and view the custom
messaging that has been added to the tool dialog box.
1. Which service areas have power outages?
__________________________________________________________________________________
__________________________________________________________________________________
2. Which service area has the most power outages?
__________________________________________________________________________________
__________________________________________________________________________________
e In the Contents pane, notice the three new datasets that have been created from the
Power Outage script tool:
• Outages
• OutageArea
• OutageDensity
Creating a Python script tool
8-13
f In the Contents pane, turn off the visibility of the Outages and OutageArea layers.
Verifying the messages and output layers allows you to confirm that the script tool ran
Lesson 8
8-14
correctly. In addition to running the script tool immediately, you can also schedule the script
tool to run at a later time or with recurrence.
g In the Geoprocessing pane, next to the Run button, click the down arrow and choose
Schedule .
In the Schedule dialog box, you can specify the task name, start date and time, recurrence,
expiration, and other options for how and when the scheduled script tool should run.
h Click Cancel to close the Schedule dialog box without scheduling the script tool.
i Close any open map views.
j From the View tab, click Reset Panes and choose Reset Panes For Mapping (Default).
k Save the project, and then exit ArcGIS Pro.
You have successfully created a Python script tool.
Creating a Python script tool
8-15
1. Which Python script tool property defines what input datasets and output datasets the
script will display?
a. General
b. Parameters
c. Validation
d. Environment
2. Which aspect of a Python script tool makes it more accessible to other users?
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
3. Which Python function will accept the user input asa string?
a. GetParameter()
b. SetParameter()
c. GetParameterAsText()
d. CopyParameter()
Lesson 8
Lesson review
8-16
Parameter identification (page 8-7)
Script tool Python script
Input polygon # Import site packages
import arcpy
# Define the variables
inPoly = arcpy.GetParameterAsText(__)
inPoly = arcpy.GetParameterAsText(0)
outPoly = arcpy.GetParameterAsText(__)
outPoly = arcpy.GetParameterAsText(1)
partSelect = arcpy.GetParameterAsText(__)
partSelect = arcpy.GetParameterAsText(3)
dField = arcpy.GetParameterAsText(__)
dField = arcpy.GetParameterAsText(2)
#Dissolve
arcpy.Dissolve_management(inPoly,
outPoly, dField, "", partSelect)
arcpy.GetMessages()
#Split
arcpy.analysis.SplitByAttributes(outPoly,
r"C:\Data", dField)
arcpy.GetMessages()
Output polygon
Dissolve field
Part definition
Answers to Lesson 8 questions
8-17
Exercise 8: Create a Python script tool (page 8-9)
1. Which service areas have power outages?
Service areas 3, 9, and 10
2. Which service area has the most power outages?
Service area 3
Answers to Lesson 8 questions (continued)
8-18
Python script tools can have custom behaviors based upon user input using validation.
Validation methods can check the parameters and return custom messaging directly within
the tool dialog box. The input parameters can also update other parameters, such as
creating a filter list based on the shape type. Tool validation helps you improve the tool's
user experience before sharing it with others.
In this lesson, you will learn how to add validation to a script tool to customize a tool's
behavior based upon user input.
Topics covered
Using validation to customize script tool behavior
Understanding the ToolValidator methods
Adding custom messaging to a tool dialog box
9 Adding validation to script tools
9-1
Python script tools are designed to be used repeatedly and shared with other users. Because
new users may not be familiar with the tool, it can be helpful to provide additional messaging
and behavior in the user interface. Validation in script tools provides a way to add this custom
behavior within the tool dialog box. It helps catch potential errors in the script prior to running
it and also improves the overall user experience.
Validation occurs in two different places: the internal validation done by the ArcGIS system and
the validation done by adding code to the script tool.
• Internal validation can perform tasks like checking if a required parameter is empty,
checking if an input dataset exists, or generating the default catalog path for output.
• Validation from adding code can perform tasks like setting default parameter values,
creating custom warning and error messaging, enabling or disabling parameters, or
categorizing parameters.
Figure 9.1. Validation process.
Validation is executed by geoprocessing when the tool is opened or when the user changes a
parameter in the dialog box. System geoprocessing tools have always been able to perform
validation based on user input within the dialog box.
Lesson 9
Customizing script tool behavior
9-2
You can customize script tool dialog boxes using parameter settings or validation code.
Validation code extends beyond the parameter settings by providing access to enable or
disable parameters and create custom messaging. In addition to allowing basic customization
options, it also allows you to build logic around the customization.
Customization Parameter
settings
Validation Validation syntax
Default values X X
self.params[5].value =
"C:\EsriTraining\PYTS\Data\
Outages.gdb"
Filter X X
self.params[3].filter.list =
["WATER", "SEWER", "GAS"]
Categories X X self.params[6].category = "Advanced"
Enable
/disable
X self.params[4].enabled = True
Using validation to create customizations
Adding validation to script tools
9-3
Customization Parameter
settings
Validation Validation syntax
Custom
message
X
self.params[1].setErrorMessage
("Custom message" )
Lesson 9
Using validation to create customizations (continued)
9-4
Figure 9.2. Ways to customize the tool dialog box using validation.
Using validation to create customizations (continued)
Adding validation to script tools
9-5
The validation script comprises four default methods that control the behavior of the script
tool. You should consider exploring each of these ToolValidator methods to understand how
they control the validation process.
In this activity, you will use the ArcGIS Pro Help to apply the different ToolValidator methods
used in the validation script.
Figure 9.3. ToolValidator methods.
Instructions
a Open a web browser and go to ArcGIS Pro Help: Customizing Script Tool Behavior (https:/
/pro.arcgis.com/en/pro-app/latest/arcpy/geoprocessing_and_python/customizing-script-
tool-behavior.htm).
b Look at the section describing each method, and then answer the following questions
about different validation methods.
c When you are finished, close the web browser.
Lesson 9
Validate script tool inputs using ToolValidator methods
9-6
https://pro.arcgis.com/en/pro-app/latest/arcpy/geoprocessing_and_python/customizing-script-tool-behavior.htm
1. Which ToolValidator method is called when the tool dialog box is first opened?
__________________________________________________________________________________
__________________________________________________________________________________
2. When is the updateParameters method called?
__________________________________________________________________________________
__________________________________________________________________________________
3. If you wanted to set a customized error message based upon a parameter value, which
ToolValidator method would you use to set the message?
__________________________________________________________________________________
__________________________________________________________________________________
4. If you wanted to disable a parameter, which ToolValidator method would you use?
__________________________________________________________________________________
__________________________________________________________________________________
Validate script tool inputs using ToolValidator methods (continued)
Adding validation to script tools
9-7
As the GIS specialist for Cumberland County Power, you will add customized behavior to your
Power Outage script tool, including tool dialog messaging based on logic. You will use
ToolValidator to raise an error if the input CSV file has no rows. You will add validation code to
check the input CSV file before the tool is run, which will allow users to identify and correct the
issue before running the script.
In this exercise, you will add code to the ToolValidator script to check user input and provide
warning and error messaging.
In this exercise, you will perform the following tasks:
• Validate user input to the script tool.
• Add custom messaging to the script tool dialog box.
• Verify the custom messaging.
Exercise 9
Add custom messaging to a script tool
15 minutes
9-8
Step 1: Open the script tool validation properties
In this step, you will open the ToolValidator script of the Power Outage tool from the default
toolbox.
a If necessary, open the PowerOutage project in ArcGIS Pro.
The instructions in this box are only necessary if you did not already create the
Power Outage tool in the PowerOutage project. If you are unsure, ask your
instructor for assistance.
1. Start ArcGIS Pro and, if necessary, sign in to your organizational account.
2. To the right of Recent Projects, click Open Another Project.
3. Browse to ..\EsriTraining\PYTS\Results\Exercise08\PowerOutage, select
PowerOutage.aprx, and then click OK.
b In the Catalog pane, expand Toolboxes, and then expand the Default.atbx toolbox.
c Right-click the Power Outage tool and choose Properties.
d In the Tool Properties dialog box, click the Validation tab to access the script.
e Click Open In Script Editor.
f If prompted,click Trust Project.
Clicking this button will open the ToolValidator script in the default Python editor as a
temporary file. Within ArcGIS Pro, PyCharm is currently set as the default editor.
Step 2: Add code to the validator script
With the ToolValidator script open, you will add code for custom messaging based on logic
that checks the number of row values in the table. Adding this logic in the validation will
provide the users with feedback about their data before running the tool.
The first part of the code will get the row count of the first parameter and assign the value to
the xyCount parameter.
a In the ToolValidator script, under the updateMessages(self) section, add an indented line
above the return statement, and type the following code:
xyCount = arcpy.GetCount_management(self.params[0].value)
Adding validation to script tools
9-9
Be sure that you indent the line until your code appears at the same level as the
commented message. Also, do not delete the return statement because it is
needed to close out the function.
The code will read the number of rows in the input phone reports table as indicated by the 0
index position within the parameters.
b Press Enter.
Next, you will use an if/elif/else statement to check the xyCount value. If the value equals
zero, then you want to return an error message. If the count is greater than 40, then you want
to return a warning message.
c In the updateMessages(self) section, below the code that you just typed, add the following
indented code to check if the xyCount equals zero:
if int(xyCount[0]) == 0:
self.params[0].setErrorMessage("File has no rows. Please select a file with
valid rows for tool to run correctly.")
d Press Enter.
e Add the following code to check whether the xyCount is greater than 40 and to return a
warning message stating that there could be performance issues:
Hint:Hint: Be sure to place the code at the same indent level as the if statement.
elif int(xyCount[0]) > 40:
self.params[0].setWarningMessage(f"File has {xyCount[0]} rows and may take
an extended amount of time to process.")
f Press Enter.
g Add the following code for all remaining values:
else:
pass
Lesson 9
9-10
h Press Enter.
i Check your code against the following code to ensure that you have entered the code
correctly:
Some lines of the following code are modified to appear in the workbook; these
lines will appear as one line in the ToolValidator script.
xyCount = arcpy.GetCount_management(self.params[0].value)
if int(xyCount[0]) == 0:
self.params[0].setErrorMessage("File has no rows. Please select a
file with valid rows for tool to run correctly.")
elif int(xyCount[0]) > 40:
self.params[0].setWarningMessage(f"File has {xyCount[0]} rows and
may take an extended amount of time to process.")
else:
pass
j From the File menu, choose Save All.
Step 3: Verify the validator code
a In ArcGIS Pro, verify that the ToolValidator script has been updated with the changes.
If the changes do not display in ArcGIS Pro, you can copy the entire script from
PyCharm and paste it into the ToolValidator script.
b Click OK.
c Exit PyCharm.
Step 4: Verify the updated tool messaging
Now that you have updated the validator code, you will ensure that it is working correctly by
testing three different input files.
a In the Catalog pane, open the Power Outage tool.
b For Phone Reports, browse to C:\EsriTraining\PYTS\Data, select PhoneReports.csv, and
Adding validation to script tools
9-11
then click OK.
c Next to Phone Reports, point to the yellow warning icon to show the warning message.
1. Why is there a warning message for the Phone Reports parameter?
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
d For Phone Reports, browse to ..\EsriTraining\PYTS\Data, select OutageXY2.csv, and then
click OK.
e Next to Phone Reports, point to the red error icon to show the error message.
There are 0 rows in this file, so a custom error message is returned for that parameter.
f For Phone Reports, browse to ..\EsriTraining\PYTS\Data, select OutageXY.csv, and then
click OK.
There are 33 rows in this file, so there are no messages returned for that parameter.
g From the View tab, click Reset Panes and choose Reset Panes For Mapping (Default).
h Save the project, if necessary, and leave ArcGIS Pro open for the next exercise.
You have successfully added custom dialog messaging to a script tool.
Lesson 9
9-12
1. Which ToolValidator method is called each time that the user changes a parameter in
the tool dialog box?
a. __init__
b. initializeParameters
c. updateParameters
d. updateMessages
2. What can be used to create custom behavior within the tool dialog box?
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
3. Validation is executed by geoprocessing when the tool is run.
a. True
b. False
Lesson review
Adding validation to script tools
9-13
Validate script tool inputs using ToolValidator methods (page 9-6)
1. Which ToolValidator method is called when the tool dialog box is first opened?
initializeParameters
2. When is the updateParameters method called?
It is called each time the user changes a parameter in the tool dialog box.
3. If you wanted to set a customized error message based upon a parameter value, which
ToolValidator method would you use to set the message?
updateMessages
4. If you wanted to disable a parameter, which ToolValidator method would you use?
updateParameters
Exercise 9: Add custom messaging to a script tool (page 9-8)
1. Why is there a warning message for the Phone Reports parameter?
There are 47 rows in the file, which is greater than 40 as defined in the validator script.
Therefore, a custom warning message is returned for that parameter.
Answers to Lesson 9 questions
9-14
Now that you have finished creating your Python script tool, you can share it with the rest
of your organization or with the greater GIS community. You will see how your script tool,
through the sharing capabilities within ArcGIS, can be consumed by other users in ArcGIS
Pro, in a web app, or even in ArcGIS Online.
In this lesson, you will learn how to share your Python script tool within ArcGIS and see a
few of the different ways it can be used by others.
Topics covered
Sharing options within ArcGIS software
Creating a geoprocessing package to share your Python script tool
Online techniques for sharing your Python script tool
Using a shared Python script tool in other applications
10 Using Python script tools in ArcGIS
10-1
Depending on the audience that you want to share with and the deployment of ArcGIS, you
can share your Python script tool in a few ways. The capabilities to share your Python script
tool depend on whether your installation includes ArcGIS Enterprise. Each method has a
different preferred audience, and you may not need to use all the methods to share your
Python script tool.
Figure 10.1. Python script tool sharing methods.
Toolbox
Because the Python script tool is contained in a toolbox, you can share that toolbox on a
network drive with others in your organization. This functionality allows you to share your
geoprocessing locally without having to publish your tool.
Geoprocessing package
A geoprocessing package is a convenient way to share your Python script tool by packaging
the tools with the data used by the tool in a single compressed file. Geoprocessing packages
Lesson 10
Methods to share a Python script tool
10-2
are usually created from successfully run geoprocessing tools. These packages allow you to
share your Python script tool with others over ArcGIS Online or email.People accessing the
package can unpack the package locally and use the Python script tool.
Web tool
Web tools contain one or more geoprocessing tools that use input data entered in a client
application, process it, and return the output locally. While web tools require ArcGIS
Enterprise, the web tool can be shared to your portal and then used in many ArcGIS apps. It
can also be used by several users at once. The web tool represents a geoprocessing service
that is running on an ArcGIS server. After a connection to the portal's federated server is made,
you can use the web tool directly. ArcGIS Pro users can also see the web tool in the Catalog
pane.
Methods to share a Python script tool (continued)
Using Python script tools in ArcGIS
10-3
As you have learned, Python script tools can be crafted for any desired workflow. With each
workflow, there are specific outputs that are used by certain users. However, these users may
be accessing the Python script tool in different ways. For some users, accessing the tool from a
local drive may be the most effective method. For other users, a web tool may be preferred.
Consider the following methods of sharing your Python script tool, and indicate which method
is more appropriate for each audience:
• Toolbox
• Geoprocessing package
• Web tool
Sharing with Method
Other users in the Federal User group
Colleague across the hall
A client
Colleague across the country
Lesson 10
Determining the appropriate method
10-4
When sharing a Python script tool, you must consider the ArcGIS licensing, Python site
packages, and geoprocessing environment settings used by the script to ensure that the end
user can perform the analysis. The following table describes each consideration in more detail.
Consideration Description
ArcGIS
licensing
An ArcGIS license is required to run all ArcPy tools. Additional
licensing is needed to run tools from ArcGIS extensions, such as the
ArcGIS Spatial Analyst extension. If the end user does not have the
required license, then the tool will fail and return error messages.
The CheckExtension and CheckProduct functions can be added to
Python scripts to evaluate whether the required licensing for an
analysis is available.
Python site
packages
Python scripts often import one or more site packages, such as
ArcPy, to access the necessary modules for an analysis. When a script
is shared as a tool, it is important to ensure that the end user has
installed the site packages that are used by the script.
Environment
settings
ArcPy tools often rely on geoprocessing environment settings to
populate default values. For example, the default location for
geoprocessing tool inputs and outputs is defined by the workspace
environment setting. When sharing a Python script tool, it is
important to ensure that end users can define the locations of all
inputs and outputs or access the data locations that are specified in
the script.
ArcGIS Pro Help: Accessing licenses and extensions in Python
Sharing considerations
Using Python script tools in ArcGIS
10-5
https://pro.arcgis.com/en/pro-app/latest/arcpy/geoprocessing_and_python/accessing-licenses-and-extensions-in-python.htm
Several packages come preinstalled with ArcGIS Pro, but that should not limit the packages
that you can use in your Python script. Many other Python packages that provide additional
functionality are available. You can add any other package for your analysis through the Python
Package Manager.
Figure 10.2. Other Python modules can be added to ArcGIS Pro.
Lesson 10
Adding Python packages to ArcGIS Pro
10-6
After your Python script tool is generating the proper output, you are ready to share it with
your desired audience. The workflow for sharing a Python script tool follows the steps
necessary to create the package or web tool and publish it.
Figure 10.3. Five-step workflow for sharing a Python script tool.
Run Python script tool
Before you can create the geoprocessing package, you must successfully complete the tool.
The completed progress will be stored in the geoprocessing history and allow you to see the
tool appear in the Share tab.
Select history item
The Python script tool will not appear as an option on the Share tab until you have a successful
completion. Within the Share tab, the Python script tool should appear in the drop-down lists
for the Geoprocessing button and the Web Tool button . The Python script tool will not
appear in the lists until you have successfully run the tool.
The Python script tool can also be shared by right-clicking the successful run in the
Catalog pane under History.
Update metadata
Some of the metadata that you should update is contained in the Python script tool interface,
and involves updating information about the parameters. For the Python script tool, you must
include metadata for the Summary and Tags fields.
Workflow to share a Python script tool
Using Python script tools in ArcGIS
10-7
Analyze
The tool interface allows you to analyze your Python script tool before publishing it to check
for errors. The analysis results may reveal potential problems with the package before you
publish.
Publish or share
The final step is to publish or share the Python script tool. Be sure to check the finished
package or web tool to ensure that it will work for your desired audience.
Lesson 10
Workflow to share a Python script tool (continued)
10-8
Geoprocessing packages allow you to share your analysis through a portable compressed data
structure without needing to publish to ArcGIS Enterprise. Depending on your desired
audience, this workflow allows you to share the analysis by sending the package through
email, storing it on a network drive, or storing it on ArcGIS Online. In this exercise, you will use
the Python script tool that you created and create a geoprocessing package to share with
colleagues in your office.
In this exercise, you will perform the following tasks:
• Update the metadata about your Python script tool.
• Share your Python script tool as a geoprocessing package.
Exercise 10
Share a geoprocessing package
10 minutes
10-9
Step 1: Create a new map
a If necessary, open the PowerOutage project in ArcGIS Pro.
The instructions in this box are only necessary if you did not create the Power
Outage tool. If you are unsure, ask your instructor for assistance.
1. Start ArcGIS Pro and, if necessary, sign in to your organizational account.
2. To the right of Recent Projects, click Open Another Project.
3. Browse to ..\EsriTraining\PYTS\Results\Exercise08\PowerOutage, select
PowerOutage.aprx, and then click OK.
b On the Insert tab, click New Map .
c In the Catalog pane, expand Map, and choose Rename.
d Type SharePackage and press Enter.
e On the Catalog pane, expand Toolboxes, and then expand Default.atbx.
f Double-click Power Outage.
g In the Geoprocessing pane, specify the following parameters:
• Phone Reports: ..\EsriTraining\PYTS\Data\OutageXY.csv
• Social Media Reports: ..\EsriTraining\PYTS\Data\SocialMediaReports.xlsx\
SocialMediaXY$
• App Reports Points: ..\EsriTraining\PYTS\Data\AppReports.shp
h Click Run to run the Power Outage script tool.
Step 2: Analyze the geoprocessing package
In this step, you will open the Share As A Geoprocessing Package tool and analyze the Python
script tool to confirm which changes need to be made before you share it.
a On the Analysis tab, in the Geoprocessing group, click History.
b On the History pane, verify the first Power Outage geoprocessing result is listed with a
green check mark.
c Click the Share tab.
Lesson 10
10-10
d In the Package group, click the Geoprocessing down arrow and choose the first Power
Outage result in the list.
e In the Share As A Geoprocessing Package tool, specify the following parameters:
• Start Packaging: Save Package To File
• Name: C:\EsriTraining\PYTS\PowerOutageTool.gpkx
• Summary: Python script tool for Cumberland County Power Coop. Used to show
outage area, show density of outage,and alert service areas.
• Tags: Esri Training, PYTS
f Click Analyze.
The metadata can be updated at any time during the creation of the Python script
tool. To reinforce the need for the metadata, you will perform the Analyze step to
locate all the places where you need to update the metadata. In subsequent tool
creation workflows, you will be able to recognize the areas that need to have
metadata before analyzing the Python script tool.
If you are using the Exercise09 result, you may not receive errors when you analyze
the script. In this case, you can proceed to the third step.
1. Which error message code is returned in the pane?
__________________________________________________________________________________
__________________________________________________________________________________
2. How many times is the error occurring in the Python script tool?
__________________________________________________________________________________
__________________________________________________________________________________
3. What does the error message indicate?
__________________________________________________________________________________
__________________________________________________________________________________
Now that you have analyzed the tool, you are ready to modify the metadata and fix the errors.
Using Python script tools in ArcGIS
10-11
Step 3: Modify the metadata
a In the Catalog pane, expand Toolboxes, and then expand Default.atbx.
b Right-click the Power Outage script and choose Edit Metadata.
c Notice the error message reported at the top.
These messages can include the tool summary, script title, bounding coordinates, tags, topics,
or theme keywords.
You can copy and paste the text for the metadata fields from the metadata_Tool.txt
file located here: C:\EsriTraining\PYTS\Data.
d Enter the following metadata:
• Tags: Esri Training, PYTS, Power Outage
• Summary (Abstract): A Python script tool for Cumberland County Power Coop to
assess power outages.
• Syntax:
Be sure to update the Dialog Explanation fields, not the Scripting Explanation
fields.
• Phone_Reports: Enter phone reports of power outages. Usually in .csv format.
• Social_Media_Reports: Enter reports from social media sources. Usually in .xls
format. Be sure to select the table within the Excel file.
• App_Report_Points: Enter reports from the power company app. Usually in point
feature format.
e On the Metadata tab, in the Manage Metadata group, click Save.
Now that you have updated the metadata, you are ready to publish your geoprocessing
package.
Step 4: Share the geoprocessing package
In this step, you will complete the process of sharing your Python script tool.
a In the Share As A Geoprocessing Package tool, click Analyze.
The error messages are now gone.
b Click Package.
A geoprocessing message will confirm that the geoprocessing package was successfully
created.
Lesson 10
10-12
c In File Explorer, browse to ..\EsriTraining\PYTS and look for the geoprocessing package.
You have successfully created a geoprocessing package to share your Python script tool.
d Close any open maps.
e From the View tab, click Reset Panes and choose Reset Panes For Mapping (Default).
f Save the project, and then exit ArcGIS Pro.
Using Python script tools in ArcGIS
10-13
By sharing your Python script tool as a web tool, you increase the number of ways that it can
be consumed within ArcGIS. Your automated workflow can now be shared in apps built within
your organization, in web maps designed to share information, and with other users in ArcGIS
Pro.
1. Which configuration option enables users to add their own data from a local file when
running the web tool?
__________________________________________________________________________________
__________________________________________________________________________________
2. Which configuration option enables users to create a hosted feature layer as the
analysis result?
__________________________________________________________________________________
__________________________________________________________________________________
Lesson 10
Sharing a web tool within ArcGIS
10-14
Before a Python script can be shared as a web tool, the result of a successful run must be
present in the geoprocessing history and ArcGIS Pro must be signed in to ArcGIS Enterprise.
After these prerequisite requirements are met, the script tool can be shared as a web tool to
ArcGIS Enterprise. There are several properties that can be configured when publishing a web
tool.
Property Description
Data The data that is built in to the tool can be copied to the server (copy all
data) or reference the source data location (reference registered data).
Upload
capability
Enabling the upload capability allows users to add their own data from a
local file when running the web tool.
Execution
mode
The web tool can be executed synchronously or asynchronously.
Generally, the asynchronous option is used for long-running tools.
Message
level
The selected message level defines the types of notifications that are
returned in the logs.
Input
mode
The input mode can be configured to allow each parameter to be
defined by the user, selected from a choice list, or set to a constant
value.
Sharing a web tool within ArcGIS video summary
Using Python script tools in ArcGIS
10-15
Throughout this course, you have been shown how to use Python to automate your workflow.
By learning about how Python has been integrated into ArcGIS Pro, you have seen how to
access properties of your data, build new datasets, and modify existing datasets. With Python
scripting, you have been able to automate a workflow and create a new Python script tool to
repeat the automated workflow. At this point, you will see how you can now take that tool and
share it within ArcGIS to use in your organization.
Figure 10.4. Python script tool workflow.
Now that you have seen the complete workflow, how would you use this workflow in your
work?
Lesson 10
Workflow review
10-16
Determining the appropriate method (page 10-4)
Sharing with Method
Other users in the Federal User group • Geoprocessing package
Colleague across the hall • Toolbox
A client • Geoprocessing package
• Web tool
Colleague across the country • Web tool
Exercise 10: Share a geoprocessing package (page 10-9)
1. Which error message code is returned in the pane?
00104
2. How many times is the error occurring in the Python script tool?
Three times
3. What does the error message indicate?
The parameter is missing a syntax dialog explanation in the item description.
Sharing a web tool within ArcGIS (page 10-14)
1. Which configuration option enables users to add their own data from a local file when
running the web tool?
The upload capability is enabled when sharing the web tool.
2. Which configuration option enables users to create a hosted feature layer as the analysis
Answers to Lesson 10 questions
10-17
result?
The optional feature service parameter option is selected for the web tool output.
Answers to Lesson 10 questions (continued)
10-18
ENVIRONMENTAL SYSTEMS RESEARCH INSTITUTE, INC. ("ESRI"), IS WILLING TO LICENSE
THE ENCLOSED ELECTRONIC VERSION OF THE TRAINING MATERIALS TO THE STUDENT
("YOU") ONLY UPON THE CONDITION THAT YOU ACCEPT ALL TERMS AND CONDITIONS
CONTAINED IN THIS ESRI DATA LICENSE AGREEMENT ("AGREEMENT"). PLEASE READ THE
TERMS AND CONDITIONS CAREFULLY. BY CLICKING, "I ACCEPT", YOU ARE INDICATING
YOUR ACCEPTANCE OF THE ESRI DATA LICENSE AGREEMENT. IF YOU DO NOT AGREE TO
THE TERMS AND CONDITIONS AS STATED, ESRI IS UNWILLING TO LICENSE THE
TRAINING MATERIALS TO YOU.
Training Materials Reservation of Ownership. This Agreement gives You certain limited rights
to use electronic and tangible versions of the digital or printed content required to complete a
course, which may include, but are not limited to, workbooks, data, concepts, exercises, and
exams ("Training Materials").Esri and its licensor(s) retain exclusive rights, title, and ownership
to the copy of Training Materials, software, data, and documentation licensed under this
Agreement. Training Materials are protected by United States copyright laws and applicable
international copyright treaties and/or conventions. All rights not specifically granted in this
Agreement are reserved to Esri and its licensor(s).
Grant of License. Esri grants to You a personal, nonexclusive, nontransferable license to use
Training Materials for Your own training purposes. You may run and install one (1) copy of
Training Materials and reproduce one (1) copy of Training Materials. You may make one (1)
additional copy of the original Training Materials for archive purposes only, unless Esri grants in
writing the right to make additional copies.
Training Materials are intended solely for the use of the training of the individual who
registered and attended a specific training course. You may not (i) separate the component
parts of the Training Materials for use on multiple systems or in the cloud, use in conjunction
with any other software package, and/or merge and compile into a separate database(s) or
documents for other analytical uses; (ii) make any attempt to circumvent the technological
measure(s) (e.g., software or hardware key) that effectively controls access to Training Materials;
(iii) remove or obscure any copyright, trademark, and/or proprietary rights notices of Esri or its
licensor(s); or (iv) use audio and/or video recording equipment during a training course.
Term. The license granted by this Agreement will commence upon Your receipt of the Training
Materials and continue until such time that (1) You elect to discontinue use of the Training
Materials or (2) Esri terminates this Agreement for Your material breach of this Agreement. This
Agreement will be terminated automatically without notice if You fail to comply with any
provision of this Agreement. Upon termination of this Agreement in either instance, You will
return to Esri or destroy all copies of the Training Materials, including any whole or partial
copies in any form, and deliver evidence of such destruction to Esri, and which evidence will
be in a form acceptable to Esri in its sole discretion. The parties hereby agree that all
provisions that operate to protect the rights of Esri and its licensor(s) will remain in force should
Appendix A
Esri data license agreement
A-1
breach occur.
Limited Warranty. Esri warrants that the media on which Training Materials is provided will be
free from defects in materials and workmanship under normal use and service for a period of
ninety (90) days from the date of receipt.
Disclaimer of Warranties. EXCEPT FOR THE LIMITED WARRANTY SET FORTH ABOVE, THE
TRAINING AND TRAINING MATERIALS CONTAINED THEREIN ARE PROVIDED "AS IS,"
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE, AND NONINFRINGEMENT. ESRI DOES NOT WARRANT THAT THE
TRAINING OR TRAINING MATERIALS WILL MEET YOUR NEEDS OR EXPECTATIONS; THAT
THE USE OF TRAINING MATERIALS WILL BE UNINTERRUPTED; OR THAT ALL
NONCONFORMITIES, DEFECTS, OR ERRORS CAN OR WILL BE CORRECTED. THE
TRAINING DATABASE HAS BEEN OBTAINED FROM SOURCES BELIEVED TO BE RELIABLE,
BUT ITS ACCURACY AND COMPLETENESS, AND THE OPINIONS BASED THEREON, ARE
NOT GUARANTEED. THE TRAINING DATABASE MAY CONTAIN SOME
NONCONFORMITIES, DEFECTS, ERRORS, AND/OR OMISSIONS. ESRI AND ITS LICENSOR(S)
DO NOT WARRANT THAT THE TRAINING DATABASE WILL MEET YOUR NEEDS OR
EXPECTATIONS, THAT THE USE OF THE TRAINING DATABASE WILL BE UNINTERRUPTED,
OR THAT ALL NONCONFORMITIES CAN OR WILL BE CORRECTED. ESRI AND ITS
LICENSOR(S) ARE NOT INVITING RELIANCE ON THIS TRAINING DATABASE, AND YOU
SHOULD ALWAYS VERIFY ACTUAL DATA, SUCH AS MAP, SPATIAL, RASTER, OR TABULAR
INFORMATION. THE DATA CONTAINED IN THIS PACKAGE IS SUBJECT TO CHANGE
WITHOUT NOTICE. IN ADDITION TO AND WITHOUT LIMITING THE PRECEDING
PARAGRAPH, ESRI DOES NOT WARRANT IN ANY WAY TRAINING DATA. TRAINING DATA
MAY NOT BE FREE OF NONCONFORMITIES, DEFECTS, ERRORS, OR OMISSIONS; BE
AVAILABLE WITHOUT INTERRUPTION; BE CORRECTED IF ERRORS ARE DISCOVERED; OR
MEET YOUR NEEDS OR EXPECTATIONS. YOU SHOULD NOT RELY ON ANY TRAINING DATA
UNLESS YOU HAVE VERIFIED TRAINING DATA AGAINST ACTUAL DATA FROM
DOCUMENTS OF RECORD, FIELD MEASUREMENT, OR OBSERVATION.
Exclusive Remedy. Your exclusive remedy and Esri's entire liability for breach of the limited
warranties set forth above will be limited, at Esri's sole discretion, to (i) replacement of any
defective Training Materials; (ii) repair, correction, or a workaround for Training Materials; or (iii)
return of the fees paid by You for Training Material that do not meet Esri's limited warranty,
provided that You uninstall, remove, and destroy all copies of the Training Materials and
execute and deliver evidence of such actions to Esri.
IN NO EVENT WILL ESRI BE LIABLE TO YOU FOR COSTS OF PROCUREMENT OF
SUBSTITUTE GOODS OR TRAINING; LOST PROFITS; LOST SALES; BUSINESS
EXPENDITURES; INVESTMENTS; BUSINESS COMMITMENTS; LOSS OF ANY GOODWILL; OR
ANY INDIRECT, SPECIAL, EXEMPLARY, CONSEQUENTIAL, OR INCIDENTAL DAMAGES
ARISING OUT OF OR RELATED TO THIS AGREEMENT, HOWEVER CAUSED OR UNDER ANY
Appendix A
Esri data license agreement (continued)
A-2
THEORY OF LIABILITY, EVEN IF ESRI HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES. ESRI'S TOTAL CUMULATIVE LIABILITY HEREUNDER, FROM ALL CAUSES OF
ACTION OF ANY KIND, WILL IN NO EVENT EXCEED THE AMOUNT ACTUALLY PAID BY YOU
FOR THE PORTION OF THE TRAINING UNDER THIS AGREEMENT. THESE LIMITATIONS
WILL APPLY NOTWITHSTANDING ANY FAILURE OF ESSENTIAL PURPOSE OF ANY LIMITED
REMEDY.
Export Regulation. You must comply with all applicable laws and regulations of the United
States including, without limitation, its export control laws. You expressly acknowledge and
agree not to export, reexport, transfer, or release Esri-provided Training Materials, in whole or
in part, to (i) any US embargoed country (including to a resident of any US embargoed
country); (ii) any person or entity on the US Treasury Department Specially Designated
Nationals List; (iii) any person or entity on the US Commerce Department Lists of Parties of
Concern; or (iv) any person or entity where such export, reexport, or provision violates any US
export control laws or regulations including, but not limited to, the terms of any export license
or licensing provision and any amendments and supplemental additions to US export laws.
Governing Law. This Agreement is governed by and construed in accordance with the laws of
the state in which training is being held or, in the case of training provided over the Internet,
the laws of the State of California, without reference to its conflict of laws principles.
Appendix A
Esri data license agreement (continued)
A-3
Answers to lesson 1 review questions
1. Which method of accessing Python is preferred when you are exploring the syntax of
geoprocessing tools?
b. Python window in ArcGIS Pro
2. What is the first step in the Python script creation workflow?
c. Plan code
3. The Python window in ArcGIS Pro is capable of running code created outside of ArcGIS Pro.
a. True
Answers to lesson 2 review questions
1. The syntax of a geoprocessing tool includes parameters that are both ____________ and
___________.
b. required, optional
2. Informative comments can only be added to a script before the script has been executed.
b. False
(Informative comments can be added to the script at any time.)
3. What should you remember about variables when you create them?
c. They are dynamic and capable of holding different data types.
Answers to lesson 3 review questions
1. How do describe functions assist in geoprocessing scripts?
Describe functions return the properties of a dataset. For example, retrieving the
spatial reference information of a feature class can be used to ensure geoprocessingCreate a new notebook................................................................................................7-10
Add Markdown to the notebook .................................................................................7-10
Import Python site packages........................................................................................7-12
Add Python code to query the data ............................................................................7-13
Add Python code to create a chart ..............................................................................7-14
iii
8 Creating a Python script tool
9 Adding validation to script tools
10 Using Python script tools in ArcGIS
Add Python code to perform analysis..........................................................................7-15
Lesson review.....................................................................................................................7-18
Answers to Lesson 7 questions..........................................................................................7-19
Lesson introduction .............................................................................................................8-1
Improving script accessibility ...............................................................................................8-2
Components of a Python script tool....................................................................................8-3
Accepting user input ...........................................................................................................8-5
Parameter identification.......................................................................................................8-7
Exercise 8: Create a Python script tool ................................................................................8-9
Prepare the Python script for user input ......................................................................8-10
Create a new map........................................................................................................8-11
Create a script tool in ArcGIS Pro ................................................................................8-12
Run the Python script tool............................................................................................8-13
Lesson review.....................................................................................................................8-16
Answers to Lesson 8 questions..........................................................................................8-17
Lesson introduction .............................................................................................................9-1
Customizing script tool behavior .........................................................................................9-2
Using validation to create customizations ...........................................................................9-3
Validate script tool inputs using ToolValidator methods .....................................................9-6
Exercise 9: Add custom messaging to a script tool.............................................................9-8
Open the script tool validation properties.....................................................................9-9
Add code to the validator script ....................................................................................9-9
Verify the validator code ..............................................................................................9-11
Verify the updated tool messaging ..............................................................................9-11
Lesson review.....................................................................................................................9-13
Answers to Lesson 9 questions..........................................................................................9-14
Lesson introduction ...........................................................................................................10-1
Methods to share a Python script tool...............................................................................10-2
Determining the appropriate method ...............................................................................10-4
Sharing considerations.......................................................................................................10-5
Adding Python packages to ArcGIS Pro ............................................................................10-6
Workflow to share a Python script tool ..............................................................................10-7
Exercise 10: Share a geoprocessing package....................................................................10-9
Create a new map......................................................................................................10-10
Analyze the geoprocessing package .........................................................................10-10
Modify the metadata..................................................................................................10-12
Share the geoprocessing package.............................................................................10-12
Sharing a web tool within ArcGIS ....................................................................................10-14
Workflow review ..............................................................................................................10-16
iv
Answers to Lesson 10 questions......................................................................................10-17
Appendices
Appendix A: Esri data license agreement .......................................................................... A-1
Appendix B: Answers to lesson review questions .............................................................. B-1
Appendix C: Additional resources...................................................................................... C-1
v
vi
Take advantage of these resources to develop ArcGIS software skills, discover applications of
geospatial technology, and tap into the experience and knowledge of the ArcGIS community.
Instructor-led and e-Learning resources
Esri instructor-led courses and e-Learning resources help you develop and apply ArcGIS skills,
recommended workflows, and best practices. View all training options at esri.com/training/
catalog/search.
Planning for organizations
Esri training consultants partner with organizations to provide course recommendations for job
roles, short-term training plans, and workforce development plans. Contact an Esri training
consultant at training@esri.com.
Esri technical certification
The Esri Technical Certification Program recognizes individuals who are proficient in best
practices for using Esri software. Exams cover desktop, developer, and enterprise domains.
Learn more at esri.com/training/certification.
Social media and publications
Twitter: @EsriTraining and @Esri
Esri on LinkedIn: linkedin.com/company/esri
Esri training blog: esri.com/trainingblog
Esri publications: Access online editions of ArcNews, ArcUser, and ArcWatch at esri.com/esri-
news/publications
Esri training newsletter: Subscribe at go.esri.com/training-news
Other Esri newsletters: Subscribe to industry-specific newsletters at go.esri.com/subscribe
Esri Press
Esri Press publishes books on the science and technology of GIS in numerous public and
private sectors. esripress.esri.com
GIS bibliography
A comprehensive index of journals, conference proceedings, books, and reports related to
GIS, including references and full-text materials. gis.library.esri.com
Esri resources
vii
https://www.esri.com/training/catalog/search/
https://www.esri.com/training/catalog/search/
mailto:training@esri.com
https://www.esri.com/training/certification
https://www.linkedin.com/company/esri
https://www.esri.com/trainingblog
https://www.esri.com/esri-news/publications
https://www.esri.com/esri-news/publicationsoutputs are in the same spatial reference.
2. Describe properties can be used to set the environment variables of a geoprocessing tool.
a. True
Appendix B
Answers to lesson review questions
B-1
3. Which Describe object property would return the value of 'Polyline'?
b. shapeType
Answers to lesson 4 review questions
1. List __________ are used to create Python lists from GIS data.
c. functions
2. Which type of loop will perform a task based on items within a list?
b. For loop
3. An if-then statement can be nested within a for loop statement.
a. True
4. When using List functions, a __________ parameter can be used to limit the values returned.
wildcard
(Note: some list functions also have a type parameter that can be used to limit the
values returned.)
Answers to lesson 5 review questions
1. Which cursor provides read-write access to field values in a feature class or table?
b. UpdateCursor
2. In addition to reading data within a table, the Search cursor allows you to delete data rows.
b. False
(The Search cursor creates a read-only view of the data; the Update cursor allows you
to delete table rows.)
3. When you work with cursors, how do you free up memory and prevent schema locks?
Delete the cursor.
4. What will the following Python code accomplish?
Appendix B
Answers to lesson review questions (continued)
B-2
fc = 'C:\EsriTraining\Default.gdb\Roads'
fields = ['ROAD_ID', 'ROAD_TYPE']
exp = " ROAD_TYPE = 'HWY' "
for row in arcpy.da.SearchCursor(fc, fields, exp):
print(f"For {row[0]} the type of highway is {row[1]}.")
It will print the road ID and type of road.
Answers to lesson 6 review questions
1. To use a geometry object, it must persist within a geodatabase.
b. False
(Geometry objects are created in memory.)
2. To create a Polyline or Polygon geometry object, which two objects must first be created?
A Point object and an Array object must be created before creating a Polyline or
Polygon geometry object.
3. What is one of the primary benefits of using a geometry object in your script?
b. Geometry objects are temporary and contained in memory.
Answers to lesson 7 review questions
1. The ability to import shared notebooks (.ipynb files) allows which benefit of ArcGIS
Notebooks?
b. Collaborate between GIS and data science teams
2. What open-source application is used to integrate ArcGIS Notebooks into ArcGIS Pro?
Jupyter Notebooks
3. Which ArcGIS Notebooks cell type allows you to add images to your Python code?
a. Markdown
Appendix B
Answers to lesson review questions (continued)
B-3
Answers to lesson 8 review questions
1. Which Python script tool property defines what input datasets and output datasets the script
will display?
b. Parameters
2. Which aspect of a Python script tool makes it more accessible to other users?
Allowing other users to specify their data in the script tool
3. Which Python function will accept the user input as a string?
c. GetParameterAsText()
Answers to lesson 9 review questions
1. Which ToolValidator method is called each time that the user changes a parameter in the
tool dialog box?
c. updateParameters
2. What can be used to create custom behavior within the tool dialog box?
Validation
3. Validation is executed by geoprocessing when the tool is run.
b. False
(Validation is executed when the tool dialog box is opened, or when the parameters
are updated.)
Appendix B
Answers to lesson review questions (continued)
B-4
Lesson 6 Resources
Components of a
geometry object • ArcGIS Pro Help: Geometry -
Lesson 10 Resources
Sharing considerations
• ArcGIS Pro Help: Accessing licenses and extensions in Python -
Appendix C
Additional resources
C-1
https://pro.arcgis.com/en/pro-app/latest/arcpy/geoprocessing_and_python/accessing-licenses-and-extensions-in-python.htm
	Course: Creating Python® Scriptsfor ArcGIS®
	Copyright
	Table of contents
	Esri resources for your organization
	Course introduction
	Icons used in this workbook
	Lesson 1: Python automation for your organization
	Benefits of Python automation
	The Python script creation workflow
	Integrating Python in ArcGIS Pro
	Python development and run environments
	Accessing Python
	Lesson review
	Answers to Lesson 1 questions
	Lesson 2: Using Python to access geoprocessing tools
	Viewing parameters in a geoprocessing tool
	Explore the syntax of a geoprocessing tool
	Ways to use variables in a script
	Using variables in a script
	Exercise 2A: Create a simple script with variables
	Step 1: Create a new ArcGIS Pro project
	Step 2: Add data for the affected area
	Step 3: Evaluate the syntax of the Copy Features tool
	Step 4: Evaluate the syntax of the Buffer tool
	Step 5: Combine the geoprocessing tools in a script
	Step 6: Verify the script in PyCharm
	Python troubleshooting techniques
	Troubleshooting errors in a script
	Exercise 2B: Add troubleshooting techniques to a Python script
	Step 1: Add informative comments
	Step 2: Add print functions
	Step 3: Comment existing code
	Step 4: Create a variable
	Step 5: Use debugging tools in PyCharm
	Lesson review
	Answers to Lesson 2 questions
	Lesson 3: Using Describe properties in geoprocessing tools
	Accessing properties with a Describe function
	Identify available Describe function properties
	Describe syntax and usage
	Accessing Describe properties
	Exercise 3: Use the Describe function in a geoprocessing script
	Step 1: Create a new map
	Step 2: Examine the properties of a feature class
	Step 3: Use the Describe function to examine properties
	Step 4: Create a new Python script in PyCharm
	Step 5: Create a Describe object
	Step 6: Use Describe properties to create a new feature class
	Step 7: Verify the new feature class
	Using the da.Describe object in a geoprocessing script
	Lesson review
	Answers to Lesson 3 questions
	Lesson 4: Automating Python scripts with lists
	List functions in Python
	Examine the ListFiles function
	Finishing the List function syntax
	Exercise 4A: Prepare to automate with Python lists
	Step 1: Create a new map
	Step 2: Create a list of workspaces
	Step 3: Create a list of features
	Step 4: Create a list of fields
	Using a for loop
	Using a for loop to iterate over lists
	Exercise 4B: Automate a geoprocessing workflow using loops
	Step 1: Create a new Python script in PyCharm
	Step 2: Copy feature classes from a workspace
	Step 3: Verify the new feature classes
	Lesson review
	Answers to Lesson 4 questions
	Lesson 5: Working with cursors
	Types of cursors
	Examine cursors
	Determine which cursor to use
	Exploring cursor syntax
	Using cursors in a workflow
	Apply the cursor workflow
	Exercise 5: Read and update values in a feature class
	Step 1: Create a new Python script in PyCharm
	Step 2: Set up the Python script
	Step 3: Create an Update cursor
	Step 4: Create a Search cursor
	Step 5: Write values to a CSV file
	Step 6: Run the script in PyCharm
	Step 7: Create a new map
	Step 8: Verify the script results
	Lesson review
	Answers to Lesson 5 questions
	Lesson 6: Geoprocessing with geometry objects
	Benefits of geometry objects
	Workflows to create geometry objects
	Discovering polyline geometry objects
	Components of a geometry object
	Discover geometry object methods
	Exercise 6: Convert coordinates into affected area polygons
	Step 1: Open a Python script in PyCharm
	Step 2: Evaluate the Python script
	Step 3: Create the geometry object from a list
	Step 4: Run the script in PyCharm
	Step 5: Create a new map
	Step 6: Verify the script output feature classes
	Lesson review
	Answers to Lesson 6 questions
	Lesson 7: Using ArcGIS Notebooks
	Benefits of ArcGIS Notebooks
	Cell types in ArcGIS Notebooks
	Explore a sample notebook
	Impact of data engineering on analysis results
	Evaluate data changes in a notebook in ArcGIS Pro
	Exercise 7: Create a notebook in ArcGIS Pro
	Step 1: Create a new map
	Step 2: Create a new notebook
	Step 3: Add Markdown to the notebook
	Step 4: Import Python site packages
	Step 5: Add Python code to query the data
	Step 6: AddPython code to create a chart
	Step 7: Add Python code to perform analysis
	Lesson review
	Answers to Lesson 7 questions
	Lesson 8: Creating a Python script tool
	Improving script accessibility
	Components of a Python script tool
	Accepting user input
	Parameter identification
	Exercise 8: Create a Python script tool
	Step 1: Prepare the Python script for user input
	Step 2: Create a new map
	Step 3: Create a script tool in ArcGIS Pro
	Step 4: Run the Python script tool
	Lesson review
	Answers to Lesson 8 questions
	Lesson 9: Adding validation to script tools
	Customizing script tool behavior
	Using validation to create customizations
	Validate script tool inputs using ToolValidator methods
	Exercise 9: Add custom messaging to a script tool
	Step 1: Open the script tool validation properties
	Step 2: Add code to the validator script
	Step 3: Verify the validator code
	Step 4: Verify the updated tool messaging
	Lesson review
	Answers to Lesson 9 questions
	Lesson 10: Using Python script tools in ArcGIS
	Methods to share a Python script tool
	Determining the appropriate method
	Sharing considerations
	Adding Python packages to ArcGIS Pro
	Workflow to share a Python script tool
	Exercise 10: Share a geoprocessing package
	Step 1: Create a new map
	Step 2: Analyze the geoprocessing package
	Step 3: Modify the metadata
	Step 4: Share the geoprocessing package
	Sharing a web tool within ArcGIS
	Sharing a web tool within ArcGIS video summary
	Workflow review
	Answers to Lesson 10 questions
	Course appendices
	Appendix A: Esri data license agreement
	Appendix B: Answers to lesson review questions
	Appendix C: Additional resourceshttps://go.esri.com/training-news
https://go.esri.com/subscribe
https://esripress.esri.com/
https://gis.library.esri.com/
ArcGIS documentation and tutorials
In-depth information, tutorials, and documentation for ArcGIS products.
ArcGIS Online: arcgis.com
ArcGIS Desktop: desktop.arcgis.com
ArcGIS Enterprise: enterprise.arcgis.com
Esri Community
Join the online community of GIS users and experts. community.esri.com
Esri events
Esri conferences and user group meetings offer a great way to network and learn how to
achieve results with ArcGIS. esri.com/events
Esri Videos
View an extensive collection of videos by Esri leaders, event keynote speakers, and product
experts. youtube.com/user/esritv
ArcGIS for Personal Use
Improve your GIS skills at home and use ArcGIS to enhance your personal projects. The ArcGIS
for Personal Use program includes a 12-month term license for ArcGIS Desktop, extension
products, and an ArcGIS Online named user account with 100 service credits. esri.com/
personaluse
GIS Dictionary
This term browser defines and describes thousands of GIS terms. support.esri.com/other-
resources/gis-dictionary
Esri resources (continued)
viii
https://arcgis.com/
https://desktop.arcgis.com/
https://enterprise.arcgis.com/
https://community.esri.com/
https://www.esri.com/events
https://www.youtube.com/user/esritv
https://www.esri.com/software/arcgis/arcgis-for-personal-use
https://www.esri.com/software/arcgis/arcgis-for-personal-use
https://support.esri.com/other-resources/gis-dictionary
https://support.esri.com/other-resources/gis-dictionary
This course uses Python's language syntax and modules to access and automate
geoprocessing workflows through Python scripts. These scripts can be run inside of the Python
Integrated Development Environment, within the Python window in ArcGIS Pro, within ArcGIS
Notebooks, as custom tools within ArcToolbox, or they can be shared as geoprocessing
packages.
This course covers the ArcPy site package, which integrates Python scripts into ArcGIS. With
ArcPy, your scripts can access additional ArcGIS functionality to work with your maps and data
beyond the geoprocessing framework.
Course goals
After completing this course, you will be able to perform the following tasks:
• Apply Python syntax rules to create robust scripts in ArcGIS Pro.
• Use automation techniques to repeat geoprocessing tasks in a Python script to create an
efficient, repeatable analysis workflow.
• Use Python to access geospatial data, edit attributes, and create and modify features.
• Create custom Python script tools that can be shared with other ArcGIS users.
Installing the course data
Some exercises in this workbook require data. Depending on the course format, the data is
available on a DVD in the back of a printed workbook or as a data download. To use the data,
extract it to your C:\EsriTraining folder.
DISCLAIMER: Some courses use sample scripts or applications that are supplied
either on the DVD or on the Internet. These samples are provided "AS IS,"
without warranty of any kind, either express or implied, including but not limited
to, the implied warranties of merchantability, fitness for a particular purpose, or
noninfringement. Esri shall not be liable for any damages under any theory of law
related to the licensee's use of these samples, even if Esri is advised of the
possibility of such damage.
Course introduction
1
Estimated times provide guidance on approximately how many minutes an
exercise will take to complete.
Notes indicate additional information, exceptions, or special circumstances
about specific course topics.
Recommended practices improve efficiency and save time.
Esri Academy resources provide more in-depth training on related topics.
Additional resources provide additional information about related topics.
Warnings indicate potential problems or actions that should be avoided.
Icons used in this workbook
2
Python is an integral part of ArcGIS and has become the scripting language of choice for
geoprocessing users. By creating scripts to complete your work, your workflows can be
optimized and streamlined with the use of Python code. Many Python modules are
preinstalled in ArcGIS Pro, and if you can find a particular module, there will be a workflow
to import that site package for your script.
In this lesson, you will learn about how Python is already integrated into ArcGIS Pro, and
how to access Python to improve your workflows.
Topics covered
Benefits of Python automation
Automation of GIS tasks
How to access Python in ArcGIS Pro
1 Python automation for your organization
1-1
As GIS technology has advanced, so has the complexity of analysis. In the future, workflows
will continue to become more complex. In many vital workflows, it has become normal to use
several geoprocessing tools, data manipulation, and custom outputs. Different personnel
within an organization may need to repeat such complex workflows many times. This
complexity can lead to errors, including when steps are missed or when data is not formatted
properly. So, how can you address the issues that arise with this increasing complexity? And
how can you ensure that repetition does not introduce new errors?
Python is a common scripting language that can be used in ArcGIS Pro to automate
geoprocessing tasks. Python scripting can reduce the complexity through creating scripts and
script tools that automate complex workflows. There are several reasons for using Python
scripting to automate your workflow:
• Optimize the processing speed of the geoprocessing tools.
• Reduce the number of steps in the workflow.
• Customize the behavior of geoprocessing tools.
• Share the script with others.
• Handle repetitive processes.
Lesson 1
Benefits of Python automation
1-2
Figure 1.1. Python scripting can make complex workflows simple.
As you begin planning your script, you need to assess which GIS tasks are used in your
workflows. Within each organization, certain workflows are followed in order to accomplish the
organization's goals. Some of the workflows occur with different frequencies, and some are
more complicated than others. GIS workflows can frequently involve several steps with various
geoprocessing tools and often include different types of data. Sometimes, these workflows can
introduce errors and be time-consuming. Through automation with Python, you can optimize
these workflows to accomplish your goals with less effort and more efficiency. An automated
workflow can provide a level of workflow standardization when the script is run at a later time.
Benefits of Python automation (continued)
Python automation for your organization
1-3
1. What types of GIS tasks could benefit from automation in your organization?
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
Lesson 1
Benefits of Python automation (continued)
1-4
Now that you have decided to automate your workflow with Python, which steps must be
considered to create a complete script? The Python script creation workflow details how you
can plan and create a Python script in ArcGIS Pro. The steps require you to understand your
input data, required processing, and desired outputs. After you understand the necessary
components, you can work through the remaining steps to create the Python script.
Figure 1.2. The Python script creation workflow.
Plan code
Before creating your Python code, you should consider which types of data will be used for
input, how that data will be handled, which geoprocessing tools will be used, and what the
outputs should be. The focus of this step is to consider the layout of the script tool to ensure
that you accomplish the goals of the workflow.
Explore code syntax
Each geoprocessing tool has a specific code syntax to operate the tool correctly. For yourscript to work effectively, you must specify the proper parameters for the tools. You can learn
the proper syntax by examining the help documentation for each geoprocessing tool and
viewing the syntax of completed geoprocessing tasks in the Python window.
Write code
After you have explored the syntax and understand which parameters are necessary for your
code, you will write the script to accomplish your workflow. You can choose to create the script
in three scripting environments: the ArcGIS Pro Python window, an ArcGIS Notebook, or an
Integrated Development Environment (IDE).
The Python script creation workflow
Python automation for your organization
1-5
Run script
After you have finished crafting your script, you can run your script. Code can be run as a
stand-alone script in an IDE, as a code snippet in the ArcGIS Pro Python window, or as a script
tool. Each of these options displays script messaging results within each environment;
however, if you run your script in the Python window or as a script tool, your results can be
instantly displayed on a map.
Share script
You can share each completed script with your organization locally by sharing the script itself.
However, with ArcGIS Pro, you have the option to not only share the script with your
organization but also with others outside of your organization who may be interested in your
analysis. This sharing process is completed over the internet through geoprocessing packages
or geoprocessing services.
Lesson 1
The Python script creation workflow (continued)
1-6
Python is seamlessly integrated into ArcGIS Pro through the geoprocessing tools, the Python
window, ArcGIS Notebooks, and IDEs. As you develop Python scripts to automate your
workflow, you will be able to switch between them to create a more robust and effective script.
All of the ways that you can access Python can be used in the Python script tool workflow.
Figure 1.3. You can work with ArcPy through geoprocessing tools, the Python window, ArcGIS Notebooks, and
IDEs.
Integrating Python in ArcGIS Pro
Python automation for your organization
1-7
After you decide to incorporate Python scripts in your workflow, you may ask yourself where to
start. One of the first steps is to decide where you will create and run your script. An
advantage of using Python is that it can be written and run from ArcGIS Pro or your preferred
Python development environment.
Python scripts can be written in a text editor, an Integrated Development Environment (IDE),
the Python window within ArcGIS Pro, or ArcGIS Notebooks. After they have been written, the
scripts can be run in an IDE, in the Python window, in ArcGIS Notebooks, or as a Python script
tool from the Catalog pane.
Each run environment has its own advantages and disadvantages to consider after the script is
created. These factors include the complexity of the script, whether you will use the script from
a graphical user interface, and whether you need to see immediate results in the map.
Python window
The Python window provides an environment to explore the syntax of geoprocessing tools.
You can drag tools from the Toolbox or the geoprocessing history into the Python window to
view the syntax of tools. You can also recall, edit, and rerun previous lines of code. The Python
window works directly with layers and content within the map. Existing Python scripts can be
loaded and run within the Python window.
ArcGIS Notebooks
ArcGIS Notebooks are integrated into ArcGIS Pro using the open-source web application
Jupyter Notebook. It provides a way to automate and document your workflows using cells.
This allows you to perform analysis and see your results in the map view without leaving
ArcGIS Pro. The advanced documentation helps you better describe each cell so that others
can easily follow your process. In addition to being able to access the Python libraries found in
ArcGIS Pro, you can use the ArcGIS API for Python. When you have written your code in
ArcGIS Notebooks, it can be saved for later use or shared with others.
IDE
An IDE gives you a place to not only write code but also run it. Many IDEs have code analysis
and debugging functionality. This allows you to receive feedback on your syntax and
troubleshoot errors that you may encounter. An IDE can be used to write, run, and debug
code, and messaging can be written directly to the console. A script can be run multiple times
within an IDE using the same parameters or a variation of parameters.
Lesson 1
Python development and run environments
1-8
Script tool
A script tool allows you to turn a Python script into your own geoprocessing tool. It provides a
graphical user interface to set parameters for the script like other geoprocessing tools. You can
add custom behavior to script tools, such as enabling and disabling parameters, providing
default values, validating input, and providing messaging based upon inputs. In addition to
these customizable features, you can provide help to the user by using documentation written
directly within the tool.
Run
environment
Times you plan to
run code
Graphic user
interface
See immediate
results in map
Python
window
Once No Yes
ArcGIS
Notebooks
Multiple No Yes
IDE Multiple No No
Script tool Multiple Yes Yes
Python development and run environments (continued)
Python automation for your organization
1-9
You can use several different methods to access Python. Consider how each method can be
used for a given scenario. For each scenario, match one of the methods for accessing Python:
• ArcGIS Pro Python window
• ArcGIS Notebook
• Script in Toolbox
• IDE
Scenario Way to
access
Python
You want to create a Python process that will be run regularly by an
intern who is not familiar with Python.
You want to explore the syntax of the Buffer tool so that you can use it
in a larger project.
You want to run a complex workflow one time with several
geoprocessing tools.
You want to write a script that has documentation that is easy to
understand.
Lesson 1
Accessing Python
1-10
1. Which method of accessing Python is preferred when you are exploring the syntax of
geoprocessing tools?
a. Text editor
b. Python window in ArcGIS Pro
c. IDE
d. Python script tool in the Catalog pane
2. What is the first step in the Python script creation workflow?
a. Explore code syntax
b. Share script
c. Plan code
d. Run script
3. The Python window in ArcGIS Pro is capable of running code created outside of ArcGIS
Pro.
a. True
b. False
Lesson review
Python automation for your organization
1-11
Benefits of Python automation (page 1-2)
1. What types of GIS tasks could benefit from automation in your organization?
Answers will vary based on personal experience.
Accessing Python (page 1-10)
Scenario Way to access Python
You want to create a Python process that will be run
regularly by an intern who is not familiar with Python.
Script tool in Toolbox
You want to explore the syntax of the Buffer tool so that
you can use it in a larger project.
• ArcGIS Notebook
• ArcGIS Pro Python
window
You want to run a complex workflow one time with
several geoprocessing tools.
IDE
Answers to Lesson 1 questions
1-12
Scenario Way to access Python
You want to write a script that has documentation that is
easy to understand.
• Script tool in Toolbox
• ArcGIS Notebook
Answers to Lesson 1 questions (continued)
1-13
Python scripting in ArcGIS Pro enables you to link geoprocessing tools and create custom
scripts to handle your workflows. The core of Python scripting is creating the proper syntax
for the geoprocessing tools and Python processes that you want to use. Different resources
are available to assist you with creating scripts within ArcGIS Pro, including online help
resources. While these resources can provide you with information about the script, one of
the best ways to improve your coding skills is by creating Python code. In this lesson, you
will create Python code in ArcGIS Pro, learn how to exploresyntax, and use the output of
one tool in another tool.
Topics covered
Discovering the syntax of a geoprocessing tool
Constructing a code snippet to run a geoprocessing tool
Incorporating variables in a code snippet
2 Using Python to access geoprocessing tools
2-1
Every geoprocessing tool available in ArcGIS Pro has a specific set of parameters that are
necessary to run the tool in a Python script. This group of parameters is called the syntax of the
geoprocessing tool—the set of rules that defines how a Python program will be written and
interpreted.
Parameters have certain important properties:
• A unique name
• Either an input or output value
• Either required or optional
Not every Python tool has the same number of input parameters, and the order of the
parameters may vary from tool to tool. It is important to consider the syntax of each tool prior
to using it in your script. Before you begin writing the code, it is a good practice to look at the
help documentation for the geoprocessing tool to consider its syntax.
Within the web help of every geoprocessing tool, the Syntax section indicates the different
parameters that are required (and usually some that are optional). The required parameters are
necessary to run the geoprocessing tool, and the optional parameters provide additional
functionality or output options.
Figure 2.1. Syntax of the Buffer tool.
After you have successfully written the Python code according to the syntax requirements, you
can run the code to create the desired output.
If you have an ArcGIS Pro ModelBuilder model, you can export the model to a
Python script to examine the syntax of the tools within the model.
Lesson 2
Viewing parameters in a geoprocessing tool
2-2
The syntax of each geoprocessing tool varies with different required and optional parameters.
When preparing to use a geoprocessing tool in your Python script, you should consider
exploring the syntax of the geoprocessing tool in the web help.
In this activity, you will use the tool help information to identify the syntax for some commonly
used geoprocessing tools.
Instructions
a Start ArcGIS Pro.
b In the ArcGIS Sign In dialog box, click Your ArcGIS Organization's URL.
c For the organization's URL, type trainingservices and click Continue.
d Select Your Course Account.
e Enter the organizational account username and password provided by your instructor.
f Under New Project, click Catalog.
g Create a new project named ExamineSyntax and click OK.
h From the Analysis tab, click Tools to open the Geoprocessing pane.
i In the Geoprocessing pane, in the search field, type the name of the geoprocessing tool
that you are researching.
j From the search results, click the tool's name to open it.
k When the tool interface appears, click the Help button .
l On the ArcGIS Pro Help web page, click Parameters, and then click the Python tab.
m In the workbook, write the syntax of each tool and indicate the required parameters.
n Save your changes, and then exit ArcGIS Pro.
1. Clip (Analysis)
__________________________________________________________________________________
__________________________________________________________________________________
Explore the syntax of a geoprocessing tool
Using Python to access geoprocessing tools
2-3
2. Copy Features
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
3. Intersect
__________________________________________________________________________________
__________________________________________________________________________________
Lesson 2
Explore the syntax of a geoprocessing tool (continued)
2-4
One of the advantages of creating a Python script is the ability to create complex processes
within a script that use several different geoprocessing tools. Within the script, different inputs
and outputs can be reused through variables. A variable is a name that represents a value. To
create a variable, you assign a value to the name.
Variables are case-sensitive and capable of holding different data types. With these dynamic
datasets, the data type is determined when the variable is referenced.
You can use variables in geoprocessing tools to replace full path names of datasets, consume
the output from another geoprocessing tool within the script, or substitute for a parameter that
can be shared between geoprocessing tools.
Examples of using variables in a script
Substituting for a file path and name of datasets in a script
Variables can be substituted in place of parameters in a script to avoid having to manually type
in the value.
Figure 2.2. Geoprocessing tool without variables and with variables.
Substituting for the output of another geoprocessing tool
Variables can be used within a script to use the output of one geoprocessing tool in the
processing of another geoprocessing tool.
Ways to use variables in a script
Using Python to access geoprocessing tools
2-5
Figure 2.3. Geoprocessing script using output as a variable.
Reusing parameters within the same script
Variables can also be used to reuse parameters in different geoprocessing tools within the
same script.
Figure 2.4. Geoprocessing tool with parameter as a variable.
Lesson 2
Ways to use variables in a script (continued)
2-6
Variables can store different types of data within a Python script. In many cases, variables can
be used for each parameter in the script syntax. In the following scenarios, determine which
parameter should be converted into a variable.
Scenario 1: Identify the affected area
You have been given a point feature class indicating source locations of contamination and a
polygon feature class of property parcels. You need to identify the parts of each parcel
affected by the contamination. You should use the Buffer tool to identify the contaminated
area around the points and then use the output buffer polygon to clip the parcels with the Clip
tool.
• arcpy.analysis.Buffer (in_features, out_feature_class, buffer_distance_or_field)
• arcpy.analysis.Clip (in_features, clip_features, out_feature_class)
See the help documentation for more information about the parameters.
1. Which parameter can be converted into a variable and used in both tools?
__________________________________________________________________________________
__________________________________________________________________________________
Scenario 2: Create new service areas
As a result of recent business growth, you have been tasked with redefining the service areas
for your company. You have received a set of census tract polygons. Each service area consists
of multiple census tracts, and each tract has been labeled according to its new service area
number.
Each service area manager needs a single feature class with a single polygon feature
representing the service area that they oversee. You have determined that you should use the
Dissolve tool to combine the census tracts into their service areas, then use the Split tool to
separate the service areas into different feature classes.
• arcpy.management.Dissolve (in_features, out_feature_class, {dissolve_field},
{statistics_fields}, {multi_part}, {unsplit_lines})
• arcpy.analysis.Split (in_features, split_features, split_field, out_workspace)
See the help documentation for more information about the parameters.
Using variables in a script
Using Python to access geoprocessing tools
2-7
2. Which parameter can be converted into a variable and used in both tools?
__________________________________________________________________________________
__________________________________________________________________________________
__________________________________________________________________________________
Lesson 2
Using variables in a script (continued)
2-8
Imagine that you area GIS specialist for Cumberland County Power, and you have received a
shapefile indicating areas that have lost power. You have been asked to convert the shapefile
into a file geodatabase feature class and then create a buffer map that will show the area of
outages. Although this analysis is for just a single outage at this point, you will begin using
Python to explore the process of automating this task in the future.
In this exercise, you will use the Python window to run two geoprocessing tools into a script
using a variable.
In this exercise, you will perform the following tasks:
• Examine the syntax of a geoprocessing tool.
• Use a variable to combine two geoprocessing tools.
Exercise 2A
Create a simple script with variables
30 minutes
2-9
Step 1: Create a new ArcGIS Pro project
You will create a new ArcGIS Pro project to be used throughout the remaining exercises.
a If necessary, start ArcGIS Pro.
The instructions in this box are only necessary if you did not already sign in to
ArcGIS Pro as part of a previous activity. If you are unsure, ask your instructor for
assistance.
1. In the ArcGIS Sign In dialog box, click Your ArcGIS Organization's URL.
2. For the organization's URL, type trainingservices and click Continue.
3. Select Your Course Account.
4. Enter the organizational account username and password provided by
your instructor, and then click Sign In.
b Under New Project, click Map.
c In the Create A New Project dialog box, set the following parameters:
• Name: PowerOutage
• Location: C:\EsriTraining\PYTS\Projects
d Click OK.
e In the Catalog pane, expand the Maps section, right-click Map, and choose Rename.
f Type ScriptVariables and press Enter.
g In the Catalog pane, expand Folders to view the folder connections in the project.
A connection to the course data folder was added to the project automatically. This folder will
be added to all new projects that you create in this course.
Step 2: Add data for the affected area
Now, you will add power outage data that was collected from a reporting app.
a In the Catalog pane, under Folders, expand the Data folder.
b Right-click the AffectedAreaApp.shp file and choose Add To Current Map .
c Notice the points that are now drawn on the map.
Lesson 2
2-10
The color of the points may be different on your display.
You will use this point feature class as an input to evaluate the syntax of geoprocessing tools.
Using Python to access geoprocessing tools
2-11
Step 3: Evaluate the syntax of the Copy Features tool
Next, you will find the syntax that you will need for your script. You will begin your research by
running the geoprocessing tools and examining the syntax to determine the required
parameters.
a From the Analysis tab, click Tools to open the Geoprocessing pane.
b In the Geoprocessing pane, in the search field, type copy features.
c Open the Copy Features tool and set the following parameters:
• Input Features: AffectedAreaApp
• Output Feature Class: ..\EsriTraining\PYTS\Default.gdb\AffectedAreaAppCopy
Hint:Hint: Default.gdb is under Databases in the Catalog pane, not Folders.
d Click Run.
e From the View tab, click Python Window to open the Python window.
f In the Geoprocessing pane, right-click the successfully completed message for Copy
Features and choose Send To Python Window.
The Python version of the completed geoprocessing tool is added to the prompt of the Python
window.
The following code block is modified to appear in the workbook; your code will
appear as one line in the Python window.
arcpy.management.CopyFeatures("AffectedAreaApp",
r"C:\EsriTraining\PYTS\Default.gdb\AffectedAreaAppCopy",
'', None, None, None)
g Examine the code, and then answer the following questions.
Hint:Hint: See the Copy Features tool help documentation for specific syntax information.
1. Which parameters are required?
__________________________________________________________________________________
__________________________________________________________________________________
Lesson 2
2-12
The difference in the paths is due to the way that the data is being referenced.
Because the AffectedAreaApp layer is in the map, it can be referenced by the layer
name. The output feature class is referenced using the full path because it is not in
the map.
2. What value was placed in the code for the optional parameters?
__________________________________________________________________________________
__________________________________________________________________________________
h Right-click the Python window prompt and choose Clear Window.
Step 4: Evaluate the syntax of the Buffer tool
Next, you will run the Buffer tool and examine the syntax to determine the required
parameters.
a In the Geoprocessing pane, click the Back button , and then in the search field, type
buffer.
b Open the Buffer tool and set the following parameters:
• Input Features: AffectedAreaAppCopy
• Output Feature Class: ..\EsriTraining\PYTS\Default.gdb\AffectedAreaAppCopy_Buffer
• Distance: 0.5 US Survey Miles
• Method: Planar
• Dissolve Type: Dissolve All Output Features Into A Single Feature
c Click Run.
d In the Contents pane, turn off visibility of the AffectedAreaAppCopy and AffectedAreaApp
layers.
e Right-click AffectedAreaAppCopy_Buffer and choose Zoom To Layer.
Using Python to access geoprocessing tools
2-13
f In the Geoprocessing pane, right-click the successfully completed message for Buffer and
choose Send To Python Window.
The Python version of the completed geoprocessing tool is added to the prompt of the Python
window.
The following code block is modified to appear in the workbook; your code will
appear as one line in the Python window.
arcpy.analysis.Buffer("AffectedAreaAppCopy",
r"C:\EsriTraining\PYTS\Default.gdb\AffectedAreaAppCopy_Buffer",
"0.5 Miles", "FULL", "ROUND", "ALL", None, "PLANAR")
g Examine the code, and then answer the following questions.
Hint:Hint: Consider looking at the help documentation for the Buffer tool for specific
information about the syntax.
3. How many required parameters are there for Buffer?
__________________________________________________________________________________
__________________________________________________________________________________
Lesson 2
2-14
h Right-click the Python window prompt and choose Clear Window.
You have now evaluated the syntax of the Copy Features tool and the Buffer tool. The
information from these tools will be used to create a Python script.
Step 5: Combine the geoprocessing tools in a script
In this step, you will use the Python window to create a script that will combine both tools
using variables.
The first lines will be to create the variables for your output.
a In the Python window, type output = r"C:\EsriTraining\PYTS\Default.gdb\
AffectedAreaAppCurrent".
b Press Enter.
c Type area = r"C:\EsriTraining\PYTS\Default.gdb\AffectedArea".
d Press Enter.
e Type distance = "0.5 Miles".
f Press Enter.
These next lines will execute the geoprocessing tools using the output of the first tool in the
second tool.
g In the Python window, type arcpy.management.CopyFeatures("AffectedAreaApp", output).
h Press Enter.
i Notice that the output of the Copy Features tool now appears in the map.
j In the Python window, type arcpy.analysis.Buffer(output, area, distance, "FULL", "ROUND",
"ALL", None, "PLANAR").
k Press Enter.
l Notice that the buffer polygon feature class now appears in the map.
In the Python window, each line of code is run every time that you press Enter. However, if you
were to copy and paste all the code blocks together in the command, the process would also
run.
m In the Python window, right-click and choose Save Transcript.
n Save the Python file in ..\EsriTraining\PYTS\Scripts as SimpleVariables.py.
o Close any open map views.
Using Python to access geoprocessing tools
2-15
p From the View tab, click Reset Panes and choose Reset Panes For Mapping (Default).
q Savethe ArcGIS Pro project and leave ArcGIS Pro open for the next exercise.
Step 6: Verify the script in PyCharm
Now, you will verify that your script has saved correctly by opening it in PyCharm.
a Start PyCharm.
b On the Project pane, under the Scripts folder, double-click SimpleVariables.py.
It may take a minute for the SimpleVariables.py script to display on the Project pane.
Any errors that occurred when typing the code will be carried into the export of
code to PyCharm. Be sure to delete any code that differs from the following
script. If there are errors, the line numbers in the exercise steps will not
correspond.
c Compare your script to the following script:
# coding: utf-8
output = r"C:\EsriTraining\PYTS\Default.gdb\AffectedAreaAppCurrent"
area = r"C:\EsriTraining\PYTS\Default.gdb\AffectedArea"
distance = "0.5 Miles"
arcpy.management.CopyFeatures("AffectedAreaApp", output)
# 
arcpy.analysis.Buffer(output, area, distance, "FULL", "ROUND", "ALL",
None, "PLANAR")
# 
d Notice the results mentioned in the copied script with "#" preceding the line.
The "#" indicates that the line is commented out and will not run. You will learn
more about this in the next exercise.
You will use this script in the next exercise, so you must ensure that the script matches.
e Leave the SimpleVariables.py file open in PyCharm.
In this script, you have successfully replaced the output name for the Copy Features tool with a
variable that you can use for the input value of the Buffer tool. By using the variable in both
Lesson 2
2-16
tools, you have successfully combined both tools into a single script. This is an important skill
to learn when creating more complex Python scripts with many geoprocessing tools.
Using Python to access geoprocessing tools
2-17
Both beginner and experienced coders make mistakes, and code does not always run
correctly. In order to find and fix errors, you should learn some basic troubleshooting
techniques. This process is commonly known as debugging. Four techniques that can be used
to debug code are informative comments, print functions, commenting out, and IDE tools.
Figure 2.5. Python troubleshooting tools.
Informative comments
Informative comments document the script workflow using words instead of code, ensuring
that you have included the necessary steps required for your script. If you encounter a system
error of exception, you can read back through your informative comments to verify that you
have not omitted something important.
Print functions
Print functions provide feedback to the Python Console. You can verify the value of variables
by printing them. You can also define your own values within the printed text. For example,
you can print line numbers or informative comments to see which parts of your script
succeeded before the error happened. With an idea of where the error happened, you can
then work backward to trace the source of the error.
Commenting out
Commenting out a line of code is done by placing a hash character (#) at the start of the line.
Unlike informative comments, the purpose of commenting out is to prevent Python from
executing a troublesome line of code, not provide information about the script. You can
Lesson 2
Python troubleshooting techniques
2-18
comment out blocks of code to isolate problem areas, or comment out specific lines of code
and replace them with modified lines of code to work through the issue.
IDE tools
IDE debugging tools provide additional troubleshooting functionality to work alongside the
code. Functionalities such as setting breakpoints to suspend the code during the debugging
process and watching a variable as it gets assigned allow you to identify potential issues as you
step through the code.
Python troubleshooting techniques (continued)
Using Python to access geoprocessing tools
2-19
To effectively debug your code, you need to implement troubleshooting techniques. These
techniques will allow you to quickly assess any errors that you receive when running your
Python script.
Review the Python script below, and then answer the questions.
Figure 2.6. This Python script should be used to answer the questions about troubleshooting techniques in this
activity.
1. Which lines of code use the commenting out troubleshooting technique?
__________________________________________________________________________________
__________________________________________________________________________________
2. Which lines of code use the print function troubleshooting technique?
__________________________________________________________________________________
__________________________________________________________________________________
Lesson 2
Troubleshooting errors in a script
2-20
3. Which lines of code use the informative comments troubleshooting technique?
__________________________________________________________________________________
__________________________________________________________________________________
Troubleshooting errors in a script (continued)
Using Python to access geoprocessing tools
2-21
This exercise continues the workflow from the previous exercise. You will use troubleshooting
techniques to plan and debug existing code. You can apply these troubleshooting techniques
at any time during script creation, but it is always good practice to apply them before sharing
your script.
In this exercise, you will perform the following tasks:
• Add informative comments to a script to describe the code sections.
• Add print functions to provide feedback during the processing of the script.
• Use comments to remove portions of the existing code during debugging.
• Run a Python script using the PyCharm debugging tools.
Exercise 2B
Add troubleshooting techniques to a Python script
20 minutes
2-22
Step 1: Add informative comments
You will use PyCharm to add troubleshooting techniques to a Python script. The .py file that
you will use is from the code that you created in the previous exercise.
a Return to PyCharm.
b Ensure that the SimpleVariables.py file is open.
The instructions in this box are only necessary if SimpleVariables.py is not open in
PyCharm. If you are unsure, ask your instructor for assistance.
1. If necessary, start PyCharm.
2. On the PyCharm menu, click File and choose Open.
3. In the Open File Or Project window, browse to the ..\EsriTraining\PYTS\
Results\Exercise02A folder.
4. Select SimpleVariables.py, and then click OK.
You will add informative comments for your workflow steps. Informative comments can be
written before you develop the actual code. However, if you are working with existing code,
you can add the necessary comments afterward.
c Place your cursor at the end of line 1 (after the # coding: utf-8 comment) and press
Enter to move to the next line.
d On line 2, type # Import site package and press Enter to move to the next line.
e On line 3, type import arcpy and press Enter to accept the code completion, and then
press Enter a second time to move to line 5.
ArcGIS Pro does not require that you import the arcpy site package within the
Python window, but in PyCharm, you need to import the arcpy site package to
access ArcGIS functionality.
f On line 5, type # Set variables.
g Place your cursor at the end of line 8 (after the distance variable is assigned) and press
Enter.
h On line 9, type # Add shapefile to geodatabase.
The results message from the Python window is included in the exported Python file. You will
delete it because it is not needed in the stand-alone script.
Using Python to access geoprocessing tools
2-23
i On line 11, select and delete the following text: # .
j Type # Create buffer from points.
k On line 13, select and delete the following text: # .l Compare your script to the following script:
# coding: utf-8
# Import site package
import arcpy
# Set variables
output = r"C:\EsriTraining\PYTS\Default.gdb\AffectedAreaAppCurrent"
area = r"C:\EsriTraining\PYTS\Default.gdb\AffectedArea"
distance = "0.5 Miles"
# Add shapefile to geodatabase
arcpy.management.CopyFeatures("AffectedAreaApp", output)
# Create buffer from points
arcpy.analysis.Buffer(output, area, distance, "FULL", "ROUND", "ALL", None, "PLANAR")
The informative comments that you have added will help you, or anyone else who uses your
script, navigate the code.
Step 2: Add print functions
Now that the informative comments have been added, you will add print functions to provide
feedback to the PyCharm Console while your script is running. If your script encounters an
error, you can review the PyCharm Console for the last message printed to identify the section
of code encountering the error.
a Place your cursor on line 4, which is after the import arcpy code, and press Enter.
b On line 5, type print("arcpy site package imported").
c Place your cursor at the end of line 9 (after the distance = "0.5 Miles" code) and
press Enter.
d On line 10, type print("Variables set").
e Place your cursor at the end of line 12 (after the
arcpy.management.CopyFeatures('AffectedAreaApp', output)
code) and press Enter.
f On line 13, type print("Shapefile imported into geodatabase").
Lesson 2
2-24
Instead of using two print functions to place text on two separate lines, you can use the Python
new line literal (\n) to indicate new line within a string.
g Place your cursor at the end of line 15 (after the arcpy.analysis.Buffer(output,
area, distance, 'FULL', 'ROUND', 'ALL', None, 'PLANAR')
code) and press Enter.
h On line 16, type print("Buffer created \nScript complete").
i Compare your script to the following script:
# coding: utf-8
# Import site package
import arcpy
print("arcpy site package imported")
# Set variables
output = r"C:\EsriTraining\PYTS\Default.gdb\AffectedAreaAppCurrent"
area = r"C:\EsriTraining\PYTS\Default.gdb\AffectedArea"
distance = "0.5 Miles"
print("Variables set")
# Add shapefile to geodatabase
arcpy.management.CopyFeatures("AffectedAreaApp", output)
print("Shapefile imported into geodatabase")
# Create buffer from points
arcpy.analysis.Buffer(output, area, distance, "FULL", "ROUND", "ALL", None, "PLANAR")
print("Buffer created \nScript complete")
You have added print functions to your script that provide feedback useful for troubleshooting
errors.
Step 3: Comment existing code
As you are tracking down errors within your script, you can comment code to keep Python
from running those specific lines of code. In this step, you will comment out existing lines of
code to prevent them from running.
a Right-click in the script window and choose Run 'SimpleVariables' .
You receive two error messages. Error 000732 says that the dataset AffectedAreaApp does not
exist or is not supported. Error 000725 says that AffectedAreaAppCurrent already exists. The
AffectedAreaApp dataset is an input to the Copy Features tool, and the
AffectedAreaAppCurrent is the output of the Copy Features tool. You will comment the code
on lines 12-16.
Using Python to access geoprocessing tools
2-25
b Select the following text on lines 12-16:
arcpy.management.CopyFeatures('AffectedAreaApp', output)
print("Shapefile imported into geodatabase")
# Create buffer from points
arcpy.analysis.Buffer(output, area, distance, 'FULL', 'ROUND', 'ALL',
None, 'PLANAR')
print("Buffer created \nScript complete")
c From the Code menu, choose Comment With Line Comment.
You can also comment code by selecting the text and using Ctrl + forward slash (/)
or by typing a hash character (#) in front of the text.
Code that has been commented out appears in a light gray color, which shows that Python will
ignore the text on this line. You can use comments to keep certain sections of code from
running while you track down the lines that might be causing your error.
d Compare your script to the following script:
# coding: utf-8
# Import site package
import arcpy
print("arcpy site package imported")
# Set variables
output = r"C:\EsriTraining\PYTS\Default.gdb\AffectedAreaAppCurrent"
area = r"C:\EsriTraining\PYTS\Default.gdb\AffectedArea"
distance = "0.5 Miles"
print("Variables set")
# Add shapefile to geodatabase
# arcpy.management.CopyFeatures("AffectedAreaApp", output)
# print("Shapefile imported into geodatabase")
# # Create buffer from points
# arcpy.analysis.Buffer(output, area, distance, "FULL", "ROUND", "ALL", None, "PLANAR")
# print("Buffer created \nScript complete")
e Right-click in the script window and choose Run 'SimpleVariables' .
Your script now runs successfully without any errors. You will uncomment lines 12–16 to finish
using the troubleshooting techniques.
f From the selected text on lines 12–16, press Ctrl + forward slash (/) to uncomment the line.
Lesson 2
2-26
Although you can delete the hash character (#) from the beginning of the lines,
using the built-in functionality is more efficient if you have an entire block of code to
uncomment.
Step 4: Create a variable
Now that you have added informative comments and print functions to your script, you will
now use PyCharm to run your script. Before you can run the script, you must create a variable
for the input to the Copy Features tool. When the original script was created in the ArcGIS Pro
Python window, the layer name was used because it was being referenced within the project.
You will create a variable for the shapefile input as you learned in the previous exercise.
a Place your cursor at the end of line 5 and press Enter.
b Type arcpy.env.overwriteOutput = True.
This environment setting allows the output of geoprocessing tools to overwrite existing data
with the same name.
c Place your cursor at the end of line 10 (after the distance = "0.5 Miles" code) and
press Enter.
d Type shpInput = r"C:\EsriTraining\PYTS\Data\AffectedAreaApp.shp".
e Comment out the following code on line 14:
arcpy.management.CopyFeatures('AffectedAreaApp', output).
Hint:Hint: Ctrl + forward slash (/)
This allows you to preserve the existing line of code while adding in the variable for the
shapefile input to a copy of the code.
f Place your cursor at the end of the commented out line 14 and press Enter to move to line
15.
g Type arcpy.management.CopyFeatures(shpInput, output).
h Verify that your script matches the following completed script:
# coding: utf-8
# Import site package
import arcpy
print("arcpy site package imported")
arcpy.env.overwriteOutput = True
# Set variables
output = r"C:\EsriTraining\PYTS\Default.gdb\AffectedAreaAppCurrent"
area = r"C:\EsriTraining\PYTS\Default.gdb\AffectedArea"
Using Python to access geoprocessing tools
2-27
distance = "0.5 Miles"
shpInput = r"C:\EsriTraining\PYTS\Data\AffectedAreaApp.shp"
print("Variables set")
# Add shapefile to geodatabase
# arcpy.management.CopyFeatures("AffectedAreaApp", output)
arcpy.management.CopyFeatures(shpInput, output)
print("Shapefile imported into geodatabase")
# Create buffer from points
arcpy.analysis.Buffer(output, area, distance, "FULL", "ROUND", "ALL", None, "PLANAR")
print("Buffer created \nScript complete")
With your script completed, it is ready to be run with the IDE debugging tools.
Step 5: Use debugging tools in PyCharm
Now that you have added troubleshooting techniques in your code, you will use the PyCharm
debugging tools.
a On line 12 (with the print("Variables set") code), set a breakpoint by clicking in the
space within the left-side column between the line numbers and the code.
A red dot displays to indicate that the breakpoint has been set.
b Right-click in the script window and choose Debug 'SimpleVariables' .
The script runs until it reaches the breakpoint, and the Debug window opens at the bottom of
the screen.
c In the Debug window, click the Debugger tab, if necessary, to view the variable