Merge branch 'O365:master' into query-docs

Author: RogerSelwyn

CHANGES.md

@@ -2,6 +2,22 @@
 
 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)
 
@@ -14,7 +30,6 @@ Almost every release features a lot of bugfixes but those are not listed here.
 - 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.

O365/__init__.py

@@ -5,8 +5,6 @@
 import warnings
 import sys
 
-from .__version__ import __version__
-
 from .account import Account
 from .connection import Connection, Protocol, MSGraphProtocol
 from .utils import FileSystemTokenBackend, EnvTokenBackend

O365/__version__.py

@@ -25,7 +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
+        # The protocol to use for the account. Defaults ot MSGraphProtocol. |br| **Type:** Protocol
         self.protocol: Protocol = protocol
 
         if not isinstance(self.protocol, Protocol):

O365/account.py

@@ -914,17 +914,22 @@ def _check_delay(self) -> None:
         self._previous_request_at = time.time()
 
     def _internal_request(
-        self, session_obj: Session, url: str, method: str, ignore401: bool = False, **kwargs
+        self,
+        session_obj: Session,
+        url: str,
+        method: str,
+        ignore40x: bool = False,
+        **kwargs,
     ) -> Response:
         """Internal handling of requests. Handles Exceptions.
 
         :param session_obj: a requests Session instance.
         :param str url: url to send request to
         :param str method: type of request (get/put/post/patch/delete)
-        :param bool ignore401: indicates whether to ignore 401 error when it would 
+        :param bool ignore40x: indicates whether to ignore 40x errors when it would
           indicate that there the token has expired. This is set to 'True' for the
-          first call to the api, and 'False' for the call that is initiated after a 
-          tpken refresh. 
+          first call to the api, and 'False' for the call that is initiated after a
+          tpken refresh.
         :param kwargs: extra params to send to the request api
         :return: Response of the request
         :rtype: requests.Response
@@ -983,7 +988,7 @@ def _internal_request(
             raise e  # re-raise exception
         except HTTPError as e:
             # Server response with 4XX or 5XX error status codes
-            if e.response.status_code == 401 and ignore401 is True:
+            if e.response.status_code in [401, 403] and ignore40x is True:
                 # This could be a token expired error.
                 if self.token_backend.token_is_expired(username=self.username):
                     # Access token has expired, try to refresh the token and try again on the next loop
@@ -1042,7 +1047,9 @@ def naive_request(self, url: str, method: str, **kwargs) -> Response:
             # lazy creation of a naive session
             self.naive_session = self.get_naive_session()
 
-        return self._internal_request(self.naive_session, url, method, ignore401=False, **kwargs)
+        return self._internal_request(
+            self.naive_session, url, method, ignore40x=False, **kwargs
+        )
 
     def oauth_request(self, url: str, method: str, **kwargs) -> Response:
         """Makes a request to url using an oauth session.
@@ -1063,20 +1070,24 @@ def oauth_request(self, url: str, method: str, **kwargs) -> Response:
                     f"No auth token found. Authentication Flow needed for user {self.username}"
                 )
 
-        # In the event of a response that returned 401 unauthorised the ignore401 flag indicates
-        # that the 401 can be a token expired error. MsGraph is returning 401 when the access token
-        # has expired. We can not distinguish between a real 401 or token expired 401. So in the event
-        # of a 401 http error we will ignore the first time and try to refresh the token, and then
-        # re-run the request. If the 401 goes away we can move on. If it keeps the 401 then we will 
+        # In the event of a response that returned 401 or 403 unauthorised the ignore40x flag indicates
+        # that the 40x can be a token expired error. MsGraph is returning 401 or 403 when the access token
+        # has expired. We can not distinguish between a real 40x or token expired 40x. So in the event
+        # of a 40x http error we will ignore the first time and try to refresh the token, and then
+        # re-run the request. If the 40x goes away we can move on. If it keeps the 40x then we will
         # raise the error.
         try:
-            return self._internal_request(self.session, url, method, ignore401=True, **kwargs)
+            return self._internal_request(
+                self.session, url, method, ignore40x=True, **kwargs
+            )
         except TokenExpiredError as e:
             # refresh and try again the request!
 
             # try to refresh the token and/or follow token backend answer on 'should_refresh_token'
             if self._try_refresh_token():
-                return self._internal_request(self.session, url, method, ignore401=False, **kwargs)
+                return self._internal_request(
+                    self.session, url, method, ignore40x=False, **kwargs
+                )
             else:
                 raise e
 

O365/connection.py

@@ -14,7 +14,7 @@
     ApiComponent,
     OneDriveWellKnowFolderNames,
     Pagination,
