2.1.9 version, type hints, unit tests for Teams API

Author: [email protected]

.travis.yml

@@ -6,6 +6,10 @@ python:
   - "3.7"
   - "3.8"
 
+matrix:
+  allow_failures:
+    - python: "2.7"
+
 install:
   - if [[ $TRAVIS_PYTHON_VERSION == 2.7 ]]; then pip install requests adal setuptools requests_ntlm; fi
   - pip install -r requirements.txt

README.md

@@ -6,7 +6,8 @@ Office 365 & Microsoft Graph library for Python
 1.   [Installation](#Installation)
 1.   [Working with SharePoint API](#Working-with-SharePoint-API) 
 2.   [Working with Outlook API](#Working-with-Outlook-API) 
-3.   [Working with OneDrive API](#Working-with-OneDrive-API)    
+3.   [Working with OneDrive API](#Working-with-OneDrive-API)
+4.   [Working with Microsoft Teams API](#Working-with-Microsoft-Teams-API)    
 
 
 ## Status
@@ -214,6 +215,44 @@ def download_files(remote_folder, local_path):
 Refer [OneDrive examples section](examples/onedrive) for a more examples.
 
 
+# Working with Microsoft Teams API
+
+#### Authentication
+
+[ADAL Python](https://adal-python.readthedocs.io/en/latest/#) 
+library is utilized to authenticate users to Active Directory (AD) and obtain tokens  
+
+#### Examples 
+
+##### Example: create a new team under a group
+
+The example demonstrates how create a new team under a group 
+which corresponds to [`Create team` endpoint](https://docs.microsoft.com/en-us/graph/api/team-put-teams?view=graph-rest-1.0&tabs=http)
+
+```
+
+tenant_name = "contoso.onmicrosoft.com"
+client = GraphClient(tenant_name, get_token)
+new_team = client.groups[group_id].add_team()
+client.execute_query()
+
+```
+
+where
+
+```
+def get_token(auth_ctx):
+    """Acquire token via client credential flow (ADAL Python library is utilized)
+    :type auth_ctx: adal.AuthenticationContext
+    """
+    token = auth_ctx.acquire_token_with_client_credentials(
+        "https://graph.microsoft.com",
+        client_id,
+        client_secret)
+    return token
+```
+
+
 # Third Party Libraries and Dependencies
 The following libraries will be installed when you install the client library:
 * [requests](https://github.com/kennethreitz/requests)

examples/directory/delete_groups.py renamed to examples/directory/delete_deletedObjects.py

@@ -3,6 +3,10 @@
 
 
 def get_token_for_user(auth_ctx):
+    """
+
+    :type auth_ctx: adal.AuthenticationContext
+    """
     token = auth_ctx.acquire_token_with_username_password(
         'https://graph.microsoft.com',
         settings['user_credentials']['username'],
@@ -13,20 +17,15 @@ def get_token_for_user(auth_ctx):
 
 client = GraphClient(settings['tenant'], get_token_for_user)
 
-groups = client.groups
-client.load(groups)
+deleted_groups = client.directory.deletedGroups
+client.load(deleted_groups)
+deleted_users = client.directory.deletedUsers
+client.load(deleted_users)
 client.execute_query()
-no = 1
-groups_count = len(groups)
-for grp in groups:
-    print("({0} of {1}) Deleting {2} group ...".format(no, groups_count, grp.properties['displayName']))
-    # 1st step: delete group
-    grp.delete_object()
-    client.execute_query()
+groups_count = len(deleted_groups)
 
-    # 2nd step: permanently delete (deleted) group
-    deleted_group = client.directory.deletedGroups[grp.id]
-    deleted_group.delete_object()
+for index, deleted_grp in enumerate(deleted_groups):
+    print("({0} of {1}) Deleting {2} group ...".format(index + 1, groups_count, deleted_grp.properties['displayName']))
+    deleted_grp.delete_object()
     client.execute_query()
     print("Group deleted.")
-    no += 1

examples/onedrive/export_files.py

@@ -1,12 +1,13 @@
 import os
 import tempfile
-
 from office365.graph.graph_client import GraphClient
 from settings import settings
 
 
 def get_token(auth_ctx):
-    """Acquire token via client credential flow (ADAL Python library is utilized)"""
+    """Acquire token via client credential flow (ADAL Python library is utilized)
+    :type auth_ctx: adal.AuthenticationContext
+    """
     token = auth_ctx.acquire_token_with_client_credentials(
         "https://graph.microsoft.com",
         settings['client_credentials']['client_id'],
@@ -37,7 +38,7 @@ def download_files(remote_folder, local_path):
 client.load(drive)
 client.execute_query()
 
-# download files from onedrive
+# download files from OneDrive
 with tempfile.TemporaryDirectory() as path:
     download_files(drive.root, path)
     print("Done")

examples/onedrive/import_files.py

@@ -2,10 +2,14 @@
 from os.path import isfile, join
 from settings import settings
 from office365.graph.graph_client import GraphClient
+from office365.graph.onedrive.drive import Drive
 
 
 def get_token(auth_ctx):
-    """Acquire token via client credential flow (ADAL Python library is utilized)"""
+    """Acquire token via client credential flow
+
+    :type auth_ctx: adal.AuthenticationContext
+    """
     token = auth_ctx.acquire_token_with_client_credentials(
         "https://graph.microsoft.com",
         settings['client_credentials']['client_id'],
@@ -14,14 +18,20 @@ def get_token(auth_ctx):
 
 
 def upload_files(remote_drive, local_root_path):
+    """
+    Uploads files from local folder into OneDrive drive
+
+    :type remote_drive: Drive
+    :type local_root_path: str
+    """
     for name in os.listdir(local_root_path):
         path = join(local_root_path, name)
         if isfile(path):
             with open(path, 'rb') as local_file:
                 content = local_file.read()
             uploaded_drive_item = remote_drive.root.upload(name, content)
             remote_drive.context.execute_query()
-            print("File '{0}' uploaded into {1}".format(path, uploaded_drive_item.webUrl),)
+            print("File '{0}' uploaded into {1}".format(path, uploaded_drive_item.webUrl), )
 
 
 # get target drive

examples/onedrive/print_folders_and_files.py

@@ -3,6 +3,11 @@
 
 
 def get_token_for_user(auth_ctx):
+    """
+    Acquire token via user credentials
+
+    :type auth_ctx: adal.AuthenticationContext
+    """
     token = auth_ctx.acquire_token_with_username_password(
         'https://graph.microsoft.com',
         settings['user_credentials']['username'],

examples/teams/__init__.py

@@ -13,9 +13,15 @@ def __init__(self, context, resource_path=None):
         super(DirectoryObjectCollection, self).__init__(context, DirectoryObject, resource_path)
 
     def __getitem__(self, key):
+        """
+
+        :param key: key is used to address a DirectoryObject resource by either an index in collection
+        or by resource id
+        :type key: int or str
+        """
         if type(key) == int:
-            return self._data[key]
-        return DirectoryObject(self.context,
+            return super(DirectoryObjectCollection, self).__getitem__(key)
+        return self._item_type(self.context,
                                ResourcePath(key, self.resource_path))
 
     def getByIds(self, ids):
@@ -40,5 +46,9 @@ def remove(self, user_id):
         self.context.get_pending_request().beforeExecute += self._construct_remove_user_request
 
     def _construct_remove_user_request(self, request):
+        """
+
+        :type request: RequestOptions
+        """
         request.method = HttpMethod.Delete
         self.context.get_pending_request().beforeExecute -= self._construct_remove_user_request

office365/graph/directory/directoryObjectCollection.py

@@ -10,6 +10,16 @@
 from office365.graph.teams.team import Team
 
 
+def _delete_group_from_directory(target_group):
+    """
+    Deletes the group from directory
+
+    :type target_group: Group
+    """
+    deleted_item = target_group.context.directory.deletedGroups[target_group.id]
+    deleted_item.delete_object()
+
+
 class Group(DirectoryObject):
     """Represents an Azure Active Directory (Azure AD) group, which can be an Office 365 group, or a security group."""
 
@@ -22,6 +32,16 @@ def add_team(self):
         self.context.get_pending_request().beforeExecute += self._construct_create_team_request
         return team
 
+    def delete_object(self, permanent_delete=False):
+        """
+        :param permanent_delete: Permanently deletes the group from directory
+        :type permanent_delete: bool
+
+        """
+        super(Group, self).delete_object()
+        if permanent_delete:
+            self.ensure_property("id", _delete_group_from_directory)
+
     def _construct_create_team_request(self, request):
         request.method = HttpMethod.Put
         request.set_header('Content-Type', "application/json")

office365/graph/directory/group.py

@@ -1,10 +1,11 @@
 from office365.graph.directory.directoryObjectCollection import DirectoryObjectCollection
 from office365.graph.directory.group import Group
 from office365.runtime.client_query import CreateEntityQuery
+from office365.graph.directory.groupProfile import GroupProfile
 
 
 class GroupCollection(DirectoryObjectCollection):
-    """User's collection"""
+    """Group's collection"""
 
     def __init__(self, context, resource_path=None):
         super(GroupCollection, self).__init__(context, resource_path)
@@ -13,7 +14,9 @@ def __init__(self, context, resource_path=None):
     def add(self, group_properties):
         """Create a Group resource.  You can create the following types of groups:
         Office 365 group (unified group)
-        Security group"""
+        Security group
+
+        :type group_properties: GroupProfile"""
         grp = Group(self.context)
         self.add_child(grp)
         qry = CreateEntityQuery(self, group_properties, grp)

office365/graph/directory/groupCollection.py

@@ -1,9 +1,13 @@
 from office365.runtime.client_value_object import ClientValueObject
 
 
-class GroupCreationProperties(ClientValueObject):
+class GroupProfile(ClientValueObject):
     def __init__(self, name):
-        super(GroupCreationProperties, self).__init__()
+        """
+
+        :param str name: Group name
+        """
+        super(GroupProfile, self).__init__()
         self.mailNickname = name
         self.displayName = name
         self.description = None

office365/graph/directory/groupCreationProperties.py renamed to office365/graph/directory/groupProfile.py

@@ -1,4 +1,5 @@
 from office365.graph.directory.directoryObject import DirectoryObject
+from office365.graph.directory.directoryObjectCollection import DirectoryObjectCollection
 from office365.graph.directory.groupCollection import GroupCollection
 from office365.graph.onedrive.drive import Drive
 from office365.outlookservices.contact_collection import ContactCollection
@@ -77,6 +78,23 @@ def joinedTeams(self):
         else:
             return GroupCollection(self.context, ResourcePath("joinedTeams", self.resource_path))
 
+    @property
+    def memberOf(self):
+        """Get groups and directory roles that the user is a direct member of."""
+        if self.is_property_available('memberOf'):
+            return self.properties['memberOf']
+        else:
+            return DirectoryObjectCollection(self.context, ResourcePath("memberOf", self.resource_path))
+
+    @property
+    def transitiveMemberOf(self):
+        """Get groups, directory roles that the user is a member of. This API request is transitive, and will also
+        return all groups the user is a nested member of. """
+        if self.is_property_available('transitiveMemberOf'):
+            return self.properties['transitiveMemberOf']
+        else:
+            return DirectoryObjectCollection(self.context, ResourcePath("transitiveMemberOf", self.resource_path))
+
     def set_property(self, name, value, persist_changes=True):
         super(User, self).set_property(name, value, persist_changes)
         # fallback: create a new resource path

office365/graph/directory/user.py

@@ -1,7 +1,7 @@
 from office365.graph.directory.directoryObjectCollection import DirectoryObjectCollection
 from office365.graph.directory.user import User
 from office365.runtime.client_query import CreateEntityQuery
-from office365.runtime.resource_path import ResourcePath
+from office365.graph.directory.userProfile import UserProfile
 
 
 class UserCollection(DirectoryObjectCollection):
@@ -11,15 +11,10 @@ def __init__(self, context, resource_path=None):
         super(UserCollection, self).__init__(context, resource_path)
         self._item_type = User
 
-    def __getitem__(self, key):
-        if type(key) == int:
-            return self._data[key]
-        return User(self.context, ResourcePath(key, self.resource_path))
-
     def add(self, user_properties):
         """Create a new user.
 
-        :type user_properties: UserCreationProperties
+        :type user_properties: UserProfile
         """
         usr = User(self.context)
         qry = CreateEntityQuery(self, user_properties, usr)

office365/graph/directory/userCollection.py

@@ -10,7 +10,9 @@ def entity_type_name(self):
 
     @property
     def id(self):
-        """The unique identifier of the drive."""
+        """The unique identifier of the drive.
+        :rtype: str or None
+        """
         if self.is_property_available("id"):
             return self.properties['id']
         return None