semantic-link-labs 0.8.10__py3-none-any.whl → 0.9.0__py3-none-any.whl

sempy_labs/_job_scheduler.py

@@ -0,0 +1,227 @@
+import sempy.fabric as fabric
+from sempy._utils._log import log
+import pandas as pd
+from typing import Optional
+from sempy_labs._helper_functions import (
+    resolve_workspace_name_and_id,
+    resolve_item_name_and_id,
+    pagination,
+    lro,
+)
+from sempy.fabric.exceptions import FabricHTTPException
+from uuid import UUID
+import sempy_labs._icons as icons
+
+
+@log
+def list_item_job_instances(
+    item: str | UUID, type: Optional[str] = None, workspace: Optional[str | UUID] = None
+) -> pd.DataFrame:
+    """
+    Returns a list of job instances for the specified item.
+
+    This is a wrapper function for the following API: `Job Scheduler - List Item Job Instances <https://learn.microsoft.com/rest/api/fabric/core/job-scheduler/list-item-job-instances>`_.
+
+    Parameters
+    ----------
+    item : str | uuid.UUID
+        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.
+    workspace : str | uuid.UUID, default=None
+        The Fabric workspace name or ID 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
+    -------
+    pandas.DataFrame
+        Shows a list of job instances for the specified item.
+    """
+
+    (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
+    )
+
+    client = fabric.FabricRestClient()
+    response = client.get(
+        f"v1/workspaces/{workspace_id}/items/{item_id}/jobs/instances"
+    )
+
+    if response.status_code != 200:
+        raise FabricHTTPException(response)
+
+    df = pd.DataFrame(
+        columns=[
+            "Job Instance Id",
+            "Item Name",
+            "Item Id",
+            "Item Type",
+            "Job Type",
+            "Invoke Type",
+            "Status",
+            "Root Activity Id",
+            "Start Time UTC",
+            "End Time UTC",
+            "Failure Reason",
+        ]
+    )
+
+    responses = pagination(client, response)
+
+    if not responses[0].get("value"):
+        return df
+
+    dfs = []
+    for r in responses:
+        for v in r.get("value", []):
+            fail = v.get("failureReason", {})
+            new_data = {
+                "Job Instance Id": v.get("id"),
+                "Item Name": item_name,
+                "Item Id": v.get("itemId"),
+                "Item Type": type,
+                "Job Type": v.get("jobType"),
+                "Invoke Type": v.get("invokeType"),
+                "Status": v.get("status"),
+                "Root Activity Id": v.get("rootActivityId"),
+                "Start Time UTC": v.get("startTimeUtc"),
+                "End Time UTC": v.get("endTimeUtc"),
+                "Error Message": fail.get("message") if fail is not None else "",
+            }
+            dfs.append(pd.DataFrame(new_data, index=[0]))
+
+    if dfs:
+        df = pd.concat(dfs, ignore_index=True)
+
+    return df
+
+
+@log
+def list_item_schedules(
+    item: str | UUID,
+    type: Optional[str] = None,
+    job_type: str = "DefaultJob",
+    workspace: Optional[str | UUID] = None,
+) -> pd.DataFrame:
+    """
+    Get scheduling settings for one specific item.
+
+    This is a wrapper function for the following API: `Job Scheduler - List Item Schedules <https://learn.microsoft.com/rest/api/fabric/core/job-scheduler/list-item-schedules>`_.
+
+    Parameters
+    ----------
+    item : str | uuid.UUID
+        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"
+        The job type.
+    workspace : str | uuid.UUID, default=None
+        The Fabric workspace name or ID 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
+    -------
+    pandas.DataFrame
+        Shows a list of scheduling settings for one specific item.
+    """
+
+    (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
+    )
+
+    df = pd.DataFrame(
+        columns=[
+            "Job Schedule Id",
+            "Enabled",
+            "Created Date Time",
+            "Start Date Time",
+            "End Date Time",
+            "Local Time Zone Id",
+            "Type",
+            "Interval",
+            "Weekdays",
+            "Times",
+            "Owner Id",
+            "Owner Type",
+        ]
+    )
+
+    client = fabric.FabricRestClient()
+    response = client.get(
+        f"v1/workspaces/{workspace_id}/items/{item_id}/jobs/{job_type}/schedules"
+    )
+
+    if response.status_code != 200:
+        raise FabricHTTPException(response)
+
+    for v in response.json().get("value", []):
+        config = v.get("configuration", {})
+        own = v.get("owner", {})
+        new_data = {
+            "Job Schedule Id": v.get("id"),
+            "Enabled": v.get("enabled"),
+            "Created Date Time": v.get("createdDateTime"),
+            "Start Date Time": config.get("startDateTime"),
+            "End Date Time": config.get("endDateTime"),
+            "Local Time Zone Id": config.get("localTimeZoneId"),
+            "Type": config.get("type"),
+            "Interval": config.get("interval"),
+            "Weekdays": config.get("weekdays"),
+            "Times": config.get("times"),
+            "Owner Id": own.get("id"),
+            "Owner Type": own.get("type"),
+        }
+
+        df = pd.concat([df, pd.DataFrame(new_data, index=[0])], ignore_index=True)
+
+    df["Enabled"] = df["Enabled"].astype(bool)
+    df["Created Date Time"] = pd.to_datetime(df["Created Date Time"])
+    df["Start Date Time"] = pd.to_datetime(df["Start Date Time"])
+
+    return df
+
+
+@log
+def run_on_demand_item_job(
+    item: str | UUID,
+    type: Optional[str] = None,
+    job_type: str = "DefaultJob",
+    workspace: Optional[str | UUID] = None,
+):
+    """
+    Run on-demand item job instance.
+
+    This is a wrapper function for the following API: `Job Scheduler - Run On Demand Item Job <https://learn.microsoft.com/rest/api/fabric/core/job-scheduler/run-on-demand-item-job>`_.
+
+    Parameters
+    ----------
+    item : str | uuid.UUID
+        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"
+        The job type.
+    workspace : str | uuid.UUID, default=None
+        The Fabric workspace name or ID 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.
+    """
+
+    (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
+    )
+
+    client = fabric.FabricRestClient()
+    response = client.post(
+        f"v1/workspaces/{workspace_id}/items/{item_id}/jobs/instances?jobType={job_type}"
+    )
+
+    lro(client, response, return_status_code=True)
+
+    print(f"{icons.green_dot} The '{item_name}' {type.lower()} has been executed.")

