Skip To Content

ArcGISProject

Summary

Provides access to ArcGIS Pro project methods and properties. A reference to this object is essential for most map automation workflows.

Discussion

The ArcGISProject object provides access to many of the project properties and methods found in the ArcGIS Pro application. The ArcGISProject object is usually one of the first object references created in a map automation script because it is the main entry point for access to almost all other ArcGIS project objects.

Once you have a reference to the ArcGISProject object, you can get access to maps using the listMaps method or access to layouts using the listLayouts method. When you have a reference to a Map object, you can get to Layer or Table objects, or once you have access to a Layout object, you can get to layout elements like GraphicElement, LegendElement, MapFrame, MapSurroundElement, pictureElement, and TextElement. From these objects you can gain access to other objects in the project. The ArcGISProject object is also useful for managing project settings like defaultGeodatabase and defaultToolbox.

The importDocument method allows you to import map (.mxd), globe (.3dd), and scene (.sxd) documents into a project. This provides a mechanism for automating the conversion of these document types into the ArcGIS Pro project. The importDocument method also allows you to import.mapx and .pagx files into an existing project.

The activeMap property is intended for scripts executed within the application, such as scripts run in the Python pane or associated with a script tool that uses validation scripts that provide information based on the active view. For example, if a map view is open, it will return the associated map. If a layout view is open, it will return the map associated with the active map frame on the layout. This property will always return a None value when a script is run outside of the application, because views are only relevant when the application is open.

Properties

PropertyExplanationData Type
activeMap
(Read Only)

Returns the map object associated with the focused view within the application.None will be returned if there are no views open that have an associated map or when a script is run outside of the application.

Map
dateSaved
(Read Only)

Returns a Python datetime object that reports the project's last saved date.

DateTime
defaultGeodatabase
(Read and Write)

The project's default geodatabase location. The string must include the geodatabase's full path and file name.

String
defaultToolbox
(Read and Write)

The project's default toolbox location. The string must include the toolbox's full path and file name.

String
documentVersion
(Read Only)

Returns the version of the document based on when it was last saved. Executing save or saveACopy will update the document version to match the application version.

String
filePath
(Read Only)

Returns a string value that reports the fully qualified project path and file name.

String
homeFolder
(Read and Write)

The project's home folder location. The string must include the full path to the desired location.

String

Method Overview

MethodExplanation
importDocument (document_path, {include_layout})

Imports map (.mxd), globe (.3dd) and scene (.sxd) documents into an ArcGIS Pro project.

listBrokenDataSources ()

Returns a Python list of Layer and/or Table objects that have broken connections to their original source data for all maps in a project.

listColorRamps ({wildcard})

The listColorRamps method references color ramps available in a project.

listLayouts ({wildcard})

Returns a Python list of Layout objects in an ArcGIS project (.aprx).

listMaps ({wildcard})

Returns a Python list of Map objects in an ArcGIS project (.aprx).

save ()

Saves changes to an ArcGISProject (.aprx).

saveACopy (file_name)

Saves an ArcGISProject (.aprx) to a new file path or name.

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

Replaces connection properties using a dictionary or a path to a workspace.

Methods

importDocument (document_path, {include_layout})
ParameterExplanationData Type
document_path

A string that includes the system path and name of a (.mxd, .3dd, or .sxd) document to import.

String
include_layout

A Boolean indicating if the layout from a map document (.mxd) is imported. If set to True, the layout and all data frames are imported. If set to False, only the data frames are imported. This parameter is ignored for globe (.3dd) and scene (.sxd) documents.

(The default value is True)

Boolean

This method imports one document at a time. If you want to import multiple documents, execute the method once for each document. A map document (.mxd) always has a layout. While migrating map documents, you may not always want to import the layout. If that is the case, set include_layout=False.

listBrokenDataSources ()
Return Value
Data TypeExplanation
List

A Python list of Layer and/or Table objects.

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

listColorRamps ({wildcard})
ParameterExplanationData Type
wildcard

A wildcard is based on the color ramp name as it appears in the application. A combination of asterisks (*) and characters can be used to help limit the resulting list.

(The default value is None)

String
Return Value
Data TypeExplanation
List

Returns a list of ColorRamp objects.

It is possible to have multiple color ramps in a project with the same name. It is important that you author your project with color ramp names that can be easily searched using a unique name. An index number can be used to return a specific color ramp. For example, the following line will return the first color ramp object in the list: cr = aprx.listColorRamps("Black*")[0].

listLayouts ({wildcard})
ParameterExplanationData Type
wildcard

A wildcard is based on the layout 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 TypeExplanation
List

A Python list of Layout objects in an ArcGIS project.

Returns a Python list of Layout objects in an ArcGIS project (.aprx).

listMaps ({wildcard})
ParameterExplanationData Type
wildcard

A wildcard is based on the map 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 TypeExplanation
List

A Python list of Map objects in an ArcGIS project.

Returns a Python list of Map objects in an ArcGIS project (.aprx).

save ()

Saves changes to an ArcGISProject (.aprx). The project is saved and the project variable continues to reference the original ArcGISProjectobject.

saveACopy (file_name)
ParameterExplanationData Type
file_name

A string used to save an ArcGISProject (.aprx) to a new file path or file name.

String

The method creates a new output project file, but the project variable continues to reference the original ArcGISProject object. It does not duplicate all the content within a project folder.

updateConnectionProperties (current_connection_info, new_connection_info, {auto_update_joins_and_relates}, {validate})
ParameterExplanationData 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

For more detailed discussion, parameter information, scenarios, and code samples, refer to the Updating And Fixing Data Sources help topic.

Code sample

ArcGISProject example 1

The following script demonstrates how to import documents into an existing ArcGIS Pro project. It also sets up some of the default project settings and saves the result to a new file.

import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\blank.aprx")
aprx.importDocument(r"C:\Projects\YosemiteNP\Documents\Yosemite.mxd")
aprx.importDocument(r"C:\Projects\YosemiteNP\Documents\Yosemite_ScenicViews.3dd")
aprx.defaultToolGeoDatabase = r"C:\Projects\YosemiteNP\Data_Vector\YosemiteData.gdb"
aprx.defaultToolbox = r"C:\Projects\YosemiteNP\Analysis\AnalysisTools.tbx"
aprx.saveACopy(r"C:\Projects\YosemiteNP\Yosemite.aprx")
ArcGISProject example 2

The following script uses the keyword current, so it should be run from the Python window. The script prints the name of each map in a project and its layers, as well as the name of each layout and its page size.

aprx = arcpy.mp.ArcGISProject("CURRENT")
for m in aprx.listMaps():
    print("Map: " + m.name)
    for lyr in m.listLayers():
        print("  " + lyr.name)
print "Layouts:"
for lyt in aprx.listLayouts():
    print("  {0} ({1} x {2} {3})".format(lyt.name, lyt.pageHeight, lyt.pageWidth, lyt.pageUnits))