semantic-link-labs 0.9.3__py3-none-any.whl → 0.9.5__py3-none-any.whl

sempy_labs/_utils.py

@@ -0,0 +1,42 @@
+item_types = {
+    "Dashboard": ["Dashboard", "dashboards"],
+    "DataPipeline": ["Data Pipeline", "dataPipelines", "pipeline-content.json"],
+    "Datamart": ["Datamart", "datamarts"],
+    "Environment": ["Environment", "environments"],
+    "Eventhouse": ["Eventhouse", "eventhouses", "EventhouseProperties.json"],
+    "Eventstream": ["Eventstream", "eventstreams", "eventstream.json"],
+    "GraphQLApi": ["GraphQL Api", "GraphQLApis"],
+    "KQLDashboard": ["KQL Dashboard", "kqlDashboards", "RealTimeDashboard.json"],
+    "KQLDatabase": [
+        "KQL Database",
+        "kqlDatabases",
+    ],  # "DatabaseProperties.json", "DatabaseSchema.kql"
+    "KQLQueryset": ["KQL Queryset", "kqlQuerysets", "RealTimeQueryset.json"],
+    "Lakehouse": ["Lakehouse", "lakehouses"],
+    "MLExperiment": ["ML Experiment", "mlExperiments"],
+    "MLModel": ["ML Model", "mlModels"],
+    "MirroredDatabase": [
+        "Mirrored Database",
+        "mirroredDatabases",
+        "mirroredDatabase.json",
+    ],
+    "MirroredWarehouse": ["Mirrored Warehouse", "mirroredWarehouses"],
+    "MountedDataFactory": [
+        "Mounted Data Factory",
+        "mountedDataFactories",
+        "mountedDataFactory-content.json",
+    ],
+    "Notebook": ["Notebook", "notebooks"],
+    "PaginatedReport": ["Paginated Report", "paginatedReports"],
+    "Reflex": ["Reflex", "reflexes", "ReflexEntities.json"],
+    "Report": ["Report", "reports", "report.json"],
+    "SQLDatabase": ["SQL Database", "sqlDatabases"],
+    "SQLEndpoint": ["SQL Endpoint", "sqlEndpoints"],
+    "SemanticModel": ["Semantic Model", "semanticModels", "model.bim"],
+    "SparkJobDefinition": [
+        "Spark Job Definition",
+        "sparkJobDefinitions",
+        "SparkJobDefinitionV1.json",
+    ],
+    "Warehouse": ["Warehouse", "warehouses"],
+}

sempy_labs/_vertipaq.py

@@ -33,9 +33,11 @@ def vertipaq_analyzer(
     export: Optional[str] = None,
     read_stats_from_data: bool = False,
     **kwargs,
-):
+) -> dict[str, pd.DataFrame]:
     """
-    Displays an HTML visualization of the Vertipaq Analyzer statistics from a semantic model.
+    Displays an HTML visualization of the `Vertipaq Analyzer <https://www.sqlbi.com/tools/vertipaq-analyzer/>`_ statistics from a semantic model.
+
+    `Vertipaq Analyzer <https://www.sqlbi.com/tools/vertipaq-analyzer/>`_ is an open-sourced tool built by SQLBI. It provides a detailed analysis of the VertiPaq engine, which is the in-memory engine used by Power BI and Analysis Services Tabular models.
 
     Parameters
     ----------
@@ -51,6 +53,11 @@ def vertipaq_analyzer(
         Default value: None.
     read_stats_from_data : bool, default=False
         Setting this parameter to true has the function get Column Cardinality and Missing Rows using DAX (Direct Lake semantic models achieve this using a Spark query to the lakehouse).
+
+    Returns
+    -------
+    dict[str, pandas.DataFrame]
+        A dictionary of pandas dataframes showing the vertipaq analyzer statistics.
     """
 
     from sempy_labs.tom import connect_semantic_model
