Arcpy.mp is a Python submodule that is part of the ArcPy site package. It is installed with ArcGIS AllSource and is available to all licenses. It was designed primarily to manipulate the contents of existing projects (.aprx) and layer files (.lyrx). You can automate the contents of projects without even having to open the application. In some cases it provides capabilities that are not available to ArcGIS AllSource, for example, arcpy.mp is required to build complete map books because it includes functions to export to, create, and manage PDF documents.
It is easier to understand the capabilities of arcpy.mp by describing some scenarios it facilitates. The following are some of the many workflows that an arcpy.mp Python script can help you accomplish:
- Automate exporting Layouts, Map Views, Map Series and Reports
- Build a variety of PDF map books, for example, a reference map book or a thematic map book with title page, multiple map pages, and any number of additional pages with supporting content, such as tabular reports and contact lists.
- Manipulate elements on a layout such as updating a picture, a company logo, or update text strings and so much more.
- Extend geoprocessing script tools to work directly with maps, layouts, and other project elements.
- Inventory scripts that log information about projects, data, broken data sources, folder connections, and more.
- Update, repair, or replace layer data sources.
- Manage project items such as layouts, maps, reports, folder connections, views, and more.
- Modify a layer's symbology.
- Automate sharing project items to be hosted in your organization online.
Intended audience and purpose
Arcpy.mp was built for the professional GIS analyst and for developers. Traditionally, the scenarios listed above had to be performed using the .NET SDK, and it often proved to be a difficult programming environment to learn for the average GIS professional. Arcpy.mp is a coarser-grained object model, meaning that the functions are designed in a way that a single function can replace many lines of finer-grained .NET code. The following is a simple example of how arcpy.mp can be used to reference an existing layout in a project and export it to a PDF document with only four lines of code:
import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")
lyt = aprx.listLayouts("Main Attractions*")[0]
lyt.exportToPDF(r"C:\Project\YosemiteNP\Output\Yosemite.pdf", resolution=300)The first line loads the arcpy module and is required for all scripts that are run external to ArcGIS AllSource. The second line references an ArcGIS AllSource project on disk. The third line finds the first layout (using a zero-based index) with a name that begins with the words Main Attractions. The last line of code exports the layout to PDF with an output resolution of 300.
Tips to get started
The best ways to get started include the following:
- Try the Getting started with arcpy.mp tutorial.
- Review Guidelines for arcpy.mp.
- If you used arcpy.mapping in earlier versions of the software and are now using ArcGIS AllSource, review Migrating from arcpy.mapping to ArcGIS Pro.
- Review Alphabetical list of arcpy.mp functions and Alphabetical list of arcpy.mp classes to familiarize yourself with the functionality that is available. These are also helpful printouts to have available when scripting with arcpy.mp.
- All arcpy.mp functions and class help topics have detailed explanations and contain sample snippets of code that can be copied and pasted directly into the Python window.
Beyond the basics
The existing arcpy.mp API can perform some incredible capabilities but also understand that it is not as extensive as the .NET SDK. If there is something you need to accomplish that isn't in the API, it doesn't mean it can't be done. The API has also been designed to allow access to the internal components that persist everything that is saved in a project or layer file. For more information, refer to the Python CIM Access help topic.
Visit the Python Map Automation sample scripts site, where more advanced solutions are available for download.