Report—ArcGIS AllSource

Summary

The Report object references a report in an ArcGIS AllSource project (.aprx) file. It provides access to common properties and methods.

Discussion

An ArcGIS AllSource project can contain multiple reports. Reports can be created using the createReport method and are accessed using the listReports method on the ArcGISProject object. The listReports method returns a Python list of Report objects. It is important to uniquely name each report so that a specific report can be easily referenced by its name. Each report has metadata properties that can be viewed or modified. Page information including page units, width, height, and margins can be accessed using the pageInfo property.

The Report object returned using the listReports method also represents the first ReportSection. The referenceDataSource property can be modified using the setReferenceDataSource method. A definitionQuery can be applied to the first report section to filter the rows exported to PDF. The listSections method gives access to all report sections and ReportLayoutSection objects in a report.

Use the exportToPDF method to export the report to a .pdf document.

Properties

Property	Explanation	Data Type
definitionQuery (Read and Write)	The definition query of the first ReportSection. Use this to filter the records exported to PDF.	String
metadata (Read and Write)	Get or set the report's Metadata class information. Note that setting metadata is dependent on the isReadOnly property value.	Metadata
name (Read and Write)	The report's name. It is important that all reports in a project have a unique name so they can be easily referenced by name.	String
pageInfo (Read Only)	The report page width, height, units, and margins. The keys for the dictionary are defined as follows: height—The report's height in page units. width—The report's width in page units. units—The report's page unit keyword. The supported values are inch, point, centimeter, and millimeter. margins—The report's margins keyword. The supported margin values are NORMAL, MODERATE, WIDE, and NARROW.	Dictionary
referenceDataSource (Read Only)	The reference data source connection information of the first ReportSection. The keys for the dictionary are defined as follows: dataset—Dataset name. workspace_factory—Workspace factory type. connection_info— A string that represents the workspace path	Dictionary

Method Overview

Method	Explanation
export (export_format, {report_export_options})	The export method exports a Report using a specified export format and optionally different report_export_options.
exportToPDF (out_pdf, {page_range_type}, {page_range}, {starting_page_number}, {total_page_number}, {resolution}, {image_quality}, {compress_vector_graphics}, {image_compression}, {embed_fonts}, {jpeg_compression_quality})	Exports a report to a Portable Document Format (PDF) file.
getDefinition (cim_version)	Gets a report's CIM definition.
listSections ({wildcard})	Returns a Python list of ReportSection and ReportLayoutSection objects in a report.
openView ()	Opens and activates a new report view pane in the application.
setDefinition (definition_object)	Sets a report's CIM definition.
setReferenceDataSource (data_source)	Sets a report's reference data source.
updatePageInfo (pageInfo)	Updates the report page information.

Methods

export (export_format, {report_export_options})

Parameter	Explanation	Data Type
export_format	The supported export format object is PDFFormat.	Object
report_export_options	The ReportExportOptions object that includes changes to default property values.	Object

Refer to the ReportExportOptions help topic to learn more details and get code samples.

exportToPDF (out_pdf, {page_range_type}, {page_range}, {starting_page_number}, {total_page_number}, {resolution}, {image_quality}, {compress_vector_graphics}, {image_compression}, {embed_fonts}, {jpeg_compression_quality})

Parameter	Explanation	Data Type
out_pdf	A string that represents the path and file name of the output export file.	String
page_range_type	A string that defines the type of page range to export. The default is ALL. ALL—Export all pages of the report. LAST—Export the last page of the report. EVEN—Export the even numbered pages of the report. ODD—Export the odd numbered pages of the report. RANGE—Export the pages listed in the page_range parameter . (The default value is ALL)	String
page_range	A string that identifies the pages to be exported if the RANGE option in the page_range_type parameter is used (for example, 1, 3, 5-12). If any other page_range_type value is used, the page_range value will be ignored.	String
starting_page_number	Applies an offset to the page numbering to add additional pages to the beginning of the report. The default offset is 1. (The default value is 1)	Integer
total_page_number	The total number of pages to label, for example, when your report displays X of Y pages. This is useful when you want to combine multiple reports into one. The default is -1, which means there is no override. (The default value is None)	Integer
resolution	An integer that defines the resolution of the export file in dots per inch (dpi). (The default value is 96)	Integer
image_quality	A string that defines output image quality. BEST—An output image quality resample ratio of 1 BETTER—An output image quality resample ratio of 2 NORMAL—An output image quality resample ratio of 3 FASTER—An output image quality resample ratio of 4 FASTEST—An output image quality resample ratio of 5 (The default value is BEST)	String
compress_vector_graphics	A Boolean that controls compression of vector and text portions of the output file. Image compression is defined separately. (The default value is True)	Boolean
image_compression	A string that defines the compression scheme used to compress image or raster data in the output file. ADAPTIVE—Automatically selects the best compression type for each image on the page. JPEG will be used for large images with many unique colors. DEFLATE will be used for all other images. JPEG—A lossy data compression. DEFLATE—A lossless data compression LZW—Lempel-Ziv-Welch, a lossless data compression NONE—Compression is not applied RLE—Run-length encoded compression (The default value is ADAPTIVE)	String
embed_fonts	A Boolean that controls the embedding of fonts in an export file. Font embedding allows text and character markers to be displayed correctly when the document is viewed on a computer that does not have the necessary fonts installed. (The default value is True)	Boolean
jpeg_compression_quality	A number that controls compression quality value when image_compression is set to ADAPTIVE or JPEG. The valid range is 1 through 100. A jpeg_compression_quality of 100 provides the best quality images but creates large export files. The recommended range is 70 through 90. (The default value is 80)	Integer

