Table Of ContentThis page intentionally left blank.
This page intentionally left blank.
>>>
®
PYTHON
®
Scripting for ArcGIS
Paul A. Zandbergen
Esri Press, 380 New York Street, Redlands, California 92373-8100
Copyright © 2013 Esri
All rights reserved. First edition
Printed in the United States of America
17 16 15 14 13 1 2 3 4 5 6 7 8 9 10
Library of Congress has cataloged the print edition as follows:
Zandbergen, Paul A., 1968-
Python scripting for ArcGIS / Paul A. Zandbergen. — First edition.
pages cm
Includes index.
ISBN 978-1-58948-371-2 (pbk.)
eISBN 978-1-58948-362-0 (electronic)
1. ArcGIS. 2. Geographic information systems. 3. Graphical user interfaces (Computer systems) 4. Python (Computer program language) I. Title.
G70.212.Z36 2013
910.285’5133--dc23 2012020676
The information contained in this document is the exclusive property of Esri unless otherwise noted. This work is protected under United States copyright law
and the copyright laws of the given countries of origin and applicable international laws, treaties, and/or conventions. No part of this work may be reproduced or
transmitted in any form or by any means, electronic or mechanical, including photocopying or recording, or by any information storage or retrieval system, except
as expressly permitted in writing by Esri. All requests should be sent to Attention: Contracts and Legal Services Manager, Esri, 380 New York Street, Redlands,
California 92373-8100 USA.
The information contained in this document is subject to change without notice.
U.S. Government Restricted/Limited Rights: Any software, documentation, and/or data delivered hereunder is subject to the terms of the License Agreement.
The commercial license rights in the License Agreement strictly govern Licensee’s use, reproduction, or disclosure of the software, data, and documentation. In no
event shall the US Government acquire greater than RESTRICTED/LIMITED RIGHTS. At a minimum, use, duplication, or disclosure by the US Government is subject
to restrictions as set forth in FAR §52.227-14 Alternates I, II, and III (DEC 2007); FAR §52.227-19(b) (DEC 2007) and/or FAR §12.211/12.212 (Commercial Technical
Data/Computer Software); and DFARS §252.227-7015 (DEC 2011) (Technical Data – Commercial Items) and/or DFARS §227.7202 (Commercial Computer Software
and Commercial Computer Software Documentation), as applicable. Contractor/Manufacturer is Esri, 380 New York Street, Redlands, CA 92373-8100, USA.
@esri.com, 3D Analyst, ACORN, Address Coder, ADF, AML, ArcAtlas, ArcCAD, ArcCatalog, ArcCOGO, ArcData, ArcDoc, ArcEdit, ArcEditor, ArcEurope,
ArcExplorer, ArcExpress, ArcGIS, arcgis.com, ArcGlobe, ArcGrid, ArcIMS, ARC/INFO, ArcInfo, ArcInfo Librarian, ArcLessons, ArcLocation, ArcLogistics, ArcMap,
ArcNetwork, ArcNews, ArcObjects, ArcOpen, ArcPad, ArcPlot, ArcPress, ArcPy, ArcReader, ArcScan, ArcScene, ArcSchool, ArcScripts, ArcSDE, ArcSdl, ArcSketch,
ArcStorm, ArcSurvey, ArcTIN, ArcToolbox, ArcTools, ArcUSA, ArcUser<,ital>, ArcView, ArcVoyager, ArcWatch, ArcWeb, ArcWorld, ArcXML, Atlas GIS, AtlasWare,
Avenue, BAO, Business Analyst, Business Analyst Online, BusinessMAP, CityEngine, CommunityInfo, Database Integrator, DBI Kit, EDN, Esri, esri.com, Esri — Team
GIS, Esri — The GIS Company, Esri — The GIS People, Esri — The GIS Software Leader, FormEdit, GeoCollector, Geographic Design System, Geography Matters,
Geography Network, geographynetwork.com, Geoloqi, Geotrigger, GIS by Esri, gis.com, GISData Server, GIS Day, gisday.com, GIS for Everyone, JTX, MapIt,
Maplex, MapObjects, MapStudio, ModelBuilder, MOLE, MPS—Atlas, PLTS, Rent-a-Tech, SDE, SML, Sourcebook•America, SpatiaLABS, Spatial Database Engine,
StreetMap, Tapestry, the ARC/INFO logo, the ArcGIS Explorer logo, the ArcGIS logo, the ArcPad logo, the Esri globe logo, the Esri Press logo, The Geographic
Advantage, The Geographic Approach, the GIS Day logo, the MapIt logo, The World’s Leading Desktop GIS, Water Writes, and Your Personal Geographic
Information System are trademarks, service marks, or registered marks of Esri in the United States, the European Community, or certain other jurisdictions.
CityEngine is a registered trademark of Procedural AG and is distributed under license by Esri. Other companies and products or services mentioned herein may
be trademarks, service marks, or registered marks of their respective mark owners.
Ask for Esri Press titles at your local bookstore or order by calling 800-447-9778, or shop online at esri.com/esripress. Outside the United States, contact your local
Esri distributor or shop online at eurospanbookstore.com/esri.
Esri Press titles are distributed to the trade by the following: E-mail:
Contents
Preface ________________________________________________xi
Acknowledgments ______________________________________xiv
Part 1: Learning the fundamentals of Python and geoprocessing __ 1
Chapter 1: Introducing Python ___________________________________ 3
1.1 Introduction ___________________________________________ 3
1.2 Exploring the features of Python _________________________ 3
1.3 Comparing scripting vs. programming ____________________ 4
1.4 Using scripting in ArcGIS _______________________________ 5
1.5 Python history and versions _____________________________ 5
1.6 About this book _______________________________________ 6
1.7 Exploring how Python is used ___________________________ 8
1.8 Choosing a Python script editor ________________________ 13
Points to remember ___________________________________ 19
Chapter 2: Geoprocessing in ArcGIS _____________________________ 21
2.1 Introduction __________________________________________ 21
2.2 What is geoprocessing? ________________________________ 21
2.3 A note on ArcObjects__________________________________ 23
2.4 Using toolboxes and tools ______________________________ 24
2.5 Learning types and categories of tools ___________________ 25
2.6 Running tools using tool dialog boxes ___________________ 26
2.7 Specifying environment settings ________________________ 30
2.8 Using batch processing ________________________________ 32
2.9 Using models and ModelBuilder ________________________ 34
2.10 Using scripting _______________________________________ 38
2.11 Running scripts as tools _______________________________ 41
2.12 Converting a model to a script __________________________ 44
2.13 Scheduling a Python script to run at prescribed times _____ 45
Points to remember ___________________________________ 47
vi Contents
Chapter 3: Using the Python window_____________________________ 49
3.1 Introduction __________________________________________ 49
3.2 Opening the Python window ___________________________ 49
3.3 Writing and running code ______________________________ 50
3.4 Getting assistance _____________________________________ 52
3.5 Exploring Python window options ______________________ 54
3.6 Saving your work _____________________________________ 55
3.7 Loading code into the Python window __________________ 56
Points to remember ___________________________________ 57
Chapter 4: Learning Python language fundamentals _______________ 59
4.1 Introduction __________________________________________ 59
4.2 Locating Python documentation and resources ___________ 59
4.3 Working with data types and structures _________________ 60
4.4 Working with numbers ________________________________ 60
4.5 Working with variables and naming _____________________ 62
4.6 Writing statements and expressions _____________________ 63
4.7 Using strings _________________________________________ 64
4.8 Using lists____________________________________________ 66
4.9 Working with Python objects ___________________________ 66
4.10 Using functions _______________________________________ 68
4.11 Using methods _______________________________________ 69
4.12 Working with strings __________________________________ 70
4.13 Working with lists ____________________________________ 74
4.14 Working with paths ___________________________________ 78
4.15 Working with modules ________________________________ 79
4.16 Controlling workfow using conditional statements _______ 81
4.17 Controlling workfow using loop structures ______________ 83
4.18 Getting user input ____________________________________ 85
4.19 Commenting scripts ___________________________________ 86
4.20 Working with code in the PythonWin editor _____________ 88
4.21 Following coding guidelines ____________________________ 89
Points to remember ___________________________________ 90
Contents vii
Part 2: Writing scripts ___________________________________________93
Chapter 5: Geoprocessing using Python _________________________ 95
5.1 Introduction __________________________________________ 95
5.2 Using the ArcPy site package ___________________________ 95
5.3 Importing ArcPy ______________________________________ 96
5.4 Working with earlier versions of ArcGIS _________________ 97
5.5 Using tools ___________________________________________ 98
5.6 Working with toolboxes _______________________________ 104
5.7 Using functions ______________________________________ 106
5.8 Using classes ________________________________________ 107
5.9 Using environment settings ___________________________110
5.10 Working with tool messages ___________________________ 112
5.11 Working with licenses ________________________________ 115
5.12 Accessing ArcGIS Desktop Help _______________________ 119
Points to remember __________________________________ 122
Chapter 6: Exploring spatial data _______________________________ 123
6.1 Introduction _________________________________________ 123
6.2 Checking for the existence of data _____________________ 123
6.3 Describing data ______________________________________ 125
6.4 Listing data _________________________________________ 127
6.5 Using lists in for loops _______________________________ 131
6.6 Working with lists ___________________________________ 132
6.7 Working with tuples__________________________________ 133
6.8 Working with dictionaries ____________________________ 134
Points to remember __________________________________ 137
Chapter 7: Manipulating spatial data ____________________________ 139
7.1 Introduction _________________________________________ 139
7.2 Using cursors to access data ___________________________ 139
7.3 Using SQL in Python _________________________________ 144
7.4 Working with table and feld names ____________________ 146
7.5 Parsing table and feld names __________________________ 148
7.6 Working with text fles _______________________________ 149
Points to remember __________________________________ 158
Chapter 8: Working with geometries ____________________________ 159
8.1 Introduction _________________________________________ 159
8.2 Working with geometry objects ________________________ 159
8.3 Reading geometries __________________________________160
8.4 Working with multipart features _______________________ 164
8.5 Working with polygons with holes _____________________ 167
8.6 Writing geometries ___________________________________ 169
8.7 Using cursors to set the spatial reference _______________ 172
8.8 Using geometry objects to work with geoprocessing tools__ 174
Points to remember __________________________________ 175
viii Contents
Chapter 9: Working with rasters ________________________________ 177
9.1 Introduction _________________________________________ 177
9.2 Listing rasters _______________________________________ 177
9.3 Describing raster properties ___________________________ 178
9.4 Working with raster objects ___________________________ 182
9.5 Working with the ArcPy Spatial Analyst module_ ________ 183
9.6 Using map algebra operators __________________________ 184
9.7 Using the ApplyEnvironment function _______________ 187
9.8 Using classes of the arcpy.sa module _________________ 188
9.9 Using raster functions to work with NumPy arrays ______ 192
Points to remember __________________________________ 193
Part 3: Carrying out specialized tasks __________________________ 195
Chapter 10: Map scripting _____________________________________ 197
10.1 Introduction _________________________________________ 197
10.2 Working with the ArcPy mapping module ______________ 197
10.3 Opening map documents _____________________________ 198
10.4 Accessing map document properties and methods _______200
10.5 Working with data frames ____________________________ 201
10.6 Working with layers __________________________________ 203
10.7 Fixing broken data sources ____________________________ 208
10.8 Working with page layout elements ____________________ 213
10.9 Exporting maps ______________________________________ 216
10.10 Printing maps _______________________________________ 218
10.11 Working with PDFs __________________________________ 219
10.12 Creating map books __________________________________220
10.13 Using sample mapping scripts _________________________ 222
Points to remember __________________________________ 225
Chapter 11: Debugging and error handling ______________________ 227
11.1 Introduction _________________________________________ 227
11.2 Recognizing syntax errors _____________________________ 227
11.3 Recognizing exceptions _______________________________230
11.4 Using debugging _____________________________________230
11.5 Using debugging tips and tricks _______________________ 237
11.6 Error handling for exceptions _________________________ 238
11.7 Raising exceptions ___________________________________ 239
11.8 Handling exceptions __________________________________ 241
11.9 Handling geoprocessing exceptions ____________________ 244
11.10 Using other error-handling methods ___________________ 247
11.11 Watching for common errors __________________________ 247
Points to remember __________________________________ 249
Contents ix
Chapter 12: Creating Python functions and classes ______________ 251
12.1 Introduction _________________________________________ 251
12.2 Creating functions ___________________________________ 251
12.3 Calling functions from other scripts ____________________ 255
12.4 Organizing code into modules _________________________ 258
12.5 Using classes ________________________________________260
12.6 Working with packages _______________________________ 264
Points to remember __________________________________ 267
Part 4: Creating and using script tools _________________________ 269
Chapter 13: Creating custom tools ______________________________ 271
13.1 Introduction _________________________________________ 271
13.2 Why create your own tools? ___________________________ 271
13.3 Steps to creating a tool _______________________________ 273
13.4 Editing tool code _____________________________________ 279
13.5 Exploring tool parameters _____________________________280
13.6 Setting tool parameters _______________________________ 285
13.7 Examining an example script tool ______________________290
13.8 Customizing tool behavior ____________________________ 293
13.9 Working with messages _______________________________ 294
13.10 Handling messages for stand-alone scripts and tools _____ 297
13.11 Customizing tool progress information _________________ 297
13.12 Running a script in process ___________________________ 301
Points to remember __________________________________ 302
Chapter 14: Sharing tools ______________________________________ 303
14.1 Introduction _________________________________________ 303
14.2 Choosing a method for distributing tools _______________ 303
14.3 Handling licensing issues _____________________________ 304
14.4 Using a standard folder structure for sharing tools _______ 305
14.5 Working with paths __________________________________ 306
14.6 Finding data and workspaces __________________________ 308
14.7 Creating a geoprocessing package ______________________310
14.8 Embedding scripts and password-protecting tools ________ 311
14.9 Documenting tools ___________________________________ 312
14.10 Example tool: Market analysis _________________________ 315
Points to remember __________________________________ 321
Appendix A Data source credits _________________________ 323
Index _______________________________________________ 327
