sempy_labs.report package

Module contents

class sempy_labs.report.ReportWrapper(report: str, workspace: str | UUID | None = None)

Bases: object

Connects to a Power BI report and retrieves its definition.

The ReportWrapper and all functions which depend on it require the report to be in the PBIR format.

Parameters:

  • report (str) – The name of the report.

  • workspace (str | uuid.UUID) – The name or ID of the workspace in which the report resides. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

Returns:

A pandas dataframe containing the report metadata definition files.

Return type:

pandas.DataFrame

disable_show_items_with_no_data()

Disables the show items with no data property in all visuals within the report.

get_theme(theme_type: str = 'baseTheme') → dict

Obtains the theme file of the report.

Parameters:

theme_type (str, default="baseTheme") – The theme type. Options: “baseTheme”, “customTheme”.

Returns:

The theme.json file

Return type:

dict

hide_tooltip_drillthrough_pages()

Hides all tooltip pages and drillthrough pages in a report.

list_bookmarks() → DataFrame

Shows a list of all bookmarks in the report.

Returns:

A pandas dataframe containing a list of all bookmarks in the report.

Return type:

pandas.DataFrame

list_custom_visuals() → DataFrame

Shows a list of all custom visuals used in the report.

Returns:

A pandas dataframe containing a list of all the custom visuals used in the report.

Return type:

pandas.DataFrame

list_page_filters(extended: bool = False) → DataFrame

Shows a list of all page filters used in the report.

Parameters:

extended (bool, default=False) – If True, adds an extra column called ‘Valid Semantic Model Object’ which identifies whether the semantic model object used in the report exists in the semantic model which feeds data to the report.

Returns:

A pandas dataframe containing a list of all the page filters used in the report.

Return type:

pandas.DataFrame

list_pages() → DataFrame

Shows a list of all pages in the report.

Returns:

A pandas dataframe containing a list of all pages in the report.

Return type:

pandas.DataFrame

list_report_filters(extended: bool = False) → DataFrame

Shows a list of all report filters used in the report.

Parameters:

extended (bool, default=False) – If True, adds an extra column called ‘Valid Semantic Model Object’ which identifies whether the semantic model object used in the report exists in the semantic model which feeds data to the report.

Returns:

A pandas dataframe containing a list of all the report filters used in the report.

Return type:

pandas.DataFrame

list_report_level_measures() → DataFrame

Shows a list of all report-level measures in the report.

Returns:

A pandas dataframe containing a list of all report-level measures in the report.

Return type:

pandas.DataFrame

list_semantic_model_objects(extended: bool = False) → DataFrame

Shows a list of all semantic model objects (measures, columns, hierarchies) that are used in the report and where the objects were used (i.e. visual, report filter, page filter, visual filter).

Parameters:

extended (bool, default=False) – If True, adds an extra column called ‘Valid Semantic Model Object’ which identifies whether the semantic model object used in the report exists in the semantic model which feeds data to the report.

Returns:

A pandas dataframe showing the semantic model objects used in the report.

Return type:

pandas.DataFrame

list_visual_filters(extended: bool = False) → DataFrame

Shows a list of all visual filters used in the report.

Parameters:

extended (bool, default=False) – If True, adds an extra column called ‘Valid Semantic Model Object’ which identifies whether the semantic model object used in the report exists in the semantic model which feeds data to the report.

Returns:

A pandas dataframe containing a list of all the visual filters used in the report.

Return type:

pandas.DataFrame

list_visual_interactions() → DataFrame

Shows a list of all modified visual interactions used in the report.

Returns:

A pandas dataframe containing a list of all modified visual interactions used in the report.

Return type:

pandas.DataFrame

list_visual_objects(extended: bool = False) → DataFrame

Shows a list of all semantic model objects used in each visual in the report.

Parameters:

extended (bool, default=False) – If True, adds an extra column called ‘Valid Semantic Model Object’ which identifies whether the semantic model object used in the report exists in the semantic model which feeds data to the report.

Returns:

