Add pagination logic. Add missing API methods

Author: ingmferrer

README.md

@@ -13,7 +13,7 @@ See [Get access on behalf of a user](https://docs.microsoft.com/en-us/graph/auth
 ## Breaking changes if you're upgrading prior 1.0.0
 - Added structure to library to match API documentation for e.g. `client.get_me()` => `client.users.get_me()`.
 - Renamed several methods to match API documentation for e.g. `client.get_me_events()` => `client.calendar.list_events()`.
-- Result from calling a method is not longer a dictionary but a Response object. To access the dict response as before then call `.data` property for e.g `r = client.users.get_me()` then `r.data`.
+- Result from calling a method is not longer a dictionary but a Response object. To access the dict response as before then call `.data` attribute for e.g `r = client.users.get_me()` then `r.data`.
 - Previous API calls made through beta endpoints are now pointing to v1.0 by default. This can be changed to beta if needed with the parameter `api_version` in the client instantiation.
 - Removed Office 365 endpoints as they were merged with the Microsoft Graph API. See [Office 365 APIs](https://docs.microsoft.com/en-us/previous-versions/office/office-365-api/).
 ## New in 1.0.0

microsoftgraph/calendar.py

@@ -17,34 +17,36 @@ def __init__(self, client) -> None:
         self._client = client
 
     @token_required
-    def list_events(self, calendar_id: str = None) -> Response:
+    def list_events(self, calendar_id: str = None, params: dict = None) -> Response:
         """Get a list of event objects in the user's mailbox. The list contains single instance meetings and series
         masters.
 
         https://docs.microsoft.com/en-us/graph/api/user-list-events?view=graph-rest-1.0&tabs=http
 
         Args:
             calendar_id (str): Calendar ID.
+            params (dict, optional): Query. Defaults to None.
 
         Returns:
             Response: Microsoft Graph Response.
         """
         url = "me/calendars/{}/events".format(calendar_id) if calendar_id else "me/events"
-        return self._client._get(self._client.base_url + url)
+        return self._client._get(self._client.base_url + url, params=params)
 
     @token_required
-    def get_event(self, event_id: str) -> Response:
+    def get_event(self, event_id: str, params: dict = None) -> Response:
         """Get the properties and relationships of the specified event object.
 
         https://docs.microsoft.com/en-us/graph/api/event-get?view=graph-rest-1.0&tabs=http
 
         Args:
             event_id (str): Event ID.
+            params (dict, optional): Query. Defaults to None.
 
         Returns:
             Response: Microsoft Graph Response.
         """
-        return self._client._get(self._client.base_url + "me/events/{}".format(event_id))
+        return self._client._get(self._client.base_url + "me/events/{}".format(event_id), params=params)
 
     @token_required
     def create_event(
@@ -106,16 +108,19 @@ def create_event(
         return self._client._post(self._client.base_url + url, json=body)
 
     @token_required
-    def list_calendars(self) -> Response:
+    def list_calendars(self, params: dict = None) -> Response:
         """Get all the user's calendars (/calendars navigation property), get the calendars from the default calendar
         group or from a specific calendar group.
 
         https://docs.microsoft.com/en-us/graph/api/user-list-calendars?view=graph-rest-1.0&tabs=http
 
+        Args:
+            params (dict, optional): Query. Defaults to None.
+
         Returns:
             Response: Microsoft Graph Response.
         """
-        return self._client._get(self._client.base_url + "me/calendars")
+        return self._client._get(self._client.base_url + "me/calendars", params=params)
 
     @token_required
     def create_calendar(self, name: str) -> Response:

microsoftgraph/client.py

@@ -1,7 +1,7 @@
 from urllib.parse import urlencode
 
 import requests
-
+import copy
 from microsoftgraph import exceptions
 from microsoftgraph.calendar import Calendar
 from microsoftgraph.contacts import Contacts
@@ -27,6 +27,7 @@ def __init__(
         api_version: str = "v1.0",
         account_type: str = "common",
         requests_hooks: dict = None,
+        paginate: bool = True,
     ) -> None:
         """Instantiates library.
 
@@ -47,6 +48,7 @@ def __init__(
 
         self.base_url = self.RESOURCE + self.api_version + "/"
         self.token = None
+        self.paginate = paginate
 
         self.calendar = Calendar(self)
         self.contacts = Contacts(self)
@@ -164,8 +166,30 @@ def set_token(self, token: dict) -> None:
         """
         self.token = token
 
+    def _paginate_response(self, response: dict, **kwargs) -> dict:
+        """Some queries against Microsoft Graph return multiple pages of data either due to server-side paging or due to
+        the use of the $top query parameter to specifically limit the page size in a request. When a result set spans
+        multiple pages, Microsoft Graph returns an @odata.nextLink property in the response that contains a URL to the
+        next page of results.
+
+        https://docs.microsoft.com/en-us/graph/paging?context=graph%2Fapi%2F1.0&view=graph-rest-1.0
+
+        Args:
+            response (dict): Graph API Response.
+
+        Returns:
+            dict: Graph API Response.
+        """
+        if not self.paginate:
+            return response
+        while "@odata.nextLink" in response.data:
+            data = response.data["value"]
+            response = self._get(response.data["@odata.nextLink"], **kwargs)
+            response.data["value"] += data
+        return response
+
     def _get(self, url, **kwargs):
-        return self._request("GET", url, **kwargs)
+        return self._paginate_response(self._request("GET", url, **kwargs), **kwargs)
 
     def _post(self, url, **kwargs):
         return self._request("POST", url, **kwargs)

microsoftgraph/contacts.py

@@ -1,4 +1,3 @@
-import json
 from microsoftgraph.decorators import token_required
 from microsoftgraph.response import Response
 
@@ -30,18 +29,20 @@ def get_contact(self, contact_id: str, params: dict = None) -> Response:
         return self._client._get(self._client.base_url + "me/contacts/{}".format(contact_id), params=params)
 
     @token_required
-    def list_contacts(self, params: dict = None) -> Response:
+    def list_contacts(self, folder_id: str = None, params: dict = None) -> Response:
         """Get a contact collection from the default contacts folder of the signed-in user.
 
         https://docs.microsoft.com/en-us/graph/api/user-list-contacts?view=graph-rest-1.0&tabs=http
 
         Args:
+            folder_id (str): Folder ID.
             params (dict, optional): Query. Defaults to None.
 
         Returns:
             Response: Microsoft Graph Response.
         """
-        return self._client._get(self._client.base_url + "me/contacts", params=params)
+        url = "me/contactfolders/{}/contacts".format(folder_id) if folder_id else "me/contacts"
+        return self._client._get(self._client.base_url + url, params=params)
 
     @token_required
     def create_contact(

microsoftgraph/mail.py

@@ -16,6 +16,22 @@ def __init__(self, client) -> None:
         """
         self._client = client
 
+    @token_required
+    def list_messages(self, folder_id: str = None, params: dict = None) -> Response:
+        """Get the messages in the signed-in user's mailbox (including the Deleted Items and Clutter folders).
+
+        https://docs.microsoft.com/en-us/graph/api/user-list-messages?view=graph-rest-1.0&tabs=http
+
+        Args:
+            folder_id (str, optional): Mail Folder ID.
+            params (dict, optional): Query. Defaults to None.
+
+        Returns:
+            Response: Microsoft Graph Response.
+        """
+        url = "me/mailFolders/{id}/messages".format(folder_id) if folder_id else "me/messages"
+        return self._client._get(self._client.base_url + url, params=params)
+
     @token_required
     def get_message(self, message_id: str, params: dict = None) -> Response:
         """Retrieve the properties and relationships of a message object.
@@ -107,3 +123,40 @@ def send_mail(
 
         # Do a POST to Graph's sendMail API and return the response.
         return self._client._post(self._client.base_url + "me/sendMail", json=email_msg)
+
+    @token_required
+    def list_mail_folders(self, params: dict = None) -> Response:
+        """Get the mail folder collection directly under the root folder of the signed-in user. The returned collection
+        includes any mail search folders directly under the root.
+
+        By default, this operation does not return hidden folders. Use a query parameter includeHiddenFolders to include
+        them in the response.
+
+        https://docs.microsoft.com/en-us/graph/api/user-list-mailfolders?view=graph-rest-1.0&tabs=http
+
+        Args:
+            params (dict, optional): Query. Defaults to None.
+
+        Returns:
+            Response: Microsoft Graph Response.
+        """
+        return self._client._get(self._client.base_url + "me/mailFolders", params=params)
+
+    @token_required
+    def create_mail_folder(self, display_name: str, is_hidden: bool = False) -> Response:
+        """Use this API to create a new mail folder in the root folder of the user's mailbox.
+
+        https://docs.microsoft.com/en-us/graph/api/user-post-mailfolders?view=graph-rest-1.0&tabs=http
+
+        Args:
+            display_name (str): Query.
+            is_hidden (bool, optional): Is the folder hidden. Defaults to False.
+
+        Returns:
+            Response: Microsoft Graph Response.
+        """
+        data = {
+            "displayName": display_name,
+            "isHidden": is_hidden,
+        }
+        return self._client._post(self._client.base_url + "me/mailFolders", json=data)

microsoftgraph/notes.py

@@ -5,7 +5,7 @@
 class Notes(object):
     def __init__(self, client) -> None:
         """Use the OneNote REST API.
-        
+
         https://docs.microsoft.com/en-us/graph/api/resources/onenote-api-overview?view=graph-rest-1.0
 
         Args:
@@ -28,32 +28,35 @@ def list_notebooks(self, params: dict = None) -> Response:
         return self._client._get(self._client.base_url + "me/onenote/notebooks", params=params)
 
     @token_required
-    def get_notebook(self, notebook_id: str) -> Response:
+    def get_notebook(self, notebook_id: str, params: dict = None) -> Response:
         """Retrieve the properties and relationships of a notebook object.
 
         https://docs.microsoft.com/en-us/graph/api/notebook-get?view=graph-rest-1.0&tabs=http
 
         Args:
             notebook_id (str): The unique identifier of the notebook.
+            params (dict, optional): Query. Defaults to None.
 
         Returns:
             Response: Microsoft Graph Response.
         """
-        return self._client._get(self._client.base_url + "me/onenote/notebooks/" + notebook_id)
+        return self._client._get(self._client.base_url + "me/onenote/notebooks/" + notebook_id, params=params)
 
     @token_required
-    def list_sections(self, notebook_id: str) -> Response:
+    def list_sections(self, notebook_id: str, params: dict = None) -> Response:
         """Retrieve a list of onenoteSection objects from the specified notebook.
 
         https://docs.microsoft.com/en-us/graph/api/notebook-list-sections?view=graph-rest-1.0&tabs=http
 
         Args:
             notebook_id (str): The unique identifier of the notebook.
+            params (dict, optional): Query. Defaults to None.
 
         Returns:
             Response: Microsoft Graph Response.
         """
-        return self._client._get(self._client.base_url + "me/onenote/notebooks/{}/sections".format(notebook_id))
+        url = "me/onenote/notebooks/{}/sections".format(notebook_id)
+        return self._client._get(self._client.base_url + url, params=params)
 
     @token_required
     def list_pages(self, params: dict = None) -> Response:

microsoftgraph/response.py

@@ -5,14 +5,13 @@ class Response:
     def __init__(self, original) -> None:
         self.original = original
 
-    def __repr__(self) -> str:
-        return "<Response [{}] ({})>".format(self.status_code, self.data)
-
-    @property
-    def data(self):
         if "application/json" in self.original.headers.get("Content-Type", ""):
-            return self.original.json()
-        return self.original.content
+            self.data = self.original.json()
+        else:
+            self.data = self.original.content
+
+    def __repr__(self) -> str:
+        return "<Response [{}]>".format(self.status_code)
 
     @property
     def status_code(self):