Merge branch 'O365:master' into master

Author: sdelgadoc

.github/workflows/build_pages.yml

@@ -0,0 +1,52 @@
+name: Pages Build
+
+on:
+    push:
+      branches: [ "master" ]
+jobs:
+  pages_build:
+    name: Build Pages
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: "Checkout the repository"
+        uses: actions/checkout@v4
+
+      - name: "Set up Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v1
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync 
+        
+      - name: "Build pages"
+        run: uv run sphinx-build -b html -c ./docs/source/ ./docs/source/ ./docs/latest/ 
+
+      - name: "Pull any updates"
+        shell: bash
+        run: git pull
+
+      - name: "Check for changes"
+        shell: bash
+        run: git status
+
+      - name: "Stage changed files"
+        shell: bash
+        run: git add ./docs/latest
+
+      - name: "Commit changed files"
+        shell: bash
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git commit -m "Update the docs" || true
+
+      - name: Push changes
+        uses: ad-m/github-push-action@master
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -49,7 +49,7 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
-doctrees/
+.doctrees/
 
 # PyBuilder
 target/
@@ -78,4 +78,7 @@ venv/
 
 # O365 specific
 o365_token\.txt
-local_tests/
+local_tests/
+
+# Mac Specifoc
+.DS_Store

CHANGES.md

@@ -2,6 +2,45 @@
 
 Almost every release features a lot of bugfixes but those are not listed here.
 
+## Version 2.1.7 (2025-09-05)
+
+> [!IMPORTANT]
+> **Breaking Change:** Removed support for Python 3.9
+> **Breaking Change:** Removed Old Query in favour of the new QueryBuilder (both are interchangeable for other methods to use it, but are build differently)
+
+- Tasks: Add population of checklist_items on Task (Thanks @RogerSelwyn)
+- Excel: Added `append_rows` and `update_cells` to `WorkSheet` (Thanks @luissantosHCIT)
+
+## Version 2.1.6 (2025-09-05)
+
+- Version Yanked
+
+## Version 2.1.5 (2025-08-04)
+- Bug fixing release
+    
+## Version 2.1.4 (2025-06-03)
+- Calendar: Schedule.get_calendar method can now use query objects with select, expand and order by (Thanks @RogerSelwyn)
+
+## Version 2.1.3 (2025-06-03)
+- Calendar: Added the recurrence type (Thanks @RogerSelwyn)
+- Calendar: Added the transaction id (Thanks @RogerSelwyn)
+- Calendar: Breaking change! Calendar and Schedule get_events method now requires params start_recurring and end_recurring when include_recurring is True.
+- Calendar: list_calendars method can now use query objects with select, expand and order by.
+- Groups: Added pagination to get_user_groups (Thanks @RogerSelwyn)
+- Tasks: Added support for check list items (Thanks @RogerSelwyn)
+- Removed Office365 protocol
+
+## Version 2.1.2 (2025-04-08)
+- Calendar: list_calendars now allows pagination (Thanks @RogerSelwyn)
+- Query: added new experimental Query object that will replace the current Query object in the future. Available in utils.query.
+- Message: non-draft messages can be saved. This allows to edit non-draft messages.
+- Connection: proxies, verify_ssl and timeout are now honored in the msal http client.
+- Message: new method `get_eml_as_object` to retrieve attached eml as Message objects.
+
+## Version 2.1.1 (2025-03-20)
+- Tasks: support unsetting tasks due and reminder (Thanks @RogerSelwyn)
+- Removed Office 365 tasks file (api was deprecated on november 2024)
+
 ## Version 2.1.0 (2025-02-11)
 
 > [!IMPORTANT]

O365/__init__.py

@@ -1,17 +1,16 @@
 """
-A simple python library to interact with Microsoft Graph and Office 365 API
+A simple python library to interact with Microsoft Graph and other MS api
 """
+
 import warnings
 import sys
 
-from .__version__ import __version__
-
 from .account import Account