sempy_labs/_kql_databases.py

@@ -8,9 +8,10 @@ from sempy_labs._helper_functions import (
     pagination,
 )
 from sempy.fabric.exceptions import FabricHTTPException
+from uuid import UUID
 
 
-def list_kql_databases(workspace: Optional[str] = None) -> pd.DataFrame:
+def list_kql_databases(workspace: Optional[str | UUID] = None) -> pd.DataFrame:
     """
     Shows the KQL databases within a workspace.
 
@@ -18,8 +19,8 @@ def list_kql_databases(workspace: Optional[str] = None) -> pd.DataFrame:
 
     Parameters
     ----------
-    workspace : str, default=None
-        The Fabric workspace name.
+    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.
 
@@ -41,7 +42,7 @@ def list_kql_databases(workspace: Optional[str] = None) -> pd.DataFrame:
         ]
     )
 
-    (workspace, workspace_id) = resolve_workspace_name_and_id(workspace)
+    (workspace_name, workspace_id) = resolve_workspace_name_and_id(workspace)
 
     client = fabric.FabricRestClient()
     response = client.get(f"/v1/workspaces/{workspace_id}/kqlDatabases")
@@ -69,7 +70,7 @@ def list_kql_databases(workspace: Optional[str] = None) -> pd.DataFrame:
 
 
 def create_kql_database(
-    name: str, description: Optional[str] = None, workspace: Optional[str] = None
+    name: str, description: Optional[str] = None, workspace: Optional[str | UUID] = None
 ):
     """
     Creates a KQL database.
@@ -82,13 +83,13 @@ def create_kql_database(
         Name of the KQL database.
     description : str, default=None
         A description of the environment.
-    workspace : str, default=None
-        The Fabric workspace name.
+    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, workspace_id) = resolve_workspace_name_and_id(workspace)
+    (workspace_name, workspace_id) = resolve_workspace_name_and_id(workspace)
 
     request_body = {"displayName": name}
 
