Summary
The ArcGISProject object 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 navigate to a number of objects using list functions. For example, you can get access to maps using the listMaps method. When you have a reference to a Map, you can reference Layer or Table objects using list functions. From these objects, you can gain further access to other objects such as LabelClass. You can also drill into layouts using the listLayouts method. After you reference a Layout, you can access layout elements such as GraphicElement, LegendElement, MapFrame, MapSurroundElement, pictureElement, and TextElement. The ArcGISProject object is also useful for managing project settings such as defaultGeodatabase and defaultToolbox.
The following diagram illustrates the utility of list functions for navigating and referencing the objects within a project, or a layer file. The diagram is only an example and does not display a complete set of objects. For example, it does not show listReports for access to the components of a Report object.
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 map files (.mapx), layout files (.pagx), or report files (.rptx) into an existing project.
There are a few methods and properties that only work with scripts that are run inside the application such as scripts run in the Python pane or those associated with a script tool. These are activeMap, activeView properties, and the closeViews() method. The activeMap property will return the map associated with either an active map view or the active map frame on an active layout view. If these conditions are not met, a NoneType will be returned. The activeView property will either return a MapView object if a map view is active or it will return a Layout object if a layout view is active. If no views are active, both properties will return None. These properties 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. The MapView returned from the activeView property is the only way to change the extent associated with a map view. There are multiple functions available on the MapView class that allow you to change the extent, such as the camera property, panToExtent, ZoomToAllLayers, and ZoomToBookmarks. The closeViews function is useful for closing specific view types within the application. To give focus to a specific view, it makes sense to close all views and use the openView method on the Layout, Map, or Report class.
The ArcGISProject class also supports several content management methods. These are createMap, copyItem, and deleteItem. The createMap method allows you to create a default map. The copyItem and deleteItem methods are limited to the Layout, Map, and Report classes.
Properties
| Property | Explanation | Data Type |
| activeMap (Read Only) | Returns the map object associated with the focused view within the application. If a layout view is active, it will return the map associated with the active map frame. Note:This property is designed to be run from within the application using a script tool or the Python window. If a script is run outside of the application, None will always be returned. | Map |
| activeView (Read Only) | Returns a MapView or a Layout, depending on the current view. If the ArcGIS Pro project has no open views, or if the active view is something other than a map view or layout view (for example, a chart, table, Model Builder view, and so on), None will be returned. Note:This property is designed to be run from within the application using a script tool or the Python window. If a script is run outside of the application, None will always be returned. | Object |
| 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. Note: this property can be set as read-only by an Administrator and therefore it can't be modified. | String |
| defaultToolbox (Read and Write) | The project's default toolbox location. The string must include the toolbox's full path and file name. Note: this property can be set as read-only by an Administrator and therefore it can't be modified. | String |
| documentVersion (Read Only) | Returns the version of the document based on when it was last saved. Running 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 |
| folderConnections (Read Only) | Returns a list of Python dictionaries, each representing the properties for individual folder connections in a project. This is a read-only property. Review the updateFolderConnections method for more information about the dictionaries and how to modify the list of connection properties. | List |
| homeFolder (Read and Write) | The project's home folder location. The string must include the full path to the desired location. Note: this property can be set as read-only by an Administrator and therefore it can't be modified. | String |
| isReadOnly (Read Only) | Returns True if a project has already been opened in another instance of the application or referenced by another script. Knowing the current state allows you to determine whether you can save the project, for example, or if you need to call saveACopy instead. | Boolean |
| metadata (Read and Write) | Get or set the project's Metadata class information. Note: setting metadata is dependent on the isReadOnly property value. | Metadata |
Method Overview
| Method | Explanation |
| closeViews ({view_type}) | Close view panes that are currently open in ArcGIS Pro. |
| copyItem (project_item, {new_name}) |
Creates a copy of an existing layout, map, or report project item. |
| createMap ({name}, {map_type}) | This method creates a map that will automatically get added to the Catalog pane. |
| deleteItem (project_item) | |
| importDocument (document_path, {include_layout}, {reuse_existing_maps}) | Imports map (.mxd), globe (.3dd), and scene (.sxd) documents into an ArcGIS Pro project. It can also be used to import the contents of map files (.mapx), layout files (.pagx), and report files (.rptx). |
| 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). |
| listReports ({wildcard}) | Returns a Python list of Report 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}, {ignore_case}) | The updateConnectionProperties method replaces connection properties using a dictionary or a path to a workspace. |
| updateFolderConnections (folder_connections, {validate}) | Replaces project folder connections using a list of dictionaries that describe each connection. |
Methods
closeViews ({view_type})| Parameter | Explanation | Data Type |
view_type | A constant that determines the type of views to be closed in the application.
(The default value is MAPS_AND_LAYOUTS) | String |
Sometimes it is useful to clean up numerous open views in the application before opening a specific view to see the resulting view with better focus. The method is limited to closing only view panes associated with a layout, map, or a report. This method will also close table views associated with a "MAP".
Note:
This method is designed to be executed from within the application using a script tool, Notebook, or the Python window. It will have no effect if executed outside of the application.
copyItem (project_item, {new_name})| Parameter | Explanation | Data Type |
project_item | An object that represents a supported project item to be copied. | Object |
new_name | A string that represents the name of the new project item. If a name is not provided, the default name will follow the sequencing nomenclature, for example, Map, Map1, Map2. | String |
| Data Type | Explanation |
| Object | If a variable reference is specified, it will represent either a layout, map, or report project item. |
This method is appropriate if you want to modify a copy of an existing project item without making changes to the original item. You can copy a layout, a map, or a report project item. It is especially useful for layouts and reports, since there are no functions available to create those project item types.
createMap ({name}, {map_type})| Parameter | Explanation | Data Type |
name | A string that represents the name of the new map. If a name is not provided, the default name will follow the sequencing nomenclature, for example, Map, Map1, Map2. | String |
map_type | The type of map to be created and are defined by the keywords below.
(The default value is Map) | String |
| Data Type | Explanation |
| Map | If a variable reference is specified, it will represent one of the supported map_type objects. |
This method returns a reference to a new map class. If the script is run within the application, the basemap specified in the project settings will get applied. If the script is run stand-alone, the Topographic basemap will automatically get added.
deleteItem (project_item)
| Parameter | Explanation | Data Type |
project_item | An object that represents a supported project item to be deleted. | Object |
The item is permanently deleted from the project. Deleting an item may have an impact on other items. For example, if you delete a map that is used in a layout, the MapFrame that references the map will also lose the reference to the map and the map property will be set to None.
importDocument (document_path, {include_layout}, {reuse_existing_maps})| Parameter | Explanation | Data Type |
document_path | A string that includes the system path and name of a document (.mxd, .3dd, or .sxd) or a map file (.mapx), layout file ( .pagx), or report file (.rptx). | String |
include_layout | A Boolean parameter indicating whether 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 other file types. (The default value is True) | Boolean |
reuse_existing_maps | A Boolean parameter to prevent the creation of duplicate maps in the project. If reuse_existing_maps is set to True, it checks the project for the maps referenced in the imported file and only copies maps that don't already exist in the project. There may be cases in which maps have the same name in different imported sources, so you may want to set this value to False. (The default value is False) | Boolean |
| Data Type | Explanation |
| Map | When importing a map document (.mxd), if include_layout is True, it returns a reference to the layout. If include_layout is False, it returns the first map in the map document. It returns the only single map found in a globe (.3dd) or scene (.sxd) document. The corresponding layout is returned with a .pagx file and report with an .rptx file. |
This method imports one document at a time. To import multiple documents, run the method once for each document. A map document (.mxd) always has a layout. While migrating map documents, if you do not want to import the layout, set include_layout=False.
listBrokenDataSources ()
| Data Type | Explanation |
| List |
The listBrokenDataSources method always returns a Python list object even if only one broken layer or table is returned.
listColorRamps ({wildcard})| Parameter | Explanation | Data 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 |
| Data Type | Explanation |
| 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})| Parameter | Explanation | Data 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 |
| Data Type | Explanation |
| 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})| Parameter | Explanation | Data 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 |
| Data Type | Explanation |
| List | A Python list of Map objects in an ArcGIS project. |
Returns a Python list of Map objects in an ArcGIS project (.aprx).
listReports ({wildcard})| Parameter | Explanation | Data Type |
wildcard | A wildcard is based on the report 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 |
| Data Type | Explanation |
| List | A Python list of Report objects in an ArcGIS project. |
Returns a Python list of Report 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)
| Parameter | Explanation | Data 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}, {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. If an empty string or None is used in current_connection_info, all connection properties will be replaced with the new_workspace_info, depending on the value of the validate parameter. | 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 value, regardless of a valid match. In this case, if a match does not exist, the data sources would be broken. (The default value is True) | Boolean |
ignore_case | Determines whether searches will be case sensitive. By default, queries are case sensitive. To perform queries that are not case sensitive, set ignore_case to True. (The default value is False) | Boolean |
For more detailed discussion, parameter information, scenarios, and code samples, see Updating and fixing data sources.
updateFolderConnections (folder_connections, {validate})| Parameter | Explanation | Data Type |
folder_connections [folder_connections,...] | A list of Python dictionaries that each contain connection properties to an individual folder. The dictionary keys are defined below.
| List |
validate | If set to True, the folder will only be added if the connectionString is a valid path. If it is not valid, the folder will not be added and the function will return the dictionary as an invalid folder. If set to False, the method will set all connections to match the connectionString, regardless of a valid match. In this case, if a match does not exist, the folder will be added but will appear as broken. (The default value is True) | Boolean |
| Data Type | Explanation |
| List | A list of folders that do not have valid connections. |
To update a project's folder connections, you must set the entire list of connections at once. You cannot add, remove, or update a single folder connection at a time. You can either build a new list from scratch or you can modify the list returned by the folderConnections property and then push the entire list back to the project using the updateFolderConnections method.
Code sample
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.defaultGeodatabase = 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")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(f" {lyt.name} ({lyt.pageHeight} x {lyt.pageWidth} {lyt.pageUnits})")The following script uses the keyword current, so it should be run from the Python window. The script copies an existing map, adds a new layer to it, sets the map's default camera property that controls the extent of newly opened views, exports the map view to PDF, and removes the newly created map from the project.
aprx = arcpy.mp.ArcGISProject("CURRENT")
#Create a copy of an existing map
existingMap = aprx.listMaps("Yosemite National Park")[0]
rangerMap = aprx.copyItem(existingMap, new_name="Ranger Stations")
#Add ranger stations layer file
lyrx = arcpy.mp.LayerFile(r"C:\Projects\YosemiteNP\LayerFiles\Ranger Stations.lyrx")
rangerMap.addLayer(lyrx)
#Close any current layout or map views
aprx.closeViews("MAPS_AND_LAYOUTS")
#Set the default map camera to the extent of the park boundary before opening the new view
#default camera only affects newly opened views
lyr = rangerMap.listLayers("*Park Boundary")[1]
rangerMap.defaultCamera.setExtent(arcpy.Describe(lyr).extent)
rangerMap.openView()
#export the newly opened active view to PDF, then delete the new map
mv = aprx.activeView
mv.exportToPDF(r"C:\Temp\RangerStations.pdf", width=700, height=500, resolution=96)
aprx.deleteItem(rangerMap)