PDF files are designed to be consistently viewable and printable across platforms. They are commonly used for distributing documents on the web and are a standard interchange format for content delivery. PDF files are editable in many graphics applications and retain annotation, labeling, and attribute data for map layers. PDF exports support embedding of fonts and can display symbology correctly even if the user does not have Esri fonts installed.

getDefinition (cim_version)

Parameter	Explanation	Data Type
cim_version	A string that represents the major version of the CIM.	String

Return Value

Data Type	Explanation
Object	Returns the CIM definition for a Report object.

CIM-level access to additional object properties was introduced at ArcGIS AllSource 2.4. CIM-level access to reports was introduced at ArcGIS AllSource 3.1. When you want to return an object's CIM definition, you must specify a cim_version. Esri follows the semantic versioning specification. This means that at major releases—for example, 3.0—breaking API changes are allowed. This allows Python script authors control over which version of the CIM is used during a script run if there is a possibility breaking changes may be introduced in the new version. If you are authoring scripts for ArcGIS AllSource 2.x, specify the cim_version to be 'V2'. If you are authoring scripts for ArcGIS AllSource 3.x, specify the cim_version to be 'V3'. Scripts authored using cim_version 'V2' will continue to work in ArcGIS AllSource 3.x.

For more information about working with the CIM and samples, see Python CIM access.

listSections ({wildcard})

Parameter	Explanation	Data Type
wildcard	A wildcard is based on the section 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

Parameter

Explanation

Data Type

wildcard

A wildcard is based on the section 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 ReportSection and ReportLayoutSection objects in a report.

Returns a Python list of ReportSection and ReportLayoutSection objects in a report.

openView ()

This is useful if the report view is not already open or another view is active in the application. The method creates a report view zoomed to its full extent and activates it. To close other, existing views before opening a new view, use the ArcGISProject closeViews method.

Note:

This method is designed to be run in the application using a script tool, Notebook, or the Python window. It will have no effect if run outside of the application.

setDefinition (definition_object)

Parameter	Explanation	Data Type
definition_object	A modified CIM definition object originally retrieved using getDefinition.	Object

For more information about working with the CIM and samples, see Python CIM Access.

setReferenceDataSource (data_source)

Parameter	Explanation	Data Type
data_source	The data reference that powers the report. This parameter can be a Layer object, a Table object, or a string that represents the path to an external data source. (The default value is None)	Object

Parameter

Explanation

Data Type

data_source

The data reference that powers the report. This parameter can be a Layer object, a Table object, or a string that represents the path to an external data source.

(The default value is None)

Object

The setReferenceDataSource method sets the data source that the report references using a Layer object, a Table object, or a string that represents the path to an external data source

updatePageInfo (pageInfo)

Parameter	Explanation	Data Type
pageInfo	The keys for the dictionary are defined as follows: height—The report's height in page units. width—The report's width in page units. units—The report's page unit keyword. The supported values are inch, point, centimeter, and millimeter. margins—The report's margins keyword. The supported margin values are NORMAL, MODERATE, WIDE, and NARROW.	Dictionary

The page width and height values are based on the units specified in the dictionary. If you change the units, you may also want to change the width and height values.

Code sample

Report example 1

The following script exports a report to PDF using a page range:

import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\USA_States\USA_States.aprx")
report = aprx.listReports("Counties Report")[0]
report.exportToPDF(r"C:\Project\USA_States\CA_Counties_Report.pdf")

Report example 2

The following script changes the metadata for a report:

aprx = arcpy.mp.ArcGISProject(r"C:\DemoData\USA_States.aprx")
report = aprx.listReports("States Report")[1] # Find second report by name
md = report.metadata # Get report metadata
md.title = "Modified States Report"
md.save()

