The ArcPy
website package provides basic functionality that enables the creation of ArcGIS geoprocessing scripts with Python. The core functionality of this package includes many capabilities including the following:
Execution of
ArcToolbox
geoprocessing tools as dynamic methodsAdding, listing, removing, and validating data stores
Describing data
Getting and setting environment variables
General utilities
Graphing
Working with fields
Working with data stores
Administration of geodatabases
Geometry operations
Getting and setting parameters
Licensing and installation
Listing data
Log history
Messaging and error handling
Progress dialog manipulation
Publishing
Working with
rasters
andNumPy
arraysWorking with spatial references and transformations
Tools and toolboxes
Workspaces
In this section, we'll examine the most commonly used classes and functions in the ArcPy
site package.
Most of the ArcPy
classes are somewhat generic, but can be divided into groups, including FeatureSets
and RecordSets
, Fields, General, Geometry, Graphing, and Parameters.
The FeatureSet
and RecordSet
objects are lightweight representations of feature classes and tables, respectively. These in-memory objects contain fields as well as data. They also serve as interchange objects with a server. The constructor for both objects accepts a string that references a feature class or table. Both contain a property that returns a JSON representation of the data as well as methods to import and export the data from the object.
There are four classes related to attribute fields, including Field
, FieldInfo
, FieldMap
, and FieldMappings
. The Field
object represents a column in a table or feature
class. This object can be retrieved using the ListFields()
and Describe()
functions which we'll cover later. Read-write properties on this object provide access to the field name, alias name, domain, the editable state, if the field can contain null values, and length. Fields must contain a value, and type.
The FieldInfo
object provides properties and methods about the fields in a layer or table view. Using this object, you can add and remove fields, control field visibility, set the split rule, set the field name, and others.
There are two objects related to field mapping: FieldMap
and FieldMappings
. The FieldMappings
object serves as a container object for one or more FieldMap
objects. Each FieldMap
object defines a field definition and a list of input fields pulled from a table or feature class. FieldMap
objects are added to the FieldMappings
object.
There is a set of generic geometry objects used to define the geometric definition of points, lines, polygons, and other geometry representations. These objects include Point
, Polyline
, Polygon
, MultiPoint
, PointGeometry
, and the generic Geometry
class. Point
, MultiPoint
, Polyline
, and Polygon
are self-explanatory, but the PointGeometry
class requires some further explanation. Although being similar to the Point
object, it does have some important differences. Point
objects are used with cursor objects when creating or returning features from a feature
class. The PointGeometry
class is used in geometry operations, but not for the creation of geometry
objects used in cursors.
There are only two classes related to graphing in ArcPy
: Graph
and GraphTemplate
. The GraphTemplate
class uses a .tee
file to construct a graph template that can then be used to create graphs from different datasets that have the same basic structure. The .tee
file contains everything needed to create the graph except for the data. ArcToolbox
contains a MakeGraph
tool that you can use to actually create the graph using the template. Similarly, the Graph
class also helps create graphs of different types and contains properties to define the graph title, axes, and legend information.
There are a number of generic classes that don't really fall into a specific group. The Extent
class represents a rectangle that defines the geographic boundaries of an objects. This object contains spatial relationship operators that allow you to compare the Extent
object to other geographies as well as properties that define the object.
The Array
class is an object that can contain Point
objects and is used to construct geometry object. The env
object represents environment variables that can be retrieved or set. Each of the properties on this object represents an environment variable. The SpatialReference
class has a number of properties that define what map projection options are used to define horizontal coordinates. ValueTable
is an object that allows the creation of a multivalue
parameter. The Result
object simulates the Result window in ArcGIS Desktop and provides the ability to maintain information about the execution of tools, including messages
, parameters
, and output
. The Raster object can be used to define map algebra expressions. There are some additional classes that fall into the general category, including ArcSDE
, SQLExecute
, Index
, NetCDFFileProperties
, and RandomNumberGenerator
.
There is a long list of ArcPy
functions that provide a wide array of functionality. Perhaps the most important functions are the dynamic methods that enable you to call geoprocessing tools in ArcToolbox
like you would any other method or function. Beyond these dynamic methods, the functions that are part of the ArcPy
core library can be grouped by data store, describing data, environment variables, fields, general, geodatabase administration, geometry, getting and setting parameters, licensing and installation, listing data, messaging and error handling, progress dialog, publishing, raster, and tools and toolboxes.
Data for services can be registered with ArcGIS Server and can include folders or databases. Functions related to data stores include AddDataStoreItem()
, ListDataStoreItem()
, RemoveDataStoreItem()
, and ValidateDataStoreItem()
. As their names suggest, these functions allow you to add, remove, list, and validate these data stores.
The Describe()
function can be used to obtain descriptive information about GIS datasets. This function accepts a single parameter that references a geographic dataset. The information returned by this function includes a variable set of properties that describe that data. The set of properties returned by this functions are correlated to the type of data being described.
There are a handful of functions related to managing environment variables. The ClearEnvironment()
function resets a specific environment variable to it's default value. GetSystemEnvironment()
gets the value of a specific environment value. ListEnvironments()
returns a list of environment names. LoadSettings()
and SaveSettings()
enable you to either read environment variable settings from an XML
file or write the settings to an XML
file. Finally, ResetEnvironments()
resets all the environment variables to the default settings.
The AddFieldDelimiters()
function is an important function when creating SQL expressions for attribute queries. The delimiters used around the fields being queried are different depending on whether you're querying shapefiles
, geodatabase files, ArcSDE
geodatabases, or personal geodatabases. For example, with geodatabase files, the field being queried needs to be surrounded by quotes whereas braces should surround personal geodatabase fields. The AddFieldDelimiters()
function handles the guess work of ensuring that you have the proper delimiter. Other functions that are part of this category include ParseFieldName()
and ValidateFieldName()
. ParseFieldName()
parses a fully qualified field name into separate components, including database, owner name, table name, and field name. Finally, the ValidateFieldName()
functions takes a string that represents a field name and a workspace path and returns a valid field name based on the naming restrictions of the output geodatabase.
There are a number of useful general functions, including RefreshActiveView()
, RefreshCatalog()
, and RefreshTOC()
, which force a refresh of these objects in ArcMap. In some cases, it's important to refresh these objects when the data has changed in some way. Other commonly used general functions include ListPrinterNames()
, which returns a list of printers to the computer where the script is running, and CreateRandomValueGenerator()
.
The Exists()
function can be used to perform a test, to see if a dataset exists before continuing with a geoprocessing operation. ValidateTableName()
, accepts a table name as a parameter as well as a workspace path and returns a valid table name for the workspace. Similarly, ParseTableName()
parses a table name into its components, including database owner and table.
There are a small number of geodatabase administration functions: AcceptConnections()
, DisconnectUser()
, and ListUsers()
. The AcceptConnections()
function allows a script to enable or disable the ability to connect to a geodatabase. DisconnectUser()
can be used to disconnect a user, and ListUsers()
generates a list of the users connected to a geodatabase.
There are a small number of ArcPy
functions related to converting geometry data. The AsShape()
function converts either an Esri JSON
or GeoJSON
object to an ArcPy Geometry
object. The FromWKB()
and FromWKT()
functions create Geometry
objects from well-known binary and well-known text formats.
There are a number of get and set functions related to parameters. Perhaps, the most well-known function in this category is GetParameterAsText()
, which is used to retrieve a specified parameter as a text string through the use of an index position from the list of parameters. GetParameterValue()
returns the default value of a desired parameter. GetParameterCount()
returns a count of the number of parameters values for a specified tool. GetParameter()
returns a Parameter
object for the specified parameter. GetParameterInfo()
returns a list of parameter
objects for a given tool. There are a couple set functions including SetParameter()
and SetParameterAsText()
. The SetParameter()
function sets a specified parameter by index using an object and is used when passing objects from a script to a script tool. SetParameterAsText()
sets a specified parameter property by index using a string value.
The functions in this category allow you to work with products and extensions. ProductInfo()
returns the current product license. SetProduct()
can be used to set the ArcGIS Desktop license. CheckProduct()
checks to see whether a license is available. There are three functions related to extensions: CheckExtension()
, CheckInExtension()
, and CheckOutExtension()
. You can get a list of installation types including server, desktop, and engine with the ListInstallations()
function.
There are many list functions that return a Python list containing data of some sort. These functions are most often used as the first step in a multistep process where the first step is simply to generate a list of data that will then be used in a geoprocessing operation. These include ListDatasets()
, ListFeatureClasses()
, ListFields()
, ListFiles()
, ListIndexes()
, ListRasters()
, ListTables()
, ListVersions()
, ListWorkspaces()
, ListSpatialReferences()
, and ListTransformations()
.
All tools produce messages as they are executing. Most messages are informational in nature, but warnings and errors can occur as well. Messages are divided into severity levels that indicate whether a message is informational only, a warning, or an error. In addition to the messages that are generated by a tool, you can also add your own messages to the stack. There are a number of get
functions such as: GetMaxSeverity()
, GetMessage()
, GetMessageCount()
, GetMessages()
, GetReturnCode()
, GetSeverity()
, and GetSeverityLevel()
. Most of these functions either retrieve messages or the severity level associated with the message.
There are also three add
functions such as: AddMessage()
, AddWarning()
, and AddError()
. These three functions correspond to the different severity levels and enable you to add your messages to the stack also being generated by the tool itself.
The progress dialog can be controlled through a set of functions, including SetProgressor()
, SetProgressorLabel()
, SetProgressorPosition()
, and ResetProgressor()
. The SetProgressor()
function creates a progressor
object. Using this object, you can then pass information to the progress dialog box. In addition, you can control the appearance of the progress dialog by choosing either the default progressor
or the step progressor
. The label and position of the status bar can be set through the SetProgressorLabel()
and SetProgressorPosition()
functions. Finally, there is a ResetProgressor()
function that resets the progressor
back to its initial state.
There are three ArcPy
functions related to creating Service Definition Draft (SDDraft) files for various types of ArcGIS Server services. The Service Definition Draft file is a file type used as an interchange file between ArcGIS Desktop and ArcGIS Server. These include CreateGeocodeSDDraft()
, CreateGPSDraft()
, and CreateImageSDDraft()
. These functions correspond to the types of services being created.
There are two functions related to converting rasters
and NumPy
arrays. The NumPyArrayToRaster()
functions converts a NumPy
array to a raster, whereas RasterToNumPyArray()
convert a raster to a NumPyArray
.
Toolboxes can be added and removed using various functions, such as AddToolbox()
, ImportToolbox()
, and RemoveToolbox()
. Any custom or third-party toolboxes must be imported before you can use them in your scripts. Server tools can also be imported. The AddToolbox()
and ImportToolbox()
functions are equivalent, so you can use either for this purpose. The ImportToolbox()
functions accepts an input that references the custom toolbox to be imported along with an optional module name. If you need to remove a toolbox, you can use the RemoveToolbox()
function. A related function that is part of this category is the IsSynchronous()
function which is used to determine if a tool is running synchronously or asynchronously. All non-server tools will be synchronous. This simply means that results are automatically returned. Any asynchronous functions will be related to ArcGIS Server tools where the data may not be returned immediately. In the case of an asynchronous, tool you must set your script up to wait for the results to be returned before continuing. This can be accomplished with the Python time.sleep()
method.