A pandas dataframe containing a list of all semantic model objects used in each visual in the report.

Return type:

pandas.DataFrame

list_visuals() → DataFrame

Shows a list of all visuals in the report.

Returns:

A pandas dataframe containing a list of all visuals in the report.

Return type:

pandas.DataFrame

migrate_report_level_measures(measures: str | List[str] | None = None)

Moves all report-level measures from the report to the semantic model on which the report is based.

Parameters:

measures (str | List[str], default=None) – A measure or list of measures to move to the semantic model. Defaults to None which resolves to moving all report-level measures to the semantic model.

remove_unnecessary_custom_visuals()

Removes any custom visuals within the report that are not used in the report.

resolve_page_display_name(page_name: UUID) → str

Obtains the page dispaly name.

Parameters:

page_name (UUID) – The name of the page of the report.

Returns:

The page display name.

Return type:

str

resolve_page_name(page_display_name: str) → UUID

Obtains the page name, page display name, and the file path for a given page in a report.

Parameters:

page_display_name (str) – The display name of the page of the report.

Returns:

The page name.

Return type:

UUID

set_active_page(page_name: str)

Sets the active page (first page displayed when opening a report) for a report.

Parameters:

page_name (str) – The page name or page display name of the report.

set_page_type(page_name: str, page_type: str)

Changes the page type of a report page.

Parameters:

  • page_name (str) – Name or display name of the report page.

  • page_type (str) – The page type. Valid page types: ‘Tooltip’, ‘Letter’, ‘4:3’, ‘16:9’.

set_page_visibility(page_name: str, hidden: bool)

Sets whether a report page is visible or hidden.

Parameters:

  • page_name (str) – The page name or page display name of the report.

  • hidden (bool) – If set to True, hides the report page. If set to False, makes the report page visible.

set_theme(theme_file_path: str)

Sets a custom theme for a report based on a theme .json file.

Parameters:

theme_file_path (str) – The file path of the theme.json file. This can either be from a Fabric lakehouse or from the web. Example for lakehouse: file_path = ‘/lakehouse/default/Files/CY23SU09.json’ Example for web url: file_path = ‘https://raw.githubusercontent.com/PowerBiDevCamp/FabricUserApiDemo/main/FabricUserApiDemo/DefinitionTemplates/Shared/Reports/StaticResources/SharedResources/BaseThemes/CY23SU08.json’

update_report(request_body: dict)
sempy_labs.report.clone_report(report: str, cloned_report: str, workspace: str | UUID | None = None, target_workspace: str | None = None, target_dataset: str | None = None, target_dataset_workspace: str | None = None)

Clones a Power BI report.

This is a wrapper function for the following API: Reports - Clone Report In Group.

Parameters:

  • report (str) – Name of the Power BI report.

  • cloned_report (str) – Name of the new Power BI report.

  • workspace (str | uuid.UUID, default=None) – The Fabric workspace name or ID. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

  • target_workspace (str, default=None) – The name of the Fabric workspace to place the cloned report. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

  • target_dataset (str, default=None) – The name of the semantic model to be used by the cloned report. Defaults to None which resolves to the semantic model used by the initial report.

  • target_dataset_workspace (str, default=None) – The workspace name in which the semantic model to be used by the report resides. Defaults to None which resolves to the semantic model used by the initial report.

sempy_labs.report.create_model_bpa_report(report: str | None = 'ModelBPA', dataset: str | None = 'ModelBPA', dataset_workspace: str | UUID | None = None)

Dynamically generates a Best Practice Analyzer report for analyzing semantic models.

Parameters:

  • report (str, default='ModelBPA') – Name of the report. Defaults to ‘ModelBPA’.

  • dataset (str, default='ModelBPA') – Name of the semantic model which feeds this report. Defaults to ‘ModelBPA’

  • dataset_workspace (str | uuid.UUID, default=None) – The Fabric workspace name or ID in which the semantic model resides. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

sempy_labs.report.create_report_from_reportjson(report: str, dataset: str | UUID, report_json: dict, theme_json: dict | None = None, workspace: str | UUID | None = None)