Report example 3

The following script sets the reference data source for the first report section in a report:

import arcpy
pdf_name = "StatesReport.pdf"
cover_page = r"C:\path\to\StatesCoverPage.pdf"
part_one_pdf = r"C:\path\to\part_one.pdf"
part_two_pdf = r"C:\path\to\part_two.pdf"
final_pdf_path = r"C:\path\to\StatesReport.pdf"
report1 = self.aprx.listReports("States Report")[0] # Attribute List template
report2 = self.aprx.listReports("States Report Summaries")[0] # Summaries only using Basic Summary template
report1.exportToPDF(part_one_pdf, starting_page_number=2, total_page_number=13, page_range_type="RANGE",
                    page_range="1-2")
report2.exportToPDF(part_two_pdf, starting_page_number=3, total_page_number=13, page_range_type="RANGE",
                    page_range="2-11")

pdfMerge = arcpy.mp.PDFDocumentCreate(final_pdf_path) # Creates an empty PDF
pdfMerge.appendPages(cover_page)
pdfMerge.appendPages(part_one_pdf)
pdfMerge.appendPages(part_two_pdf)
pdfMerge.saveAndClose()

Report example 4

The following script modifies the definition query for the first report section in a report:

aprx = arcpy.mp.ArcGISProject(r"C:\DemoData\USA_States.aprx")
report = aprx.listReports()[2] # Find the third report in the project
print(report.name)
# State Population Report
report.definitionQuery = "STATE_NAME = 'California'"
print(report.definitionQuery)
# STATE_NAME = 'California'

Report example 5

The following script gets all report and report layout section objects using listSections:

aprx = arcpy.mp.ArcGISProject('current') # Run this from the Python window in Pro
report = aprx.listReports("Complete Report")[0] # Find report by name
sections = report.listSections() # Get all report and report layout sections in a report
for s in sections:
	print(f"Section Name: {s.name} Section Type: {s.type}")
# Section Name: Cover Page Section Type: REPORT_LAYOUT_SECTION
# Section Name: Cities Section Type: REPORT_SECTION
# Section Name: States Section Type: REPORT_SECTION

Report example 6

The following script changes the report definition for a text element:

aprx = arcpy.mp.ArcGISProject(r'C:\projects\WaterSupply.aprx')
report = aprx.listReports('Suppliers')[0] # Find the report by name
df = report.getDefinition('V3') # Get the current CIM definition of the report

report_section = df.elements[0] # Find the first report section in the CIM
report_header = report_section.elements[4] # Find the report header subsection
title_text = report_header.elements[3] # Find the title text element

symbol = title_text.graphic.symbol.symbol # Get the text symbol
symbol.fontFamilyName = "Arial" # Change the font 

report.setDefinition(df) # Set the new CIM definition

Report example 7

The following script creates a report and opens a new view:

aprx = arcpy.mp.ArcGISProject('current') # This must be run in the application
map = aprx.listMaps('TaxLots')[0] # Find the map by name

# Define report properties
ds = map.listTables('Owners')[0] # Find the data source table by name
pi = {'width': 297, 'height': 420, 'units': 'MILLIMETER', 'margins': 'WIDE'} # Define page info
f = [{'fieldName': 'Name', 'sortInfo': 'DESC', 'groupField': False},
        {'fieldName': 'Address', 'sortInfo': 'ASC', 'groupField': False},
        {'fieldName': 'Status', 'sortInfo': 'None', 'groupField': False}] # Define fields
s = [] # Pass no statistics

report = aprx.createReport(
            page_info = pi,
            data_source = ds,
            fields = f,
            statistics = s,
            name = 'Owners') # Create the report

report_view = report.openView() # Open a new report view

Report example 8

The following script gets the page information for a report:

aprx = arcpy.mp.ArcGISProject('current') # This must be run in the application
map = aprx.listMaps('TaxLots')[0] # Find the map by name

# Define report properties
ds = map.listTables('Owners')[0] # Find the data source table by name
pi = {'width': 297, 'height': 420, 'units': 'MILLIMETER', 'margins': 'WIDE'} # Define page info
f = [{'fieldName': 'Name', 'sortInfo': 'DESC', 'groupField': False},
        {'fieldName': 'Address', 'sortInfo': 'ASC', 'groupField': False},
        {'fieldName': 'Status', 'sortInfo': 'None', 'groupField': False}] # Define fields
s = [] # Pass no statistics

report = aprx.createReport(
            page_info = pi,
            data_source = ds,
            fields = f,
            statistics = s,
            name = 'Owners') # Create the report

report_view = report.openView() # Open a new report view

Feedback on this topic?