Merge branch 'master' of https://github.com/yeyeric/python-o365

Author: Eric Mugnier

CHANGES.md

@@ -3,6 +3,14 @@
 Almost every release features a lot of bugfixes but those are not listed here.
 
 
+## Version 2.0.26 (2023-02-02)
+
+###Features:
+- Connection now allows setting default headers (Thanks @yeyeric)
+- Now it's possible to request inmutable Ids to the MS Graph protocol (Thanks @yeyeric and @NielsDebrier)
+- Added more Well Known Folder Names (Thanks @ponquersohn)
+
+
 ## Version 2.0.25 (2023-01-13)
 
 ###Features:

O365/__version__.py

@@ -1 +1 @@
-__version__ = '2.0.25'
+__version__ = '2.0.26'

O365/calendar.py

@@ -1613,6 +1613,10 @@ def __init__(self, *, parent=None, con=None, **kwargs):
         self.can_share = cloud_data.get(self._cc('canShare'), False)
         self.can_view_private_items = cloud_data.get(
             self._cc('canViewPrivateItems'), False)
+        
+        # Hex color only returns a value when a custom calandar is set
+        # Hex color is read-only, cannot be used to set calendar's color
+        self.hex_color = cloud_data.get(self._cc('hexColor'), None)
 
     def __str__(self):
         return self.__repr__()

O365/excel.py

@@ -1393,9 +1393,9 @@ def update(self, *, name=None, show_headers=None, show_totals=None, style=None):
         data = {}
         if name:
             data['name'] = name
-        if show_headers:
+        if show_headers is not None:
             data['showHeaders'] = show_headers
-        if show_totals:
+        if show_totals is not None:
             data['showTotals'] = show_totals
         if style:
             data['style'] = style

O365/mailbox.py

@@ -914,6 +914,116 @@ def archive_folder(self):
             folder_id=OutlookWellKnowFolderNames.ARCHIVE.value,
         )
 
