Improves docstrings and type hinting. Renames method names for APIs. Adds throttling property.

Author: ingmferrer

microsoftgraph/calendar.py

@@ -1,101 +1,112 @@
 from microsoftgraph.decorators import token_required
 from microsoftgraph.response import Response
+from datetime import datetime
 
 
 class Calendar(object):
-    def __init__(self, client):
+    def __init__(self, client) -> None:
+        """Working with Outlook Calendar.
+
+        https://docs.microsoft.com/en-us/graph/api/resources/calendar?view=graph-rest-1.0
+
+        Args:
+            client (Client): Library Client.
+        """
         self._client = client
 
     @token_required
-    def get_me_events(self) -> Response:
-        """Get a list of event objects in the user's mailbox. The list contains single instance meetings and
-        series masters.
+    def list_events(self) -> Response:
+        """Get a list of event objects in the user's mailbox. The list contains single instance meetings and series
+        masters.
 
-        Currently, this operation returns event bodies in only HTML format.
+        https://docs.microsoft.com/en-us/graph/api/user-list-events?view=graph-rest-1.0&tabs=http
 
         Returns:
-            A dict.
-
+            Response: Microsoft Graph Response.
         """
         return self._client._get(self._client.base_url + "me/events")
 
     @token_required
-    def create_calendar_event(
+    def create_event(
         self,
         subject: str,
         content: str,
-        start_datetime: str,
+        start_datetime: datetime,
         start_timezone: str,
-        end_datetime: str,
+        end_datetime: datetime,
         end_timezone: str,
         location: str,
         calendar: str = None,
+        content_type: str = "HTML",
         **kwargs,
     ) -> Response:
-        """
-        Create a new calendar event.
+        """Create an event in the user's default calendar or specified calendar.
+
+        https://docs.microsoft.com/en-us/graph/api/user-post-events?view=graph-rest-1.0&tabs=http
+
+        Additional time zones: https://docs.microsoft.com/en-us/graph/api/resources/datetimetimezone?view=graph-rest-1.0
 
         Args:
-            subject: subject of event, string
-            content: content of event, string
-            start_datetime: in the format of 2017-09-04T11:00:00, dateTimeTimeZone string
-            start_timezone: in the format of Pacific Standard Time, string
-            end_datetime: in the format of 2017-09-04T11:00:00, dateTimeTimeZone string
-            end_timezone: in the format of Pacific Standard Time, string
-            location:   string
-            attendees: list of dicts of the form:
-                        {"emailAddress": {"address": a['attendees_email'],"name": a['attendees_name']}
-            calendar:
+            subject (str): The text of the event's subject line.
+            content (str): The body of the message associated with the event.
+            start_datetime (datetime): A single point of time in a combined date and time representation ({date}T{time};
+            start_timezone (datetime): Represents a time zone, for example, "Pacific Standard Time".
+            end_datetime (str): A single point of time in a combined date and time representation ({date}T{time}; for
+            end_timezone (str): Represents a time zone, for example, "Pacific Standard Time".
+            location (str): The location of the event.
+            calendar (str, optional): Calendar ID. Defaults to None.
+            content_type (str, optional): It can be in HTML or text format. Defaults to HTML.
 
         Returns:
-            A dict.
-
+            Response: Microsoft Graph Response.
         """
-        # TODO: attendees
-        # attendees_list = [{
-        #     "emailAddress": {
-        #         "address": a['attendees_email'],
-        #         "name": a['attendees_name']
-        #     },
-        #     "type": a['attendees_type']
-        # } for a in kwargs['attendees']]
+        if isinstance(start_datetime, datetime):
+            start_datetime = start_datetime.strftime("%Y-%m-%dT%H:%M:%S.%f")
+        if isinstance(end_datetime, datetime):
+            start_datetime = start_datetime.strftime("%Y-%m-%dT%H:%M:%S.%f")
+
         body = {
             "subject": subject,
-            "body": {"contentType": "HTML", "content": content},
-            "start": {"dateTime": start_datetime, "timeZone": start_timezone},
-            "end": {"dateTime": end_datetime, "timeZone": end_timezone},
+            "body": {
+                "contentType": content_type,
+                "content": content,
+            },
+            "start": {
+                "dateTime": start_datetime,
+                "timeZone": start_timezone,
+            },
+            "end": {
+                "dateTime": end_datetime,
+                "timeZone": end_timezone,
+            },
             "location": {"displayName": location},
-            # "attendees": attendees_list
         }
         url = "me/calendars/{}/events".format(calendar) if calendar is not None else "me/events"
         return self._client._post(self._client.base_url + url, json=body)
 
     @token_required
