semantic-link-labs 0.7.4__py3-none-any.whl → 0.8.1__py3-none-any.whl

sempy_labs/admin/_domains.py

@@ -0,0 +1,411 @@
+import sempy.fabric as fabric
+from typing import Optional, List
+import sempy_labs._icons as icons
+from sempy_labs._helper_functions import lro
+from sempy.fabric.exceptions import FabricHTTPException
+import pandas as pd
+from uuid import UUID
+
+
+def resolve_domain_id(domain_name: str) -> UUID:
+    """
+    Obtains the domain Id for a given domain name.
+
+    Parameters
+    ----------
+    domain_name : str
+        The domain name
+
+    Returns
+    -------
+    UUID
+        The domain Id.
+    """
+
+    dfL = list_domains()
+    dfL_filt = dfL[dfL["Domain Name"] == domain_name]
+    if len(dfL_filt) == 0:
+        raise ValueError(f"{icons.red_dot} '{domain_name}' is not a valid domain name.")
+
+    return dfL_filt["Domain ID"].iloc[0]
+
+
+def list_domains(non_empty_only: bool = False) -> pd.DataFrame:
+    """
+    Shows a list of domains.
+
+    Parameters
+    ----------
+    non_empty_only : bool, default=False
+        When True, only return domains that have at least one workspace containing an item.
+        Defaults to False.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of the domains.
+    """
+
+    # https://learn.microsoft.com/en-us/rest/api/fabric/admin/domains/list-domains?tabs=HTTP
+
+    df = pd.DataFrame(
+        columns=[
+            "Domain ID",
+            "Domain Name",
+            "Description",
+            "Parent Domain ID",
+            "Contributors Scope",
+        ]
+    )
+
+    client = fabric.FabricRestClient()
+    url = "/v1/admin/domains"
+    if non_empty_only:
+        url = f"{url}?nonEmptyOnly=True"
+    response = client.get(url)
+
+    if response.status_code != 200:
+        raise FabricHTTPException(response)
+
+    for v in response.json().get("domains", []):
+        new_data = {
+            "Domain ID": v.get("id"),
+            "Domain Name": v.get("displayName"),
+            "Description": v.get("description"),
+            "Parent Domain ID": v.get("parentDomainId"),
+            "Contributors Scope": v.get("contributorsScope"),
+        }
+        df = pd.concat([df, pd.DataFrame(new_data, index=[0])], ignore_index=True)
+
+    return df
+
+
+def list_domain_workspaces(domain_name: str) -> pd.DataFrame:
+    """
+    Shows a list of workspaces within the domain.
+
+    Parameters
+    ----------
+    domain_name : str
+        The domain name.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of workspaces within the domain.
+    """
+
+    # https://learn.microsoft.com/en-us/rest/api/fabric/admin/domains/list-domain-workspaces?tabs=HTTP
+
+    domain_id = resolve_domain_id(domain_name)
+
+    df = pd.DataFrame(columns=["Workspace ID", "Workspace Name"])
+
+    client = fabric.FabricRestClient()
+    response = client.get(f"/v1/admin/domains/{domain_id}/workspaces")
+
+    if response.status_code != 200:
+        raise FabricHTTPException(response)
+
+    for v in response.json().get("value", []):
+        new_data = {
+            "Workspace ID": v.get("id"),
+            "Workspace Name": v.get("displayName"),
+        }
+        df = pd.concat([df, pd.DataFrame(new_data, index=[0])], ignore_index=True)
+
+    return df
+
+
+def create_domain(
+    domain_name: str,
+    description: Optional[str] = None,
+    parent_domain_name: Optional[str] = None,
+):
+    """
+    Creates a new domain.
+
+    Parameters
+    ----------
+    domain_name : str
+        The domain name.
+    description : str, default=None
+        The domain description.
+    parent_domain_name : str, default=None
+        The parent domain name.
+    """
+
+    # https://learn.microsoft.com/en-us/rest/api/fabric/admin/domains/create-domain?tabs=HTTP
+
+    if parent_domain_name is not None:
+        parent_domain_id = resolve_domain_id(parent_domain_name)
+
+    payload = {}
+    payload["displayName"] = domain_name
+    if description is not None:
+        payload["description"] = description
+    if parent_domain_name is not None:
+        payload["parentDomainId"] = parent_domain_id
+
+    client = fabric.FabricRestClient()
+    response = client.post("/v1/admin/domains", json=payload)
+
+    if response.status_code != 201:
+        raise FabricHTTPException(response)
+
+    print(f"{icons.green_dot} The '{domain_name}' domain has been created.")
+
+
+def delete_domain(domain_name: str):
+    """
+    Deletes a domain.
+
+    Parameters
+    ----------
+    domain_name : str
+        The domain name.
+    """
+
+    # https://learn.microsoft.com/en-us/rest/api/fabric/admin/domains/delete-domain?tabs=HTTP
+
+    domain_id = resolve_domain_id(domain_name)
+
+    client = fabric.FabricRestClient()
+    response = client.delete(f"/v1/admin/domains/{domain_id}")
+
+    if response.status_code != 200:
+        raise FabricHTTPException(response)
+
+    print(f"{icons.green_dot} The '{domain_name}' domain has been deleted.")
+
+
+def update_domain(
+    domain_name: str,
+    description: Optional[str] = None,
+    contributors_scope: Optional[str] = None,
+):
+    """
+    Updates a domain's properties.
+
+    Parameters
+    ----------
+    domain_name : str
+        The domain name.
+    description : str, default=None
+        The domain description.
+    contributors_scope : str, default=None
+        The domain `contributor scope <https://learn.microsoft.com/rest/api/fabric/admin/domains/update-domain?tabs=HTTP#contributorsscopetype>`_.
+    """
+
+    # https://learn.microsoft.com/en-us/rest/api/fabric/admin/domains/update-domain?tabs=HTTP
+
+    contributors_scopes = ["AdminsOnly", "AllTenant", "SpecificUsersAndGroups"]
+
+    if contributors_scope not in contributors_scopes:
+        raise ValueError(
+            f"{icons.red_dot} Invalid contributors scope. Valid options: {contributors_scopes}."
+        )
+
+    domain_id = resolve_domain_id(domain_name)
+
+    payload = {}
+    payload["displayName"] = domain_name
+
+    if description is not None:
+        payload["description"] = description
+    if contributors_scope is not None:
+        payload["contributorsScope"] = contributors_scope
+
+    client = fabric.FabricRestClient()
+    response = client.patch(f"/v1/admin/domains/{domain_id}", json=payload)
+
+    if response != 200:
+        raise FabricHTTPException(response)
+
+    print(f"{icons.green_dot} The '{domain_name}' domain has been updated.")
+
+
+def assign_domain_workspaces_by_capacities(
+    domain_name: str, capacity_names: str | List[str]
+):
+    """
+    Assigns all workspaces that reside on the specified capacities to the specified domain.
+
+    Parameters
+    ----------
+    domain_name : str
+        The domain name.
+    capacity_names : str | List[str]
+        The capacity names.
+    """
+
+    # https://learn.microsoft.com/en-us/rest/api/fabric/admin/domains/assign-domain-workspaces-by-capacities?tabs=HTTP
+
+    from sempy_labs.admin import list_capacities
+
+    domain_id = resolve_domain_id(domain_name)
+
+    if isinstance(capacity_names, str):
+        capacity_names = [capacity_names]
+
+    dfC = list_capacities()
+
+    # Check for invalid capacities
+    invalid_capacities = [
+        name for name in capacity_names if name not in dfC["Display Name"].values
+    ]
+
+    if len(invalid_capacities) == 1:
+        raise ValueError(
+            f"{icons.red_dot} The {invalid_capacities} capacity is not valid."
+        )
+    elif len(invalid_capacities) > 1:
+        raise ValueError(
+            f"{icons.red_dot} The {invalid_capacities} capacities are not valid."
+        )
+
+    # Get list of capacity Ids for the payload
+    dfC_filt = dfC[dfC["Display Name"].isin(capacity_names)]
+    capacity_list = list(dfC_filt["Id"].str.upper())
+
+    payload = {"capacitiesIds": capacity_list}
+
+    client = fabric.FabricRestClient()
+    response = client.post(
+        f"/v1/admin/domains/{domain_id}/assignWorkspacesByCapacities",
+        json=payload,
+    )
+
+    lro(client, response)
+
+    print(
+        f"{icons.green_dot} The workspaces in the {capacity_names} capacities have been assigned to the '{domain_name}' domain."
+    )
+
+
+def assign_domain_workspaces(domain_name: str, workspace_names: str | List[str]):
+    """
+    Assigns workspaces to the specified domain by workspace.
+
+    Parameters
+    ----------
+    domain_name : str
+        The domain name.
+    workspace_names : str | List[str]
+        The Fabric workspace(s).
+    """
+
+    # https://learn.microsoft.com/en-us/rest/api/fabric/admin/domains/assign-domain-workspaces-by-ids?tabs=HTTP
+
+    domain_id = resolve_domain_id(domain_name=domain_name)
+
+    if isinstance(workspace_names, str):
+        workspace_names = [workspace_names]
+
+    dfW = fabric.list_workspaces()
+
+    # Check for invalid capacities
+    invalid_workspaces = [
+        name for name in workspace_names if name not in dfW["Name"].values
+    ]
+
+    if len(invalid_workspaces) == 1:
+        raise ValueError(
+            f"{icons.red_dot} The {invalid_workspaces} workspace is not valid."
+        )
+    elif len(invalid_workspaces) > 1:
+        raise ValueError(
+            f"{icons.red_dot} The {invalid_workspaces} workspaces are not valid."
+        )
+
+    dfW_filt = dfW[dfW["Name"].isin(workspace_names)]
+    workspace_list = list(dfW_filt["Id"])
+
+    payload = {"workspacesIds": workspace_list}
+
+    client = fabric.FabricRestClient()
+    response = client.post(
+        f"/v1/admin/domains/{domain_id}/assignWorkspaces",
+        json=payload,
+    )
+
+    lro(client, response)
+
+    print(
+        f"{icons.green_dot} The {workspace_names} workspaces have been assigned to the '{domain_name}' domain."
+    )
+
+
+def unassign_all_domain_workspaces(domain_name: str):
+    """
+    Unassigns all workspaces from the specified domain.
+
+    Parameters
+    ----------
+    domain_name : str
+        The domain name.
+    """
+
+    # https://learn.microsoft.com/en-us/rest/api/fabric/admin/domains/unassign-all-domain-workspaces?tabs=HTTP
+
+    domain_id = resolve_domain_id(domain_name=domain_name)
+
+    client = fabric.FabricRestClient()
+    response = client.post(f"/v1/admin/domains/{domain_id}/unassignAllWorkspaces")
+
+    if response.status_code != 200:
+        raise FabricHTTPException(response)
+    print(
+        f"{icons.green_dot} All workspaces assigned to the '{domain_name}' domain have been unassigned."
+    )
+
+
+def unassign_domain_workspaces(domain_name: str, workspace_names: str | List[str]):
+    """
+    Unassigns workspaces from the specified domain by workspace.
+
+    Parameters
+    ----------
+    domain_name : str
+        The domain name.
+    workspace_names : str | List[str]
+        The Fabric workspace(s).
+    """
+
+    # https://learn.microsoft.com/en-us/rest/api/fabric/admin/domains/unassign-domain-workspaces-by-ids?tabs=HTTP
+
+    domain_id = resolve_domain_id(domain_name=domain_name)
+
+    if isinstance(workspace_names, str):
+        workspace_names = [workspace_names]
+
+    dfW = fabric.list_workspaces()
+
+    # Check for invalid capacities
+    invalid_workspaces = [
+        name for name in workspace_names if name not in dfW["Name"].values
+    ]
+
+    if len(invalid_workspaces) == 1:
+        raise ValueError(
+            f"{icons.red_dot} The {invalid_workspaces} workspace is not valid."
+        )
+    elif len(invalid_workspaces) > 1:
+        raise ValueError(
+            f"{icons.red_dot} The {invalid_workspaces} workspaces are not valid."
+        )
+
+    dfW_filt = dfW[dfW["Name"].isin(workspace_names)]
+    workspace_list = list(dfW_filt["Id"])
+
+    payload = {"workspacesIds": workspace_list}
+    client = fabric.FabricRestClient()
+    response = client.post(
+        f"/v1/admin/domains/{domain_id}/unassignWorkspaces", json=payload
+    )
+
+    if response.status_code != 200:
+        raise FabricHTTPException(response)
+    print(
+        f"{icons.green_dot} The {workspace_names} workspaces assigned to the '{domain_name}' domain have been unassigned."
+    )

