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

sempy_labs/_helper_functions.py

@@ -30,6 +30,11 @@ def _build_url(url: str, params: dict) -> str:
     return url
 
 
+def _encode_user(user: str) -> str:
+
+    return urllib.parse.quote(user, safe="@")
+
+
 def create_abfss_path(
     lakehouse_id: UUID,
     lakehouse_workspace_id: UUID,
@@ -130,14 +135,16 @@ def create_relationship_name(
     )
 
 
-def resolve_report_id(report: str, workspace: Optional[str | UUID] = None) -> UUID:
+def resolve_report_id(
+    report: str | UUID, workspace: Optional[str | UUID] = None
+) -> UUID:
     """
     Obtains the ID of the Power BI report.
 
     Parameters
     ----------
-    report : str
-        The name of the Power BI report.
+    report : str | uuid.UUID
+        The name or ID 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
@@ -145,11 +152,11 @@ def resolve_report_id(report: str, workspace: Optional[str | UUID] = None) -> UU
 
     Returns
     -------
-    UUID
+    uuid.UUID
         The ID of the Power BI report.
     """
 
-    return fabric.resolve_item_id(item_name=report, type="Report", workspace=workspace)
+    return resolve_item_id(item=report, type="Report", workspace=workspace)
 
 
 def resolve_report_name(report_id: UUID, workspace: Optional[str | UUID] = None) -> str:
@@ -176,6 +183,127 @@ def resolve_report_name(report_id: UUID, workspace: Optional[str | UUID] = None)
     )
 
 
+def delete_item(
+    item: str | UUID, type: str, workspace: Optional[str | UUID] = None
+) -> None:
+    """
+    Deletes an item from a Fabric workspace.
+
+    Parameters
+    ----------
+    item : str | uuid.UUID
+        The name or ID of the item to be deleted.
+    type : str
+        The type of the item to be deleted.
+    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.
+    """
+
+    from sempy_labs._utils import item_types
+
+    (workspace_name, workspace_id) = resolve_workspace_name_and_id(workspace)
+    (item_name, item_id) = resolve_item_name_and_id(item, type, workspace_id)
+    item_type = item_types.get(type)[0].lower()
+
+    fabric.delete_item(item_id=item_id, workspace=workspace_id)
+
+    print(
+        f"{icons.green_dot} The '{item_name}' {item_type} has been successfully deleted from the '{workspace_name}' workspace."
+    )
+
+
+def create_item(
+    name: str,
+    type: str,
+    description: Optional[str] = None,
+    definition: Optional[dict] = None,
+    workspace: Optional[str | UUID] = None,
+):
+    """
+    Creates an item in a Fabric workspace.
+
+    Parameters
+    ----------
+    name : str
+        The name of the item to be created.
+    type : str
+        The type of the item to be created.
+    description : str, default=None
+        A description of the item to be created.
+    definition : dict, default=None
+        The definition of the item to be created.
+    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.
+    """
+    from sempy_labs._utils import item_types
+
+    (workspace_name, workspace_id) = resolve_workspace_name_and_id(workspace)
+    item_type = item_types.get(type)[0].lower()
+    item_type_url = item_types.get(type)[1]
+
+    payload = {
+        "displayName": name,
+    }
+    if description:
+        payload["description"] = description
+    if definition:
+        payload["definition"] = definition
+
+    _base_api(
+        request=f"/v1/workspaces/{workspace_id}/{item_type_url}",
+        method="post",
+        payload=payload,
+        status_codes=[201, 202],
+        lro_return_status_code=True,
+    )
+    print(
+        f"{icons.green_dot} The '{name}' {item_type} has been successfully created within the in the '{workspace_name}' workspace."
+    )
+
+
+def get_item_definition(
+    item: str | UUID,
+    type: str,
+    workspace: Optional[str | UUID] = None,
+    format: Optional[str] = None,
+    return_dataframe: bool = True,
+    decode: bool = True,
+):
+
+    from sempy_labs._utils import item_types
+
+    (workspace_name, workspace_id) = resolve_workspace_name_and_id(workspace)
+    item_id = resolve_item_id(item, type, workspace_id)
+    item_type_url = item_types.get(type)[1]
+    path = item_types.get(type)[2]
+
+    url = f"/v1/workspaces/{workspace_id}/{item_type_url}/{item_id}/getDefinition"
+    if format:
+        url += f"?format={format}"
+
+    result = _base_api(
+        request=url,
+        method="post",
+        status_codes=None,
+        lro_return_json=True,
+    )
+
+    if return_dataframe:
+        return pd.json_normalize(result["definition"]["parts"])
+
+    value = next(
+        p.get("payload") for p in result["definition"]["parts"] if p.get("path") == path
+    )
+    if decode:
+        json.loads(_decode_b64(value))
+    else:
+        return value
+
+
 def resolve_item_id(
     item: str | UUID, type: str, workspace: Optional[str] = None
 ) -> UUID:
@@ -268,14 +396,7 @@ def resolve_dataset_id(
         The ID of the semantic model.
     """
 
-    if _is_valid_uuid(dataset):
-        dataset_id = dataset
-    else:
-        dataset_id = fabric.resolve_item_id(
-            item_name=dataset, type="SemanticModel", workspace=workspace
-        )
-
-    return dataset_id
+    return resolve_item_id(item=dataset, type="SemanticModel", workspace=workspace)
 
 
 def resolve_dataset_name(
@@ -512,7 +633,6 @@ def save_as_delta_table(
         or if no lakehouse attached, resolves to the workspace of the notebook.
     """
 
-    from pyspark.sql import SparkSession
     from pyspark.sql.types import (
         StringType,
         IntegerType,
@@ -544,8 +664,6 @@ def save_as_delta_table(
             f"{icons.red_dot} Invalid 'delta_table_name'. Delta tables in the lakehouse cannot have spaces in their names."
         )
 
-    dataframe.columns = [col.replace(" ", "_") for col in dataframe.columns]
-
     spark = _create_spark_session()
 
     type_mapping = {
@@ -563,6 +681,7 @@ def save_as_delta_table(
     }
 
     if isinstance(dataframe, pd.DataFrame):
+        dataframe.columns = [col.replace(" ", "_") for col in dataframe.columns]
         if schema is None:
             spark_df = spark.createDataFrame(dataframe)
         else:
@@ -574,6 +693,9 @@ def save_as_delta_table(
             )
             spark_df = spark.createDataFrame(dataframe, schema_map)
     else:
+        for col_name in dataframe.columns:
+            new_name = col_name.replace(" ", "_")
+            dataframe = dataframe.withColumnRenamed(col_name, new_name)
         spark_df = dataframe
 
     filePath = create_abfss_path(
@@ -644,7 +766,7 @@ def resolve_workspace_name_and_id(
 
     Returns
     -------
-    str, str
+    str, uuid.UUID
         The name and ID of the Fabric workspace.
     """
 
@@ -909,14 +1031,14 @@ def resolve_capacity_name(capacity_id: Optional[UUID] = None) -> str:
     return dfC_filt["Display Name"].iloc[0]
 
 
-def resolve_capacity_id(capacity_name: Optional[str] = None) -> UUID:
+def resolve_capacity_id(capacity: Optional[str | UUID] = None, **kwargs) -> UUID:
     """
     Obtains the capacity Id for a given capacity name.
 
     Parameters
     ----------
-    capacity_name : str, default=None
-        The capacity name.
+    capacity : str | uuid.UUID, default=None
+        The capacity name or ID.
         Defaults to None which resolves to the capacity id of the workspace of the attached lakehouse
         or if no lakehouse attached, resolves to the capacity name of the workspace of the notebook.
 
@@ -926,16 +1048,22 @@ def resolve_capacity_id(capacity_name: Optional[str] = None) -> UUID:
         The capacity Id.
     """
 
-    if capacity_name is None:
+    if "capacity_name" in kwargs:
+        capacity = kwargs["capacity_name"]
+        print(
+            f"{icons.warning} The 'capacity_name' parameter is deprecated. Please use 'capacity' instead."
+        )
+
+    if capacity is None:
         return get_capacity_id()
+    if _is_valid_uuid(capacity):
+        return capacity
 
     dfC = fabric.list_capacities()
-    dfC_filt = dfC[dfC["Display Name"] == capacity_name]
+    dfC_filt = dfC[dfC["Display Name"] == capacity]
 
     if dfC_filt.empty:
-        raise ValueError(
-            f"{icons.red_dot} The '{capacity_name}' capacity does not exist."
-        )
+        raise ValueError(f"{icons.red_dot} The '{capacity}' capacity does not exist.")
 
     return dfC_filt["Id"].iloc[0]
 
@@ -1098,12 +1226,7 @@ def resolve_warehouse_id(
         The warehouse Id.
     """
 
-    if _is_valid_uuid(warehouse):
-        return warehouse
-    else:
-        return fabric.resolve_item_id(
-            item_name=warehouse, type="Warehouse", workspace=workspace
-        )
+    return resolve_item_id(item=warehouse, type="Warehouse", workspace=workspace)
 
 
 def get_language_codes(languages: str | List[str]):
@@ -1163,14 +1286,14 @@ def convert_to_alphanumeric_lowercase(input_string):
 
 
 def resolve_environment_id(
-    environment: str, workspace: Optional[str | UUID] = None
+    environment: str | UUID, workspace: Optional[str | UUID] = None
 ) -> UUID:
     """
     Obtains the environment Id for a given environment.
 
     Parameters
     ----------
-    environment: str
+    environment: str | uuid.UUID
         Name of the environment.
     workspace : str | uuid.UUID, default=None
         The Fabric workspace name or ID in which the semantic model resides.
@@ -1179,13 +1302,11 @@ def resolve_environment_id(
 
     Returns
     -------
-    UUID
+    uuid.UUID
         The environment Id.
     """
 
-    return fabric.resolve_item_id(
-        item_name=environment, type="Environment", workspace=workspace
-    )
+    return resolve_item_id(item=environment, type="Environment", workspace=workspace)
 
 
 def _make_clickable(val):
@@ -1217,14 +1338,16 @@ def convert_to_friendly_case(text: str) -> str:
     return text
 
 
-def resolve_notebook_id(notebook: str, workspace: Optional[str | UUID] = None) -> UUID:
+def resolve_notebook_id(
+    notebook: str | UUID, workspace: Optional[str | UUID] = None
+) -> UUID:
     """
     Obtains the notebook Id for a given notebook.
 
     Parameters
     ----------
-    notebook: str
-        Name of the notebook.
+    notebook: str | uuid.UUID
+        Name or ID of the notebook.
     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
@@ -1236,9 +1359,7 @@ def resolve_notebook_id(notebook: str, workspace: Optional[str | UUID] = None) -
         The notebook Id.
     """
 
-    return fabric.resolve_item_id(
-        item_name=notebook, type="Notebook", workspace=workspace
-    )
+    return resolve_item_id(item=notebook, type="Notebook", workspace=workspace)
 
 
 def generate_guid():
@@ -1524,9 +1645,15 @@ def _base_api(
             raise NotImplementedError
     else:
         headers = _get_headers(auth.token_provider.get(), audience=client)
+        if client == "graph":
+            url = f"https://graph.microsoft.com/v1.0/{request}"
+        elif client == "azure":
+            url = request
+        else:
+            raise NotImplementedError
         response = requests.request(
             method.upper(),
-            f"https://graph.microsoft.com/v1.0/{request}",
+            url,
             headers=headers,
             json=payload,
         )
@@ -1637,3 +1764,33 @@ def _run_spark_sql_query(query):
     spark = _create_spark_session()
 
     return spark.sql(query)
+
+
+def _mount(lakehouse, workspace) -> str:
+    """
+    Mounts a lakehouse to a notebook if it is not already mounted. Returns the local path to the lakehouse.
+    """
+
+    import notebookutils
+
+    (workspace_name, workspace_id) = resolve_workspace_name_and_id(workspace=workspace)
+    (lakehouse_name, lakehouse_id) = resolve_lakehouse_name_and_id(
+        lakehouse=lakehouse, workspace=workspace
+    )
+
+    lake_path = create_abfss_path(lakehouse_id, workspace_id)
+    mounts = notebookutils.fs.mounts()
+    mount_point = f"/{workspace_name.replace(' ', '')}{lakehouse_name.replace(' ', '')}"
+    if not any(i.get("source") == lake_path for i in mounts):
+        # Mount lakehouse if not mounted
+        notebookutils.fs.mount(lake_path, mount_point)
+        print(
+            f"{icons.green_dot} Mounted the '{lakehouse_name}' lakehouse within the '{workspace_name}' to the notebook."
+        )
+
+    mounts = notebookutils.fs.mounts()
+    local_path = next(
+        i.get("localPath") for i in mounts if i.get("source") == lake_path
+    )
+
+    return local_path

sempy_labs/_job_scheduler.py

@@ -1,6 +1,6 @@
 from sempy._utils._log import log
 import pandas as pd
-from typing import Optional
+from typing import Optional, List
 from sempy_labs._helper_functions import (
     resolve_workspace_name_and_id,
     resolve_item_name_and_id,
@@ -189,7 +189,7 @@ def run_on_demand_item_job(
     Parameters
     ----------
     item : str | uuid.UUID
-        The item name or ID
+        The item name or ID.
     type : str, default=None
         The item `type <https://learn.microsoft.com/rest/api/fabric/core/items/list-items?tabs=HTTP#itemtype>`_. If specifying the item name as the item, the item type is required.
     job_type : str, default="DefaultJob"
@@ -213,3 +213,227 @@ def run_on_demand_item_job(
     )
 
     print(f"{icons.green_dot} The '{item_name}' {type.lower()} has been executed.")
+
+
+def create_item_schedule_cron(
+    item: str | UUID,
+    type: str,
+    start_date_time: str,
+    end_date_time: str,
+    local_time_zone: str,
+    job_type: str = "DefaultJob",
+    interval_minutes: int = 10,
+    enabled: bool = True,
+    workspace: Optional[str | UUID] = None,
+):
+    """
+    Create a new schedule for an item based on a `chronological time <https://learn.microsoft.com/rest/api/fabric/core/job-scheduler/create-item-schedule?tabs=HTTP#cronscheduleconfig>`_.
+
+    This is a wrapper function for the following API: `Job Scheduler - Create Item Schedule <https://learn.microsoft.com/rest/api/fabric/core/job-scheduler/create-item-schedule>`_.
+
+    Parameters
+    ----------
+    item : str | uuid.UUID
+        The item name or ID.
+    type : str
+        The item `type <https://learn.microsoft.com/rest/api/fabric/core/items/list-items?tabs=HTTP#itemtype>`_. If specifying the item name as the item, the item type is required.
+    start_date_time: str
+        The start date and time of the schedule. Example: "2024-04-28T00:00:00".
+    end_date_time: str
+        The end date and time of the schedule. Must be later than the start_date_time. Example: "2024-04-30T23:59:00".
+    local_time_zone: str
+        The `time zone <https://learn.microsoft.com/windows-hardware/manufacture/desktop/default-time-zones?view=windows-11>`_ of the schedule. Example: "Central Standard Time".
+    job_type : str, default="DefaultJob"
+        The job type.
+    interval_minutes: int, default=10
+        The schedule interval (in minutes).
+    enabled: bool, default=True
+        Whether the schedule is enabled.
+    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.
+    """
+
+    (workspace_name, workspace_id) = resolve_workspace_name_and_id(workspace)
+    (item_name, item_id) = resolve_item_name_and_id(
+        item=item, type=type, workspace=workspace
+    )
+
+    payload = {
+        "enabled": enabled,
+        "configuration": {
+            "startDateTime": start_date_time,
+            "endDateTime": end_date_time,
+            "localTimeZoneId": local_time_zone,
+            "type": "Cron",
+            "interval": interval_minutes,
+        },
+    }
+
+    _base_api(
+        request=f"v1/workspaces/{workspace_id}/items/{item_id}/jobs/{job_type}/schedules",
+        method="post",
+        payload=payload,
+        status_codes=201,
+    )
+
+    print(
+        f"{icons.green_dot} The schedule for the '{item_name}' {type.lower()} has been created."
+    )
+
+
+def create_item_schedule_daily(
+    item: str | UUID,
+    type: str,
+    start_date_time: str,
+    end_date_time: str,
+    local_time_zone: str,
+    times: List[str],
+    job_type: str = "DefaultJob",
+    enabled: bool = True,
+    workspace: Optional[str | UUID] = None,
+):
+    """
+    Create a new daily schedule for an item.
+
+    This is a wrapper function for the following API: `Job Scheduler - Create Item Schedule <https://learn.microsoft.com/rest/api/fabric/core/job-scheduler/create-item-schedule>`_.
+
+    Parameters
+    ----------
+    item : str | uuid.UUID
+        The item name or ID.
+    type : str
+        The item `type <https://learn.microsoft.com/rest/api/fabric/core/items/list-items?tabs=HTTP#itemtype>`_. If specifying the item name as the item, the item type is required.
+    start_date_time: str
+        The start date and time of the schedule. Example: "2024-04-28T00:00:00".
+    end_date_time: str
+        The end date and time of the schedule. Must be later than the start_date_time. Example: "2024-04-30T23:59:00".
+    local_time_zone: str
+        The `time zone <https://learn.microsoft.com/windows-hardware/manufacture/desktop/default-time-zones?view=windows-11>`_ of the schedule. Example: "Central Standard Time".
+    times : List[str]
+        A list of time slots in hh:mm format, at most 100 elements are allowed. Example: ["00:00", "12:00"].
+    job_type : str, default="DefaultJob"
+        The job type.
+    enabled: bool, default=True
+        Whether the schedule is enabled.
+    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.
+    """
+
+    (workspace_name, workspace_id) = resolve_workspace_name_and_id(workspace)
+    (item_name, item_id) = resolve_item_name_and_id(
+        item=item, type=type, workspace=workspace
+    )
+
+    payload = {
+        "enabled": enabled,
+        "configuration": {
+            "startDateTime": start_date_time,
+            "endDateTime": end_date_time,
+            "localTimeZoneId": local_time_zone,
+            "type": "Daily",
+            "times": times,
+        },
+    }
+
+    _base_api(
+        request=f"v1/workspaces/{workspace_id}/items/{item_id}/jobs/{job_type}/schedules",
+        method="post",
+        payload=payload,
+        status_codes=201,
+    )
+
+    print(
+        f"{icons.green_dot} The schedule for the '{item_name}' {type.lower()} has been created."
+    )
+
+
+def create_item_schedule_weekly(
+    item: str | UUID,
+    type: str,
+    start_date_time: str,
+    end_date_time: str,
+    local_time_zone: str,
+    times: List[str],
+    weekdays: List[str],
+    job_type: str = "DefaultJob",
+    enabled: bool = True,
+    workspace: Optional[str | UUID] = None,
+):
+    """
+    Create a new daily schedule for an item.
+
+    This is a wrapper function for the following API: `Job Scheduler - Create Item Schedule <https://learn.microsoft.com/rest/api/fabric/core/job-scheduler/create-item-schedule>`_.
+
+    Parameters
+    ----------
+    item : str | uuid.UUID
+        The item name or ID.
+    type : str
+        The item `type <https://learn.microsoft.com/rest/api/fabric/core/items/list-items?tabs=HTTP#itemtype>`_. If specifying the item name as the item, the item type is required.
+    start_date_time: str
+        The start date and time of the schedule. Example: "2024-04-28T00:00:00".
+    end_date_time: str
+        The end date and time of the schedule. Must be later than the start_date_time. Example: "2024-04-30T23:59:00".
+    local_time_zone: str
+        The `time zone <https://learn.microsoft.com/windows-hardware/manufacture/desktop/default-time-zones?view=windows-11>`_ of the schedule. Example: "Central Standard Time".
+    times : List[str]
+        A list of time slots in hh:mm format, at most 100 elements are allowed. Example: ["00:00", "12:00"].
+    weekdays : List[str]
+        A list of weekdays. Example: ["Monday", "Tuesday"].
+    job_type : str, default="DefaultJob"
+        The job type.
+    enabled: bool, default=True
+        Whether the schedule is enabled.
+    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.
+    """
+
+    (workspace_name, workspace_id) = resolve_workspace_name_and_id(workspace)
+    (item_name, item_id) = resolve_item_name_and_id(
+        item=item, type=type, workspace=workspace
+    )
+
+    weekdays = [w.capitalize() for w in weekdays]
+    weekday_list = [
+        "Sunday",
+        "Monday",
+        "Tuesday",
+        "Wednesday",
+        "Thursday",
+        "Friday",
+        "Saturday",
+    ]
+    for weekday in weekdays:
+        if weekday not in weekday_list:
+            raise ValueError(
+                f"{icons.red_dot} Invalid weekday: {weekday}. Must be one of {weekday_list}."
+            )
+
+    payload = {
+        "enabled": enabled,
+        "configuration": {
+            "startDateTime": start_date_time,
+            "endDateTime": end_date_time,
+            "localTimeZoneId": local_time_zone,
+            "type": "Weekly",
+            "times": times,
+            "weekdays": weekdays,
+        },
+    }
+
+    _base_api(
+        request=f"v1/workspaces/{workspace_id}/items/{item_id}/jobs/{job_type}/schedules",
+        method="post",
+        payload=payload,
+        status_codes=201,
+    )
+
+    print(
+        f"{icons.green_dot} The schedule for the '{item_name}' {type.lower()} has been created."
+    )