-    def create_calendar(self, name: str) -> Response:
-        """Create an event in the user's default calendar or specified calendar.
-
-        You can specify the time zone for each of the start and end times of the event as part of these values,
-        as the  start and end properties are of dateTimeTimeZone type.
+    def list_calendars(self) -> Response:
+        """Get all the user's calendars (/calendars navigation property), get the calendars from the default calendar
+        group or from a specific calendar group.
 
-        When an event is sent, the server sends invitations to all the attendees.
-
-        Args:
-            name:
+        https://docs.microsoft.com/en-us/graph/api/user-list-calendars?view=graph-rest-1.0&tabs=http
 
         Returns:
-            A dict.
-
+            Response: Microsoft Graph Response.
         """
-        body = {"name": "{}".format(name)}
-        return self._client._post(self._client.base_url + "me/calendars", json=body)
+        return self._client._get(self._client.base_url + "me/calendars")
 
     @token_required
-    def get_me_calendars(self) -> Response:
-        """Get all the user's calendars (/calendars navigation property), get the calendars from the default
-        calendar group or from a specific calendar group.
+    def create_calendar(self, name: str) -> Response:
+        """Create a new calendar for a user.
 
-        Returns:
-            A dict.
+        https://docs.microsoft.com/en-us/graph/api/user-post-calendars?view=graph-rest-1.0&tabs=http
+
+        Args:
+            name (str): The calendar name.
 
+        Returns:
+            Response: Microsoft Graph Response.
         """
-        return self._client._get(self._client.base_url + "me/calendars")
+        body = {"name": "{}".format(name)}
+        return self._client._post(self._client.base_url + "me/calendars", json=body)

microsoftgraph/client.py

@@ -4,14 +4,14 @@
 
 from microsoftgraph import exceptions
 from microsoftgraph.calendar import Calendar
-from microsoftgraph.excel import Excel
+from microsoftgraph.contacts import Contacts
+from microsoftgraph.files import Files
 from microsoftgraph.mail import Mail
-from microsoftgraph.onedrive import Onedrive
-from microsoftgraph.onenote import Onenote
-from microsoftgraph.outlook import Outlook
+from microsoftgraph.notes import Notes
 from microsoftgraph.response import Response
-from microsoftgraph.users import User
+from microsoftgraph.users import Users
 from microsoftgraph.webhooks import Webhooks
+from microsoftgraph.workbooks import Workbooks
 
 
 class Client(object):
@@ -21,8 +21,25 @@ class Client(object):
     RESOURCE = "https://graph.microsoft.com/"
 
     def __init__(
-        self, client_id: str, client_secret: str, api_version: str = "v1.0", account_type: str = "common"
+        self,
+        client_id: str,
+        client_secret: str,
+        api_version: str = "v1.0",
+        account_type: str = "common",
+        requests_hooks: dict = None,
     ) -> None:
+        """Instantiates library.
+
+        Args:
+            client_id (str): Application client id.
+            client_secret (str): Application client secret.
+            api_version (str, optional): v1.0 or beta. Defaults to "v1.0".
+            account_type (str, optional): common, organizations or consumers. Defaults to "common".
+            requests_hooks (dict, optional): Requests library event hooks. Defaults to None.
+
+        Raises:
+            Exception: requests_hooks is not a dict.
+        """
         self.client_id = client_id
         self.client_secret = client_secret
         self.api_version = api_version