Creates a report based on a report.json file (and an optional themes.json file).

This is a wrapper function for the following API: Items - Create Report.

Parameters:

  • report (str) – Name of the report.

  • dataset (str | uuid.UUID) – Name or ID of the semantic model to connect to the report.

  • report_json (dict) – The report.json file to be used to create the report.

  • theme_json (dict, default=None) – The theme.json file to be used for the theme of the report.

  • workspace (str | uuid.UUID, default=None) – The Fabric workspace name or ID. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

sempy_labs.report.download_report(report: str | UUID, file_name: str | None = None, download_type: str = 'LiveConnect', workspace: str | UUID | None = None)

Downloads the specified report from the specified workspace to a Power BI .pbix file.

This is a wrapper function for the following API: Reports - Export Report In Group <https://learn.microsoft.com/rest/api/power-bi/reports/export-report-in-group>.

Parameters:

  • report (str | uuid.UUID) – Name or ID of the report.

  • file_name (str, default=None) – Name of the .pbix file to be saved. Defaults to None which resolves to the name of the report.

  • download_type (str, default="LiveConnect") – The type of download. Valid values are “LiveConnect” and “IncludeModel”.

  • workspace (str | uuid.UUID, default=None) – The Fabric workspace name or ID. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

sempy_labs.report.export_report(report: str, export_format: str, file_name: str | None = None, bookmark_name: str | None = None, page_name: str | None = None, visual_name: str | None = None, report_filter: str | None = None, workspace: str | UUID | None = None)

Exports a Power BI report to a file in your lakehouse.

This is a wrapper function for the following APIs: Reports - Export To File In Group, Reports - Get Export To File Status In Group, Reports - Get File Of Export To File In Group.

Parameters:

  • report (str) – Name of the Power BI report.

  • export_format (str) – The format in which to export the report. For image formats, enter the file extension in this parameter, not ‘IMAGE’. Valid formats

  • file_name (str, default=None) – The name of the file to be saved within the lakehouse. Do not include the file extension. Defaults ot the reportName parameter value.

  • bookmark_name (str, default=None) – The name (GUID) of a bookmark within the report.

  • page_name (str, default=None) – The name (GUID) of the report page.

  • visual_name (str, default=None) – The name (GUID) of a visual. If you specify this parameter you must also specify the page_name parameter.

  • report_filter (str, default=None) – A report filter to be applied when exporting the report. Syntax is user-friendly. See above for examples.

  • workspace (str | uuid.UUID, default=None) – The Fabric workspace name or ID. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

sempy_labs.report.get_report_datasources(report: str | UUID, workspace: str | UUID | None = None) → DataFrame

Returns a list of data sources for the specified paginated report (RDL) from the specified workspace.

Parameters:

  • report (str | uuid.UUID) – Name or ID of the Power BI report.

  • workspace (str | uuid.UUID, default=None) – The name or ID of the Fabric workspace in which the report resides. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

Returns:

A pandas dataframe showing a list of data sources for the specified paginated report (RDL) from the specified workspace.

Return type:

pandas.DataFrame

sempy_labs.report.get_report_definition(report: str, workspace: str | UUID | None = None, return_dataframe: bool = True) → DataFrame | dict

Gets the collection of definition files of a report.

This is a wrapper function for the following API: Items - Get Report Definition.

Parameters:

  • report (str) – Name of the report.

  • workspace (str | uuid.UUID, default=None) – The Fabric workspace name or ID in which the report resides. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

  • return_dataframe (bool, default=True) – If True, returns a dataframe. If False, returns a json dictionary.

Returns:

The collection of report definition files within a pandas dataframe.

Return type:

pandas.DataFrame | dict

sempy_labs.report.get_report_json(report: str, workspace: str | UUID | None = None, save_to_file_name: str | None = None) → dict

Gets the report.json file content of a Power BI report.

This is a wrapper function for the following API: Items - Get Report Definition.

