Referencing the current map document

When running a geoprocessing script from the ArcGIS Python window or a custom script tool, you will often need to make a reference to the map document which is currently loaded in ArcMap. This is typically the first step in your script before you perform geoprocessing operations against layers and tables in a map document. In this recipe, you will learn how to reference the current map document from your Python geoprocessing script.

Getting ready

Before you can actually perform any operations on a map document file, you need to make a reference to it in your Python script. This is done by calling the MapDocument() method on the arcpy.mapping module. You can reference either the currently running document or a document at a specific location on disk. To reference the currently active document, you simply supply the keyword CURRENT as a parameter to the MapDocument() function. This loads the currently active document in ArcMap. The following code example shows how a reference to the current active document is obtained:

mxd = mapping.MapDocument("CURRENT")

Note

You can only use the CURRENT keyword when running a script from the ArcGIS Python window or a custom script tool in ArcToolbox. If you attempt to use this keyword when running a script from IDLE or any other development environment, it won't have access to the map document file that is currently loaded in ArcGIS. I should also point out that the CURRENT keyword is not case sensitive. You could just as easily use "current".

To reference a map document on a local or remote drive, simply supply the path to the map document as well as the map document name as a parameter to MapDocument(). For example, you would reference the crime.mxd file in the c:\data folder with the following reference: arcpy.mapping.MapDocument("C:/data/crime.mxd").

How to do it…

Follow these steps to learn how to access the currently active map document in ArcMap:

1. Open c:\ArcpyBook\Ch2\Crime_Ch2.mxd with ArcMap.
2. Click on the Python window button located on the main ArcMap toolbar.
3. Import the arcpy.mapping module by typing the following into the Python window. Here, and in future recipes, we'll assign the arcpy.mapping module to a variable called mapping. This will make your code easier to read and cut down on the amount of code you have to write. Instead of having to prefix all your code with arcpy.mapping, you can just refer to it as mapping. It is not required that you follow this form, but it does make your code cleaner and faster to write. Furthermore, you can name the variable as you wish. For example, instead of calling it mapping you may call it MAP or mp or whatever makes sense.

   import arcpy.mapping as mapping

4. Reference the currently active document (Crime_Ch2.mxd) and assign the reference to a variable by typing the following into the Python Window below the first line of code that you added in the last step:

   mxd = mapping.MapDocument("CURRENT")

5. Set a title for map document:

   mxd.title = "Crime Project"

6. Save a copy of the map document file with the saveACopy() method:

   mxd.saveACopy("c:/ArcpyBook/Ch2/crime_copy.mxd")

7. Navigate to File | Map Document Properties, in order to view the new title you gave to the map document.
8. You can check your work by examining the c:\ArcpyBook\code\Ch2\ReferenceCurrentMapDocument.py solution file.

How it works…

The MapDocument class has a constructor that creates an instance of this class. In object-oriented programming, an instance is also known as an object. The constructor for MapDocument can accept either the CURRENT keyword or a path to a map document file on a local or remote drive. The constructor creates an object and assigns it to the variable mxd. You can then access the properties and methods available on this object using dot notation. In this particular case, we printed out the title of the map document file using the MapDocument.title property and we also used the MapDocument.saveACopy() method to save a copy of the map document file.