LayerFile

Summary

Provides access to layers in a layer file (.lyr or .lyrx) and other basic layer management methods.

Discussion

The LayerFile class provides methods and properties that provide access to individual layers contained in a layer file. Layer files can contain one or many layers and those layers can also include group layers.

The ArcGIS Pro application can read both .lyr or .lyrx layer file types. Changes can only be saved to a .lyrx layer file type. If you are making changes to a .lyr, you must call the saveACopy method.

Properties

Property	Explanation	Data Type
filePath (Read Only)	Returns a string value that reports the fully qualified layer file path and file name.	String
metadata (Read and Write)	Get or set the layer file's Metadata class information. Note, setting metadata is dependent on the isReadOnly property value.	Metadata
version (Read Only)	Returns a string of the version based on when the project was last saved. It uses semantic versioning format: Major.Minor.Patch.	String

Method Overview

Method	Explanation
addLayer (add_layer_or_layerfile, {add_position})	Provides the ability to add a Layer or LayerFile to a layer file (.lyrx) using basic placement options.
addLayerToGroup (target_group_layer, add_layer_or_layerfile, {add_position})	Provides the ability to add a Layer or the contents of a LayerFile to an existing group layer in a layer file (.lyrx) using basic placement options.
insertLayer (reference_layer, insert_layer_or_layerfile, {insert_position})	Provides the ability to add a Layer or LayerFile into a layer file (.lyrx) by specifying a location.
listBrokenDataSources ()	Returns a Python list of Layer objects in a layer file that have broken connections to their original source data.
listLayers ({wildcard})	Returns a Python list of Layer objects in a layer file.
moveLayer (reference_layer, move_layer, {insert_position})	Provides the ability to move a layer or group layer in a layer file to a specific location in the layer stack.
removeLayer (remove_layer)	Provides the ability to remove a layer from a layer file.
save ()	Saves an existing layer file reference to a .lyrx file, even if the file referenced was a .lyr file.
saveACopy (file_name)	Saves a LayerFile to a new path or file name.
updateConnectionProperties (current_connection_info, new_connection_info, {auto_update_joins_and_relates}, {validate}, {ignore_case})	Replaces connection properties using a dictionary or a path to a workspace.

Methods

addLayer (add_layer_or_layerfile, {add_position})

Parameter	Explanation	Data Type
add_layer_or_layerfile	A reference to a Layer or LayerFile object representing the layer or layers to be added.	Layer
add_position	A constant that determines the placement of the added layer or layers in a layer file. AUTO_ARRANGE —Automatically places the layer or layers based on its layer weight rules and geometry. BOTTOM —Places the layer or layers at the bottom of the TOC layer stack. TOP —Places the layer or layers at the top of the TOC layer stack. (The default value is AUTO_ARRANGE)	String

Return Value

Data Type	Explanation
List	A Python list of Layer objects.

The addLayer method provides a way to add a layer or collection of layers to a layer file. The default add_position adds the layers using the same auto-arrange logic that places layers in a map similarly to how the Add Data button works in the application; it places each layer based on layer weight rules and geometry type. The other placement choices are either at the top or the bottom of the layer stack. For more precise layer placement control, refer to the insertLayer method.

The layer that is added can reference an already existing layer in a project or a layer file (.lyr or .lyrx) on disk. A reference to a layer can be a single layer, a group layer with multiple sublayers, or a collection of root-level layers and group layers if referencing a .lyrx file.

The way a layer appears in the table of contents (TOC) after it is added depends on the source layer and how it appears. For example, some layers are completely collapsed and do not display their symbols in the TOC. This setting is built into the layer. If a layer is collapsed, saved to a layer file, and then added to a map, the layer will be collapsed in the new map when added through addLayer.

addLayerToGroup (target_group_layer, add_layer_or_layerfile, {add_position})

Parameter	Explanation	Data Type
target_group_layer	A reference to an existing group Layer object.	Layer
add_layer_or_layerfile	A reference to a Layer or LayerFile object representing the layer or layers to be added.	Layer
add_position	A constant that determines the placement of the added layer or layers in the target_group_layer. AUTO_ARRANGE —Automatically places the layer based on its layer weight rules and geometry. BOTTOM —Places the layer at the bottom of the TOC layer stack. TOP —Places the layer at the top of the TOC layer stack. (The default value is AUTO_ARRANGE)	String

The addLayerToGroup method is the only way to add a layer or collection of layers to an existing, empty group layer in a layer file. The default add_position adds the layers using the same auto-arrange logic that places layers in a map similarly to how the Add Data button works in the application; it places each layer based on layer weight rules and geometry type. The other placement choices are either at the top or the bottom of the layer stack. For more precise layer placement control, refer to the insertLayer method.

The layer that is added can reference an already existing layer in a project or reference a layer file (.lyr or .lyrx) on disk. A reference to a layer can be a single layer, a group layer with multiple sublayers, or a collection of root-level layers and group layers if referencing a .lyrx file.

The way a layer appears in the table of contents (TOC) after it is added depends on the source layer and how it appears. For example, some layers are completely collapsed and do not display their symbols in the TOC. This setting is built into the layer. If a layer is collapsed, saved to a layer file, and then added to a map, the layer will be collapsed in the new map when added through addLayerToGroup.

insertLayer (reference_layer, insert_layer_or_layerfile, {insert_position})

