The ArcPy mapping module, part of the ArcPy site package, provides some really exciting features for map automation, including the ability to manage map document and layer files as well as the data within these files. Support is also provided to automate map export and printing as well as the creation of map books and publication of map documents to ArcGIS Server map services.
The capabilities of the module include the following:
Managing map document and layer files
Managing the data within map document and layer files
Changing layer symbology and properties
Inserting layers into a data frame or group layer
Moving layers in a data frame or group layer
Zooming to selected features
Working with time-enabled layers in a data frame
Creating reports
Changing the map extent
Finding and fixing broken data links
Printing maps
Exporting maps to PDF files
Exporting maps to image files
Updating the layout view
Building a map book with Data Driven Pages
Publishing a map document to an ArcGIS Server service
In this section, I'll present an overview of the available functionality provided by the classes and functions in the ArcPy mapping module.
The classes available in the ArcPy mapping module can loosely be grouped into several categories, including map documents and associated datasets, Data Driven Pages, managing time-related layers, element classes related to a layout view, PDF document creation and editing, and symbology.
There are four classes in the ArcPy mapping module related to map documents and their associated data: MapDocument, DataFrame, Layer, and TableView. These four classes are probably the most essential and often used objects in the module.
The MapDocument class is probably the most essential object in the ArcPy mapping module and is required to some degree in most of the scripts you write using this module. A reference to this object is required for most scripts, so it's usually one of the first lines of code in a geoprocessing script. The constructor for this object accepts either a string that contains the keyword CURRENT or a path to a map document file.
There are a number of properties on this object that expose a variety of functionality, including getting the active data frame or active view, to the author of the document, the last date when the document was exported, printed, or saved, a description, path to the file, title, and a few others. You can also determine if the map document is Data Driven Pages enabled, and, if so, a DataDrivenPages object can be returned with the dataDrivenPages property.
In addition, there are a number of methods on this object that allow you to perform various operations, such as fixing broken data links, saving the map document, and working with thumbnails. Two methods, findAndReplaceWorkspacePaths() and replaceWorkspaces(), can be used to fix broken data links. The findAndReplaceWorkspacePaths() method replaces an old workspace path with a new workspace path for all layers and tables in the map document. The replaceWorkspaces() method is used to change the workspace type of all layers and tables in the map document. The save() and saveACopy() methods are used to save the map document, and makeThumbnail() and deleteThumbnail() are used when working with thumbnail images of a map document.
A DataFrame in a map document serves as a working area and container for datasets, including layers and standalone tables. Most of the properties on the DataFrame object are read/write and include the ability to work with the geographic extent, change the size and position of the element in layout view, get or set the name, scale, spatial reference, description, and a few others. If you have time-enabled layers in the data frame, the read-only property time provides access to the DataFrameTime object that we'll discuss next.
There are two methods on the DataFrame class: panToExtent() and zoomToSelectedFeatures(). The panToExtent() object accepts an Extent object as a parameter and pans the map to the geographic extent provided. The zoomToSelectedFeatures() method zooms the map to the extent of the selected set of features.
The Layer class provides a reference to layers in a map document or layer file, and provides many properties and methods to work with the object. I'll examine the most commonly used in this section.
There are a number of ways that you can create an instance of the Layer object including a Layer(lyr_file_path) constructor that creates instance of this object by passing a path to the .lyr file as a parameter to the constructor.
Some of the properties on this object provide access to common properties found in the Layer Properties dialog in ArcMap that is displayed by right-clicking on a layer and selecting Properties. However, many of these properties are not exposed to scripting through the Layer object. The properties that are exposed allow you to get and set the definition query, description, label classes, minimum and maximum scale, name, turning labels on and off, transparency, and the visibility of the layer.
There are a number of is properties that allow you to test the layer type. These include isFeatureLayer, isGroupLayer, isNetworkAnalystLayer, isRasterLayer, and isServiceLayer.
A set of properties dealing with the source dataset of the layer is also present, such as datasetName, dataSource, and workspacePath. datasetName returns the name of the layer's dataset the way it appears in the workspace, not the table of contents. The dataSource property returns the complete path for the layer's data source including the workspace path and dataset name combined. workspacePath returns a path to the workspace for the layer or ArcSDE connection file.
The Layer class also includes a number of methods that allow you to work with the extent of the layer or selected features from a layer, fix a layer that becomes broken due to a new workspace path or type, and save the layer file or save it to a new copy.
The TableView object allows you to manage standalone tables in a map document file. The constructor for this object accepts a parameter that includes a full path to the workspace where the table exists and should also include the name of the table.
There are only a handful of properties on this object, most of which relate to dataset path and naming. The workspacePath property returns a path to the table's workspace or connection file. The datasetName returns the name of the table in the workspace, and dataSource returns the table's source path. One helpful property is definitionQuery. This property provides the ability to limit the displayed records to only records that match a specific query.
There are also a couple of methods on this object that allow you to fix a broken data source, including findAndReplaceWorkspacePath() and replaceDataSource(). These are the same methods that are available on the Layer object and also perform the same functionality.
The Data Driven Pages functionality is handled through the DataDrivenPages class. The Data Driven Pages functionality in ArcGIS enables you to create a series of maps for a geographic area for the purpose of creating a map book. ArcMap includes a Data Driven Pages toolbar that you can use to create this series of maps without having to write any code. You could also elect to automate the entire process through a Python script without using the toolbar. However, the creation of a map book is best accomplished through a combination of the Data Driven Pages toolbar and scripting with ArcPy mapping using the DataDrivenPages class. The toolbar could be used to author the Data Driven Pages functionality in the map document, and the scripting would handle any custom requirements, such as changing titles for each map in the series as well as exporting the maps to pdf files. The methods and properties on the DataDrivenPages class enable you to work with the individual pages in a map document that already has Data Driven Pages enabled.
There are two classes in the ArcPy mapping module related to time-enabled layers: DataFrameTime and LayerTime.
Time-enabled layers in a data frame can be controlled through the DataFrameTime object. This object can be used in scenarios where map documents have already been published with time-aware layers, including the use of the Time Slider Options dialog to set various properties. It can also be used in situations where map documents don't already have time-enabled layers, but the intent is to add them through a script.
Properties of the DataFrameTime object allow you to get and set the start time, current time, end time, time window, and time window units. It also includes a read-only property to obtain the time step interval. The only method on the DataFrameTime object is resetTimeExtent(), which resets the time extent of the data frame.
This class provides the ability to manage time-enabled layers. It provides information about how time is stored and configured. The properties on the class are read-only and allow you to retrieve information about the start and end times for the layer, the fields being used to store the start and end times, the time format, time zone, whether the time information is observing daylight saving time, and the time step interval. There are no methods associated with the LayerTime class.
Element classes in ArcPy mapping represent everything that you add to the layout view in ArcMap. Using these element classes, you can make changes to the layout view through your scripts including changing the size and position of elements and altering the data associated with an element. In addition to the classes discussed here, the previously discussed DataFrame element can also be included with these.
The LegendElement class provides properties for the positioning of the legend on the page layout and modifying of the legend title, and also provides access to the legend items and the parent data frame. A LegendElement class can be associated with only a single data frame. The methods available on this class enable you to update or remove legend items, adjust the column count, and obtain a list of the legend items.
The GraphicElement class is a generic object for various graphics that can be added to the page layout, including tables, graphs, Neatlines, markers, lines, and area shapes. This object provides a limited set of properties that allow you to reposition and resize the elements on the layout as well as set the name. In addition, there are two methods on this class: clone() and delete(). The clone() method creates a copy of the element, whereas delete() is used to remove the element from the layout.
The MapsurroundElement can refer to north arrows, scale bars, and scale text and like LegendElement, is associated with a single data frame. Properties on this object enable repositioning and resizing on the page.
PictureElement represents a raster or image on the page layout. The most useful property on this object allows you to get and set the data source that can be extremely helpful when you need to change a picture such as a logo in multiple map documents. For example, you could write a script that iterates through all your map document files and replaces the current logo with a new logo. You can also reposition the object.
TextElement represents text on a page layout, including inserted text, callouts, rectangle text and titles, but does not include legend titles or text that is part of a table or chart. Properties enable modifying the text string, which can be extremely useful in situations where you need to make the same text string change in multiple places in the page layout or over multiple map documents, and of course repositioning of the object is also available.
Although there is only one class related to creating pdf documents in the ArcPy mapping module, we'll explore a second way that you can create pdf documents when we discuss the ExportToPDF() function in the next section.
You can manipulate existing PDF documents or create new PDF documents using the PDFDocument class. You can merge pages, set document open behavior, add file attachments, and create or change document security settings. The PDFDocumentOpen() function is used to open an existing PDF file for manipulation. The PDFDocumentCreate() function creates a new PDF document. These functions are often used in the creation of map books.
You'll need to use PDFDocumentCreate() to create a new PDF document by providing a path and filename for the document. The PDF is not actually created on disk until you insert or append pages and then call PDFDocument.saveAndClose(). The appendPages() and insertPages() functions are used to insert and append pages.
PDFDocumentOpen() accepts a parameter that specifies the path to a PDF file and returns an instance of the PDFDocument class. Once you can make modifications to PDF file properties, you can add or insert files and can attach documents. Make sure that you call PDFDocument.saveAndClose() after all operations to save the changes to disk.
A number of properties can be set on a PDF document through the PDFDocument object, including getting a page count, attaching files, updating the title, author, subject, keywords, open behavior, and the layout. You can also update the document security by calling PDFDocument.updateDocSecurity() to set a password, encryption, and security restrictions.
There are a number of classes in the ArcPy mapping module that provides a limited ability to make changes to the symbology of an application including GraduatedColorsSymbology, GraduatedSymbolsSymbology, RasterClassifiedSymbology, and UniqueValuesSymbology classes.
This class provides a limited ability to change the appearance of a layer's graduated color symbology. Layer symbology can be applied to layers in a map document or layer file. Properties on this object enable you to get and set the class break values, labels, number of classes, field used to create the symbology, description, and normalization. The only method on this object is reclassify(), which resets the layer's symbology. For access to a more complete set of symbology properties and settings, you would need to make the changes in ArcMap, save the changes to a layer file, and then use the UpdateLayer() function in ArcPy mapping.
The GraduatedSymbolsSymbology class is similar to GraduatedColorSymbology but deals with graduated symbols instead of graduated colors. Like GraduatedColorSymbology, this object also provides access to a limited set of properties that you can use to change how graduated symbols are symbolized. The properties and methods are the same as described on the GraduatedColorsSymbology class.
RasterClassifiedSymbology allows limited access to properties that can be used to change the symbology of a raster layer. This object is similar to the GraduatedColorsSymbology and GraduatedSymbolsSymbology objects we discussed earlier, in which it provides access to only a limited set of properties such as the class break values, labels, descriptions, number of classes, the value field, and others.
This class provides access to properties that can be used to control a layer's unique value symbology. This class is similar to the other symbology objects we have already discussed, in which it exposes a limited number of properties for controlling things such as the field used for the values, labels, descriptions, and others.
The ArcPy mapping functions can be divided into sections that control the export and printing of maps and managing map documents and layers.
There are a handful of functions related to exporting maps to various image file formats. These include ExportToAI(), ExportToBMP(), ExportToEMF(), ExportToEPS(), ExportToGIF(), ExportToJPEG(), ExportToPNG(), ExportToSVG(), and ExportToTIFF(). Each of the functions accepts somewhat different parameters, but all will by default export the layout view in ArcMap to an image file. Instead of exporting the layout view, you can also elect to export a specific data frame by passing a reference as a parameter to the function.
Yet another export function is the ExportToPDF() function that can be used to export either the layout view or a data frame to a PDF file. As we'll discuss later in this section, there are also two additional functions that can be used to work with pdf files.
There are two functions related to printing the layout view or a specific data frame. The ListPrinterNames() function gathers a list of the available printers to the computer where the script is running. Using the list returned, you can then pass a specific printer to the PrintMap() function to print either the layout view or a specific data frame to a printer. If you don't pass a printer name to the PrintMap() function, it will attempt to find a printer saved with the map document or the default system printer if a printer hasn't been saved with the map document.
There is one additional function in this category that is used to export reports. This is the ExportReport() function, which exports a formatted, tabular report using data in the map document file. It uses a report template file that has been previously created.
There is a wide range of functions to manage map documents and layers. Various function types, including managing layers and tables, working with pdf files, working with ArcGIS Server services, generating lists, and working with ArcGIS Server are available.
A handful of list functions can be used to generate lists of bookmarks, data frames, broken data sources, layers, layout elements, map services, style items, and table views. These functions each return a Python list of data that can also be filtered in various ways. For example, the ListLayers() function accepts two optional parameters including a wildcard and data frame that can be used to restrict the list of layers that is returned. By default, all layers in the map document or layer file are returned, but it is often necessary to limit the returned objects. All the list functions contain similar optional parameters that can be used to limit the returned list.
Layers and tables can be added, removed, and updated. You can add layers to a map document or group layer using either AddLayer() or AddLayerToGroup(). In addition, the InsertLayer() function can be used to add a layer to a map document or group layer with more precision. It uses a reference layer to precisely define the location of the layer to be added. The MoveLayer() function, which is used to move a layer to a new location within a specific data frame , also uses a reference layer. Standalone tables can be added or removed from a map document using AddTableView() or RemoveTableView(). The symbology and properties of a layer can be updated through the UpdateLayer() method. There is also an UpdateLayerTime() function that can be used to update the properties of a time-enabled layer.
In the previous section, the ExportToPDF() function was introduced. There are two additional functions related to working with pdf files including PDFDocumentCreate() and PDFDocumentOpen(). Both are commonly used in the creation of map books. PDFDocumentCreate(), as its name suggests, is used to create new pdf files, whereas PDFDocumentOpen() can be used to open an existing pdf file. Both return an instance of the PDFDocument class.
Map documents can be published to ArcGIS Server as services. The ArcPy mapping module provides several functions related to this conversion and publication process. Before a map document can be published as a service, it must go through a conversion process. The first step in the process is to create a Service Definition Draft file (SDDraft). This can be accomplished with the CreateMapSDDraft() function. This function also returns a Python dictionary containing errors, warnings, and information messages. Any errors must be resolved before publication. This can also be accomplished with the AnalyzeForSD() function. After any errors have been resolved, there are two geoprocessing tools that you can use to publish the file as a service.
Other functions related to working with ArcGIS Server include ConvertWebMapToMapDocument(), which can be used to convert a web map in JSON format to a map document. In addition, the CreateGISServerConnectionFile() function creates a connection file for accessing ArcGIS Server.
There are also some deprecated functions that you shouldn't use but that are still technically part of the module including AnalyzeForMSD(), ConvertToMSD(), DeleteMapService(), ListMapServices(), and PublishMSDToServer(). These functions have either been replaced by new functions or tools, or are now provided through the ArcGIS REST API.