semantic-link-labs 0.12.8__py3-none-any.whl

sempy_labs/_sql_audit_settings.py

@@ -0,0 +1,207 @@
+from sempy_labs._helper_functions import (
+    resolve_item_id,
+    resolve_workspace_name_and_id,
+    _base_api,
+    _create_dataframe,
+    _update_dataframe_datatypes,
+    resolve_workspace_id,
+)
+import pandas as pd
+from typing import Optional, List, Literal
+import sempy_labs._icons as icons
+from uuid import UUID
+from sempy._utils._log import log
+
+
+def _get_base_url(item, type, workspace):
+
+    workspace_id = resolve_workspace_id(workspace)
+    item_id = resolve_item_id(item=item, type=type, workspace=workspace)
+
+    type_dict = {
+        "Warehouse": "warehouses",
+        "SQLEndpoint": "sqlEndpoints",
+    }
+    type_for_url = type_dict.get(type)
+
+    if type in ["SQLEndpoint", "Warehouse"]:
+        url = f"/v1/workspaces/{workspace_id}/{type_for_url}/{item_id}"
+    else:
+        raise ValueError(
+            f"{icons.red_dot} The type must be 'Warehouse' or 'SQLEndpoint'."
+        )
+
+    return url
+
+
+@log
+def get_sql_audit_settings(
+    item: str | UUID,
+    type: Literal["Warehouse", "SQLEndpoint"],
+    workspace: Optional[str | UUID] = None,
+) -> pd.DataFrame:
+    """
+    Shows the SQL audit settings of a Fabric item.
+
+    This is a wrapper function for the following API: `SQL Audit Settings - Get SQL Audit Settings <https://learn.microsoft.com/rest/api/fabric/warehouse/sql-audit-settings/get-sql-audit-settings>`_.
+
+    Service Principal Authentication is supported (see `here <https://learn.microsoft.com/rest/api/fabric/warehouse/sql-audit-settings/get-sql-audit-settings#service-principal-authentication>`_).
+
+    Parameters
+    ----------
+    item : str | uuid.UUID
+        The name or ID of the item (Warehouse or SQLEndpoint).
+    type : Literal['Warehouse', 'SQLEndpoint']
+        The type of the item. Must be 'Warehouse' or 'SQLEndpoint'.
+    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 containing the SQL audit settings of the specified warehouse.
+    """
+
+    columns = {
+        "State": "string",
+        "Retention Days": "int",
+        "Audit Actions And Group": "list",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    url = _get_base_url(item=item, type=type, workspace=workspace)
+    response = _base_api(
+        request=f"{url}/settings/sqlAudit",
+        client="fabric_sp",
+    ).json()
+
+    rows = []
+    rows.append(
+        {
+            "State": response.get("state"),
+            "Retention Days": response.get("retentionDays"),
+            "Audit Actions And Group": response.get("auditActionsAndGroups"),
+        }
+    )
+
+    if rows:
+        df = pd.DataFrame(rows, columns=list(columns.keys()))
+        _update_dataframe_datatypes(dataframe=df, column_map=columns)
+
+    return df
+
+
+@log
+def update_sql_audit_settings(
+    item: str | UUID,
+    type: Literal["Warehouse", "SQLEndpoint"],
+    workspace: Optional[str | UUID] = None,
+    retention_days: Optional[int] = None,
+    state: Optional[str] = None,
+):
+    """
+    Update settings associated with the item.
+
+    This is a wrapper function for the following API: SQL Audit Settings - Update SQL Audit Settings <https://learn.microsoft.com/rest/api/fabric/warehouse/sql-audit-settings/update-sql-audit-settings>`_.
+
+    Service Principal Authentication is supported (see `here <https://learn.microsoft.com/rest/api/fabric/warehouse/sql-audit-settings/get-sql-audit-settings#service-principal-authentication>`_).
+
+    Parameters
+    ----------
+    item : str | uuid.UUID
+        The name or ID of the item (Warehouse or SQLEndpoint).
+    type : Literal['Warehouse', 'SQLEndpoint']
+        The type of the item. Must be 'Warehouse' or 'SQLEndpoint'.
+    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 = {}
+    if retention_days is not None:
+        if not isinstance(retention_days, int) or retention_days < 0:
+            raise ValueError(
+                f"{icons.red_dot} retention_days must be a non-negative integer."
+            )
+        payload["retentionDays"] = retention_days
+    if state is not None:
+        state = state.capitalize()
+        if state not in ["Enabled", "Disabled"]:
+            raise ValueError(
+                f"{icons.red_dot} state must be either 'Enabled' or 'Disabled'."
+            )
+        payload["state"] = state
+
+    if not payload:
+        print(
+            f"{icons.info} No updates were made as neither retention_days nor state were provided."
+        )
+        return
+
+    url = _get_base_url(item=item, type=type, workspace=workspace)
+    _base_api(
+        request=f"{url}/settings/sqlAudit",
+        client="fabric_sp",
+        method="patch",
+        payload=payload,
+    )
+
+    print(
+        f"{icons.green_dot} The SQL audit settings for the '{item}' {type.lower()} within the '{workspace_name}' workspace have been updated accordingly."
+    )
+
+
+@log
+def set_audit_actions_and_group(
+    item: str | UUID,
+    type: Literal["Warehouse", "SQLEndpoint"],
+    sql_audit_groups: List[str],
+    workspace: Optional[str | UUID] = None,
+):
+    """
+    Update the audit actions and groups for this item.
+
+    This is a wrapper function for the following API: SQL Audit Settings - Set Audit Actions And Groups <https://learn.microsoft.com/rest/api/fabric/warehouse/sql-audit-settings/set-audit-actions-and-groups>`_.
+
+    Service Principal Authentication is supported (see `here <https://learn.microsoft.com/rest/api/fabric/warehouse/sql-audit-settings/get-sql-audit-settings#service-principal-authentication>`_).
+
+    Parameters
+    ----------
+    item : str | uuid.UUID
+        The name or ID of the item (Warehouse or SQLEndpoint).
+    type : Literal['Warehouse', 'SQLEndpoint']
+        The type of the item. Must be 'Warehouse' or 'SQLEndpoint'.
+    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)
+
+    if (
+        not sql_audit_groups
+        or not isinstance(sql_audit_groups, list)
+        or not all(isinstance(item, str) for item in sql_audit_groups)
+    ):
+        raise ValueError(
+            f"{icons.red_dot} sql_audit_groups must be a non-empty list of strings."
+        )
+
+    url = _get_base_url(item=item, type=type, workspace=workspace)
+    _base_api(
+        request=f"{url}/settings/sqlAudit/setAuditActionsAndGroups",
+        client="fabric_sp",
+        method="post",
+        payload=sql_audit_groups,
+    )
+
+    print(
+        f"{icons.green_dot} The SQL audit actions and groups for the '{item}' {type.lower()} within the '{workspace_name}' workspace have been updated accordingly."
+    )