Parameters:

  • report (str) – Name of the Power BI report.

  • workspace (str | uuid.UUID, default=None) – The Fabric workspace name or ID in which the report exists. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

  • save_to_file_name (str, default=None) – Specifying this parameter will save the report.json file to the lakehouse attached to the notebook with the file name of this parameter.

Returns:

The report.json file for a given Power BI report.

Return type:

dict

sempy_labs.report.launch_report(report: str, workspace: str | UUID | None = None)

Shows a Power BI report within a Fabric notebook.

Parameters:

  • report (str) – Name of the Power BI report.

  • workspace (str | uuid.UUID, default=None) – The Fabric workspace name or ID. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

Returns:

An embedded Power BI report within the notebook.

Return type:

str

sempy_labs.report.report_bpa_rules() → DataFrame

Shows the default rules for the report BPA used by the run_report_bpa function.

Returns:

A pandas dataframe containing the default rules for the run_report_bpa function.

Return type:

pandas.DataFrame

sempy_labs.report.report_rebind(report: str | List[str], dataset: str, report_workspace: str | UUID | None = None, dataset_workspace: str | UUID | None = None)

Rebinds a report to a semantic model.

This is a wrapper function for the following API: Reports - Rebind Report In Group.

Parameters:

  • report (str | List[str]) – Name(s) of the Power BI report(s).

  • dataset (str) – Name of the semantic model.

  • report_workspace (str | uuid.UUID, default=None) – The name or ID of the Fabric workspace in which the report resides. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

  • dataset_workspace (str | uuid.UUID, default=None) – The name or ID of the Fabric workspace in which the semantic model resides. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

sempy_labs.report.report_rebind_all(dataset: str, new_dataset: str, dataset_workspace: str | None = None, new_dataset_workpace: str | None = None, report_workspace: str | List[str] | None = None)

Rebinds all reports across all workspaces which are bound to a specific semantic model to a new semantic model.

Parameters:

  • dataset (str) – Name of the semantic model currently binded to the reports.

  • new_dataset (str) – Name of the semantic model to rebind to the reports.

  • dataset_workspace (str, default=None) – The name of the Fabric workspace in which the original semantic model resides. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

  • new_dataset_workspace (str, default=None) – The name of the Fabric workspace in which the new semantic model resides. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

  • report_workspace (str | List[str], default=None) – The name(s) of the Fabric workspace(s) in which the report(s) reside(s). Defaults to None which finds all reports in all workspaces which use the semantic model and rebinds them to the new semantic model.

sempy_labs.report.run_report_bpa(report: str, rules: DataFrame | None = None, workspace: str | UUID | None = None, export: bool = False, return_dataframe: bool = False)

Displays an HTML visualization of the results of the Best Practice Analyzer scan for a report. Note: As with all functions which rely on the ReportWrapper, this function requires the report to be in the ‘PBIR’ format.

Parameters:

  • report (str) – Name of the report.

  • rules (pandas.DataFrame, default=None) – A pandas dataframe containing rules to be evaluated.

  • workspace (str | uuid.UUID, default=None) – The Fabric workspace name or ID. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.

  • export (bool, default=False) – If True, exports the resulting dataframe to a delta table in the lakehouse attached to the notebook.

  • return_dataframe (bool, default=False) – If True, returns a pandas dataframe instead of the visualization.

Returns:

A pandas dataframe in HTML format showing report objects which violated the best practice analyzer rules.

Return type:

pandas.DataFrame

sempy_labs.report.update_report_from_reportjson(report: str | UUID, report_json: dict, workspace: str | UUID | None = None)

Updates a report based on a report.json file.

This is a wrapper function for the following API: Items - Update Report Definition.

Parameters:

  • report (str | uuid.UUID) – Name or ID of the report.

  • report_json (dict) – The report.json file to be used to update the report.

  • workspace (str | uuid.UUID, default=None) – The Fabric workspace name or ID in which the report resides. Defaults to None which resolves to the workspace of the attached lakehouse or if no lakehouse attached, resolves to the workspace of the notebook.