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 such as 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 such as 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 map files (.mapx), layout files (.pagx), or report files (.rptx) into an existing project.

The activeMap property will return the map associated with either an active map view or the active map frame on an active layout view. 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. Both of these properties are intended for scripts to be executed in the application, such as scripts run in the Python pane or those associated with a script tool. 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.

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 executed 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 executed 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.	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
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.
importDocument (document_path, {include_layout}, {reuse_existing_maps})	Imports map (.mxd), globe (.3dd), and scene (.sxd) documents into an ArcGIS Pro project. It also imports 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})	Replaces connection properties using a dictionary or a path to a workspace.

Methods

closeViews ({view_type})

Parameter	Explanation	Data Type
view_type	A constant that determines the type of views to be closed in the application. LAYOUTS—Close all open layout view panes. MAPS—Close all open map view panes. MAPS_AND_LAYOUTS—Close all open layout and map view panes. (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 or a map. 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.

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 (.mxd, .3dd, or .sxd) document 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	By default, importing a layout file (.pagx) copies all the maps referenced by the layout. If the maps already exist in the project, you can set reuse_existing_maps to True, which checks the project for the maps referenced in the layout file, and only copies maps that don't exist in the project. This avoids duplicating maps within the project. This parameter is ignored for other file types. (The default value is False)	Boolean

This method imports one document at a time. 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 Type	Explanation
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})

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

Return Value

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

Return Value

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

Return Value

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

Return Value

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.	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
ignore_case	Determines whether searches will be case sensitive or not. By default, queries are case sensitive. To perform case-insensitive queries, set ignore_case to True. (The default value is False)	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.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")

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(f"  {lyt.name} ({lyt.pageHeight} x {lyt.pageWidth} {lyt.pageUnits})")