@@ -32,13 +49,19 @@ def __init__(
         self.token = None
 
         self.calendar = Calendar(self)
-        self.excel = Excel(self)
+        self.contacts = Contacts(self)
+        self.files = Files(self)
         self.mail = Mail(self)
-        self.onedrive = Onedrive(self)
-        self.onenote = Onenote(self)
-        self.outlook = Outlook(self)
-        self.user = User(self)
+        self.notes = Notes(self)
+        self.users = Users(self)
         self.webhooks = Webhooks(self)
+        self.workbooks = Workbooks(self)
+
+        if requests_hooks and not isinstance(requests_hooks, dict):
+            raise Exception(
+                'requests_hooks must be a dict. e.g. {"response": func}. http://docs.python-requests.org/en/master/user/advanced/#event-hooks'
+            )
+        self.requests_hooks = requests_hooks
 
     def authorization_url(self, redirect_uri: str, scope: list, state: str = None) -> str:
         """Generates an Authorization URL.
@@ -163,6 +186,8 @@ def _request(self, method, url, headers=None, **kwargs):
         _headers["Authorization"] = "Bearer " + self.token["access_token"]
         if headers:
             _headers.update(headers)
+        if self.requests_hooks:
+            kwargs.update({"hooks": self.requests_hooks})
         if "files" not in kwargs:
             # If you use the 'files' keyword, the library will set the Content-Type to multipart/form-data
             # and will generate a boundary.

microsoftgraph/contacts.py

@@ -0,0 +1,99 @@
+from microsoftgraph.decorators import token_required
+from microsoftgraph.response import Response
+
+
+class Contacts(object):
+    def __init__(self, client) -> None:
+        """Working with Outlook Contacts.
+
+        https://docs.microsoft.com/en-us/graph/api/resources/contact?view=graph-rest-1.0
+
+        Args:
+            client (Client): Library Client.
+        """
+        self._client = client
+
+    @token_required
+    def get_contact(self, contact_id: str, params: dict = None) -> Response:
+        """Retrieve the properties and relationships of a contact object.
+
+        https://docs.microsoft.com/en-us/graph/api/contact-get?view=graph-rest-1.0&tabs=http
+
+        Args:
+            contact_id (str): The contact's unique identifier.
+            params (dict, optional): Query. Defaults to None.
+
+        Returns:
+            Response: Microsoft Graph Response.
+        """
+        url = "{0}me/contacts/{1}".format(self._client.base_url, contact_id)
+        return self._client._get(url, params=params)
+
+    @token_required
+    def list_contacts(self, 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:
+            params (dict, optional): Query. Defaults to None.
+
+        Returns:
+            Response: Microsoft Graph Response.
+        """
+        url = "{0}me/contacts".format(self._client.base_url)
+        return self._client._get(url, params=params)
+
+    @token_required
+    def create_contact(self, **kwargs) -> Response:
+        """Add a contact to the root Contacts folder.
+
+        https://docs.microsoft.com/en-us/graph/api/user-post-contacts?view=graph-rest-1.0&tabs=http
+
+        Returns:
+            Response: Microsoft Graph Response.
+        """
+        url = "{0}me/contacts".format(self._client.base_url)
+        return self._client._post(url, **kwargs)
+
+    @token_required
+    def create_contact_in_folder(self, folder_id: str, **kwargs) -> Response:
+        """Add a contact to another contact folder.
+
+        https://docs.microsoft.com/en-us/graph/api/user-post-contacts?view=graph-rest-1.0&tabs=http
+
+        Args:
+            folder_id (str): Unique identifier of the contact folder.
+
+        Returns:
+            Response: Microsoft Graph Response.
+        """
+        url = "{0}me/contactFolders/{1}/contacts".format(self._client.base_url, folder_id)
+        return self._client._post(url, **kwargs)
+
+    @token_required
+    def list_contact_folders(self, params: dict = None) -> Response:
+        """Get the contact folder collection in the default Contacts folder of the signed-in user.
+
+        https://docs.microsoft.com/en-us/graph/api/user-list-contactfolders?view=graph-rest-1.0&tabs=http
+
+        Args:
+            params (dict, optional): Query. Defaults to None.
+
+        Returns:
+            Response: Microsoft Graph Response.
+        """
+        url = "{0}me/contactFolders".format(self._client.base_url)
+        return self._client._get(url, params=params)
+
+    @token_required
+    def create_contact_folder(self, **kwargs) -> Response:
+        """Create a new contactFolder under the user's default contacts folder.
+
+        https://docs.microsoft.com/en-us/graph/api/user-post-contactfolders?view=graph-rest-1.0&tabs=http
+
+        Returns:
+            Response: Microsoft Graph Response.
+        """
+        url = "{0}me/contactFolders".format(self._client.base_url)
+        return self._client._post(url, **kwargs)