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

sempy_labs/_sql.py

@@ -34,7 +34,7 @@ def _bytes2mswin_bstr(value: bytes) -> bytes:
 class ConnectBase:
     def __init__(
         self,
-        item: str,
+        item: str | UUID,
         workspace: Optional[Union[str, UUID]] = None,
         timeout: Optional[int] = None,
         endpoint_type: str = "warehouse",
@@ -49,6 +49,11 @@ class ConnectBase:
             (resource_name, resource_id) = resolve_item_name_and_id(
                 item=item, type=endpoint_type.capitalize(), workspace=workspace_id
             )
+        if endpoint_type == "sqldatabase":
+            # SQLDatabase is has special case for resolving the name and id
+            (resource_name, resource_id) = resolve_item_name_and_id(
+                item=item, type="SQLDatabase", workspace=workspace_id
+            )
         else:
             (resource_name, resource_id) = resolve_lakehouse_name_and_id(
                 lakehouse=item, workspace=workspace_id
@@ -61,6 +66,8 @@ class ConnectBase:
 
         if endpoint_type == "warehouse":
             tds_endpoint = response.json().get("properties", {}).get("connectionString")
+        if endpoint_type == "sqldatabase":
+            tds_endpoint = response.json().get("properties", {}).get("serverFqdn")
         else:
             tds_endpoint = (
                 response.json()
@@ -72,7 +79,10 @@ class ConnectBase:
         # Set up the connection string
         access_token = SynapseTokenProvider()()
         tokenstruct = _bytes2mswin_bstr(access_token.encode())
-        conn_str = f"DRIVER={{ODBC Driver 18 for SQL Server}};SERVER={tds_endpoint};DATABASE={resource_name};Encrypt=Yes;"
+        if endpoint_type == "sqldatabase":
+            conn_str = f"DRIVER={{ODBC Driver 18 for SQL Server}};SERVER={tds_endpoint};DATABASE={resource_name}-{resource_id};Encrypt=Yes;"
+        else:
+            conn_str = f"DRIVER={{ODBC Driver 18 for SQL Server}};SERVER={tds_endpoint};DATABASE={resource_name};Encrypt=Yes;"
 
         if timeout is not None:
             conn_str += f"Connect Timeout={timeout};"
@@ -141,10 +151,24 @@ class ConnectBase:
 class ConnectWarehouse(ConnectBase):
     def __init__(
         self,
-        warehouse: str,
+        warehouse: str | UUID,
         workspace: Optional[Union[str, UUID]] = None,
-        timeout: Optional[int] = None,
+        timeout: int = 30,
     ):
+        """
+        Run a SQL or T-SQL query against a Fabric Warehouse.
+
+        Parameters
+        ----------
+        warehouse : str | uuid.UUID
+            The name or ID of the Fabric warehouse.
+        workspace : str | uuid.UUID, default=None
+            The name or ID of the 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.
+        timeout : int, default=30
+            The timeout for the connection in seconds.
+        """
         super().__init__(
             item=warehouse,
             workspace=workspace,
@@ -156,13 +180,56 @@ class ConnectWarehouse(ConnectBase):
 class ConnectLakehouse(ConnectBase):
     def __init__(
         self,
-        lakehouse: str,
+        lakehouse: str | UUID,
         workspace: Optional[Union[str, UUID]] = None,
-        timeout: Optional[int] = None,
+        timeout: int = 30,
     ):
+        """
+        Run a SQL or T-SQL query against a Fabric lakehouse.
+
+        Parameters
+        ----------
+        lakehouse : str | uuid.UUID
+            The name or ID of the Fabric lakehouse.
+        workspace : str | uuid.UUID, default=None
+            The name or ID of the 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.
+        timeout : int, default=30
+            The timeout for the connection in seconds.
+        """
         super().__init__(
             item=lakehouse,
             workspace=workspace,
             timeout=timeout,
             endpoint_type="lakehouse",
         )
+
+
+class ConnectSQLDatabase(ConnectBase):
+    def __init__(
+        self,
+        sql_database: str | UUID,
+        workspace: Optional[Union[str, UUID]] = None,
+        timeout: int = 30,
+    ):
+        """
+        Run a SQL or T-SQL query against a Fabric SQL database.
+
+        Parameters
+        ----------
+        sql_database : str | uuid.UUID
+            The name or ID of the Fabric SQL database.
+        workspace : str | uuid.UUID, default=None
+            The name or ID of the 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.
+        timeout : int, default=30
+            The timeout for the connection in seconds.
+        """
+        super().__init__(
+            item=sql_database,
+            workspace=workspace,
+            timeout=timeout,
+            endpoint_type="sqldatabase",
+        )

sempy_labs/_sqldatabase.py

@@ -0,0 +1,227 @@
+import sempy.fabric as fabric
+from sempy_labs._helper_functions import (
+    resolve_workspace_name_and_id,
+    _base_api,
+    _create_dataframe,
+    _update_dataframe_datatypes,
+)
+import pandas as pd
+from typing import Optional
+import sempy_labs._icons as icons
+from uuid import UUID
+
+## Still debugging the creation of an sql database
+# def create_warehouse(
+#     warehouse: str,
+#     description: Optional[str] = None,
+#     case_insensitive_collation: bool = False,
+#     workspace: Optional[str | UUID] = None,
+# ):
+#     """
+#     Creates a Fabric warehouse.
+
+#     This is a wrapper function for the following API: `Items - Create Warehouse <https://learn.microsoft.com/rest/api/fabric/warehouse/items/create-warehouse>`_.
+
+#     Parameters
+#     ----------
+#     warehouse: str
+#         Name of the warehouse.
+#     description : str, default=None
+#         A description of the warehouse.
+#     case_insensitive_collation: bool, default=False
+#         If True, creates the warehouse with case-insensitive collation.
+#     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)
+
+#     payload = {"displayName": warehouse}
+
+#     if description:
+#         payload["description"] = description
+#     if case_insensitive_collation:
+#         payload.setdefault("creationPayload", {})
+#         payload["creationPayload"][
+#             "defaultCollation"
+#         ] = "Latin1_General_100_CI_AS_KS_WS_SC_UTF8"
+
+#     _base_api(
+#         request=f"/v1/workspaces/{workspace_id}/warehouses",
+#         payload=payload,
+#         method="post",
+#         lro_return_status_code=True,
+#         status_codes=[201, 202],
+#     )
+
+#     print(
+#         f"{icons.green_dot} The '{warehouse}' warehouse has been created within the '{workspace_name}' workspace."
+#     )
+
+
+def _list_sql_databases(workspace: Optional[str | UUID] = None) -> pd.DataFrame:
+    """
+    Shows the databses within a workspace.
+
+
+    Parameters
+    ----------
+    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.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing the SQLDabatases within a workspace.
+    """
+
+    columns = {
+        "SQL Database Name": "string",
+        "SQL Database Id": "string",
+        "Description": "string",
+        "Connection Type": "string",
+        "Connection Info": "string",
+        "Database Name": "string",
+        "Server FQDN": "string",
+        "Provisioning Status": "string",
+        "Created Date": "datetime",
+        "Last Updated Time UTC": "datetime",
+    }
+    df = _create_dataframe(columns=columns)
+
+    (workspace_name, workspace_id) = resolve_workspace_name_and_id(workspace)
+
+    responses = _base_api(
+        request=f"/v1/workspaces/{workspace_id}/sqldatabases", uses_pagination=True
+    )
+
+    for r in responses:
+        for v in r.get("value", []):
+            prop = v.get("properties", {})
+
+            new_data = {
+                "SQL Database Name": v.get("displayName"),
+                "SQL Database Id": v.get("id"),
+                "Description": v.get("description"),
+                "Connection Type": v.get("type"),
+                "Connection Info": prop.get("connectionInfo"),
+                "Database Name": prop.get("databaseName"),
+                "Server FQDN": prop.get("serverFqdn"),
+                "Provisioning Status": prop.get("provisioningState"),
+                "Created Date": prop.get("createdDate"),
+                "Last Updated Time UTC": prop.get("lastUpdatedTimeUtc"),
+            }
+            df = pd.concat([df, pd.DataFrame(new_data, index=[0])], ignore_index=True)
+
+    _update_dataframe_datatypes(dataframe=df, column_map=columns)
+
+    return df
+
+
+## Still debugging the deletion of an sql database
+# def delete_warehouse(name: str, workspace: Optional[str | UUID] = None):
+#     """
+#     Deletes a Fabric warehouse.
+
+#     This is a wrapper function for the following API: `Items - Delete Warehouse <https://learn.microsoft.com/rest/api/fabric/warehouse/items/delete-warehouse>`_.
+
+#     Parameters
+#     ----------
+#     name: str
+#         Name 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."
+#     )
+
+
+def get_sql_database_tables(
+    sql_database: str | UUID, workspace: Optional[str | UUID] = None
+) -> pd.DataFrame:
+    """
+    Shows a list of the tables in the Fabric SQLDabatse. This function is based on INFORMATION_SCHEMA.TABLES.
+
+    Parameters
+    ----------
+    sql_database : str | uuid.UUID
+        Name or ID of the Fabric SQLDabatase.
+    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.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of the tables in the Fabric SQLDabatase.
+    """
+
+    from sempy_labs._sql import ConnectSQLDatabase
+
+    with ConnectSQLDatabase(sql_database=sql_database, workspace=workspace) as sql:
+        df = sql.query(
+            """
+        SELECT TABLE_SCHEMA AS [Schema], TABLE_NAME AS [Table Name], TABLE_TYPE AS [Table Type]
+        FROM INFORMATION_SCHEMA.TABLES
+        WHERE TABLE_TYPE = 'BASE TABLE'
+        """
+        )
+
+    return df
+
+
+def get_sql_database_columns(
+    sql_database: str | UUID, workspace: Optional[str | UUID] = None
+) -> pd.DataFrame:
+    """
+    Shows a list of the columns in each table within the Fabric SQLDabatase. This function is based on INFORMATION_SCHEMA.COLUMNS.
+
+    Parameters
+    ----------
+    sql_database : str | uuid.UUID
+        Name or ID of the Fabric SQLDabatase.
+    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.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of the columns in each table within the Fabric SQLDabatase.
+    """
+
+    from sempy_labs._sql import ConnectSQLDatabase
+
+    with ConnectSQLDatabase(sql_database=sql_database, workspace=workspace) as sql:
+        df = sql.query(
+            """
+        SELECT t.TABLE_SCHEMA AS [Schema], t.TABLE_NAME AS [Table Name], c.COLUMN_NAME AS [Column Name], c.DATA_TYPE AS [Data Type], c.IS_NULLABLE AS [Is Nullable], c.CHARACTER_MAXIMUM_LENGTH AS [Character Max Length]
+        FROM INFORMATION_SCHEMA.TABLES AS t
+        LEFT JOIN INFORMATION_SCHEMA.COLUMNS AS c
+        ON t.TABLE_NAME = c.TABLE_NAME
+        AND t.TABLE_SCHEMA = c.TABLE_SCHEMA
+        WHERE t.TABLE_TYPE = 'BASE TABLE'
+        """
+        )
+
+    return df

sempy_labs/admin/__init__.py

@@ -1,21 +1,48 @@
+from sempy_labs.admin._shared import (
+    list_widely_shared_artifacts,
+)
+from sempy_labs.admin._datasets import (
+    list_datasets,
+    list_dataset_users,
+)
+from sempy_labs.admin._apps import (
+    list_apps,
+    list_app_users,
+)
+from sempy_labs.admin._reports import (
+    list_reports,
+    list_report_users,
+)
+from sempy_labs.admin._activities import (
+    list_activity_events,
+)
 from sempy_labs.admin._scanner import (
     scan_workspaces,
 )
+from sempy_labs.admin._capacities import (
+    patch_capacity,
+    list_capacities,
+    get_capacity_assignment_status,
+    get_capacity_state,
+)
+from sempy_labs.admin._tenant import (
+    list_tenant_settings,
+    delete_capacity_tenant_setting_override,
+    update_tenant_setting,
+    update_capacity_tenant_setting_override,
+    list_workspaces_tenant_settings_overrides,
+    list_capacity_tenant_settings_overrides,
+    list_capacities_delegated_tenant_settings,
+    list_domain_tenant_settings_overrides,
+)
 from sempy_labs.admin._basic_functions import (
     assign_workspaces_to_capacity,
     unassign_workspaces_from_capacity,
     list_workspaces,
     list_workspace_access_details,
     list_modified_workspaces,
-    list_datasets,
-    list_reports,
-    list_capacities,
-    list_tenant_settings,
-    list_capacities_delegated_tenant_settings,
     list_access_entities,
-    list_activity_events,
-    get_capacity_assignment_status,
-    get_capacity_state,
+    list_workspace_users,
 )
 from sempy_labs.admin._domains import (
     list_domains,
@@ -72,4 +99,18 @@ __all__ = [
     "get_capacity_assignment_status",
     "scan_workspaces",
     "get_capacity_state",
+    "list_apps",
+    "list_app_users",
+    "list_dataset_users",
+    "list_report_users",
+    "patch_capacity",
+    "list_workspace_users",
+    "list_widely_shared_artifacts",
+    "delete_capacity_tenant_setting_override",
+    "update_tenant_setting",
+    "update_capacity_tenant_setting_override",
+    "list_workspaces_tenant_settings_overrides",
+    "list_capacity_tenant_settings_overrides",
+    "list_capacities_delegated_tenant_settings",
+    "list_domain_tenant_settings_overrides",
 ]

sempy_labs/admin/_activities.py

@@ -0,0 +1,166 @@
+import pandas as pd
+from typing import Optional
+from dateutil.parser import parse as dtparser
+from sempy._utils._log import log
+from sempy_labs._helper_functions import (
+    _base_api,
+    _create_dataframe,
+    _update_dataframe_datatypes,
+)
+import sempy_labs._icons as icons
+
+
+@log
+def list_activity_events(
+    start_time: str,
+    end_time: str,
+    activity_filter: Optional[str] = None,
+    user_id_filter: Optional[str] = None,
+    return_dataframe: bool = True,
+) -> pd.DataFrame | dict:
+    """
+    Shows a list of audit activity events for a tenant.
+
+    This is a wrapper function for the following API: `Admin - Get Activity Events <https://learn.microsoft.com/rest/api/power-bi/admin/get-activity-events>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    start_time : str
+        Start date and time of the window for audit event results. Example: "2024-09-25T07:55:00".
+    end_time : str
+        End date and time of the window for audit event results. Example: "2024-09-25T08:55:00".
+    activity_filter : str, default=None
+        Filter value for activities. Example: 'viewreport'.
+    user_id_filter : str, default=None
+        Email address of the user.
+    return_dataframe : bool, default=True
+        If True the response is a pandas.DataFrame. If False returns the original Json. Default True
+
+    Returns
+    -------
+    pandas.DataFrame | dict
+        A pandas dataframe or json showing a list of audit activity events for a tenant.
+    """
+    start_dt = dtparser(start_time)
+    end_dt = dtparser(end_time)
+
+    if not start_dt.date() == end_dt.date():
+        raise ValueError(
+            f"{icons.red_dot} Start and End Times must be within the same UTC day. Please refer to the documentation here: https://learn.microsoft.com/rest/api/power-bi/admin/get-activity-events#get-audit-activity-events-within-a-time-window-and-for-a-specific-activity-type-and-user-id-example"
+        )
+
+    columns = {
+        "Id": "string",
+        "Record Type": "string",
+        "Creation Time": "datetime",
+        "Operation": "string",
+        "Organization Id": "string",
+        "User Type": "string",
+        "User Key": "string",
+        "Workload": "string",
+        "Result Status": "string",
+        "User Id": "string",
+        "Client IP": "string",
+        "User Agent": "string",
+        "Activity": "string",
+        "Workspace Name": "string",
+        "Workspace Id": "string",
+        "Object Id": "string",
+        "Request Id": "string",
+        "Object Type": "string",
+        "Object Display Name": "string",
+        "Experience": "string",
+        "Refresh Enforcement Policy": "string",
+        "Is Success": "bool",
+        "Activity Id": "string",
+        "Item Name": "string",
+        "Dataset Name": "string",
+        "Report Name": "string",
+        "Capacity Id": "string",
+        "Capacity Name": "string",
+        "App Name": "string",
+        "Dataset Id": "string",
+        "Report Id": "string",
+        "Artifact Id": "string",
+        "Artifact Name": "string",
+        "Report Type": "string",
+        "App Report Id": "string",
+        "Distribution Method": "string",
+        "Consumption Method": "string",
+        "Artifact Kind": "string",
+    }
+    df = _create_dataframe(columns=columns)
+
+    response_json = {"activityEventEntities": []}
+    url = f"/v1.0/myorg/admin/activityevents?startDateTime='{start_time}'&endDateTime='{end_time}'"
+
+    conditions = []
+    if activity_filter is not None:
+        conditions.append(f"Activity eq '{activity_filter}'")
+    if user_id_filter is not None:
+        conditions.append(f"UserId eq '{user_id_filter}'")
+
+    if conditions:
+        url += f"&$filter={f' and '.join(conditions)}"
+
+    responses = _base_api(request=url, client="fabric_sp", uses_pagination=True)
+
+    for r in responses:
+        if return_dataframe:
+            for i in r.get("activityEventEntities", []):
+                new_data = {
+                    "Id": i.get("id"),
+                    "Record Type": i.get("RecordType"),
+                    "Creation Time": i.get("CreationTime"),
+                    "Operation": i.get("Operation"),
+                    "Organization Id": i.get("OrganizationId"),
+                    "User Type": i.get("UserType"),
+                    "User Key": i.get("UserKey"),
+                    "Workload": i.get("Workload"),
+                    "Result Status": i.get("ResultStatus"),
+                    "User Id": i.get("UserId"),
+                    "Client IP": i.get("ClientIP"),
+                    "User Agent": i.get("UserAgent"),
+                    "Activity": i.get("Activity"),
+                    "Workspace Name": i.get("WorkSpaceName"),
+                    "Workspace Id": i.get("WorkspaceId"),
+                    "Object Id": i.get("ObjectId"),
+                    "Request Id": i.get("RequestId"),
+                    "Object Type": i.get("ObjectType"),
+                    "Object Display Name": i.get("ObjectDisplayName"),
+                    "Experience": i.get("Experience"),
+                    "Refresh Enforcement Policy": i.get("RefreshEnforcementPolicy"),
+                    "Is Success": i.get("IsSuccess"),
+                    "Activity Id": i.get("ActivityId"),
+                    "Item Name": i.get("ItemName"),
+                    "Dataset Name": i.get("DatasetName"),
+                    "Report Name": i.get("ReportName"),
+                    "Capacity Id": i.get("CapacityId"),
+                    "Capacity Name": i.get("CapacityName"),
+                    "App Name": i.get("AppName"),
+                    "Dataset Id": i.get("DatasetId"),
+                    "Report Id": i.get("ReportId"),
+                    "Artifact Id": i.get("ArtifactId"),
+                    "Artifact Name": i.get("ArtifactName"),
+                    "Report Type": i.get("ReportType"),
+                    "App Report Id": i.get("AppReportId"),
+                    "Distribution Method": i.get("DistributionMethod"),
+                    "Consumption Method": i.get("ConsumptionMethod"),
+                    "Artifact Kind": i.get("ArtifactKind"),
+                }
+                df = pd.concat(
+                    [df, pd.DataFrame(new_data, index=[0])],
+                    ignore_index=True,
+                )
+        else:
+            response_json["activityEventEntities"].extend(
+                r.get("activityEventEntities")
+            )
+
+    if return_dataframe:
+        _update_dataframe_datatypes(dataframe=df, column_map=columns)
+        return df
+    else:
+        return response_json