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

sempy_labs/admin/_capacities.py

@@ -0,0 +1,250 @@
+import pandas as pd
+from uuid import UUID
+import sempy_labs._icons as icons
+from typing import Optional, Tuple
+from sempy._utils._log import log
+from sempy_labs._helper_functions import (
+    _base_api,
+    _create_dataframe,
+    _update_dataframe_datatypes,
+    _is_valid_uuid,
+    get_capacity_id,
+)
+
+
+def patch_capacity(capacity: str | UUID, tenant_key_id: UUID):
+    """
+    Changes specific capacity information. Currently, this API call only supports changing the capacity's encryption key.
+
+    This is a wrapper function for the following API: `Admin - Patch Capacity As Admin <https://learn.microsoft.com/rest/api/power-bi/admin/patch-capacity-as-admin>`_.
+
+    Parameters
+    ----------
+    capacity : str | uuid.UUID
+        The name or ID of the capacity.
+    tenant_key_id : str
+        The ID of the encryption key.
+    """
+
+    (capacity_name, capacity_id) = _resolve_capacity_name_and_id(capacity)
+
+    payload = {
+        "tenantKeyId": tenant_key_id,
+    }
+
+    _base_api(
+        request=f"/v1.0/myorg/admin/capacities/{capacity_id}",
+        method="patch",
+        payload=payload,
+    )
+
+    print(
+        f"{icons.green_dot} The capacity '{capacity_name}' has been successfully patched."
+    )
+
+
+def _resolve_capacity_name_and_id(
+    capacity: str | UUID,
+) -> Tuple[str, UUID]:
+
+    dfC = list_capacities(capacity=capacity)
+    if dfC.empty:
+        raise ValueError(f"{icons.red_dot} The '{capacity}' capacity was not found.")
+
+    capacity_name = dfC["Capacity Name"].iloc[0]
+    capacity_id = dfC["Capacity Id"].iloc[0]
+
+    return capacity_name, capacity_id
+
+
+def _list_capacities_meta() -> pd.DataFrame:
+    """
+    Shows the a list of capacities and their properties. This function is the admin version.
+
+    This is a wrapper function for the following API: `Admin - Get Capacities As Admin <https://learn.microsoft.com/rest/api/power-bi/admin/get-capacities-as-admin>`_.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing the capacities and their properties
+    """
+
+    columns = {
+        "Capacity Id": "string",
+        "Capacity Name": "string",
+        "Sku": "string",
+        "Region": "string",
+        "State": "string",
+        "Admins": "string",
+    }
+    df = _create_dataframe(columns=columns)
+
+    responses = _base_api(
+        request="/v1.0/myorg/admin/capacities", client="fabric_sp", uses_pagination=True
+    )
+
+    for r in responses:
+        for i in r.get("value", []):
+            new_data = {
+                "Capacity Id": i.get("id").lower(),
+                "Capacity Name": i.get("displayName"),
+                "Sku": i.get("sku"),
+                "Region": i.get("region"),
+                "State": i.get("state"),
+                "Admins": [i.get("admins", [])],
+            }
+            df = pd.concat([df, pd.DataFrame(new_data, index=[0])], ignore_index=True)
+
+    return df
+
+
+def get_capacity_assignment_status(
+    workspace: Optional[str | UUID] = None,
+) -> pd.DataFrame:
+    """
+    Gets the status of the assignment-to-capacity operation for the specified workspace.
+
+    This is a wrapper function for the following API: `Capacities - Groups CapacityAssignmentStatus <https://learn.microsoft.com/rest/api/power-bi/capacities/groups-capacity-assignment-status>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    workspace : str | uuid.UUID, default=None
+        The 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
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing the status of the assignment-to-capacity operation for the specified workspace.
+    """
+    from sempy_labs.admin._basic_functions import _resolve_workspace_name_and_id
+
+    (workspace_name, workspace_id) = _resolve_workspace_name_and_id(workspace)
+
+    columns = {
+        "Status": "string",
+        "Activity Id": "string",
+        "Start Time": "datetime",
+        "End Time": "datetime",
+        "Capacity Id": "string",
+        "Capacity Name": "string",
+    }
+    df = _create_dataframe(columns=columns)
+
+    response = _base_api(
+        request=f"/v1.0/myorg/groups/{workspace_id}/CapacityAssignmentStatus",
+        client="fabric_sp",
+    )
+    v = response.json()
+    capacity_id = v.get("capacityId")
+
+    (capacity_name, capacity_id) = _resolve_capacity_name_and_id(capacity=capacity_id)
+
+    new_data = {
+        "Status": v.get("status"),
+        "Activity Id": v.get("activityId"),
+        "Start Time": v.get("startTime"),
+        "End Time": v.get("endTime"),
+        "Capacity Id": capacity_id,
+        "Capacity Name": capacity_name,
+    }
+
+    df = pd.concat([df, pd.DataFrame([new_data])], ignore_index=True)
+
+    _update_dataframe_datatypes(dataframe=df, column_map=columns)
+
+    return df
+
+
+def get_capacity_state(capacity: Optional[str | UUID] = None):
+    """
+    Gets the state of a capacity.
+
+    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, default=None
+        The capacity name or ID.
+        Defaults to None which resolves to the capacity of the attached lakehouse
+        or if no lakehouse is attached, resolves to the workspace of the notebook.
+
+    Returns
+    -------
+    str
+        The capacity state.
+    """
+
+    df = list_capacities()
+
+    if capacity is None:
+        capacity = get_capacity_id()
+    if _is_valid_uuid(capacity):
+        df_filt = df[df["Capacity Id"] == capacity]
+    else:
+        df_filt = df[df["Capacity Name"] == capacity]
+
+    if df_filt.empty:
+        raise ValueError(f"{icons.red_dot} The capacity '{capacity}' was not found.")
+
+    return df_filt["State"].iloc[0]
+
+
+@log
+def list_capacities(
+    capacity: Optional[str | UUID] = None,
+) -> pd.DataFrame:
+    """
+    Shows the a list of capacities and their properties.
+
+    This is a wrapper function for the following API: `Admin - Get Capacities As Admin <https://learn.microsoft.com/rest/api/power-bi/admin/get-capacities-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, default=None
+        The capacity name or ID to filter. If None, all capacities are returned.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing the capacities and their properties.
+    """
+
+    columns = {
+        "Capacity Id": "string",
+        "Capacity Name": "string",
+        "Sku": "string",
+        "Region": "string",
+        "State": "string",
+        "Admins": "string",
+    }
+    df = _create_dataframe(columns=columns)
+
+    responses = _base_api(
+        request="/v1.0/myorg/admin/capacities", client="fabric_sp", uses_pagination=True
+    )
+
+    for r in responses:
+        for i in r.get("value", []):
+            new_data = {
+                "Capacity Id": i.get("id").lower(),
+                "Capacity Name": i.get("displayName"),
+                "Sku": i.get("sku"),
+                "Region": i.get("region"),
+                "State": i.get("state"),
+                "Admins": [i.get("admins", [])],
+            }
+            df = pd.concat([df, pd.DataFrame(new_data, index=[0])], ignore_index=True)
+
+    if capacity is not None:
+        if _is_valid_uuid(capacity):
+            df = df[df["Capacity Id"] == capacity.lower()]
+        else:
+            df = df[df["Capacity Name"] == capacity]
+
+    return df