sempy_labs/directlake/_directlake_schema_sync.py

@@ -12,7 +12,7 @@ import sempy_labs._icons as icons
 def direct_lake_schema_sync(
     dataset: str,
     workspace: Optional[str] = None,
-    add_to_model: Optional[bool] = False,
+    add_to_model: bool = False,
     **kwargs,
 ):
     """

sempy_labs/directlake/_dl_helper.py

@@ -5,7 +5,11 @@ from typing import Optional, List, Union, Tuple
 from uuid import UUID
 import sempy_labs._icons as icons
 from sempy._utils._log import log
-from sempy_labs._helper_functions import retry, resolve_dataset_id
+from sempy_labs._helper_functions import (
+    retry,
+    resolve_dataset_id,
+    resolve_lakehouse_name,
+)
 
 
 def check_fallback_reason(
@@ -28,16 +32,17 @@ def check_fallback_reason(
     pandas.DataFrame
         The tables in the semantic model and their fallback reason.
     """
+    from sempy_labs.tom import connect_semantic_model
 
     workspace = fabric.resolve_workspace_name(workspace)
 
-    dfP = fabric.list_partitions(dataset=dataset, workspace=workspace)
-    dfP_filt = dfP[dfP["Mode"] == "DirectLake"]
-
-    if len(dfP_filt) == 0:
-        raise ValueError(
-            f"{icons.red_dot} The '{dataset}' semantic model is not in Direct Lake. This function is only applicable to Direct Lake semantic models."
-        )
+    with connect_semantic_model(
+        dataset=dataset, workspace=workspace, readonly=True
+    ) as tom:
+        if not tom.is_direct_lake():
+            raise ValueError(
+                f"{icons.red_dot} The '{dataset}' semantic model is not in Direct Lake. This function is only applicable to Direct Lake semantic models."
+            )
 
     df = fabric.evaluate_dax(
         dataset=dataset,
@@ -73,8 +78,9 @@ def generate_direct_lake_semantic_model(
     workspace: Optional[str] = None,
     lakehouse: Optional[str] = None,
     lakehouse_workspace: Optional[str] = None,
-    overwrite: Optional[bool] = False,
-    refresh: Optional[bool] = True,
+    schema: str = "dbo",
+    overwrite: bool = False,
+    refresh: bool = True,
 ):
     """
     Dynamically generates a Direct Lake semantic model based on tables in a Fabric lakehouse.
@@ -96,23 +102,32 @@ def generate_direct_lake_semantic_model(
         The Fabric workspace in which the lakehouse 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.
+    schema : str, default="dbo"
+        The schema used for the lakehouse.
     overwrite : bool, default=False
         If set to True, overwrites the existing semantic model if it already exists.
     refresh: bool, default=True
         If True, refreshes the newly created semantic model after it is created.
-
-    Returns
-    -------
     """
 
     from sempy_labs.lakehouse import get_lakehouse_tables, get_lakehouse_columns
-    from sempy_labs import create_blank_semantic_model, refresh_semantic_model
-    from sempy_labs.tom import connect_semantic_model
     from sempy_labs.directlake import get_shared_expression
+    from sempy_labs.tom import connect_semantic_model
+    from sempy_labs._generate_semantic_model import create_blank_semantic_model
+    from sempy_labs._refresh_semantic_model import refresh_semantic_model
 
     if isinstance(lakehouse_tables, str):
         lakehouse_tables = [lakehouse_tables]
 
+    workspace = fabric.resolve_workspace_name(workspace)
+    if lakehouse_workspace is None:
+        lakehouse_workspace = workspace
+    if lakehouse is None:
+        lakehouse_id = fabric.get_lakehouse_id()
+        lakehouse_workspace_id = fabric.get_workspace_id()
+        lakehouse_workspace = fabric.resolve_workspace_name(lakehouse_workspace_id)
+        lakehouse = resolve_lakehouse_name(lakehouse_id, lakehouse_workspace)
+
     dfLT = get_lakehouse_tables(lakehouse=lakehouse, workspace=lakehouse_workspace)
 
     # Validate lakehouse tables
@@ -158,7 +173,7 @@ def generate_direct_lake_semantic_model(
 
         for t in lakehouse_tables:
             tom.add_table(name=t)
-            tom.add_entity_partition(table_name=t, entity_name=t)
+            tom.add_entity_partition(table_name=t, entity_name=t, schema_name=schema)
             dfLC_filt = dfLC[dfLC["Table Name"] == t]
             for i, r in dfLC_filt.iterrows():
                 lakeCName = r["Column Name"]
@@ -212,6 +227,7 @@ def get_direct_lake_source(
     response = client.post(
         "metadata/relations/upstream?apiVersion=3", json=request_body
     )
+
     artifacts = response.json().get("artifacts", [])
     sql_id, sql_object_name, sql_workspace_id, artifact_type = None, None, None, None
 

sempy_labs/directlake/_generate_shared_expression.py

@@ -58,14 +58,15 @@ def generate_shared_expression(
     if response.status_code != 200:
         raise FabricHTTPException(response)
 
+    prop = response.json().get("properties")
+
     if item_type == "Lakehouse":
-        prop = response.json()["properties"]["sqlEndpointProperties"]
-        sqlEPCS = prop["connectionString"]
-        sqlepid = prop["id"]
-        provStatus = prop["provisioningStatus"]
+        sqlprop = prop.get("sqlEndpointProperties")
+        sqlEPCS = sqlprop.get("connectionString")
+        sqlepid = sqlprop.get("id")
+        provStatus = sqlprop.get("provisioningStatus")
     elif item_type == "Warehouse":
-        prop = response.json()["properties"]
-        sqlEPCS = prop["connectionString"]
+        sqlEPCS = prop.get("connectionString")
         sqlepid = item_id
         provStatus = None
 
@@ -74,12 +75,8 @@ def generate_shared_expression(
             f"{icons.red_dot} The SQL Endpoint for the '{item_name}' lakehouse within the '{workspace}' workspace has not yet been provisioned. Please wait until it has been provisioned."
         )
 
-    sh = (
-        'let\n\tdatabase = Sql.Database("'
-        + sqlEPCS
-        + '", "'
-        + sqlepid
-        + '")\nin\n\tdatabase'
-    )
+    start_expr = "let\n\tdatabase = "
+    end_expr = "\nin\n\tdatabase"
+    mid_expr = f'Sql.Database("{sqlEPCS}", "{sqlepid}")'
 
-    return sh
+    return f"{start_expr}{mid_expr}{end_expr}"

sempy_labs/directlake/_guardrails.py

@@ -7,10 +7,7 @@ import sempy_labs._icons as icons
 def get_direct_lake_guardrails() -> pd.DataFrame:
     """
     Shows the guardrails for when Direct Lake semantic models will fallback to Direct Query
-     based on Microsoft's `online documentation <https://learn.microsoft.com/power-bi/enterprise/directlake-overview>`_.
-
-    Parameters
-    ----------
+    based on Microsoft's `online documentation <https://learn.microsoft.com/power-bi/enterprise/directlake-overview>`_.
 
     Returns
     -------
@@ -21,9 +18,12 @@ def get_direct_lake_guardrails() -> pd.DataFrame:
     url = "https://learn.microsoft.com/power-bi/enterprise/directlake-overview"
 
     tables = pd.read_html(url)
-    df = tables[0]
-    df["Fabric SKUs"] = df["Fabric SKUs"].str.split("/")
-    df = df.explode("Fabric SKUs", ignore_index=True)
+    for df in tables:
+        first_column_name = df.columns[0]
+        if first_column_name.startswith("Fabric"):
+            df[first_column_name] = df[first_column_name].str.split("/")
+            df = df.explode(first_column_name, ignore_index=True)
+            break
 
     return df
 

sempy_labs/directlake/_update_directlake_model_lakehouse_connection.py

@@ -32,10 +32,6 @@ def update_direct_lake_model_lakehouse_connection(
         The Fabric workspace used by the lakehouse.
         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
-    -------
-
     """
 
     workspace = fabric.resolve_workspace_name(workspace)
@@ -57,25 +53,19 @@ def update_direct_lake_model_lakehouse_connection(
             f"Therefore it cannot be used to support the '{dataset}' semantic model within the '{workspace}' workspace."
         )
 
-    dfP = fabric.list_partitions(dataset=dataset, workspace=workspace)
-    dfP_filt = dfP[dfP["Mode"] == "DirectLake"]
+    shEx = get_shared_expression(lakehouse, lakehouse_workspace)
 
-    if len(dfP_filt) == 0:
-        raise ValueError(
-            f"{icons.red_dot} The '{dataset}' semantic model is not in Direct Lake. This function is only applicable to Direct Lake semantic models."
-        )
-    else:
-        with connect_semantic_model(
-            dataset=dataset, readonly=False, workspace=workspace
-        ) as tom:
+    with connect_semantic_model(
+        dataset=dataset, readonly=False, workspace=workspace
+    ) as tom:
+
+        if not tom.is_direct_lake():
+            raise ValueError(
+                f"{icons.red_dot} The '{dataset}' semantic model is not in Direct Lake. This function is only applicable to Direct Lake semantic models."
+            )
+
+        tom.model.Expressions["DatabaseQuery"].Expression = shEx
 
-            shEx = get_shared_expression(lakehouse, lakehouse_workspace)
-            try:
-                tom.model.Expressions["DatabaseQuery"].Expression = shEx
-                print(
-                    f"{icons.green_dot} The expression in the '{dataset}' semantic model has been updated to point to the '{lakehouse}' lakehouse in the '{lakehouse_workspace}' workspace."
-                )
-            except Exception as e:
-                raise ValueError(
-                    f"{icons.red_dot} The expression in the '{dataset}' semantic model was not updated."
-                ) from e
+    print(
+        f"{icons.green_dot} The expression in the '{dataset}' semantic model has been updated to point to the '{lakehouse}' lakehouse in the '{lakehouse_workspace}' workspace."
+    )

sempy_labs/directlake/_update_directlake_partition_entity.py

@@ -100,7 +100,7 @@ def add_table_to_direct_lake_semantic_model(
     dataset: str,
     table_name: str,
     lakehouse_table_name: str,
-    refresh: Optional[bool] = True,
+    refresh: bool = True,
     workspace: Optional[str] = None,
 ):
     """

sempy_labs/directlake/_warm_cache.py

@@ -15,7 +15,7 @@ import sempy_labs._icons as icons
 def warm_direct_lake_cache_perspective(
     dataset: str,
     perspective: str,
-    add_dependencies: Optional[bool] = False,
+    add_dependencies: bool = False,
     workspace: Optional[str] = None,
 ) -> pd.DataFrame:
     """

sempy_labs/lakehouse/_get_lakehouse_tables.py

@@ -24,9 +24,9 @@ from sempy.fabric.exceptions import FabricHTTPException
 def get_lakehouse_tables(
     lakehouse: Optional[str] = None,
     workspace: Optional[str] = None,
-    extended: Optional[bool] = False,
-    count_rows: Optional[bool] = False,
-    export: Optional[bool] = False,
+    extended: bool = False,
+    count_rows: bool = False,
+    export: bool = False,
 ) -> pd.DataFrame:
     """
     Shows the tables of a lakehouse and their respective properties. Option to include additional properties relevant to Direct Lake guardrails.