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

sempy_labs/graph/_groups.py

@@ -0,0 +1,402 @@
+import pandas as pd
+from uuid import UUID
+from sempy_labs._helper_functions import (
+    _is_valid_uuid,
+    _base_api,
+    _create_dataframe,
+    _update_dataframe_datatypes,
+)
+import sempy_labs._icons as icons
+from typing import List, Literal
+
+
+def resolve_group_id(group: str | UUID) -> UUID:
+    """
+    Resolves the group ID from the group name or ID.
+
+    Service Principal Authentication is required (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    group : str | uuid.UUID
+        The group name or ID.
+
+    Returns
+    -------
+    uuid.UUID
+        The group ID.
+    """
+    if _is_valid_uuid(group):
+        group_id = group
+    else:
+        dfG = list_groups()
+        dfG_filt = dfG[dfG["Group Name"] == group]
+        if dfG_filt.empty:
+            raise ValueError(f"{icons.red_dot} The '{group}' group does not exist.")
+        group_id = dfG_filt["Group Id"].iloc[0]
+
+    return group_id
+
+
+def list_groups() -> pd.DataFrame:
+    """
+    Shows a list of groups and their properties.
+
+    This is a wrapper function for the following API: `List groups <https://learn.microsoft.com/graph/api/group-list>`_.
+
+    Service Principal Authentication is required (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 groups and their properties.
+    """
+
+    result = _base_api(request="groups", client="graph").json()
+
+    columns = {
+        "Group Id": "string",
+        "Group Name": "string",
+        "Mail": "string",
+        "Description": "string",
+        "Classification": "string",
+        "Mail Enabled": "bool",
+        "Security Enabled": "bool",
+        "Created Date Time": "datetime",
+        "Expiration Date Time": "string",
+        "Deleted Date Time": "string",
+        "Renewed Date Time": "string",
+        "Visibility": "string",
+        "Security Identifier": "string",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    for v in result.get("value"):
+        new_data = {
+            "Group Id": v.get("id"),
+            "Group Name": v.get("displayName"),
+            "Mail": v.get("mail"),
+            "Description": v.get("description"),
+            "Classification": v.get("classification"),
+            "Mail Enabled": v.get("mailEnabled"),
+            "Security Enabled": v.get("securityEnabled"),
+            "Created Date Time": v.get("createdDateTime"),
+            "Expiration Date Time": v.get("expirationDateTime"),
+            "Renewed Date Time": v.get("renewedDateTime"),
+            "Deleted Date Time": v.get("deletedDateTime"),
+            "Visibility": v.get("visibility"),
+            "Security Identifier": v.get("securityIdentifier"),
+        }
+
+        df = pd.concat([df, pd.DataFrame(new_data, index=[0])], ignore_index=True)
+
+    _update_dataframe_datatypes(dataframe=df, column_map=columns)
+
+    return df
+
+
+def _get_group(group_id: UUID) -> pd.DataFrame:
+    """
+    Shows a list of groups and their properties.
+
+    This is a wrapper function for the following API: `Get group <https://learn.microsoft.com/graph/api/group-get>`_.
+
+    Service Principal Authentication is required (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    group_id : uuid.UUID
+        The group ID.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of groups and their properties.
+    """
+
+    result = _base_api(request=f"groups/{group_id}", client="graph").json()
+
+    columns = {
+        "Group Id": "string",
+        "Group Name": "string",
+        "Mail": "string",
+        "Description": "string",
+        "Classification": "string",
+        "Mail Enabled": "bool",
+        "Security Enabled": "bool",
+        "Created Date Time": "datetime",
+        "Expiration Date Time": "string",
+        "Deleted Date Time": "string",
+        "Renewed Date Time": "string",
+        "Visibility": "string",
+        "Security Identifier": "string",
+    }
+    df = _create_dataframe(columns=columns)
+
+    for v in result.get("value"):
+        new_data = {
+            "Group Id": v.get("id"),
+            "Group Name": v.get("displayName"),
+            "Mail": v.get("mail"),
+            "Description": v.get("description"),
+            "Classification": v.get("classification"),
+            "Mail Enabled": v.get("mailEnabled"),
+            "Security Enabled": v.get("securityEnabled"),
+            "Created Date Time": v.get("createdDateTime"),
+            "Expiration Date Time": v.get("expirationDateTime"),
+            "Deleted Date Time": v.get("deletedDateTime"),
+            "Renewed Date Time": v.get("renewedDateTime"),
+            "Visibility": v.get("visibility"),
+            "Security Identifier": v.get("securityIdentifier"),
+        }
+
+        df = pd.concat([df, pd.DataFrame(new_data, index=[0])], ignore_index=True)
+
+    _update_dataframe_datatypes(dataframe=df, column_map=columns)
+
+    return df
+
+
+def list_group_members(group: str | UUID) -> pd.DataFrame:
+    """
+    Shows a list of the members of a group.
+
+    This is a wrapper function for the following API: `List group members <https://learn.microsoft.com/graph/api/group-list-members>`_.
+
+    Service Principal Authentication is required (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    group : str | uuid.UUID
+        The group name or ID.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of the members of a group.
+    """
+
+    group_id = resolve_group_id(group)
+
+    result = _base_api(request=f"groups/{group_id}/members", client="graph").json()
+
+    columns = {
+        "Member Id": "string",
+        "Member Name": "string",
+        "User Principal Name": "string",
+        "Mail": "string",
+        "Job Title": "string",
+        "Office Location": "string",
+        "Mobile Phone": "string",
+        "Business Phones": "string",
+        "Preferred Language": "string",
+        "Given Name": "string",
+        "Surname": "string",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    for v in result.get("value"):
+        new_data = {
+            "Member Id": v.get("id"),
+            "Member Name": v.get("displayName"),
+            "User Principal Name": v.get("userPrincipalName"),
+            "Mail": v.get("mail"),
+            "Job Title": v.get("jobTitle"),
+            "Office Location": v.get("officeLocation"),
+            "Mobile Phone": v.get("mobilePhone"),
+            "Business Phones": str(v.get("businessPhones")),
+            "Preferred Language": v.get("preferredLanguage"),
+            "Given Name": v.get("givenName"),
+            "Surname": v.get("surname"),
+        }
+
+        df = pd.concat([df, pd.DataFrame(new_data, index=[0])], ignore_index=True)
+
+    return df
+
+
+def list_group_owners(group: str | UUID) -> pd.DataFrame:
+    """
+    Shows a list of the owners of a group.
+
+    This is a wrapper function for the following API: `List group owners <https://learn.microsoft.com/graph/api/group-list-owners>`_.
+
+    Service Principal Authentication is required (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    group : str | uuid.UUID
+        The group name or ID.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing a list of the owners of a group.
+    """
+
+    group_id = resolve_group_id(group)
+
+    result = _base_api(request=f"groups/{group_id}/owners", client="graph").json()
+
+    columns = {
+        "Owner Id": "string",
+        "Owner Name": "string",
+        "User Principal Name": "string",
+        "Mail": "string",
+        "Job Title": "string",
+        "Office Location": "string",
+        "Mobile Phone": "string",
+        "Business Phones": "string",
+        "Preferred Language": "string",
+        "Given Name": "string",
+        "Surname": "string",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    for v in result.get("value"):
+        new_data = {
+            "Owner Id": v.get("id"),
+            "Owner Name": v.get("displayName"),
+            "User Principal Name": v.get("userPrincipalName"),
+            "Mail": v.get("mail"),
+            "Job Title": v.get("jobTitle"),
+            "Office Location": v.get("officeLocation"),
+            "Mobile Phone": v.get("mobilePhone"),
+            "Business Phones": str(v.get("businessPhones")),
+            "Preferred Language": v.get("preferredLanguage"),
+            "Given Name": v.get("givenName"),
+            "Surname": v.get("surname"),
+        }
+
+        df = pd.concat([df, pd.DataFrame(new_data, index=[0])], ignore_index=True)
+
+    return df
+
+
+def _base_add_to_group(
+    group: str | UUID,
+    object: str | UUID,
+    object_type: Literal["members", "owners"],
+):
+
+    from sempy_labs.graph._users import resolve_user_id
+
+    object_list = []
+
+    if isinstance(object, str):
+        object = [object]
+
+    group_id = resolve_group_id(group)
+    url = f"groups/{group_id}/{object_type}/$ref"
+
+    for m in object:
+        if _is_valid_uuid(m):
+            member_id = m
+        else:
+            member_id = resolve_user_id(m)
+        if object_type == "members":
+            object_list.append(
+                f"https://graph.microsoft.com/v1.0/directoryObjects/{member_id}"
+            )
+        else:
+            object_list.append(f"https://graph.microsoft.com/v1.0/users/{member_id}")
+
+    # Must submit one request for each owner. Members can be sent in a single request.
+    if object_type == "members":
+        payload = {"members@odata.bind": object_list}
+
+        _base_api(
+            request=url,
+            client="graph",
+            payload=payload,
+            method="post",
+            status_codes=204,
+        )
+
+    else:
+        for o in object_list:
+            payload = {"odata.id": o}
+            _base_api(
+                request=url,
+                client="graph",
+                payload=payload,
+                method="post",
+                status_codes=204,
+            )
+
+    print(
+        f"{icons.green_dot} The {object} {object_type[:-1]}(s) have been added to the '{group}' group."
+    )
+
+
+def add_group_members(
+    group: str | UUID,
+    user: str | UUID | List[str | UUID],
+):
+    """
+    Adds a member to a group.
+
+    This is a wrapper function for the following API: `Add members <https://learn.microsoft.com/graph/api/group-post-members>`_.
+
+    Service Principal Authentication is required (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    group : str | uuid.UUID
+        The group name or ID.
+    user : str | uuid.UUID
+        The user ID or user principal name.
+    """
+
+    _base_add_to_group(group=group, object=user, object_type="members")
+
+
+def add_group_owners(
+    group: str | UUID,
+    user: str | UUID | List[str | UUID],
+):
+    """
+    Adds an owner to a group.
+
+    This is a wrapper function for the following API: `Add owners <https://learn.microsoft.com/graph/api/group-post-owners>`_.
+
+    Service Principal Authentication is required (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    group : str | uuid.UUID
+        The group name or ID.
+    user : str | uuid.UUID
+        The user ID or user principal name.
+    """
+
+    _base_add_to_group(group=group, object=user, object_type="owners")
+
+
+def renew_group(group: str | UUID):
+    """
+    Renews the group.
+
+    This is a wrapper function for the following API: `Renew group <https://learn.microsoft.com/graph/api/group-post-renew>`_.
+
+    Service Principal Authentication is required (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    group : str | uuid.UUID
+        The group name or ID.
+    """
+
+    group_id = resolve_group_id(group)
+
+    _base_api(
+        request=f"groups/{group_id}/renew",
+        client="graph",
+        method="post",
+        status_codes=204,
+    )
+
+    print(f"{icons.green_dot} The '{group}' group has been renewed.")

sempy_labs/graph/_teams.py

@@ -0,0 +1,113 @@
+import pandas as pd
+from uuid import UUID
+from sempy_labs._helper_functions import (
+    _base_api,
+    _create_dataframe,
+    _update_dataframe_datatypes,
+)
+
+
+def list_teams() -> pd.DataFrame:
+    """
+    Shows a list of teams and their properties.
+
+    This is a wrapper function for the following API: `List teams <https://learn.microsoft.com/graph/api/teams-list>`_.
+
+    Service Principal Authentication is required (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 teams and their properties.
+    """
+
+    result = _base_api(request="teams", client="graph").json()
+
+    columns = {
+        "Team Id": "str",
+        "Team Name": "str",
+        "Description": "str",
+        "Creation Date Time": "datetime",
+        "Classification": "str",
+        "Specialization": "str",
+        "Visibility": "str",
+        "Web Url": "str",
+        "Archived": "bool",
+        "Favorite By Me": "bool",
+        "Discoverable By Me": "bool",
+        "Member Count": "int",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    for v in result.get("value"):
+        new_data = {
+            "Team Id": v.get("id"),
+            "Team Name": v.get("displayName"),
+            "Description": v.get("description"),
+            "Creation Date Time": v.get("createdDateTime"),
+            "Classification": v.get("classification"),
+            "Specialization": v.get("specialization"),
+            "Visibility": v.get("visibility"),
+            "Web Url": v.get("webUrl"),
+            "Archived": v.get("isArchived"),
+            "Favorite By Me": v.get("isFavoriteByMe"),
+            "Discoverable By Me": v.get("isDiscoverableByMe"),
+            "Member Count": v.get("memberCount"),
+        }
+
+        df = pd.concat([df, pd.DataFrame(new_data, index=[0])], ignore_index=True)
+
+    _update_dataframe_datatypes(dataframe=df, column_map=columns)
+
+    return df
+
+
+def list_chats(user: str | UUID) -> pd.DataFrame:
+    """
+    In progress...
+    """
+
+    from sempy_labs.graph._users import resolve_user_id
+
+    user_id = resolve_user_id(user=user)
+    result = _base_api(request=f"users/{user_id}/chats", client="graph").json()
+
+    columns = {
+        "Chat Id": "str",
+        "Type": "str",
+        "Members": "str",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    for v in result.get("value"):
+        new_data = {
+            "Chat Id": v.get("id"),
+            "Type": v.get("chatType"),
+            "Members": v.get("members"),
+        }
+
+        df = pd.concat([df, pd.DataFrame(new_data, index=[0])], ignore_index=True)
+
+    return df
+
+
+def send_teams_message(chat_id: str, message: str):
+    """
+    In progress...
+    """
+
+    payload = {
+        "body": {
+            "content": message,
+        }
+    }
+
+    _base_api(
+        request=f"chats/{chat_id}/messages",
+        client="graph",
+        method="post",
+        payload=payload,
+        status_codes=201,
+    )

sempy_labs/graph/_users.py

@@ -0,0 +1,191 @@
+import pandas as pd
+from uuid import UUID
+import sempy_labs._icons as icons
+from typing import List
+from sempy_labs._helper_functions import (
+    _is_valid_uuid,
+    _base_api,
+    _create_dataframe,
+)
+
+
+def resolve_user_id(user: str | UUID) -> UUID:
+    """
+    Resolves the user ID from the user principal name or ID.
+
+    Service Principal Authentication is required (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    user : str | uuid.UUID
+        The user ID or user principal name.
+
+    Returns
+    -------
+    uuid.UUID
+        The user ID.
+    """
+
+    if _is_valid_uuid(user):
+        return user
+    else:
+        result = _base_api(request=f"users/{user}", client="graph").json()
+        return result.get("id")
+
+
+def get_user(user: str | UUID) -> pd.DataFrame:
+    """
+    Shows properties of a given user.
+
+    This is a wrapper function for the following API: `Get a user <https://learn.microsoft.com/graph/api/user-get>`_.
+
+    Service Principal Authentication is required (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    user : str | uuid.UUID
+        The user ID or user principal name.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A pandas dataframe showing properties of a given user.
+    """
+
+    result = _base_api(request=f"users/{user}", client="graph").json()
+
+    new_data = {
+        "User Id": result.get("id"),
+        "User Principal Name": result.get("userPrincipalName"),
+        "User Name": result.get("displayName"),
+        "Mail": result.get("mail"),
+        "Job Title": result.get("jobTitle"),
+        "Office Location": result.get("officeLocation"),
+        "Mobile Phone": result.get("mobilePhone"),
+        "Business Phones": str(result.get("businessPhones")),
+        "Preferred Language": result.get("preferredLanguage"),
+        "Surname": result.get("surname"),
+    }
+
+    return pd.DataFrame([new_data])
+
+
+def list_users() -> pd.DataFrame:
+    """
+    Shows a list of users and their properties.
+
+    This is a wrapper function for the following API: `List users <https://learn.microsoft.com/graph/api/user-list>`_.
+
+    Service Principal Authentication is required (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 users and their properties.
+    """
+
+    result = _base_api(request="users", client="graph").json()
+
+    columns = {
+        "User Id": "string",
+        "User Principal Name": "string",
+        "User Name": "string",
+        "Mail": "string",
+        "Job Title": "string",
+        "Office Location": "string",
+        "Mobile Phone": "string",
+        "Business Phones": "string",
+        "Preferred Language": "string",
+        "Surname": "string",
+    }
+
+    df = _create_dataframe(columns=columns)
+
+    for v in result.get("value"):
+        new_data = {
+            "User Id": v.get("id"),
+            "User Principal Name": v.get("userPrincipalName"),
+            "User Name": v.get("displayName"),
+            "Mail": v.get("mail"),
+            "Job Title": v.get("jobTitle"),
+            "Office Location": v.get("officeLocation"),
+            "Mobile Phone": v.get("mobilePhone"),
+            "Business Phones": str(v.get("businessPhones")),
+            "Preferred Language": v.get("preferredLanguage"),
+            "Surname": v.get("surname"),
+        }
+
+        df = pd.concat([df, pd.DataFrame(new_data, index=[0])], ignore_index=True)
+
+    return df
+
+
+def send_mail(
+    user: UUID | str,
+    subject: str,
+    to_recipients: str | List[str],
+    content: str,
+    cc_recipients: str | List[str] = None,
+):
+    """
+    Sends an email to the specified recipients.
+
+    This is a wrapper function for the following API: `user: sendMail <https://learn.microsoft.com/graph/api/user-sendmail>`_.
+
+    Service Principal Authentication is required (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
+
+    Parameters
+    ----------
+    user : uuid.UUID | str
+        The user ID or user principal name.
+    subject : str
+        The email subject.
+    to_recipients : str | List[str]
+        The email address of the recipients.
+    content : str
+        The email content.
+    cc_recipients : str | List[str], default=None
+        The email address of the CC recipients.
+    """
+
+    user_id = resolve_user_id(user=user)
+
+    if isinstance(to_recipients, str):
+        to_recipients = [to_recipients]
+
+    if isinstance(cc_recipients, str):
+        cc_recipients = [cc_recipients]
+
+    to_email_addresses = [
+        {"emailAddress": {"address": email}} for email in to_recipients
+    ]
+
+    cc_email_addresses = (
+        [{"emailAddress": {"address": email}} for email in cc_recipients]
+        if cc_recipients
+        else None
+    )
+
+    payload = {
+        "message": {
+            "subject": subject,
+            "body": {
+                "contentType": "Text",
+                "content": content,
+            },
+            "toRecipients": to_email_addresses,
+        },
+    }
+
+    if cc_email_addresses:
+        payload["message"]["ccRecipients"] = cc_email_addresses
+
+    _base_api(
+        request=f"users/{user_id}/sendMail",
+        client="graph",
+        status_codes=202,
+        payload=payload,
+        method="post",
+    )
+
+    print(f"{icons.green_dot} The email has been sent to {to_recipients}.")