sempy_labs/admin/_datasets.py

@@ -0,0 +1,184 @@
+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_datasets(
+    top: Optional[int] = None,
+    filter: Optional[str] = None,
+    skip: Optional[int] = None,
+) -> pd.DataFrame:
+    """
+    Shows a list of datasets for the organization.
+
+    This is a wrapper function for the following API: `Admin - Datasets GetDatasetsAsAdmin <https://learn.microsoft.com/rest/api/power-bi/admin/datasets-get-datasets-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=None
+        Returns only the first n results.
+    filter : str, default=None
+        Returns a subset of a results based on Odata filter query parameter condition.
+    skip : int, default=None
+        Skips the first n results.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of datasets for the organization.
+    """
+
+    columns = {
+        "Dataset Id": "string",
+        "Dataset Name": "string",
+        "Web URL": "string",
+        "Add Rows API Enabled": "bool",
+        "Configured By": "string",
+        "Is Refreshable": "bool",
+        "Is Effective Identity Required": "bool",
+        "Is Effective Identity Roles Required": "bool",
+        "Target Storage Mode": "string",
+        "Created Date": "datetime",
+        "Content Provider Type": "string",
+        "Create Report Embed URL": "string",
+        "QnA Embed URL": "string",
+        "Upstream Datasets": "string",
+        "Users": "string",
+        "Is In Place Sharing Enabled": "bool",
+        "Workspace Id": "string",
+        "Auto Sync Read Only Replicas": "bool",
+        "Max Read Only Replicas": "int",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    params = {}
+    url = "/v1.0/myorg/admin/datasets"
+
+    if top is not None:
+        params["$top"] = top
+
+    if filter is not None:
+        params["$filter"] = filter
+
+    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(
+            {
+                "Dataset Id": v.get("id"),
+                "Dataset Name": v.get("name"),
+                "Web URL": v.get("webUrl"),
+                "Add Rows API Enabled": v.get("addRowsAPIEnabled"),
+                "Configured By": v.get("configuredBy"),
+                "Is Refreshable": v.get("isRefreshable"),
+                "Is Effective Identity Required": v.get("isEffectiveIdentityRequired"),
+                "Is Effective Identity Roles Required": v.get(
+                    "isEffectiveIdentityRolesRequired"
+                ),
+                "Target Storage Mode": v.get("targetStorageMode"),
+                "Created Date": pd.to_datetime(v.get("createdDate")),
+                "Content Provider Type": v.get("contentProviderType"),
+                "Create Report Embed URL": v.get("createReportEmbedURL"),
+                "QnA Embed URL": v.get("qnaEmbedURL"),
+                "Upstream Datasets": v.get("upstreamDatasets", []),
+                "Users": v.get("users", []),
+                "Is In Place Sharing Enabled": v.get("isInPlaceSharingEnabled"),
+                "Workspace Id": v.get("workspaceId"),
+                "Auto Sync Read Only Replicas": v.get("queryScaleOutSettings", {}).get(
+                    "autoSyncReadOnlyReplicas"
+                ),
+                "Max Read Only Replicas": v.get("queryScaleOutSettings", {}).get(
+                    "maxReadOnlyReplicas"
+                ),
+            }
+        )
+
+    if rows:
+        df = pd.DataFrame(rows, columns=list(columns.keys()))
+
+    _update_dataframe_datatypes(dataframe=df, column_map=columns)
+
+    return df
+
+
+def _resolve_dataset_id(dataset: str | UUID) -> str:
+    if _is_valid_uuid(dataset):
+        return dataset
+    else:
+        df = list_datasets()
+        df_filt = df[df["Dataset Name"] == dataset]
+        if df_filt.empty:
+            raise ValueError(f"{icons.red_dot} The '{dataset}' dataset does not exist.")
+        return df_filt["Dataset Id"].iloc[0]
+
+
+def list_dataset_users(dataset: str | UUID) -> pd.DataFrame:
+    """
+    Shows a list of users that have access to the specified dataset.
+
+    This is a wrapper function for the following API: `Admin - Datasets GetDatasetUsersAsAdmin <https://learn.microsoft.com/rest/api/power-bi/admin/datasets-get-dataset-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
+    ----------
+    dataset : str | uuid.UUID
+        The name or ID of the dataset.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of users that have access to the specified dataset.
+    """
+
+    dataset_id = _resolve_dataset_id(dataset)
+
+    columns = {
+        "User Name": "string",
+        "Email Address": "string",
+        "Dataset User Access Right": "string",
+        "Identifier": "string",
+        "Graph Id": "string",
+        "Principal Type": "string",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    url = f"/v1.0/myorg/admin/datasets/{dataset_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"),
+                "Dataset User Access Right": v.get("datasetUserAccessRight"),
+                "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

sempy_labs/admin/_domains.py

@@ -319,7 +319,7 @@ def assign_domain_workspaces_by_capacities(
         The capacity names.
     """
 
-    from sempy_labs.admin import list_capacities
+    from sempy_labs.admin._capacities import list_capacities
 
     if "domain_name" in kwargs:
         domain = kwargs["domain_name"]

sempy_labs/admin/_items.py

@@ -3,9 +3,11 @@ from typing import Optional, Tuple
 from uuid import UUID
 import sempy_labs._icons as icons
 from sempy_labs.admin._basic_functions import (
-    _resolve_capacity_name_and_id,
     _resolve_workspace_name_and_id,
 )
+from sempy_labs.admin._capacities import (
+    _resolve_capacity_name_and_id,
+)
 from sempy_labs._helper_functions import (
     _is_valid_uuid,
     _build_url,

sempy_labs/admin/_reports.py

@@ -0,0 +1,165 @@
+import pandas as pd
+from typing import Optional
+from sempy_labs._helper_functions import (
+    _base_api,
+    _create_dataframe,
+    _update_dataframe_datatypes,
+    _is_valid_uuid,
+)
+from uuid import UUID
+import sempy_labs._icons as icons
+
+
+def list_reports(
+    top: Optional[int] = None,
+    skip: Optional[int] = None,
+    filter: Optional[str] = None,
+) -> pd.DataFrame:
+    """
+    Shows a list of reports for the organization.
+
+    This is a wrapper function for the following API: `Admin - Reports GetReportsAsAdmin <https://learn.microsoft.com/rest/api/power-bi/admin/reports-get-reports-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=None
+        Returns only the first n results.
+    skip : int, default=None
+        Skips the first n results.
+    filter : str, default=None
+        Returns a subset of a results based on Odata filter query parameter condition.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of reports for the organization.
+    """
+
+    columns = {
+        "Report Id": "string",
+        "Report Name": "string",
+        "Type": "string",
+        "Web URL": "string",
+        "Embed URL": "string",
+        "Dataset Id": "string",
+        "Created Date": "datetime_coerce",
+        "Modified Date": "datetime_coerce",
+        "Created By": "string",
+        "Modified By": "string",
+        "Sensitivity Label Id": "string",
+        "Users": "string",
+        "Subscriptions": "string",
+        "Workspace Id": "string",
+        "Report Flags": "int",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    url = "/v1.0/myorg/admin/reports?"
+    if top is not None:
+        url += f"$top={top}&"
+    if skip is not None:
+        url += f"$skip={skip}&"
+    if filter is not None:
+        url += f"$filter={filter}&"
+
+    url.rstrip("$").rstrip("?")
+    response = _base_api(request=url, client="fabric_sp")
+    rows = []
+
+    for v in response.json().get("value", []):
+        rows.append(
+            {
+                "Report Id": v.get("id"),
+                "Report Name": v.get("name"),
+                "Type": v.get("reportType"),
+                "Web URL": v.get("webUrl"),
+                "Embed URL": v.get("embedUrl"),
+                "Dataset Id": v.get("datasetId"),
+                "Created Date": v.get("createdDateTime"),
+                "Modified Date": v.get("modifiedDateTime"),
+                "Created By": v.get("createdBy"),
+                "Modified By": v.get("modifiedBy"),
+                "Sensitivity Label Id": v.get("sensitivityLabel", {}).get("labelId"),
+                "Users": v.get("users"),
+                "Subscriptions": v.get("subscriptions"),
+                "Workspace Id": v.get("workspaceId"),
+                "Report Flags": v.get("reportFlags"),
+            }
+        )
+
+    if rows:
+        df = pd.DataFrame(rows, columns=list(columns.keys()))
+
+    _update_dataframe_datatypes(dataframe=df, column_map=columns)
+
+    return df
+
+
+def _resolve_report_id(report: str | UUID) -> str:
+    if _is_valid_uuid(report):
+        return report
+    else:
+        df = list_reports()
+        df_filt = df[df["Report Name"] == report]
+        if df_filt.empty:
+            raise ValueError(f"{icons.red_dot} The '{report}' report does not exist.")
+        return df_filt["Report Id"].iloc[0]
+
+
+def list_report_users(report: str | UUID) -> pd.DataFrame:
+    """
+    Shows a list of users that have access to the specified report.
+
+    This is a wrapper function for the following API: `Admin - Reports GetDatasetUsersAsAdmin <https://learn.microsoft.com/rest/api/power-bi/admin/datasets-get-report-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
+    ----------
+    report : str | uuid.UUID
+        The name or ID of the report.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of users that have access to the specified report.
+    """
+
+    report_id = _resolve_report_id(report)
+
+    columns = {
+        "User Name": "string",
+        "Email Address": "string",
+        "Report User Access Right": "string",
+        "Identifier": "string",
+        "Graph Id": "string",
+        "Principal Type": "string",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    url = f"/v1.0/myorg/admin/reports/{report_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"),
+                "Report User Access Right": v.get("reportUserAccessRight"),
+                "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

sempy_labs/admin/_scanner.py

@@ -2,7 +2,6 @@ import sempy.fabric as fabric
 from typing import Optional, List
 from uuid import UUID
 from sempy.fabric.exceptions import FabricHTTPException
-import numpy as np
 import time
 import sempy_labs._icons as icons
 from sempy_labs.admin._basic_functions import list_workspaces