sempy_labs/_sql_endpoints.py

@@ -0,0 +1,214 @@
+from typing import Optional, Literal
+from uuid import UUID
+import pandas as pd
+from sempy_labs._helper_functions import (
+    _base_api,
+    _create_dataframe,
+    resolve_workspace_name_and_id,
+    resolve_item_name_and_id,
+    _update_dataframe_datatypes,
+    resolve_workspace_id,
+)
+import sempy_labs._icons as icons
+from sempy._utils._log import log
+
+
+@log
+def list_sql_endpoints(workspace: Optional[str | UUID] = None) -> pd.DataFrame:
+    """
+    Shows the SQL endpoints 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 SQL endpoints within a workspace.
+    """
+
+    columns = {
+        "SQL Endpoint Id": "string",
+        "SQL Endpoint Name": "string",
+        "Description": "string",
+    }
+    df = _create_dataframe(columns=columns)
+
+    workspace_id = resolve_workspace_id(workspace)
+
+    responses = _base_api(
+        request=f"/v1/workspaces/{workspace_id}/sqlEndpoints", uses_pagination=True
+    )
+
+    rows = []
+    for r in responses:
+        for v in r.get("value", []):
+            rows.append(
+                {
+                    "SQL Endpoint Id": v.get("id"),
+                    "SQL Endpoint Name": v.get("displayName"),
+                    "Description": v.get("description"),
+                }
+            )
+
+    if rows:
+        df = pd.DataFrame(rows, columns=list(columns.keys()))
+
+    return df
+
+
+@log
+def refresh_sql_endpoint_metadata(
+    item: str | UUID,
+    type: Literal["Lakehouse", "MirroredDatabase"],
+    workspace: Optional[str | UUID] = None,
+    timeout_unit: Literal["Seconds", "Minutes", "Hours", "Days"] = "Minutes",
+    timeout_value: int = 15,
+) -> pd.DataFrame:
+    """
+    Refreshes the metadata of a SQL endpoint.
+
+    This is a wrapper function for the following API: `Items - Refresh Sql Endpoint Metadata <https://learn.microsoft.com/rest/api/fabric/sqlendpoint/items/refresh-sql-endpoint-metadata>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    item : str | uuid.UUID
+        The name or ID of the item (Lakehouse or MirroredDatabase).
+    type : Literal['Lakehouse', 'MirroredDatabase']
+        The type of the item. Must be 'Lakehouse' or 'MirroredDatabase'.
+    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.
+    timeout_unit : Literal['Seconds', 'Minutes', 'Hours', 'Days'], default='Minutes'
+        The unit of time for the request duration before timing out. Additional duration types may be added over time.
+    timeout_value : int, default=15
+        The number of time units in the request duration.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing the status of the metadata refresh operation.
+    """
+
+    (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
+    )
+
+    if type == "Lakehouse":
+        response = _base_api(
+            request=f"/v1/workspaces/{workspace_id}/lakehouses/{item_id}",
+            client="fabric_sp",
+        )
+        sql_endpoint_id = (
+            response.json()
+            .get("properties", {})
+            .get("sqlEndpointProperties", {})
+            .get("id")
+        )
+    elif type == "MirroredDatabase":
+        response = _base_api(
+            request=f"/v1/workspaces/{workspace_id}/mirroredDatabases/{item_id}",
+            client="fabric_sp",
+        )
+        sql_endpoint_id = (
+            response.json()
+            .get("properties", {})
+            .get("sqlEndpointProperties", {})
+            .get("id")
+        )
+    else:
+        raise ValueError("Invalid type. Must be 'Lakehouse' or 'MirroredDatabase'.")
+
+    timeout_unit = timeout_unit.capitalize()
+    if timeout_unit not in ["Seconds", "Minutes", "Hours", "Days"]:
+        raise ValueError(
+            "Invalid timeout_unit. Must be 'Seconds', 'Minutes', 'Hours', or 'Days'."
+        )
+    if timeout_unit == "Hours" and timeout_value > 24:
+        raise ValueError("timeout_value cannot exceed 24 when timeout_unit is 'Hours'.")
+    if timeout_unit == "Days" and timeout_value > 1:
+        raise ValueError("timeout_value cannot exceed 1 when timeout_unit is 'Days'.")
+    if timeout_unit == "Minutes" and timeout_value > 1440:
+        raise ValueError(
+            "timeout_value cannot exceed 1440 when timeout_unit is 'Minutes'."
+        )
+    if timeout_unit == "Seconds" and timeout_value > 86400:
+        raise ValueError(
+            "timeout_value cannot exceed 86400 when timeout_unit is 'Seconds'."
+        )
+
+    payload = {"timeout": {"timeUnit": timeout_unit, "value": timeout_value}}
+
+    result = _base_api(
+        request=f"v1/workspaces/{workspace_id}/sqlEndpoints/{sql_endpoint_id}/refreshMetadata",
+        method="post",
+        client="fabric_sp",
+        status_codes=[200, 202],
+        lro_return_json=True,
+        payload=payload,
+    )
+
+    columns = {
+        "Table Name": "string",
+        "Status": "string",
+        "Start Time": "datetime",
+        "End Time": "datetime",
+        "Last Successful Sync Time": "datetime",
+        "Error Code": "string",
+        "Error Message": "string",
+    }
+
+    if result:
+        df = pd.json_normalize(result.get("value"))
+
+        # Extract error code and message, set to None if no error
+        df["Error Code"] = df.get("error.errorCode", None)
+        df["Error Message"] = df.get("error.message", None)
+
+        # Friendly column renaming
+        df.rename(
+            columns={
+                "tableName": "Table Name",
+                "startDateTime": "Start Time",
+                "endDateTime": "End Time",
+                "status": "Status",
+                "lastSuccessfulSyncDateTime": "Last Successful Sync Time",
+            },
+            inplace=True,
+        )
+
+        # Drop the original 'error' column if present
+        df.drop(columns=[col for col in ["error"] if col in df.columns], inplace=True)
+
+        # Optional: Reorder columns
+        column_order = [
+            "Table Name",
+            "Status",
+            "Start Time",
+            "End Time",
+            "Last Successful Sync Time",
+            "Error Code",
+            "Error Message",
+        ]
+        df = df[column_order]
+
+        printout = f"{icons.green_dot} The metadata of the SQL endpoint for the '{item_name}' {type.lower()} within the '{workspace_name}' workspace has been refreshed"
+        print(f"{printout} for all tables.")
+        _update_dataframe_datatypes(df, columns)
+    else:
+        # If the target item has no tables to refresh the metadata for
+        df = pd.DataFrame(columns=columns.keys())
+        print(
+            f"{icons.yellow_dot} The SQL endpoint '{item_name}' {type.lower()} within the '{workspace_name}' workspace has no tables to refresh..."
+        )
+
+    return df