+    def clutter_folder(self):
+        """Shortcut to get Clutter Folder instance
+           The clutter folder low-priority messages are moved to when using the Clutter feature.
+        
+        :rtype: mailbox.Folder
+        """
+        return self.folder_constructor(
+            parent=self,
+            name="Clutter",
+            folder_id=OutlookWellKnowFolderNames.CLUTTER.value,
+        )
+
+    def conflicts_folder(self):
+        """Shortcut to get Conflicts Folder instance
+           The folder that contains conflicting items in the mailbox.
+        
+        :rtype: mailbox.Folder
+        """
+        return self.folder_constructor(
+            parent=self,
+            name="Conflicts",
+            folder_id=OutlookWellKnowFolderNames.CONFLICTS.value,
+        )
+
+    def conversationhistory_folder(self):
+        """Shortcut to get Conversation History Folder instance
+           The folder where Skype saves IM conversations (if Skype is configured to do so).
+        
+        :rtype: mailbox.Folder
+        """
+        return self.folder_constructor(
+            parent=self,
+            name="Conflicts",
+            folder_id=OutlookWellKnowFolderNames.CONVERSATIONHISTORY.value,
+        )        
+
+    def localfailures_folder(self):
+        """Shortcut to get Local Failure Folder instance
+        The folder that contains items that exist on the local client but could not be uploaded to the server.
+
+        :rtype: mailbox.Folder
+        """
+        return self.folder_constructor(
+            parent=self,
+            name="Local Failures",
+            folder_id=OutlookWellKnowFolderNames.LOCALFAILURES.value,
+        )      
+
+    def recoverableitemsdeletions_folder(self):
+        """Shortcut to get Recoverable Items Deletions (Purges) Folder instance
+        The folder that contains soft-deleted items: deleted either from the Deleted Items folder, or by pressing shift+delete in Outlook. 
+        This folder is not visible in any Outlook email client, 
+        but end users can interact with it through the Recover Deleted Items from Server feature in Outlook or Outlook on the web.
+
+        :rtype: mailbox.Folder
+        """
+        return self.folder_constructor(
+            parent=self,
+            name="Recoverable Items Deletions (Purges)",
+            folder_id=OutlookWellKnowFolderNames.RECOVERABLEITEMSDELETIONS.value,
+        )         
+
+    def scheduled_folder(self):
+        """Shortcut to get Scheduled Folder instance
+        The folder that contains messages that are scheduled to reappear in the inbox using the Schedule feature in Outlook for iOS.
+        
+        :rtype: mailbox.Folder
+        """
+        return self.folder_constructor(
+            parent=self,
+            name="Scheduled",
+            folder_id=OutlookWellKnowFolderNames.SCHEDULED.value,
+        )         
+    
+    def searchfolders_folder(self):
+        """Shortcut to get Search Folders Folder instance
+        The parent folder for all search folders defined in the user's mailbox.
+        
+        :rtype: mailbox.Folder
+        """
+        return self.folder_constructor(
+            parent=self,
+            name="Search Folders",
+            folder_id=OutlookWellKnowFolderNames.SEARCHFOLDERS.value,
+        )     
+    
+    def serverfailures_folder(self):
+        """Shortcut to get Server Failures Folder instance
+        The folder that contains items that exist on the server but could not be synchronized to the local client.
+        
+        :rtype: mailbox.Folder
+        """
+        return self.folder_constructor(
+            parent=self,
+            name="Server Failures",
+            folder_id=OutlookWellKnowFolderNames.SERVERFAILURES.value,
+        )    
+
+    def syncissues_folder(self):
+        """Shortcut to get Sync Issues Folder instance
+        The folder that contains synchronization logs created by Outlook.
+        
+        :rtype: mailbox.Folder
+        """
+        return self.folder_constructor(
+            parent=self,
+            name="Sync Issues",
+            folder_id=OutlookWellKnowFolderNames.SYNCISSUES.value,
+        )         
+
     def get_settings(self):
         """Return the MailboxSettings.
 
@@ -934,3 +1044,4 @@ def get_settings(self):
         return self.mailbox_settings_constructor(
             parent=self, **{self._cloud_data_key: data}
         )
+

O365/utils/utils.py

@@ -55,6 +55,16 @@ class OutlookWellKnowFolderNames(Enum):
     SENT = 'SentItems'
     OUTBOX = 'Outbox'
     ARCHIVE = 'Archive'
+    CLUTTER='clutter'
+    CONFLICTS='conflicts'
+    CONVERSATIONHISTORY='conversationhistory'
+    LOCALFAILURES='localfailures'
+    RECOVERABLEITEMSDELETIONS='recoverableitemsdeletions'
+    SCHEDULED='scheduled'
+    SEARCHFOLDERS='searchfolders'
+    SERVERFAILURES='serverfailures'
+    SYNCISSUES='syncissues'
+
 
 
 class OneDriveWellKnowFolderNames(Enum):

O365/utils/windows_tz.py

@@ -453,7 +453,7 @@
     "Europe/Istanbul": "Turkey Standard Time",
     "Europe/Jersey": "GMT Standard Time",
     "Europe/Kaliningrad": "Kaliningrad Standard Time",
-    "Europe/Kiev": "FLE Standard Time",
+    "Europe/Kyiv": "FLE Standard Time",
     "Europe/Kirov": "Russian Standard Time",
     "Europe/Lisbon": "GMT Standard Time",
     "Europe/Ljubljana": "Central European Standard Time",

README.md

@@ -153,7 +153,7 @@ When to use one or the other and requirements:
  **Authentication**                 | 2 step authentication with user consent                  | 2 step authentication with user consent                    | 1 step authentication
  **Auth Scopes**                    | Required                                                 | Required                                                   | None
  **Token Expiration**               | 60 Minutes without refresh token or 90 days*             | 60 Minutes without refresh token or 90 days*               | 60 Minutes*
- **Login Expiration**               | Unlimited if there is a refresh token and as long as a re| Unlimited if there is a refresh token and as long as a refresh is done within the 90 days          | Unlimited
+ **Login Expiration**               | Unlimited if there is a refresh token and as long as a refresh is done within the 90 days | Unlimited if there is a refresh token and as long as a refresh is done within the 90 days          | Unlimited
  **Resources**                      | Access the user resources, and any shared resources      | Access the user resources, and any shared resources        | All Azure AD users the app has access to
  **Microsoft Account Type**         | Any                                                      | Any                                                        | Not Allowed for Personal Accounts
  **Tenant ID Required**             | Defaults to "common"                                     | Defaults to "common"                                       | Required (can't be "common")
@@ -290,10 +290,15 @@ For the "with your own identity" authentication method, you can just use `accoun
 
     The following example is done using Flask.
     ```python
+    from flask import request
+    from O365 import Account
+    
+    
     @route('/stepone')
     def auth_step_one():
+        # callback = absolute url to auth_step_two_callback() page, https://domain.tld/steptwo
+        callback = url_for('auth_step_two_callback', _external=True)  # Flask example
 
-        callback = 'my absolute url to auth_step_two_callback'
         account = Account(credentials)
         url, state = account.con.get_authorization_url(requested_scopes=my_scopes,
                                                        redirect_uri=callback)
@@ -313,7 +318,11 @@ For the "with your own identity" authentication method, you can just use `accoun
         # rebuild the redirect_uri used in auth_step_one
         callback = 'my absolute url to auth_step_two_callback'
 
-        result = account.con.request_token(request.url,
+        # get the request URL of the page which will include additional auth information
+        # Example request: /steptwo?code=abc123&state=xyz456
+        requested_url = request.url  # uses Flask's request() method
+
+        result = account.con.request_token(requested_url,
                                            state=my_saved_state,
                                            redirect_uri=callback)
         # if result is True, then authentication was succesful
@@ -440,9 +449,12 @@ Methods that stores tokens:
 
 To store the token you will have to provide a properly configured TokenBackend.
 
-Actually there are only two implemented (but you can easely implement more like a CookieBackend, RedisBackend, etc.):
+There are a few `TokenBackend` classes implemented (and you can easily implement more like a CookieBackend, RedisBackend, etc.):
 - `FileSystemTokenBackend` (Default backend): Stores and retrieves tokens from the file system. Tokens are stored as files.
+- `EnvTokenBackend`: Stores and retrieves tokens from environment variables.
 - `FirestoreTokenBackend`: Stores and retrives tokens from a Google Firestore Datastore. Tokens are stored as documents within a collection.
+- `AWSS3Backend`: Stores and retrieves tokens from an AWS S3 bucket. Tokens are stored as a file within a S3 bucket.
+- `AWSSecretsBackend`: Stores and retrieves tokens from an AWS Secrets Management vault.
 
 For example using the FileSystem Token Backend:
 

setup.py

@@ -3,7 +3,7 @@
 from setuptools import setup, find_packages
 
 
-VERSION = '2.0.25'
+VERSION = '2.0.26'
 
 # Available classifiers: https://pypi.org/pypi?%3Aaction=list_classifiers
 CLASSIFIERS = [