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

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,3 +1,15 @@
+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,
 )
@@ -12,6 +24,7 @@ from sempy_labs.admin._apps import (
 from sempy_labs.admin._reports import (
     list_reports,
     list_report_users,
+    list_report_subscriptions,
 )
 from sempy_labs.admin._activities import (
     list_activity_events,
@@ -24,6 +37,7 @@ from sempy_labs.admin._capacities import (
     list_capacities,
     get_capacity_assignment_status,
     get_capacity_state,
+    list_capacity_users,
 )
 from sempy_labs.admin._tenant import (
     list_tenant_settings,
@@ -41,7 +55,6 @@ from sempy_labs.admin._basic_functions import (
     list_workspaces,
     list_workspace_access_details,
     list_modified_workspaces,
-    list_access_entities,
     list_workspace_users,
 )
 from sempy_labs.admin._domains import (
@@ -113,4 +126,11 @@ __all__ = [
     "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/_apps.py

@@ -40,7 +40,7 @@ def list_apps(
         "App Id": "string",
         "Description": "string",
         "Published By": "string",
-        "Last Update": "datetime",
+        "Last Update": "datetime_coerce",
     }
 
     df = _create_dataframe(columns=columns)

sempy_labs/admin/_artifacts.py

@@ -0,0 +1,62 @@
+import pandas as pd
+from sempy_labs._helper_functions import (
+    _base_api,
+)
+from uuid import UUID
+from typing import Optional
+from sempy_labs.admin._basic_functions import (
+    _resolve_workspace_name_and_id,
+    _create_dataframe,
+    _update_dataframe_datatypes,
+)
+
+
+def list_unused_artifacts(workspace: Optional[str | UUID] = None) -> pd.DataFrame:
+    """
+    Returns a list of datasets, reports, and dashboards that have not been used within 30 days for the specified workspace.
+
+    This is a wrapper function for the following API: `Admin - Groups GetUnusedArtifactsAsAdmin <https://learn.microsoft.com/rest/api/power-bi/admin/groups-get-unused-artifacts-as-admin>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of datasets, reports, and dashboards that have not been used within 30 days for the specified workspace.
+    """
+
+    (workspace_name, workspace_id) = _resolve_workspace_name_and_id(workspace)
+
+    columns = {
+        "Artifact Name": "string",
+        "Artifact Id": "string",
+        "Artifact Type": "string",
+        "Artifact Size in MB": "int",
+        "Created Date Time": "datetime",
+        "Last Accessed Date Time": "datetime",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    responses = _base_api(
+        request=f"/v1.0/myorg/admin/groups/{workspace_id}/unused",
+        client="fabric_sp",
+        uses_pagination=True,
+    )
+
+    for r in responses:
+        for i in r.get("unusedArtifactEntities", []):
+            new_data = {
+                "Artifact Name": i.get("artifactId"),
+                "Artifact Id": i.get("displayName"),
+                "Artifact Type": i.get("artifactType"),
+                "Artifact Size in MB": i.get("artifactSizeInMB"),
+                "Created Date Time": i.get("createdDateTime"),
+                "Last Accessed Date Time": i.get("lastAccessedDateTime"),
+            }
+
+            df = pd.concat([df, pd.DataFrame(new_data, index=[0])], ignore_index=True)
+
+    _update_dataframe_datatypes(dataframe=df, column_map=columns)
+
+    return df

sempy_labs/admin/_basic_functions.py

@@ -298,58 +298,6 @@ def list_modified_workspaces(
     return df
 
 
-def list_access_entities(
-    user_email_address: str,
-) -> pd.DataFrame:
-    """
-    Shows a list of permission details for Fabric and Power BI items the specified user can access.
-
-    This is a wrapper function for the following API: `Users - List Access Entities <https://learn.microsoft.com/rest/api/fabric/admin/users/list-access-entities>`_.
-
-    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
-
-    Parameters
-    ----------
-    user_email_address : str
-        The user's email address.
-
-    Returns
-    -------
-    pandas.DataFrame
-        A pandas dataframe showing a list of permission details for Fabric and Power BI items the specified user can access.
-    """
-
-    columns = {
-        "Item Id": "string",
-        "Item Name": "string",
-        "Item Type": "string",
-        "Permissions": "string",
-        "Additional Permissions": "string",
-    }
-    df = _create_dataframe(columns=columns)
-
-    responses = _base_api(
-        request=f"/v1/admin/users/{user_email_address}/access",
-        client="fabric_sp",
-        uses_pagination=True,
-    )
-
-    for r in responses:
-        for v in r.get("accessEntities", []):
-            new_data = {
-                "Item Id": v.get("id"),
-                "Item Name": v.get("displayName"),
-                "Item Type": v.get("itemAccessDetails", {}).get("type"),
-                "Permissions": v.get("itemAccessDetails", {}).get("permissions"),
-                "Additional Permissions": v.get("itemAccessDetails", {}).get(
-                    "additionalPermissions"
-                ),
-            }
-            df = pd.concat([df, pd.DataFrame([new_data])], ignore_index=True)
-
-    return df
-
-
 def list_workspace_access_details(
     workspace: Optional[Union[str, UUID]] = None,
 ) -> pd.DataFrame:

sempy_labs/admin/_capacities.py

@@ -248,3 +248,64 @@ def list_capacities(
             df = df[df["Capacity Name"] == capacity]
 
     return df
+
+
+def list_capacity_users(capacity: str | UUID) -> pd.DataFrame:
+    """
+    Shows a list of users that have access to the specified workspace.
+
+    This is a wrapper function for the following API: `Admin - Capacities GetCapacityUsersAsAdmin <https://learn.microsoft.com/rest/api/power-bi/admin/capacities-get-capacity-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
+    ----------
+    capacity : str | uuid.UUID
+        The name or ID of the capacity.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of users that have access to the specified workspace.
+    """
+
+    (capacity_name, capacity_id) = _resolve_capacity_name_and_id(capacity)
+
+    columns = {
+        "User Name": "string",
+        "Email Address": "string",
+        "Capacity User Access Right": "string",
+        "Identifier": "string",
+        "Graph Id": "string",
+        "Principal Type": "string",
+        "User Type": "string",
+        "Profile": "string",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    response = _base_api(
+        request=f"/v1.0/myorg/admin/capacities/{capacity_id}/users", client="fabric_sp"
+    )
+
+    rows = []
+    for v in response.json().get("value", []):
+        rows.append(
+            {
+                "User Name": v.get("displayName"),
+                "Email Address": v.get("emailAddress"),
+                "Capacity User Access Right": v.get("capacityUserAccessRight"),
+                "Identifier": v.get("identifier"),
+                "Graph Id": v.get("graphId"),
+                "Principal Type": v.get("principalType"),
+                "User Type": v.get("userType"),
+                "Profile": v.get("profile"),
+            }
+        )
+
+    if rows:
+        df = pd.DataFrame(rows, columns=list(columns.keys()))
+
+    _update_dataframe_datatypes(dataframe=df, column_map=columns)
+
+    return df

sempy_labs/admin/_reports.py

@@ -163,3 +163,77 @@ def list_report_users(report: str | UUID) -> pd.DataFrame:
     _update_dataframe_datatypes(dataframe=df, column_map=columns)
 
     return df
+
+
+def list_report_subscriptions(report: str | UUID) -> pd.DataFrame:
+    """
+    Shows a list of report subscriptions along with subscriber details. This is a preview API call.
+
+    This is a wrapper function for the following API: `Admin - Reports GetReportSubscriptionsAsAdmin <https://learn.microsoft.com/rest/api/power-bi/admin/reports-get-report-subscriptions-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
+    ----------
+    report : str | uuid.UUID
+        The name or ID of the report.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of report subscriptions along with subscriber details. This is a preview API call.
+    """
+
+    report_id = _resolve_report_id(report)
+
+    columns = {
+        "Subscription Id": "string",
+        "Title": "string",
+        "Artifact Id": "string",
+        "Artifact Name": "string",
+        "Sub Artifact Name": "string",
+        "Artifact Type": "string",
+        "Is Enabled": "bool",
+        "Frequency": "string",
+        "Start Date": "datetime",
+        "End Date": "string",
+        "Link To Content": "bool",
+        "Preview Image": "bool",
+        "Attachment Format": "string",
+        "Users": "string",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    response = _base_api(
+        request=f"/v1.0/myorg/admin/reports/{report_id}/subscriptions",
+        client="fabric_sp",
+    )
+
+    rows = []
+    for v in response.json().get("value", []):
+        rows.append(
+            {
+                "Subscription Id": v.get("id"),
+                "Title": v.get("title"),
+                "Artifact Id": v.get("artifactId"),
+                "Artifact Name": v.get("artifactDisplayName"),
+                "Sub Artifact Name": v.get("subArtifactDisplayName"),
+                "Artifact Type": v.get("artifactType"),
+                "Is Enabled": v.get("isEnabled"),
+                "Frequency": v.get("frequency"),
+                "Start Date": v.get("startDate"),
+                "End Date": v.get("endDate"),
+                "Link To Content": v.get("linkToContent"),
+                "Preview Image": v.get("previewImage"),
+                "Attachment Format": v.get("attachmentFormat"),
+                "Users": str(v.get("users")),
+            }
+        )
+
+    if rows:
+        df = pd.DataFrame(rows, columns=list(columns.keys()))
+
+    _update_dataframe_datatypes(dataframe=df, column_map=columns)
+
+    return df

sempy_labs/admin/_shared.py

@@ -50,11 +50,13 @@ def list_widely_shared_artifacts(
     )
 
     responses = _base_api(
-        request=f"/v1.0/myorg/admin/widelySharedArtifacts/{api}", client="fabric_sp"
+        request=f"/v1.0/myorg/admin/widelySharedArtifacts/{api}",
+        client="fabric_sp",
+        uses_pagination=True,
     )
 
     for r in responses:
-        for v in r.get("value", []):
+        for v in r.get("ArtifactAccessEntities", []):
             sharer = v.get("sharer", {})
             new_data = {
                 "Artifact Id": v.get("artifactId"),