sempy_labs/_tags.py

@@ -0,0 +1,201 @@
+from sempy_labs._helper_functions import (
+    _base_api,
+    _create_dataframe,
+    _update_dataframe_datatypes,
+    resolve_item_name_and_id,
+    resolve_workspace_name_and_id,
+    _is_valid_uuid,
+)
+import pandas as pd
+from typing import Optional, List
+from uuid import UUID
+import sempy_labs._icons as icons
+from sempy._utils._log import log
+
+
+@log
+def list_tags() -> pd.DataFrame:
+    """
+    Shows a list of all the tenant's tags.
+
+    This is a wrapper function for the following API: `Tags - List Tags <https://learn.microsoft.com/rest/api/fabric/core/tags/list-tags>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of all the tenant's tags.
+    """
+
+    columns = {
+        "Tag Name": "string",
+        "Tag Id": "string",
+    }
+    df = _create_dataframe(columns=columns)
+
+    responses = _base_api(
+        request="/v1/tags",
+        uses_pagination=True,
+        client="fabric_sp",
+    )
+
+    rows = []
+    for r in responses:
+        for v in r.get("value", []):
+            rows.append(
+                {
+                    "Tag Name": v.get("displayName"),
+                    "Tag Id": v.get("id"),
+                }
+            )
+
+    if rows:
+        df = pd.DataFrame(rows, columns=list(columns.keys()))
+        _update_dataframe_datatypes(dataframe=df, column_map=columns)
+
+    return df
+
+
+@log
+def resolve_tags(tags: str | List[str]) -> List[str]:
+    """
+    Resolves the tags to a list of strings.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    tags : str | List[str]
+        The tags to resolve.
+
+    Returns
+    -------
+    List[str]
+        A list of resolved tags.
+    """
+
+    if isinstance(tags, str):
+        tags = [tags]
+
+    if all(_is_valid_uuid(tag) for tag in tags):
+        return tags
+
+    df = list_tags()
+
+    tag_list = []
+    for tag in tags:
+        if _is_valid_uuid(tag):
+            tag_list.append(tag)
+        else:
+            df_filt = df[df["Tag Name"] == tag]
+            if df_filt.empty:
+                raise ValueError(f"Tag '{tag}' not found in the tenant's tags.")
+            tag_id = df_filt["Tag Id"].iloc[0]
+            tag_list.append(tag_id)
+
+    return tag_list
+
+
+@log
+def apply_tags(
+    item: str | UUID,
+    type: str,
+    tags: str | UUID | List[str | UUID],
+    workspace: Optional[str | UUID] = None,
+):
+    """
+    Shows a list of all the tenant's tags.
+
+    This is a wrapper function for the following API: `Tags - Apply Tags <https://learn.microsoft.com/rest/api/fabric/core/tags/apply-tags>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    item : str | uuid.UUID
+        The name or ID of the item to apply tags to.
+    type : str
+        The type of the item to apply tags to. For example: "Lakehouse".
+    tags : str | uuid.UUID | List[str | uuid.UUID]
+        The name or ID of the tag(s) to apply to the item.
+    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, type, workspace_id)
+
+    if isinstance(tags, str):
+        tags = [tags]
+
+    tag_list = resolve_tags(tags)
+
+    payload = {
+        "tags": tag_list,
+    }
+
+    _base_api(
+        request=f"/v1/workspaces/{workspace_id}/items/{item_id}/applyTags",
+        client="fabric_sp",
+        method="post",
+        payload=payload,
+    )
+
+    print(
+        f"{icons.green_dot} Tags {tags} applied to the '{item_name}' {type.lower()} within the '{workspace_name}' workspace"
+    )
+
+
+@log
+def unapply_tags(
+    item: str | UUID,
+    type: str,
+    tags: str | UUID | List[str | UUID],
+    workspace: Optional[str | UUID] = None,
+):
+    """
+    Shows a list of all the tenant's tags.
+
+    This is a wrapper function for the following API: `Tags - Unapply Tags <https://learn.microsoft.com/rest/api/fabric/core/tags/unapply-tags>`_.
+
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    item : str | uuid.UUID
+        The name or ID of the item to apply tags to.
+    type : str
+        The type of the item to apply tags to. For example: "Lakehouse".
+    tags : str | uuid.UUID | List[str | uuid.UUID]
+        The name or ID of the tag(s) to apply to the item.
+    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, type, workspace_id)
+
+    if isinstance(tags, str):
+        tags = [tags]
+
+    tag_list = resolve_tags(tags)
+
+    payload = {
+        "tags": tag_list,
+    }
+
+    _base_api(
+        request=f"/v1/workspaces/{workspace_id}/items/{item_id}/unapplyTags",
+        client="fabric_sp",
+        method="post",
+        payload=payload,
+    )
+
+    print(
+        f"{icons.green_dot} Tags {tags} applied to the '{item_name}' {type.lower()} within the '{workspace_name}' workspace"
+    )

sempy_labs/_translations.py

@@ -0,0 +1,43 @@
+import sempy.fabric as fabric
+import pandas as pd
+from typing import List, Optional, Union
+from sempy._utils._log import log
+from uuid import UUID
+
+
+@log
+def translate_semantic_model(
+    dataset: str | UUID,
+    languages: Union[str, List[str]],
+    exclude_characters: Optional[str] = None,
+    workspace: Optional[str | UUID] = None,
+) -> pd.DataFrame:
+    """
+    Translates names, descriptions, display folders for all objects in a semantic model.
+
+    Parameters
+    ----------
+    dataset : str | uuid.UUID
+        Name or ID of the semantic model.
+    languages : str, List[str]
+        The language code(s) in which to translate the semantic model.
+    exclude_characters : str
+        A string specifying characters which will be replaced by a space in the translation text when sent to the translation service.
+    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
+        Shows a pandas dataframe which displays all of the translations in the semantic model.
+    """
+
+    return fabric.translate_semantic_model(
+        dataset=dataset,
+        languages=languages,
+        exclude_characters=exclude_characters,
+        workspace=workspace,
+        model_readonly=False,
+    )