semantic-link-labs 0.9.6__py3-none-any.whl → 0.9.7__py3-none-any.whl

sempy_labs/directlake/_update_directlake_model_lakehouse_connection.py

@@ -1,18 +1,64 @@
-import sempy.fabric as fabric
 from sempy_labs.directlake._generate_shared_expression import generate_shared_expression
 from sempy_labs._helper_functions import (
-    resolve_lakehouse_name,
     resolve_dataset_name_and_id,
     resolve_workspace_name_and_id,
     resolve_item_name_and_id,
     resolve_lakehouse_name_and_id,
 )
+from sempy._utils._log import log
 from sempy_labs.tom import connect_semantic_model
 from typing import Optional
 import sempy_labs._icons as icons
 from uuid import UUID
+import re
 
 
+def _extract_expression_list(expression):
+    """
+    Finds the pattern for DL/SQL & DL/OL expressions in the semantic model.
+    """
+
+    pattern_sql = r'Sql\.Database\s*\(\s*"([^"]+)"\s*,\s*"([^"]+)"\s*\)'
+    pattern_no_sql = r'AzureDataLakeStorage\s*\{\s*"server".*?:\s*onelake\.dfs\.fabric\.microsoft\.com"\s*,\s*"path"\s*:\s*"/([\da-fA-F-]+)\s*/\s*([\da-fA-F-]+)\s*/"\s*\}'
+
+    match_sql = re.search(pattern_sql, expression)
+    match_no_sql = re.search(pattern_no_sql, expression)
+
+    result = []
+    if match_sql:
+        value_1, value_2 = match_sql.groups()
+        result = [value_1, value_2, True]
+    elif match_no_sql:
+        value_1, value_2 = match_no_sql.groups()
+        result = [value_1, value_2, False]
+
+    return result
+
+
+def _get_direct_lake_expressions(
+    dataset: str | UUID, workspace: Optional[str | UUID] = None
+) -> dict:
+    """
+    Extracts a dictionary of all Direct Lake expressions from a semantic model.
+    """
+
+    from sempy_labs.tom import connect_semantic_model
+
+    result = {}
+
+    with connect_semantic_model(dataset=dataset, workspace=workspace) as tom:
+        for e in tom.model.Expressions:
+            expr_name = e.Name
+            expr = e.Expression
+
+            list_values = _extract_expression_list(expr)
+            if list_values:
+                result[expr_name] = list_values
+
+    return result
+
+
+@log
 def update_direct_lake_model_lakehouse_connection(
     dataset: str | UUID,
     workspace: Optional[str | UUID] = None,
@@ -39,41 +85,23 @@ def update_direct_lake_model_lakehouse_connection(
         or if no lakehouse attached, resolves to the workspace of the notebook.
     """
 
-    (workspace_name, workspace_id) = resolve_workspace_name_and_id(workspace)
-    (dataset_name, dataset_id) = resolve_dataset_name_and_id(dataset, workspace_id)
-
-    (lakehouse_name, lakehouse_id) = resolve_lakehouse_name_and_id(
-        lakehouse=lakehouse, workspace=lakehouse_workspace
-    )
-
-    icons.sll_tags.append("UpdateDLConnection")
-
-    shEx = generate_shared_expression(
-        item_name=lakehouse, item_type="Lakehouse", workspace=lakehouse_workspace
-    )
-
-    with connect_semantic_model(
-        dataset=dataset_id, readonly=False, workspace=workspace_id
-    ) as tom:
-
-        if not tom.is_direct_lake():
-            raise ValueError(
-                f"{icons.red_dot} The '{dataset_name}' semantic model is not in Direct Lake. This function is only applicable to Direct Lake semantic models."
-            )
-
-        tom.model.Expressions["DatabaseQuery"].Expression = shEx
-
-    print(
-        f"{icons.green_dot} The expression in the '{dataset_name}' semantic model has been updated to point to the '{lakehouse}' lakehouse in the '{lakehouse_workspace}' workspace."
+    update_direct_lake_model_connection(
+        dataset=dataset,
+        workspace=workspace,
+        source=lakehouse,
+        source_type="Lakehouse",
+        source_workspace=lakehouse_workspace,
     )
 
 
+@log
 def update_direct_lake_model_connection(
     dataset: str | UUID,
     workspace: Optional[str | UUID] = None,
     source: Optional[str] = None,
     source_type: str = "Lakehouse",
     source_workspace: Optional[str | UUID] = None,
+    use_sql_endpoint: bool = True,
 ):
     """
     Remaps a Direct Lake semantic model's SQL Endpoint connection to a new lakehouse/warehouse.
@@ -95,7 +123,14 @@ def update_direct_lake_model_connection(
         The Fabric workspace name or ID used by the lakehouse/warehouse.
         Defaults to None which resolves to the workspace of the attached lakehouse
         or if no lakehouse attached, resolves to the workspace of the notebook.
+    use_sql_endpoint : bool, default=True
+        If True, the SQL Endpoint will be used for the connection.
+        If False, Direct Lake over OneLake will be used.
     """
+    if use_sql_endpoint:
+        icons.sll_tags.append("UpdateDLConnection_SQL")
+    else:
+        icons.sll_tags.append("UpdateDLConnection_DLOL")
 
     (workspace_name, workspace_id) = resolve_workspace_name_and_id(workspace)
     (dataset_name, dataset_id) = resolve_dataset_name_and_id(dataset, workspace_id)
@@ -119,12 +154,16 @@ def update_direct_lake_model_connection(
             item=source, type=source_type, workspace=source_workspace
         )
 
-    icons.sll_tags.append("UpdateDLConnection")
-
-    shEx = generate_shared_expression(
-        item_name=source_name, item_type=source_type, workspace=source_workspace
+    shared_expression = generate_shared_expression(
+        item_name=source_name,
+        item_type=source_type,
+        workspace=source_workspace,
+        use_sql_endpoint=use_sql_endpoint,
     )
 
+    expression_dict = _get_direct_lake_expressions(dataset=dataset, workspace=workspace)
+    expressions = list(expression_dict.keys())
+
     with connect_semantic_model(
         dataset=dataset_id, readonly=False, workspace=workspace_id
     ) as tom:
@@ -134,8 +173,15 @@ def update_direct_lake_model_connection(
                 f"{icons.red_dot} The '{dataset_name}' semantic model within the '{workspace_name}' workspace is not in Direct Lake. This function is only applicable to Direct Lake semantic models."
             )
 
-        tom.model.Expressions["DatabaseQuery"].Expression = shEx
+        # Update the single connection expression
+        if len(expressions) == 1:
+            expr = expressions[0]
+            tom.model.Expressions[expr].Expression = shared_expression
 
-    print(
-        f"{icons.green_dot} The expression in the '{dataset_name}' semantic model within the '{workspace_name}' workspace has been updated to point to the '{source}' {source_type.lower()} in the '{source_workspace}' workspace."
-    )
+            print(
+                f"{icons.green_dot} The expression in the '{dataset_name}' semantic model within the '{workspace_name}' workspace has been updated to point to the '{source}' {source_type.lower()} in the '{source_workspace}' workspace."
+            )
+        else:
+            print(
+                f"{icons.info} Multiple expressions found in the model. Please use the update_direct_lake_partition_entity function to update specific tables."
+            )

sempy_labs/directlake/_update_directlake_partition_entity.py

@@ -8,11 +8,13 @@ from sempy_labs._helper_functions import (
     resolve_workspace_name_and_id,
     resolve_workspace_name,
 )
+from sempy._utils._log import log
 from typing import List, Optional, Union
 import sempy_labs._icons as icons
 from uuid import UUID
 
 
+@log
 def update_direct_lake_partition_entity(
     dataset: str | UUID,
     table_name: Union[str, List[str]],
@@ -96,6 +98,7 @@ def update_direct_lake_partition_entity(
             )
 
 
+@log
 def add_table_to_direct_lake_semantic_model(
     dataset: str | UUID,
     table_name: str,

sempy_labs/graph/_groups.py

@@ -6,6 +6,7 @@ from sempy_labs._helper_functions import (
     _create_dataframe,
     _update_dataframe_datatypes,
 )
+from sempy._utils._log import log
 import sempy_labs._icons as icons
 from typing import List, Literal
 
@@ -38,6 +39,7 @@ def resolve_group_id(group: str | UUID) -> UUID:
     return group_id
 
 
+@log
 def list_groups() -> pd.DataFrame:
     """
     Shows a list of groups and their properties.
@@ -158,6 +160,7 @@ def _get_group(group_id: UUID) -> pd.DataFrame:
     return df
 
 
+@log
 def list_group_members(group: str | UUID) -> pd.DataFrame:
     """
     Shows a list of the members of a group.
@@ -217,6 +220,7 @@ def list_group_members(group: str | UUID) -> pd.DataFrame:
     return df
 
 
+@log
 def list_group_owners(group: str | UUID) -> pd.DataFrame:
     """
     Shows a list of the owners of a group.
@@ -332,6 +336,7 @@ def _base_add_to_group(
     )
 
 
+@log
 def add_group_members(
     group: str | UUID,
     user: str | UUID | List[str | UUID],
@@ -376,6 +381,7 @@ def add_group_owners(
     _base_add_to_group(group=group, object=user, object_type="owners")
 
 
+@log
 def renew_group(group: str | UUID):
     """
     Renews the group.

sempy_labs/graph/_teams.py

@@ -1,5 +1,6 @@
 import pandas as pd
 from uuid import UUID
+from sempy._utils._log import log
 from sempy_labs._helper_functions import (
     _base_api,
     _create_dataframe,
@@ -7,6 +8,7 @@ from sempy_labs._helper_functions import (
 )
 
 
+@log
 def list_teams() -> pd.DataFrame:
     """
     Shows a list of teams and their properties.

sempy_labs/graph/_users.py

@@ -7,6 +7,7 @@ from sempy_labs._helper_functions import (
     _base_api,
     _create_dataframe,
 )
+from sempy._utils._log import log
 
 
 def resolve_user_id(user: str | UUID) -> UUID:
@@ -33,6 +34,7 @@ def resolve_user_id(user: str | UUID) -> UUID:
         return result.get("id")
 
 
+@log
 def get_user(user: str | UUID) -> pd.DataFrame:
     """
     Shows properties of a given user.
@@ -70,6 +72,7 @@ def get_user(user: str | UUID) -> pd.DataFrame:
     return pd.DataFrame([new_data])
 
 
+@log
 def list_users() -> pd.DataFrame:
     """
     Shows a list of users and their properties.
@@ -120,6 +123,7 @@ def list_users() -> pd.DataFrame:
     return df
 
 
+@log
 def send_mail(
     user: UUID | str,
     subject: str,

sempy_labs/lakehouse/__init__.py

@@ -1,12 +1,15 @@
-from sempy_labs.lakehouse._get_lakehouse_columns import get_lakehouse_columns
-from sempy_labs.lakehouse._get_lakehouse_tables import get_lakehouse_tables
+from sempy_labs.lakehouse._get_lakehouse_columns import (
+    get_lakehouse_columns,
+)
+from sempy_labs.lakehouse._get_lakehouse_tables import (
+    get_lakehouse_tables,
+)
 from sempy_labs.lakehouse._lakehouse import (
     lakehouse_attached,
     optimize_lakehouse_tables,
     vacuum_lakehouse_tables,
     run_table_maintenance,
 )
-
 from sempy_labs.lakehouse._shortcuts import (
     # create_shortcut,
     create_shortcut_onelake,
@@ -14,6 +17,10 @@ from sempy_labs.lakehouse._shortcuts import (
     reset_shortcut_cache,
     list_shortcuts,
 )
+from sempy_labs.lakehouse._blobs import (
+    recover_lakehouse_object,
+    list_blobs,
+)
 
 __all__ = [
     "get_lakehouse_columns",
@@ -27,4 +34,6 @@ __all__ = [
     "reset_shortcut_cache",
     "run_table_maintenance",
     "list_shortcuts",
+    "recover_lakehouse_object",
+    "list_blobs",
 ]

sempy_labs/lakehouse/_blobs.py

@@ -0,0 +1,231 @@
+from sempy_labs._helper_functions import (
+    resolve_workspace_id,
+    resolve_lakehouse_id,
+    _xml_to_dict,
+    _create_dataframe,
+    _update_dataframe_datatypes,
+)
+from sempy._utils._log import log
+from uuid import UUID
+from typing import Optional, List
+import sempy_labs._icons as icons
+import xml.etree.ElementTree as ET
+import pandas as pd
+
+
+def _request_blob_api(
+    request: str,
+    method: str = "get",
+    payload: Optional[dict] = None,
+    status_codes: int | List[int] = 200,
+):
+
+    import requests
+    import notebookutils
+    from sempy.fabric.exceptions import FabricHTTPException
+
+    if isinstance(status_codes, int):
+        status_codes = [status_codes]
+
+    token = notebookutils.credentials.getToken("storage")
+
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/json",
+        "x-ms-version": "2025-05-05",
+    }
+
+    response = requests.request(
+        method.upper(),
+        f"https://onelake.blob.fabric.microsoft.com/{request}",
+        headers=headers,
+        json=payload,
+    )
+
+    if response.status_code not in status_codes:
+        raise FabricHTTPException(response)
+
+    return response
+
+
+@log
+def list_blobs(
+    lakehouse: Optional[str | UUID] = None,
+    workspace: Optional[str | UUID] = None,
+    container: Optional[str] = None,
+) -> pd.DataFrame:
+    """
+    Returns a list of blobs for a given lakehouse.
+
+    This function leverages the following API: `List Blobs <https://learn.microsoft.com/rest/api/storageservices/list-blobs?tabs=microsoft-entra-id>`_.
+
+    Parameters
+    ----------
+    lakehouse : str | uuid.UUID, default=None
+        The Fabric lakehouse name or ID.
+        Defaults to None which resolves to the lakehouse attached to the notebook.
+    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.
+    container : str, default=None
+        The container name to list blobs from. If None, lists all blobs in the lakehouse.
+        Valid values are "Tables" or "Files". If not specified, the function will list all blobs in the lakehouse.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of blobs in the lakehouse.
+    """
+
+    workspace_id = resolve_workspace_id(workspace)
+    lakehouse_id = resolve_lakehouse_id(lakehouse, workspace_id)
+
+    if container is None:
+        path_prefix = f"{workspace_id}/{lakehouse_id}"
+    else:
+        if container not in ["Tables", "Files"]:
+            raise ValueError(
+                f"{icons.red_dot} Invalid container '{container}' within the file_path parameter. Expected 'Tables' or 'Files'."
+            )
+        path_prefix = f"{workspace_id}/{lakehouse_id}/{container}"
+
+    response = _request_blob_api(
+        request=f"{path_prefix}?restype=container&comp=list&include=deleted"
+    )
+    root = ET.fromstring(response.content)
+    response_json = _xml_to_dict(root)
+
+    columns = {
+        "Blob Name": "str",
+        "Is Deleted": "bool",
+        "Deletion Id": "str",
+        "Creation Time": "datetime",
+        "Expiry Time": "datetime",
+        "Etag": "str",
+        "Resource Type": "str",
+        "Content Length": "int",
+        "Content Type": "str",
+        "Content Encoding": "str",
+        "Content Language": "str",
+        "Content CRC64": "str",
+        "Content MD5": "str",
+        "Cache Control": "str",
+        "Content Disposition": "str",
+        "Blob Type": "str",
+        "Access Tier": "str",
+        "Access Tier Inferred": "str",
+        "Server Encrypted": "bool",
+        "Deleted Time": "str",
+        "Remaining Retention Days": "str",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    for blob in (
+        response_json.get("EnumerationResults", {}).get("Blobs", {}).get("Blob", {})
+    ):
+        p = blob.get("Properties", {})
+        new_data = {
+            "Blob Name": blob.get("Name"),
+            "Is Deleted": blob.get("Deleted", False),
+            "Deletion Id": blob.get("DeletionId"),
+            "Creation Time": p.get("Creation-Time"),
+            "Expiry Time": p.get("Expiry-Time"),
+            "Etag": p.get("Etag"),
+            "Resource Type": p.get("ResourceType"),
+            "Content Length": p.get("Content-Length"),
+            "Content Type": p.get("Content-Type"),
+            "Content Encoding": p.get("Content-Encoding"),
+            "Content Language": p.get("Content-Language"),
+            "Content CRC64": p.get("Content-CRC64"),
+            "Content MD5": p.get("Content-MD5"),
+            "Cache Control": p.get("Cache-Control"),
+            "Content Disposition": p.get("Content-Disposition"),
+            "Blob Type": p.get("BlobType"),
+            "Access Tier": p.get("AccessTier"),
+            "Access Tier Inferred": p.get("AccessTierInferred"),
+            "Server Encrypted": p.get("ServerEncrypted"),
+            "Deleted Time": p.get("DeletedTime"),
+            "Remaining Retention Days": p.get("RemainingRetentionDays"),
+        }
+
+        df = pd.concat([df, pd.DataFrame(new_data, index=[0])], ignore_index=True)
+
+    _update_dataframe_datatypes(dataframe=df, column_map=columns)
+
+    return df
+
+
+@log
+def recover_lakehouse_object(
+    file_path: str,
+    lakehouse: Optional[str | UUID] = None,
+    workspace: Optional[str | UUID] = None,
+):
+    """
+    Recovers an object (i.e. table, file, folder) in a lakehouse from a deleted state. Only `soft-deleted objects <https://learn.microsoft.com/fabric/onelake/onelake-disaster-recovery#soft-delete-for-onelake-files>`_ can be recovered (deleted for less than 7 days).
+
+    Parameters
+    ----------
+    file_path : str
+        The file path of the object to restore. For example: "Tables/my_delta_table".
+    lakehouse : str | uuid.UUID, default=None
+        The Fabric lakehouse name or ID.
+        Defaults to None which resolves to the lakehouse attached to the notebook.
+    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_id = resolve_workspace_id(workspace)
+    lakehouse_id = resolve_lakehouse_id(lakehouse, workspace_id)
+
+    blob_path_prefix = f"{lakehouse_id}/{file_path}"
+
+    container = file_path.split("/")[0]
+    if container not in ["Tables", "Files"]:
+        raise ValueError(
+            f"{icons.red_dot} Invalid container '{container}' within the file_path parameter. Expected 'Tables' or 'Files'."
+        )
+
+    df = list_blobs(lakehouse=lakehouse, workspace=workspace, container=container)
+
+    for _, r in df.iterrows():
+        blob_name = r.get("Blob Name")
+        is_deleted = r.get("Is Deleted")
+        if blob_name.startswith(blob_path_prefix) and is_deleted:
+            print(f"{icons.in_progress} Restoring the '{blob_name}' blob...")
+            _request_blob_api(
+                request=f"{workspace_id}/{lakehouse_id}/{file_path}?comp=undelete",
+                method="put",
+            )
+            print(f"{icons.green_dot} The '{blob_name}' blob has been restored.")
+
+
+def _get_user_delegation_key():
+
+    # https://learn.microsoft.com/rest/api/storageservices/get-user-delegation-key
+
+    from datetime import datetime, timedelta, timezone
+
+    utc_now = datetime.now(timezone.utc)
+    start_time = utc_now + timedelta(minutes=2)
+    expiry_time = start_time + timedelta(minutes=45)
+    start_str = start_time.strftime("%Y-%m-%dT%H:%M:%SZ")
+    expiry_str = expiry_time.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    payload = f"""<?xml version="1.0" encoding="utf-8"?>
+    <KeyInfo>
+        <Start>{start_str}</Start>
+        <Expiry>{expiry_str}</Expiry>
+    </KeyInfo>"""
+
+    response = _request_blob_api(
+        request="restype=service&comp=userdelegationkey",
+        method="post",
+        payload=payload,
+    )
+
+    return response.content

sempy_labs/lakehouse/_shortcuts.py

@@ -24,12 +24,15 @@ def create_shortcut_onelake(
     shortcut_name: Optional[str] = None,
     source_path: str = "Tables",
     destination_path: str = "Tables",
+    shortcut_conflict_policy: Optional[str] = None,
 ):
     """
     Creates a `shortcut <https://learn.microsoft.com/fabric/onelake/onelake-shortcuts>`_ to a delta table in OneLake.
 
     This is a wrapper function for the following API: `OneLake Shortcuts - Create Shortcut <https://learn.microsoft.com/rest/api/fabric/core/onelake-shortcuts/create-shortcut>`_.
 
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
     Parameters
     ----------
     table_name : str
@@ -51,6 +54,8 @@ def create_shortcut_onelake(
         A string representing the full path to the table/file in the source lakehouse, including either "Files" or "Tables". Examples: Tables/FolderName/SubFolderName; Files/FolderName/SubFolderName.
     destination_path: str, default="Tables"
         A string representing the full path where the shortcut is created, including either "Files" or "Tables". Examples: Tables/FolderName/SubFolderName; Files/FolderName/SubFolderName.
+    shortcut_conflict_policy : str, default=None
+        When provided, it defines the action to take when a shortcut with the same name and path already exists. The default action is 'Abort'. Additional ShortcutConflictPolicy types may be added over time.
     """
 
     if not (source_path.startswith("Files") or source_path.startswith("Tables")):
@@ -103,7 +108,8 @@ def create_shortcut_onelake(
     # Check if the shortcut already exists
     try:
         response = _base_api(
-            request=f"/v1/workspaces/{destination_workspace_id}/items/{destination_lakehouse_id}/shortcuts/{destination_path}/{actual_shortcut_name}"
+            request=f"/v1/workspaces/{destination_workspace_id}/items/{destination_lakehouse_id}/shortcuts/{destination_path}/{actual_shortcut_name}",
+            client="fabric_sp",
         )
         response_json = response.json()
         del response_json["target"]["type"]
@@ -119,11 +125,21 @@ def create_shortcut_onelake(
     except FabricHTTPException:
         pass
 
+    url = f"/v1/workspaces/{destination_workspace_id}/items/{destination_lakehouse_id}/shortcuts"
+
+    if shortcut_conflict_policy:
+        if shortcut_conflict_policy not in ["Abort", "GenerateUniqueName"]:
+            raise ValueError(
+                f"{icons.red_dot} The 'shortcut_conflict_policy' parameter must be either 'Abort' or 'GenerateUniqueName'."
+            )
+        url += f"?shortcutConflictPolicy={shortcut_conflict_policy}"
+
     _base_api(
-        request=f"/v1/workspaces/{destination_workspace_id}/items/{destination_lakehouse_id}/shortcuts",
+        request=url,
         payload=payload,
         status_codes=201,
         method="post",
+        client="fabric_sp",
     )
 
     print(
@@ -211,6 +227,8 @@ def delete_shortcut(
 
     This is a wrapper function for the following API: `OneLake Shortcuts - Delete Shortcut <https://learn.microsoft.com/rest/api/fabric/core/onelake-shortcuts/delete-shortcut>`_.
 
+    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
     Parameters
     ----------
     shortcut_name : str
@@ -234,6 +252,7 @@ def delete_shortcut(
     _base_api(
         request=f"/v1/workspaces/{workspace_id}/items/{lakehouse_id}/shortcuts/{shortcut_path}/{shortcut_name}",
         method="delete",
+        client="fabric_sp",
     )
 
     print(
@@ -288,7 +307,7 @@ def list_shortcuts(
         Defaults to None which resolves to the workspace of the attached lakehouse
         or if no lakehouse attached, resolves to the workspace of the notebook.
     path: str, default=None
-        The path within lakehouse where to look for shortcuts. If provied, must start with either "Files" or "Tables". Examples: Tables/FolderName/SubFolderName; Files/FolderName/SubFolderName.
+        The path within lakehouse where to look for shortcuts. If provided, must start with either "Files" or "Tables". Examples: Tables/FolderName/SubFolderName; Files/FolderName/SubFolderName.
         Defaults to None which will retun all shortcuts on the given lakehouse
 
     Returns