-    ExperimentalQuery,
+    QueryBuilder,
     CompositeFilter
 )
 
@@ -1188,12 +1188,12 @@ def get_child_folders(self, limit=None, *, query=None, order_by=None, batch=None
         if query:
             if not isinstance(query, str):
                 if isinstance(query, CompositeFilter):
-                    q = ExperimentalQuery(protocol=self.protocol)
+                    q = QueryBuilder(protocol=self.protocol)
                     query = query & q.unequal('folder', None)
                 else:
                     query = query.on_attribute('folder').unequal(None)
         else:
-            q = ExperimentalQuery(protocol=self.protocol)
+            q = QueryBuilder(protocol=self.protocol)
             query = q.unequal('folder', None)
 
         return self.get_items(limit=limit, query=query, order_by=order_by, batch=batch)
@@ -1606,6 +1606,7 @@ def _base_get_list(self, url, limit=None, *, query=None, order_by=None,
         items = (
             self._classifier(item)(parent=self, **{self._cloud_data_key: item})
             for item in data.get('value', []))
+
         next_link = data.get(NEXT_LINK_KEYWORD, None)
         if batch and next_link:
             return Pagination(parent=self, data=items,
@@ -1655,12 +1656,12 @@ def get_child_folders(self, limit=None, *, query=None, order_by=None, batch=None
         if query:
             if not isinstance(query, str):
                 if isinstance(query, CompositeFilter):
-                    q = ExperimentalQuery(protocol=self.protocol)
+                    q = QueryBuilder(protocol=self.protocol)
                     query = query & q.unequal('folder', None)
                 else:
                     query = query.on_attribute('folder').unequal(None)
         else:
-            q = ExperimentalQuery(protocol=self.protocol)
+            q = QueryBuilder(protocol=self.protocol)
             query = q.unequal('folder', None)
 
         return self.get_items(limit=limit, query=query, order_by=order_by, batch=batch)

O365/drive.py

@@ -10,7 +10,7 @@
 from urllib.parse import quote
 
 from .drive import File
-from .utils import ApiComponent, TrackerSet, to_snake_case
+from .utils import ApiComponent, TrackerSet, to_snake_case, col_index_to_label
 
 log = logging.getLogger(__name__)
 
@@ -1948,6 +1948,74 @@ def add_named_range(self, name, reference, comment="", is_formula=False):
             parent=self, **{self._cloud_data_key: response.json()}
         )
 
+    def update_cells(self, address, rows):
+        """
+        Updates the cells at a given range in this worksheet. This is a convenience method since there is no
+        direct endpoint API for tableless row updates.
+        :param str|Range address: the address to resolve to a range which can be used for updating cells.
+        :param list[list[str]] rows: list of rows to push to this range. If updating a single cell, pass a list
+            containing a single row (list) containing a single cell worth of data.
+        """
+        if isinstance(address, str):
+            address = self.get_range(address)
+
+        if not isinstance(address, Range):
+            raise ValueError("address was not an accepted type: str or Range")
+
+        if not isinstance(rows, list):
+            raise ValueError("rows was not an accepted type: list[list[str]]")
+
+        # Let's not even try pushing to API if the range rectangle mismatches the input row and column count.
+        row_count = len(rows)
+        col_count = len(rows[0]) if row_count > 0 else 1
+
+        if address.row_count != row_count or address.column_count != col_count:
+            raise ValueError("rows and columns are not the same size as the range selected. This is required by the Microsoft Graph API.")
+
+        address.values = rows
+        address.update()
+
+    def append_rows(self, rows):
+        """
+        Appends rows to the end of a worksheet. There is no direct Graph API to do this operation without a Table
+        instance. Instead, this method identifies the last row in the worksheet and requests a range after that row
+        and updates that range.
+
+        Beware! If you open your workbook from sharepoint and delete all of the rows in one go and attempt to append
+        new rows, you will get undefined behavior from the Microsoft Graph API. I don't know if I did not give enough
+        time for the backend to synchronize from the moment of deletion on my browser and the moment I triggered my
+        script, but this is something I have observed. Sometimes insertion fails and sometimes it inserts where the new
+        row would have been if data had not been deleted from the browser side. Maybe it is an API cache issue. However,
+        after the first row is inserted successfully, this undefined behavior goes away on repeat calls to my scripts.
+        Documenting this behavior for future consumers of this API.
+
+        :param list[list[str]] rows: list of rows to push to this range. If updating a single cell, pass a list
+            containing a single row (list) containing a single cell worth of data.
+        """
+        row_count = len(rows)
+        col_count = len(rows[0]) if row_count > 0 else 0
+        col_index = col_count - 1
+
+        # Find the last row index so we can grab a range after it.
+        current_range = self.get_used_range()
+        # Minor adjustment because Graph will return [['']] in an empty worksheet.
+        # Also, beware that Graph might report ghost values if testing using the front end site and that can be interesting
+        # during debugging. I ctrl + A and delete then click elsewhere before testing again.
+        # Might also take a moment for the backend to eventually catch up to the changes.
+        # Graph can be weirdly slow. It might be an institution thing.
+        if current_range.row_count == 1 and len(current_range.values[0]) == 1 and current_range.values[0][0] == '':
+            current_range.values = []
+            current_range.row_count = 0
+
+        target_index = current_range.row_count
+
+        # Generate the address needed to outline the bounding rectangle to use to fill in data.
+        col_name = col_index_to_label(col_index)
+        insert_range_address = 'A{}:{}{}'.format(target_index + 1, col_name, target_index + row_count)
+
+        # Request to push the data to the given range.
+        self.update_cells(insert_range_address, rows)
+
     def get_named_range(self, name):
         """Retrieves a Named range by it's name"""
         url = self.build_url(self._endpoints.get("get_named_range").format(name=name))

O365/excel.py

@@ -337,6 +337,11 @@ def __init__(self, *, parent=None, con=None, **kwargs):
         completed_obj = cloud_data.get(cc("completedDateTime"), {})
         self.__completed = self._parse_date_time_time_zone(completed_obj)
 
+        self.__checklist_items = (
+            self.checklist_item_constructor(parent=self, **{self._cloud_data_key: item})
+            for item in cloud_data.get(cc("checklistItems"), [])
+        )
+
     def __str__(self):
         """Representation of the Task via the Graph api as a string."""
         return self.__repr__()
@@ -581,6 +586,15 @@ def is_completed(self):
         """
         return self.__is_completed
 
+    @property
+    def checklist_items(self):
+        """Checklist items for the task.
+
+        :getter: Get checklistItems
+        :type: list[ChecklistItem]
+        """
+        return self.__checklist_items
+
     def mark_completed(self):
         """Mark the task as completed."""
         self.__is_completed = True

O365/tasks.py

@@ -3,10 +3,10 @@
 from .utils import CaseEnum, ImportanceLevel, TrackerSet
 from .utils import Recipient, Recipients, HandleRecipientsMixin
 from .utils import NEXT_LINK_KEYWORD, ME_RESOURCE, USERS_RESOURCE
-from .utils import OneDriveWellKnowFolderNames, Pagination, Query
+from .utils import OneDriveWellKnowFolderNames, Pagination
 from .token import BaseTokenBackend, FileSystemTokenBackend, FirestoreBackend, AWSS3Backend, AWSSecretsBackend, EnvTokenBackend, BitwardenSecretsManagerBackend, DjangoTokenBackend
+from .range import col_index_to_label
 from .windows_tz import get_iana_tz, get_windows_tz
 from .consent import consent_input_token
 from .casing import to_snake_case, to_pascal_case, to_camel_case
-
-from .query import QueryBuilder as ExperimentalQuery, CompositeFilter
+from .query import QueryBuilder, CompositeFilter

O365/utils/__init__.py

@@ -0,0 +1,27 @@
+CAPITALIZED_ASCII_CODE = ord('A')
+CAPITALIZED_WINDOW = 26
+
+
+def col_index_to_label(col_index):
+    """
+    Given a column index, returns the label corresponding to the column name. For example, index 0 would be
+    A ... until 25 which would be Z.
+    This function will recurse until a full label is generated using chunks of CAPITALIZED_WINDOW. Meaning,
+    an index of 51 should yield a label of ZZ corresponding to the ZZ column.
+
+    :param int col_index: number associated with the index position of the requested column. For example, column index 0
+        would correspond to column label A.
+    """
+    label = ''
+    extra_letter_index = (col_index // CAPITALIZED_WINDOW) - 1 # Minor adjustment for the no repeat (0) case.
+
+    # If we do need to prepend a new letter to the column label do so recursively such that we could simulate
+    # labels like AA or AAA or AAAA ... etc.
+    if extra_letter_index >= 0:
+        label += col_index_to_label(extra_letter_index)
+
+    # Otherwise, passthrough and add the letter the input index corresponds to.
+    return label + index_to_col_char(col_index)
+
+def index_to_col_char(index):
+    return chr(CAPITALIZED_ASCII_CODE + index % CAPITALIZED_WINDOW)