Parameter	Explanation	Data Type
reference_layer	A Layer object representing an existing layer that determines the location where the new layer will be inserted.	Layer
insert_layer_or_layerfile	A reference to a Layer or LayerFile object representing the layer or layers to be added.	Layer
insert_position	A constant that determines the placement of the added layer or layers relative to the reference_layer. AFTER —Inserts the new layer after or below the reference layer. BEFORE —Inserts the new layer before or above the reference layer. (The default value is BEFORE)	String

The insertLayer method is a more precise way of positioning a layer into a layer file because a reference_layer is used to specify the exact location. The layer is either added before or after the reference_layer.

If the reference_layer references a layer at the root level of a layer file, the inserted layer will be added to the root level. If the reference_layer references a layer in a group layer, the inserted layer will be added to the group.

The layer that is inserted can reference an already existing layer in a project or a layer file (.lyr or .lyrx) on disk. A reference to a layer can be a single layer, a group layer with multiple sublayers, or a collection of root-level layers and group layers if referencing a .lyrx file.

The way a layer appears in the table of contents (TOC) after it is added depends on the source layer and how it appears. For example, some layers are completely collapsed and do not display their symbols in the TOC. This setting is built into the layer. If a layer is collapsed, saved to a layer file, and then added to a map, the layer will be collapsed in the new map when added through insertLayer.

listBrokenDataSources ()

Return Value

Data Type	Explanation
List	A Python list of Layer objects.

The listBrokenDataSources method always returns a Python list object even if only one broken layer or table is returned.

listLayers ({wildcard})

Parameter	Explanation	Data Type
wildcard	A wildcard is based on the layer name and is not case sensitive. A combination of asterisks (*) and characters can be used to help limit the resulting list. (The default value is None)	String

Return Value

Data Type	Explanation
List	Returns a Python list of Layer objects in a layer file.

Returns a Python list of Layer objects in a layer file.

moveLayer (reference_layer, move_layer, {insert_position})

Parameter	Explanation	Data Type
reference_layer	A Layer object representing an existing layer that determines the location where the new layer will be moved.	Layer
move_layer	A reference to a Layer object representing the layer to be moved.	Layer
insert_position	A constant that determines the placement of the moved layer relative to the reference layer. AFTER —Moves the layer after or below the reference layer. BEFORE —Moves the layer before or above the reference layer. (The default value is BEFORE)	String

The moveLayer method moves a layer in a layer file. move_layer and reference_layer must reside in the same layer file.

removeLayer (remove_layer)

Parameter	Explanation	Data Type
remove_layer	A reference to a Layer object representing the layer to be removed.	Layer

The removeLayer method removes a single layer or group layer from a specific layer file. If there is more than one layer that meets the criteria, only the first layer is removed unless the script iterates through each layer in a returned list.

save ()

There is a subtle difference between a reference to a layer file (.lyr or .lyrx) and a standard map layer. The save method only works when a variable references a layer file and will not work with a map layer. When a layer is loaded from a layer file it will remember the file name and use that when the save method is called. If a map layer is being referenced, a file name is not initially set, so you will need to use the saveACopy method instead. If a .lyr file type is being referenced and save is called, it will be converted to a.lyrx file type.

saveACopy (file_name)

Parameter	Explanation	Data Type
file_name	A string used to save a LayerFile to a new path or file name. You can only save to .lyrx files.	String

Provides an option to save a LayerFile to a different file name. Newly saved layer files will always be saved to .lyrx files.

updateConnectionProperties (current_connection_info, new_connection_info, {auto_update_joins_and_relates}, {validate}, {ignore_case})

Parameter	Explanation	Data Type
current_connection_info	A string that represents the workspace path or a Python dictionary that contains connection properties to the source you want to update.	String
new_connection_info	A string that represents the workspace path or a Python dictionary that contains connection properties with the new source information.	String
auto_update_joins_and_relates	If set to True, the updateConnectionProperties method will also update the connections for associated joins or relates. (The default value is True)	Boolean
validate	If set to True, the connection properties will only be updated if the new_connection_info value is a valid connection. If it is not valid, the connection will not be replaced. If set to False, the method will set all connections to match the new_connection_info, regardless of a valid match. In this case, if a match does not exist, then the data sources would be broken. (The default value is True)	Boolean
ignore_case	Determines whether searches will be case sensitive or not. By default, queries are case sensitive. To perform case-insensitive queries, set ignore_case to True. (The default value is False)	Boolean

For more detailed discussion, parameter information, scenarios, and code samples, refer to the Updating and fixing data sources help topic.

Code sample

LayerFile example 1

The following script prints the names of the individual layers in a layer file that have broken data sources.

import arcpy
lyrFile = arcpy.mp.LayerFile(r"C:\Projects\YosemiteNP\Yosemite.lyrx")
for lyr in lyrFile.listLayers():
    if lyr.supports("datasource"):
        if lyr.isBroken:
            print(lyr.name)

LayerFile example 2

The following script will remove all layers from a map named Yosemite National Park and add the layers that are in the layer file named Yosemite.lyrx.

import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")
m = aprx.listMaps("Yosemite National Park")[0]
for lyr in m.listLayers():
    m.removeLayer(lyr)
lf = arcpy.mp.LayerFile(r"C:\Projects\YosemiteNP\Yosemite.lyrx")
m.addLayer(lf)
aprx.save()
del aprx