UpdateLayer (arcpy.mapping)

Summary

Provides the ability to update all layer properties or just the symbology for a layer in a map document (.mxd) by extracting the information from a source layer.

Discussion

The arcpy.mapping API only provides access to a limited number of layer properties that can be directly modified but all properties found in the Layer Properties dialog box can be modified using the UpdateLayer function. The information is extracted from a source layer and applied to the layer in a map document that needs to be updated. The source_layer can either be a layer (.lyr) file or a layer within a map document. UpdateLayer is a robust function because it can be used in several different ways to produce different results.

One option is to update only a layer's symbology. In this case, the update_layer and source_layer must have similar geometry types. Depending on the renderer (for example, unique value using a particular attribute), the attribute definitions also need to be the same. Updating symbology only is the default behavior.

Another option is to update ALL layer properties, including symbology (symbology_only=False). For example, you may want to update the field aliases, selection symbology, query definitions, and so on, for a layer that exists in many map documents. An easy way of doing this is to use ArcMap to modify the layer with the appropriate properties and then save the layer out to a layer (.lyr) file. The layer file can then be used as a source_layer to update all the properties for a given layer. Use care when updating all properties and make sure they are not properties that you don't want overwritten.

UpdateLayer is also capable of switching out completely unrelated layers. For example, you could replace a polygon layer with a raster layer or a group layer. This capability is only possible if the symbology_only value is set to False; otherwise, you might have conflicts with attributes and/or geometry types. UpdateLayer, when not restricted to symbology, is essentially calling the RemoveLayer and AddLayer functions.

If you want to update the properties for a layer within a layer file, you must modify the properties of the layer in a map document first and then save the changes back to a layer file. See the Layer object's save or saveACopy methods.

If you are only interested in updating a layer's time properties, see UpdateLayerTime.

Syntax

UpdateLayer (data_frame, update_layer, source_layer, {symbology_only})

Parameter	Explanation	Data Type
data_frame	A reference to a DataFrame object that contains the layer to be updated.	DataFrame
update_layer	A Layer object representing an existing layer that will be updated.	Layer
source_layer	A reference to a Layer object that contains the information to be applied to the update_layer.	Layer
symbology_only	A Boolean that determines whether or not to update only the layer's symbology, or all other properties as well. If set to True, only the layer's symbology will be updated. (The default value is True)	Boolean

Code Sample

UpdateLayer example 1

The following script will update a layer's symbology only using a layer file. The layer is called Rivers and is in a data frame called County Maps.

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "County Maps")[0]
updateLayer = arcpy.mapping.ListLayers(mxd, "Rivers", df)[0]
sourceLayer = arcpy.mapping.Layer(r"C:\Project\Data\Rivers.lyr")
arcpy.mapping.UpdateLayer(df, updateLayer, sourceLayer, True)
mxd.saveACopy(r"C:\Project\Project2.mxd")
del mxd, sourceLayer

UpdateLayer example 2

The following script will completely replace a layer called Rivers with a group layer from another map document which displays different river feature classes at different scales.

import arcpy

#Reference layer in secondary map document
mxd2 = arcpy.mapping.MapDocument(r"C:\Project\ProjectTemplate.mxd")
df2 = arcpy.mapping.ListDataFrames(mxd2, "Layers")[0]
sourceLayer = arcpy.mapping.ListLayers(mxd2, "Rivers Group Layer", df2)[0]

#Update layer in primary map document
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "County Maps")[0]
updateLayer = arcpy.mapping.ListLayers(mxd, "Rivers", df)[0]
arcpy.mapping.UpdateLayer(df, updateLayer, sourceLayer, False)

#Save to a new map document and clear variable references
mxd.saveACopy(r"C:\Project\Project2.mxd")
del mxd, mxd2