@@ -502,6 +509,14 @@ def vertipaq_analyzer(
 
     if export is None:
         visualize_vertipaq(dfs)
+        return {
+            "Model Summary": export_Model,
+            "Tables": export_Table,
+            "Partitions": export_Part,
+            "Columns": export_Col,
+            "Relationships": export_Rel,
+            "Hierarchies": export_Hier,
+        }
 
     # Export vertipaq to delta tables in lakehouse
     if export in ["table", "zip"]:

sempy_labs/_warehouses.py

@@ -1,9 +1,9 @@
-import sempy.fabric as fabric
 from sempy_labs._helper_functions import (
     resolve_workspace_name_and_id,
     _base_api,
     _create_dataframe,
     _update_dataframe_datatypes,
+    delete_item,
 )
 import pandas as pd
 from typing import Optional
@@ -115,7 +115,7 @@ def list_warehouses(workspace: Optional[str | UUID] = None) -> pd.DataFrame:
     return df
 
 
-def delete_warehouse(name: str, workspace: Optional[str | UUID] = None):
+def delete_warehouse(name: str | UUID, workspace: Optional[str | UUID] = None):
     """
     Deletes a Fabric warehouse.
 
@@ -123,27 +123,15 @@ def delete_warehouse(name: str, workspace: Optional[str | UUID] = None):
 
     Parameters
     ----------
-    name: str
-        Name of the warehouse.
+    name: str | uuid.UUID
+        Name or ID of the warehouse.
     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.
     """
 
-    (workspace_name, workspace_id) = resolve_workspace_name_and_id(workspace)
-
-    item_id = fabric.resolve_item_id(
-        item_name=name, type="Warehouse", workspace=workspace_id
-    )
-
-    _base_api(
-        request=f"/v1/workspaces/{workspace_id}/warehouses/{item_id}", method="delete"
-    )
-
-    print(
-        f"{icons.green_dot} The '{name}' warehouse within the '{workspace_name}' workspace has been deleted."
-    )
+    delete_item(item=name, type="Warehouse", workspace=workspace)
 
 
 def get_warehouse_tables(

sempy_labs/_workloads.py

@@ -6,9 +6,10 @@ from sempy_labs._helper_functions import (
     _base_api,
     _create_dataframe,
 )
+from uuid import UUID
 
 
-def list_workloads(capacity_name: str) -> pd.DataFrame:
+def list_workloads(capacity: str | UUID, **kwargs) -> pd.DataFrame:
     """
     Returns the current state of the specified capacity workloads.
     If a workload is enabled, the percentage of maximum memory that the workload can consume is also returned.
@@ -17,8 +18,8 @@ def list_workloads(capacity_name: str) -> pd.DataFrame:
 
     Parameters
     ----------
-    capacity_name : str
-        The capacity name.
+    capacity : str | uuid.UUID
+        The capacity name or ID.
 
     Returns
     -------
@@ -28,6 +29,12 @@ def list_workloads(capacity_name: str) -> pd.DataFrame:
 
     from sempy_labs._helper_functions import resolve_capacity_id
 
+    if "capacity_name" in kwargs:
+        capacity = kwargs["capacity_name"]
+        print(
+            f"{icons.warning} The 'capacity_name' parameter is deprecated. Please use 'capacity' instead."
+        )
+
     columns = {
         "Workload Name": "string",
         "State": "string",
@@ -35,7 +42,7 @@ def list_workloads(capacity_name: str) -> pd.DataFrame:
     }
     df = _create_dataframe(columns=columns)
 
-    capacity_id = resolve_capacity_id(capacity_name=capacity_name)
+    capacity_id = resolve_capacity_id(capacity=capacity)
 
     response = _base_api(request=f"/v1.0/myorg/capacities/{capacity_id}/Workloads")
 
@@ -53,10 +60,11 @@ def list_workloads(capacity_name: str) -> pd.DataFrame:
 
 
 def patch_workload(
-    capacity_name: str,
+    capacity: str | UUID,
     workload_name: str,
     state: Optional[str] = None,
     max_memory_percentage: Optional[int] = None,
+    **kwargs,
 ):
     """
     Changes the state of a specific workload to Enabled or Disabled.
@@ -66,8 +74,8 @@ def patch_workload(
 
     Parameters
     ----------
-    capacity_name : str
-        The capacity name.
+    capacity : str | uuid.UUID
+        The capacity name or ID.
     workload_name : str
         The workload name.
     state : str, default=None
@@ -78,7 +86,13 @@ def patch_workload(
 
     from sempy_labs._helper_functions import resolve_capacity_id
 
-    capacity_id = resolve_capacity_id(capacity_name=capacity_name)
+    if "capacity_name" in kwargs:
+        capacity = kwargs["capacity_name"]
+        print(
+            f"{icons.warning} The 'capacity_name' parameter is deprecated. Please use 'capacity' instead."
+        )
+
+    capacity_id = resolve_capacity_id(capacity=capacity)
 
     states = ["Disabled", "Enabled", "Unsupported"]
     state = state.capitalize()
@@ -119,5 +133,5 @@ def patch_workload(
     _base_api(request=url, method="patch", payload=payload)
 
     print(
-        f"The '{workload_name}' workload within the '{capacity_name}' capacity has been updated accordingly."
+        f"The '{workload_name}' workload within the '{capacity}' capacity has been updated accordingly."
     )

sempy_labs/_workspaces.py

@@ -204,7 +204,9 @@ def add_user_to_workspace(
 
 
 def assign_workspace_to_capacity(
-    capacity_name: str, workspace: Optional[str | UUID] = None
+    capacity: str | UUID,
+    workspace: Optional[str | UUID] = None,
+    **kwargs,
 ):
     """
     Assigns a workspace to a capacity.
@@ -213,16 +215,22 @@ def assign_workspace_to_capacity(
 
     Parameters
     ----------
-    capacity_name : str
-        The name of the capacity.
+    capacity : str | uuid.UUID
+        The name or ID of the capacity.
     workspace : str | uuid.UUID, default=None
         The name or ID of the Fabric workspace.
         Defaults to None which resolves to the workspace of the attached lakehouse
         or if no lakehouse attached, resolves to the workspace of the notebook.
     """
 
+    if "capacity_name" in kwargs:
+        capacity = kwargs["capacity_name"]
+        print(
+            f"{icons.warning} The 'capacity_name' parameter is deprecated. Please use 'capacity' instead."
+        )
+
     (workspace_name, workspace_id) = resolve_workspace_name_and_id(workspace)
-    capacity_id = resolve_capacity_id(capacity_name=capacity_name)
+    capacity_id = resolve_capacity_id(capacity=capacity)
 
     payload = {"capacityId": capacity_id}
 
@@ -233,7 +241,7 @@ def assign_workspace_to_capacity(
         status_codes=[200, 202],
     )
     print(
-        f"{icons.green_dot} The '{workspace_name}' workspace has been assigned to the '{capacity_name}' capacity."
+        f"{icons.green_dot} The '{workspace_name}' workspace has been assigned to the '{capacity}' capacity."
     )
 
 

sempy_labs/admin/__init__.py

@@ -1,21 +1,61 @@
+from sempy_labs.admin._users import (
+    list_access_entities,
+    list_user_subscriptions,
+)
+from sempy_labs.admin._workspaces import (
+    add_user_to_workspace,
+    delete_user_from_workspace,
+    restore_deleted_workspace,
+)
+from sempy_labs.admin._artifacts import (
+    list_unused_artifacts,
+)
+from sempy_labs.admin._shared import (
+    list_widely_shared_artifacts,
+)
+from sempy_labs.admin._datasets import (
+    list_datasets,
+    list_dataset_users,
+)
+from sempy_labs.admin._apps import (
+    list_apps,
+    list_app_users,
+)
+from sempy_labs.admin._reports import (
+    list_reports,
+    list_report_users,
+    list_report_subscriptions,
+)
+from sempy_labs.admin._activities import (
+    list_activity_events,
+)
 from sempy_labs.admin._scanner import (
     scan_workspaces,
 )
+from sempy_labs.admin._capacities import (
+    patch_capacity,
+    list_capacities,
+    get_capacity_assignment_status,
+    get_capacity_state,
+    list_capacity_users,
+)
+from sempy_labs.admin._tenant import (
+    list_tenant_settings,
+    delete_capacity_tenant_setting_override,
+    update_tenant_setting,
+    update_capacity_tenant_setting_override,
+    list_workspaces_tenant_settings_overrides,
+    list_capacity_tenant_settings_overrides,
+    list_capacities_delegated_tenant_settings,
+    list_domain_tenant_settings_overrides,
+)
 from sempy_labs.admin._basic_functions import (
     assign_workspaces_to_capacity,
     unassign_workspaces_from_capacity,
     list_workspaces,
     list_workspace_access_details,
     list_modified_workspaces,
-    list_datasets,
-    list_reports,
-    list_capacities,
-    list_tenant_settings,
-    list_capacities_delegated_tenant_settings,
-    list_access_entities,
-    list_activity_events,
-    get_capacity_assignment_status,
-    get_capacity_state,
+    list_workspace_users,
 )
 from sempy_labs.admin._domains import (
     list_domains,
@@ -72,4 +112,25 @@ __all__ = [
     "get_capacity_assignment_status",
     "scan_workspaces",
     "get_capacity_state",
+    "list_apps",
+    "list_app_users",
+    "list_dataset_users",
+    "list_report_users",
+    "patch_capacity",
+    "list_workspace_users",
+    "list_widely_shared_artifacts",
+    "delete_capacity_tenant_setting_override",
+    "update_tenant_setting",
+    "update_capacity_tenant_setting_override",
+    "list_workspaces_tenant_settings_overrides",
+    "list_capacity_tenant_settings_overrides",
+    "list_capacities_delegated_tenant_settings",
+    "list_domain_tenant_settings_overrides",
+    "list_unused_artifacts",
+    "add_user_to_workspace",
+    "delete_user_from_workspace",
+    "restore_deleted_workspace",
+    "list_capacity_users",
+    "list_user_subscriptions",
+    "list_report_subscriptions",
 ]

sempy_labs/admin/_activities.py

@@ -0,0 +1,166 @@
+import pandas as pd
+from typing import Optional
+from dateutil.parser import parse as dtparser
+from sempy._utils._log import log
+from sempy_labs._helper_functions import (
+    _base_api,
+    _create_dataframe,
+    _update_dataframe_datatypes,
+)
+import sempy_labs._icons as icons
+
+
+@log
+def list_activity_events(
+    start_time: str,
+    end_time: str,
+    activity_filter: Optional[str] = None,
+    user_id_filter: Optional[str] = None,
+    return_dataframe: bool = True,
+) -> pd.DataFrame | dict:
+    """
+    Shows a list of audit activity events for a tenant.
+
+    This is a wrapper function for the following API: `Admin - Get Activity Events <https://learn.microsoft.com/rest/api/power-bi/admin/get-activity-events>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    start_time : str
+        Start date and time of the window for audit event results. Example: "2024-09-25T07:55:00".
+    end_time : str
+        End date and time of the window for audit event results. Example: "2024-09-25T08:55:00".
+    activity_filter : str, default=None
+        Filter value for activities. Example: 'viewreport'.
+    user_id_filter : str, default=None
+        Email address of the user.
+    return_dataframe : bool, default=True
+        If True the response is a pandas.DataFrame. If False returns the original Json. Default True
+
+    Returns
+    -------
+    pandas.DataFrame | dict
+        A pandas dataframe or json showing a list of audit activity events for a tenant.
+    """
+    start_dt = dtparser(start_time)
+    end_dt = dtparser(end_time)
+
+    if not start_dt.date() == end_dt.date():
+        raise ValueError(
+            f"{icons.red_dot} Start and End Times must be within the same UTC day. Please refer to the documentation here: https://learn.microsoft.com/rest/api/power-bi/admin/get-activity-events#get-audit-activity-events-within-a-time-window-and-for-a-specific-activity-type-and-user-id-example"
+        )
+
+    columns = {
+        "Id": "string",
+        "Record Type": "string",
+        "Creation Time": "datetime",
+        "Operation": "string",
+        "Organization Id": "string",
+        "User Type": "string",
+        "User Key": "string",
+        "Workload": "string",
+        "Result Status": "string",
+        "User Id": "string",
+        "Client IP": "string",
+        "User Agent": "string",
+        "Activity": "string",
+        "Workspace Name": "string",
+        "Workspace Id": "string",
+        "Object Id": "string",
+        "Request Id": "string",
+        "Object Type": "string",
+        "Object Display Name": "string",
+        "Experience": "string",
+        "Refresh Enforcement Policy": "string",
+        "Is Success": "bool",
+        "Activity Id": "string",
+        "Item Name": "string",
+        "Dataset Name": "string",
+        "Report Name": "string",
+        "Capacity Id": "string",
+        "Capacity Name": "string",
+        "App Name": "string",
+        "Dataset Id": "string",
+        "Report Id": "string",
+        "Artifact Id": "string",
+        "Artifact Name": "string",
+        "Report Type": "string",
+        "App Report Id": "string",
+        "Distribution Method": "string",
+        "Consumption Method": "string",
+        "Artifact Kind": "string",
+    }
+    df = _create_dataframe(columns=columns)
+
+    response_json = {"activityEventEntities": []}
+    url = f"/v1.0/myorg/admin/activityevents?startDateTime='{start_time}'&endDateTime='{end_time}'"
+
+    conditions = []
+    if activity_filter is not None:
+        conditions.append(f"Activity eq '{activity_filter}'")
+    if user_id_filter is not None:
+        conditions.append(f"UserId eq '{user_id_filter}'")
+
+    if conditions:
+        url += f"&$filter={f' and '.join(conditions)}"
+
+    responses = _base_api(request=url, client="fabric_sp", uses_pagination=True)
+
+    for r in responses:
+        if return_dataframe:
+            for i in r.get("activityEventEntities", []):
+                new_data = {
+                    "Id": i.get("id"),
+                    "Record Type": i.get("RecordType"),
+                    "Creation Time": i.get("CreationTime"),
+                    "Operation": i.get("Operation"),
+                    "Organization Id": i.get("OrganizationId"),
+                    "User Type": i.get("UserType"),
+                    "User Key": i.get("UserKey"),
+                    "Workload": i.get("Workload"),
+                    "Result Status": i.get("ResultStatus"),
+                    "User Id": i.get("UserId"),
+                    "Client IP": i.get("ClientIP"),
+                    "User Agent": i.get("UserAgent"),
+                    "Activity": i.get("Activity"),
+                    "Workspace Name": i.get("WorkSpaceName"),
+                    "Workspace Id": i.get("WorkspaceId"),
+                    "Object Id": i.get("ObjectId"),
+                    "Request Id": i.get("RequestId"),
+                    "Object Type": i.get("ObjectType"),
+                    "Object Display Name": i.get("ObjectDisplayName"),
+                    "Experience": i.get("Experience"),
+                    "Refresh Enforcement Policy": i.get("RefreshEnforcementPolicy"),
+                    "Is Success": i.get("IsSuccess"),
+                    "Activity Id": i.get("ActivityId"),
+                    "Item Name": i.get("ItemName"),
+                    "Dataset Name": i.get("DatasetName"),
+                    "Report Name": i.get("ReportName"),
+                    "Capacity Id": i.get("CapacityId"),
+                    "Capacity Name": i.get("CapacityName"),
+                    "App Name": i.get("AppName"),
+                    "Dataset Id": i.get("DatasetId"),
+                    "Report Id": i.get("ReportId"),
+                    "Artifact Id": i.get("ArtifactId"),
+                    "Artifact Name": i.get("ArtifactName"),
+                    "Report Type": i.get("ReportType"),
+                    "App Report Id": i.get("AppReportId"),
+                    "Distribution Method": i.get("DistributionMethod"),
+                    "Consumption Method": i.get("ConsumptionMethod"),
+                    "Artifact Kind": i.get("ArtifactKind"),
+                }
+                df = pd.concat(
+                    [df, pd.DataFrame(new_data, index=[0])],
+                    ignore_index=True,
+                )
+        else:
+            response_json["activityEventEntities"].extend(
+                r.get("activityEventEntities")
+            )
+
+    if return_dataframe:
+        _update_dataframe_datatypes(dataframe=df, column_map=columns)
+        return df
+    else:
+        return response_json

sempy_labs/admin/_apps.py

@@ -0,0 +1,143 @@
+import pandas as pd
+from typing import Optional
+from sempy_labs._helper_functions import (
+    _build_url,
+    _base_api,
+    _create_dataframe,
+    _update_dataframe_datatypes,
+    _is_valid_uuid,
+)
+from uuid import UUID
+import sempy_labs._icons as icons
+
+
+def list_apps(
+    top: Optional[int] = 1000,
+    skip: Optional[int] = None,
+) -> pd.DataFrame:
+    """
+    Shows a list of apps in the organization.
+
+    This is a wrapper function for the following API: `Admin - Apps GetAppsAsAdmin <https://learn.microsoft.com/rest/api/power-bi/admin/apps-get-apps-as-admin>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    top : int, default=1000
+        Returns only the first n results.
+    skip : int, default=None
+        Skips the first n results.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of apps in the organization.
+    """
+
+    columns = {
+        "App Name": "string",
+        "App Id": "string",
+        "Description": "string",
+        "Published By": "string",
+        "Last Update": "datetime_coerce",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    params = {}
+    url = "/v1.0/myorg/admin/apps"
+
+    params["$top"] = top
+
+    if skip is not None:
+        params["$skip"] = skip
+
+    url = _build_url(url, params)
+    response = _base_api(request=url, client="fabric_sp")
+
+    rows = []
+    for v in response.json().get("value", []):
+        rows.append(
+            {
+                "App Name": v.get("name"),
+                "App Id": v.get("id"),
+                "Description": v.get("description"),
+                "Published By": v.get("publishedBy"),
+                "Last Update": v.get("lastUpdate"),
+            }
+        )
+
+    if rows:
+        df = pd.DataFrame(rows, columns=list(columns.keys()))
+
+    _update_dataframe_datatypes(dataframe=df, column_map=columns)
+
+    return df
+
+
+def _resolve_app_id(app: str | UUID) -> str:
+    if _is_valid_uuid(app):
+        return app
+    else:
+        df = list_apps()
+        df_filt = df[df["App Name"] == app]
+        if df_filt.empty:
+            raise ValueError(f"{icons.red_dot} The '{app}' app does not exist.")
+        return df_filt["App Id"].iloc[0]
+
+
+def list_app_users(app: str | UUID) -> pd.DataFrame:
+    """
+    Shows a list of users that have access to the specified app.
+
+    This is a wrapper function for the following API: `Admin - Apps GetAppUsersAsAdmin <https://learn.microsoft.com/rest/api/power-bi/admin/apps-get-app-users-as-admin>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    app : str | uuid.UUID
+        The name or ID of the app.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of users that have access to the specified app.
+    """
+
+    app_id = _resolve_app_id(app)
+
+    columns = {
+        "User Name": "string",
+        "Email Address": "string",
+        "App User Access Right": "string",
+        "Identifier": "string",
+        "Graph Id": "string",
+        "Principal Type": "string",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    url = f"/v1.0/myorg/admin/apps/{app_id}/users"
+    response = _base_api(request=url, client="fabric_sp")
+
+    rows = []
+    for v in response.json().get("value", []):
+        rows.append(
+            {
+                "User Name": v.get("displayName"),
+                "Email Address": v.get("emailAddress"),
+                "App User Access Right": v.get("appUserAccessRight"),
+                "Identifier": v.get("identifier"),
+                "Graph Id": v.get("graphId"),
+                "Principal Type": v.get("principalType"),
+            }
+        )
+
+    if rows:
+        df = pd.DataFrame(rows, columns=list(columns.keys()))
+
+    _update_dataframe_datatypes(dataframe=df, column_map=columns)
+
+    return df