ListLayers (arcpy.mapping)

Summary

Returns a Python list of Layer objects that exist within a map document (.mxd), a data frame within a map document, or layers within a layer (.lyr) file.

Discussion

ListLayers always returns a Python list object even if only one layer is returned. In order to return a Layer object, an index value must be used on the list (e.g., lyr = arcpy.mapping.ListLayers(mxd)[0]). For loops on a list provide an easy mechanism to iterate through each item in a list (e.g., for lyr in arcpy.mapping.ListLayers(mxd):).

When working with layer files, the data_frame parameter should not be used because layer files don't support data frames; if it is, it will be ignored. The Layer() function is for referencing layer (.lyr) files stored on disk.

Group layers are treated just like layers. The index values are simply generated from top to bottom as they appear in the table of contents or the way they would appear in a layer file. The same applies if a group layer is within another group layer. A map document with a single group layer with three layers within it will return a Python list of four layer objects, the group layer being the first. One way of determining if a layer is inside a group layer is to interrogate the longName property. A layer's longName will include the group layer name as part of the name.

Wildcards are used on the name property and are not case sensitive. A wildcard string of "so*" will return a layer with the name Soils. Wildcards can be skipped in the scripting syntax simply by passing an empty string (""), an asterisk (*), or entering wildcard=None, or nothing at all if it is the last optional parameter in the syntax.

It is possible that there might be layers in a map document or layer file that have the same name. If that is the case, then other properties may need to be used to isolate a specific layer. Properties such as a layer's description or a layer's dataSource could be used to do this. It is ideal that all layers in a map document or at least in a layer be uniquely named.

Syntax

ListLayers (map_document_or_layer, {wildcard}, {data_frame})

Parameter	Explanation	Data Type
map_document_or_layer	A variable that references a MapDocument or Layer object.	Object
wildcard	A combination of asterisks (*) and characters can be used to help limit the results. (The default value is None)	String
data_frame	A variable that references a DataFrame object. (The default value is None)	DataFrame

Return Value

Data Type	Explanation
Layer	A Python list of Layer objects.

Code Sample

ListLayers example 1:

This script will print the name of the first layer in a data frame named Traffic Analysis. The wildcard parameter is skipped using a blank string.

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "Traffic Analysis")[0]
print arcpy.mapping.ListLayers(mxd, "", df)[0].name
del mxd

ListLayers example 2:

The following script will find a layer called Lakes in a data frame named County Maps, turn the layer on (to be visible) and set the transparency to 50%. An issue is that there happens to be two layers with the same name in the same data frame so the description property is used to further isolate the layer of interest. Ideally, all layers would have a unique name but that isn't always the case so other properties have to be used to isolate the layer of interest. In this example, the description is used.

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "County Maps")[0]
for lyr in arcpy.mapping.ListLayers(mxd, "Lakes", df):
    if lyr.description == "USGS Lakes":
        lyr.visible = True
        lyr.transparency = 50
mxd.save()
del mxd