@@ -103,11 +104,11 @@ def create_kql_database(
     lro(client, response, status_codes=[201, 202])
 
     print(
-        f"{icons.green_dot} The '{name}' KQL database has been created within the '{workspace}' workspace."
+        f"{icons.green_dot} The '{name}' KQL database has been created within the '{workspace_name}' workspace."
     )
 
 
-def delete_kql_database(name: str, workspace: Optional[str] = None):
+def delete_kql_database(name: str, workspace: Optional[str | UUID] = None):
     """
     Deletes a KQL database.
 
@@ -117,15 +118,15 @@ def delete_kql_database(name: str, workspace: Optional[str] = None):
     ----------
     name: str
         Name of the KQL database.
-    workspace : str, default=None
-        The Fabric workspace name.
+    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, workspace_id) = resolve_workspace_name_and_id(workspace)
+    (workspace_name, workspace_id) = resolve_workspace_name_and_id(workspace)
     kql_database_id = fabric.resolve_item_id(
-        item_name=name, type="KQLDatabase", workspace=workspace
+        item_name=name, type="KQLDatabase", workspace=workspace_id
     )
 
     client = fabric.FabricRestClient()
@@ -136,5 +137,5 @@ def delete_kql_database(name: str, workspace: Optional[str] = None):
     if response.status_code != 200:
         raise FabricHTTPException(response)
     print(
-        f"{icons.green_dot} The '{name}' KQL database within the '{workspace}' workspace has been deleted."
+        f"{icons.green_dot} The '{name}' KQL database within the '{workspace_name}' workspace has been deleted."
     )

sempy_labs/_kql_querysets.py

@@ -8,9 +8,10 @@ from sempy_labs._helper_functions import (
     pagination,
 )
 from sempy.fabric.exceptions import FabricHTTPException
+from uuid import UUID
 
 
-def list_kql_querysets(workspace: Optional[str] = None) -> pd.DataFrame:
+def list_kql_querysets(workspace: Optional[str | UUID] = None) -> pd.DataFrame:
     """
     Shows the KQL querysets within a workspace.
 
@@ -18,8 +19,8 @@ def list_kql_querysets(workspace: Optional[str] = None) -> pd.DataFrame:
 
     Parameters
     ----------
-    workspace : str, default=None
-        The Fabric workspace name.
+    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.
 
@@ -37,7 +38,7 @@ def list_kql_querysets(workspace: Optional[str] = None) -> pd.DataFrame:
         ]
     )
 
-    (workspace, workspace_id) = resolve_workspace_name_and_id(workspace)
+    (workspace_name, workspace_id) = resolve_workspace_name_and_id(workspace)
 
     client = fabric.FabricRestClient()
     response = client.get(f"/v1/workspaces/{workspace_id}/kqlQuerysets")
@@ -59,7 +60,7 @@ def list_kql_querysets(workspace: Optional[str] = None) -> pd.DataFrame:
 
 
 def create_kql_queryset(
-    name: str, description: Optional[str] = None, workspace: Optional[str] = None
+    name: str, description: Optional[str] = None, workspace: Optional[str | UUID] = None
 ):
     """
     Creates a KQL queryset.
@@ -72,13 +73,13 @@ def create_kql_queryset(
         Name of the KQL queryset.
     description : str, default=None
         A description of the environment.
-    workspace : str, default=None
-        The Fabric workspace name.
+    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, workspace_id) = resolve_workspace_name_and_id(workspace)
+    (workspace_name, workspace_id) = resolve_workspace_name_and_id(workspace)
 
     request_body = {"displayName": name}
 
@@ -93,11 +94,11 @@ def create_kql_queryset(
     lro(client, response, status_codes=[201, 202])
 
     print(
-        f"{icons.green_dot} The '{name}' KQL queryset has been created within the '{workspace}' workspace."
+        f"{icons.green_dot} The '{name}' KQL queryset has been created within the '{workspace_name}' workspace."
     )
 
 
-def delete_kql_queryset(name: str, workspace: Optional[str] = None):
+def delete_kql_queryset(name: str, workspace: Optional[str | UUID] = None):
     """
     Deletes a KQL queryset.
 
@@ -107,15 +108,15 @@ def delete_kql_queryset(name: str, workspace: Optional[str] = None):
     ----------
     name: str
         Name of the KQL queryset.
-    workspace : str, default=None
-        The Fabric workspace name.
+    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, workspace_id) = resolve_workspace_name_and_id(workspace)
+    (workspace_name, workspace_id) = resolve_workspace_name_and_id(workspace)
     kql_database_id = fabric.resolve_item_id(
-        item_name=name, type="KQLQueryset", workspace=workspace
+        item_name=name, type="KQLQueryset", workspace=workspace_id
     )
 
     client = fabric.FabricRestClient()
@@ -126,5 +127,5 @@ def delete_kql_queryset(name: str, workspace: Optional[str] = None):
     if response.status_code != 200:
         raise FabricHTTPException(response)
     print(
-        f"{icons.green_dot} The '{name}' KQL queryset within the '{workspace}' workspace has been deleted."
+        f"{icons.green_dot} The '{name}' KQL queryset within the '{workspace_name}' workspace has been deleted."
     )