Getting ready

arcpy.mapping provides the ability to add layers or group layers into an existing map document file. You can take advantage of the ArcMap "auto-arrange" functionality, which automatically places a layer in the data frame for visibility. This is essentially the same functionality provided by the Add Data button in ArcMap, which positions a layer in the data frame based on geometry type and layer weight rules.

When adding a layer to a map document, the layer must reference an existing layer found in a layer file on disk, the same map document and data frame, the same map document with a different data frame, or a completely separate map document. A layer can be either a layer in a map document or a layer in a .lyr file. To add a layer to a map document, you must first create an instance of the Layer class and then call the AddLayer() function, passing in the new layer along with the data frame where it should be placed and rules for how it is to be positioned.

How to do it…

Follow these steps to learn how to add a layer to a map document:

How it works…

In the first two lines, we simply reference the arcpy.mapping module and get a reference to the currently active map document. Next, we create a new variable called df, which holds a reference to the Crime data frame. This is obtained through the ListDataFrames() function that returns a list of data frame objects. We then use list access to return the first item in the list, which is the Crime data frame. A new Layer instance, called layer is then created from a layer file stored on disk. This layer file is called School_Districts.lyr. Finally, we call the AddLayer() function, passing in the data frame where the layer will reside along with a reference to the layer, and a parameter indicating that we would like to use the auto-arrange feature. In addition to allowing ArcMap to automatically place the layer into the data frame using auto-arrange, you can also specifically place the layer at either the top or bottom of the data frame or a group layer using the BOTTOM or TOP position.

There's more…

In addition to providing the capability of adding a layer to a map document, arcpy.mapping also provides an AddLayerToGroup() function, which can be used to add a layer to a group layer. The layer can be added to the top or bottom of the group layer or you can use auto-arrange for placement. You may also add layers to an empty group layer. However, just as with regular layer objects, group layers cannot be added to a layer file.

Layers can also be removed from a data frame or group layer. RemoveLayer() is the function used to remove a layer or group layer. In the event that two layers have the same name, only the first is removed unless your script is set up to iterate.