-from .connection import Connection, Protocol, MSGraphProtocol, MSOffice365Protocol
+from .connection import Connection, Protocol, MSGraphProtocol
 from .utils import FileSystemTokenBackend, EnvTokenBackend
 from .message import Message
 
 
 if sys.warnoptions:
     # allow Deprecation warnings to appear
-    warnings.simplefilter('always', DeprecationWarning)
+    warnings.simplefilter("always", DeprecationWarning)

O365/__version__.py

@@ -1,12 +1,12 @@
-from typing import Type, Tuple, Optional, Callable, List
 import warnings
+from typing import Callable, List, Optional, Tuple, Type
 
-from .connection import Connection, Protocol, MSGraphProtocol, MSOffice365Protocol
+from .connection import Connection, MSGraphProtocol, Protocol
 from .utils import ME_RESOURCE, consent_input_token
 
 
 class Account:
-    connection_constructor: Type = Connection
+    connection_constructor: Type = Connection  #: :meta private:
 
     def __init__(self, credentials: Tuple[str, str], *,
                  username: Optional[str] = None,
@@ -25,6 +25,7 @@ def __init__(self, credentials: Tuple[str, str], *,
         protocol = protocol or MSGraphProtocol  # Defaults to Graph protocol
         if isinstance(protocol, type):
             protocol = protocol(default_resource=main_resource, **kwargs)
+        # The protocol to use for the account. Defaults ot MSGraphProtocol. |br| **Type:** Protocol
         self.protocol: Protocol = protocol
 
         if not isinstance(self.protocol, Protocol):
@@ -57,6 +58,7 @@ def __init__(self, credentials: Tuple[str, str], *,
         kwargs['username'] = username
 
         self.con = self.connection_constructor(credentials, **kwargs)
+        #: The resource in use for the account. |br| **Type:** str
         self.main_resource: str = main_resource or self.protocol.default_resource
 
     def __repr__(self):
@@ -77,7 +79,10 @@ def is_authenticated(self) -> bool:
             if self.con.load_token_from_backend() is False:
                 return False
 
-        return not self.con.token_backend.token_is_expired(username=self.con.username, refresh_token=True)
+        return (
+                self.con.token_backend.token_is_long_lived(username=self.con.username)
+                or not self.con.token_backend.token_is_expired(username=self.con.username)
+        )
 
     def authenticate(self, *, requested_scopes: Optional[list] = None, redirect_uri: Optional[str] = None,
                      handle_consent: Callable = consent_input_token, **kwargs) -> bool:
@@ -182,11 +187,12 @@ def username(self) -> Optional[str]:
         return self.con.username
 
     def get_authenticated_usernames(self) -> list[str]:
-        """ Returns a list of usernames that are authenticated and have a valid access or refresh token. """
+        """ Returns a list of usernames that are authenticated and have a valid access token or a refresh token."""
         usernames = []
+        tb = self.con.token_backend
         for account in self.con.token_backend.get_all_accounts():
             username = account.get('username')
-            if username and not self.con.token_backend.token_is_expired(username=username, refresh_token=True):
+            if username and (tb.token_is_long_lived(username=username) or not tb.token_is_expired(username=username)):
                 usernames.append(username)
 
         return usernames
@@ -265,7 +271,7 @@ def address_book(self, *, resource: Optional[str] = None, address_book: str = 'p
 
     def directory(self, resource: Optional[str] = None):
         """ Returns the active directory instance"""
-        from .directory import Directory, USERS_RESOURCE
+        from .directory import USERS_RESOURCE, Directory
 
         return Directory(parent=self, main_resource=resource or USERS_RESOURCE)
 
@@ -331,10 +337,7 @@ def planner(self, *, resource: str = ''):
     def tasks(self, *, resource: str = ''):
         """ Get an instance to read information from Microsoft ToDo """
 
-        if isinstance(self.protocol, MSOffice365Protocol):
-            from .tasks import ToDo
-        else:
-            from .tasks_graph import ToDo as ToDo
+        from .tasks import ToDo
 
         return ToDo(parent=self, main_resource=resource)
 

O365/account.py

@@ -4,18 +4,22 @@
 from dateutil.parser import parse
 from requests.exceptions import HTTPError
 
-from .utils import Recipients
-from .utils import AttachableMixin, TrackerSet
-from .utils import Pagination, NEXT_LINK_KEYWORD, ApiComponent
-from .message import Message, RecipientType
 from .category import Category
-
+from .message import Message, RecipientType
+from .utils import (
+    NEXT_LINK_KEYWORD,
+    ApiComponent,
+    AttachableMixin,
+    Pagination,
+    Recipients,
+    TrackerSet,
+)
 
 log = logging.getLogger(__name__)
 
 
 class Contact(ApiComponent, AttachableMixin):
-    """ Contact manages lists of events on associated contact on office365. """
+    """ Contact manages lists of events on associated contact on Microsoft 365. """
 
     _endpoints = {
         'contact': '/contacts',
@@ -25,7 +29,7 @@ class Contact(ApiComponent, AttachableMixin):
         'photo_size': '/contacts/{id}/photos/{size}/$value',
     }
 
-    message_constructor = Message
+    message_constructor = Message  #: :meta private:
 
     def __init__(self, *, parent=None, con=None, **kwargs):
         """ Create a contact API component
@@ -56,6 +60,7 @@ def __init__(self, *, parent=None, con=None, **kwargs):
         # internal to know which properties need to be updated on the server
         self._track_changes = TrackerSet(casing=cc)
 
+        #: The contact's unique identifier. |br| **Type:** str
         self.object_id = cloud_data.get(cc('id'), None)
         self.__created = cloud_data.get(cc('createdDateTime'), None)
         self.__modified = cloud_data.get(cc('lastModifiedDateTime'), None)
@@ -457,7 +462,7 @@ def personal_notes(self, value):
 
     @property
     def folder_id(self):
-        """ ID of the folder
+        """ID of the containing folder
 
         :rtype: str
         """
@@ -594,7 +599,8 @@ def new_message(self, recipient=None, *, recipient_type=RecipientType.TO):
         return new_message
 
     def get_profile_photo(self, size=None):
-        """ Returns this contact profile photo
+        """Returns this contact profile photo
+
         :param str size: 48x48, 64x64, 96x96, 120x120, 240x240,
          360x360, 432x432, 504x504, and 648x648
         """
@@ -636,8 +642,8 @@ class BaseContactFolder(ApiComponent):
         'child_folders': '/contactFolders/{id}/childFolders'
     }
 
-    contact_constructor = Contact
-    message_constructor = Message
+    contact_constructor = Contact  #: :meta private:
+    message_constructor = Message  #: :meta private:
 
     def __init__(self, *, parent=None, con=None, **kwargs):
         """ Create a contact folder component
@@ -663,17 +669,21 @@ def __init__(self, *, parent=None, con=None, **kwargs):
             main_resource=main_resource)
 
         # This folder has no parents if root = True.
+        #: Indicates if this is the root folder. |br| **Type:** bool
         self.root = kwargs.pop('root', False)
 
         cloud_data = kwargs.get(self._cloud_data_key, {})
 
         # Fallback to manual folder if nothing available on cloud data
+        #: The folder's display name. |br| **Type:** str
         self.name = cloud_data.get(self._cc('displayName'),
                                    kwargs.get('name',
                                               ''))
         # TODO: Most of above code is same as mailbox.Folder __init__
 
+        #: Unique identifier of the contact folder. |br| **Type:** str
         self.folder_id = cloud_data.get(self._cc('id'), None)
+        #: The ID of the folder's parent folder. |br| **Type:** str
         self.parent_id = cloud_data.get(self._cc('parentFolderId'), None)
 
     def __str__(self):