From 35faee3685c0ac55fdd35f43d0fd3499a72111fd Mon Sep 17 00:00:00 2001
From: vgrem <vvgrem@gmail.com>
Date: Sun, 21 Jan 2024 21:14:53 +0200
Subject: [PATCH] worksheet enhancements & example to return grouped items from
 a list (#806)

---
 examples/onedrive/excel/get_cell.py           | 21 +++++++++++++
 examples/sharepoint/listitems/from_folder.py  | 16 ++++++++++
 examples/sharepoint/listitems/get_grouped.py  | 31 +++++++++++++++++++
 .../workbooks/worksheets/worksheet.py         | 14 +++++++++
 office365/sharepoint/lists/list.py            |  2 +-
 5 files changed, 83 insertions(+), 1 deletion(-)
 create mode 100644 examples/onedrive/excel/get_cell.py
 create mode 100644 examples/sharepoint/listitems/from_folder.py
 create mode 100644 examples/sharepoint/listitems/get_grouped.py

diff --git a/examples/onedrive/excel/get_cell.py b/examples/onedrive/excel/get_cell.py
new file mode 100644
index 00000000..fbd62c0d
--- /dev/null
+++ b/examples/onedrive/excel/get_cell.py
@@ -0,0 +1,21 @@
+"""
+Gets the range object containing the single cell based on row and column numbers.
+
+https://learn.microsoft.com/en-us/graph/api/worksheet-cell?view=graph-rest-1.0
+"""
+import sys
+
+from office365.graph_client import GraphClient
+from tests import test_client_id, test_password, test_tenant, test_username
+
+client = GraphClient.with_username_and_password(
+    test_tenant, test_client_id, test_username, test_password
+)
+drive_item = client.me.drive.root.get_by_path("Financial Sample.xlsx")
+worksheets = drive_item.workbook.worksheets.get().execute_query()
+if len(worksheets) == 0:
+    sys.exit("No worksheets found")
+
+
+result = worksheets["Sheet1"].cell(row=1, column=1).execute_query()
+print(result.values)
diff --git a/examples/sharepoint/listitems/from_folder.py b/examples/sharepoint/listitems/from_folder.py
new file mode 100644
index 00000000..84b5635a
--- /dev/null
+++ b/examples/sharepoint/listitems/from_folder.py
@@ -0,0 +1,16 @@
+from office365.sharepoint.client_context import ClientContext
+from office365.sharepoint.listitems.caml.query import CamlQuery
+from tests import test_client_credentials, test_team_site_url
+
+
+def create_custom_query():
+    qry = CamlQuery()
+    qry.FolderServerRelativeUrl = "Shared Documents/Archive"
+    return qry
+
+
+ctx = ClientContext(test_team_site_url).with_credentials(test_client_credentials)
+lib = ctx.web.lists.get_by_title("Documents")
+result = lib.get_items(create_custom_query()).execute_query()
+for item in result:
+    print(item.properties)
diff --git a/examples/sharepoint/listitems/get_grouped.py b/examples/sharepoint/listitems/get_grouped.py
new file mode 100644
index 00000000..ecf47102
--- /dev/null
+++ b/examples/sharepoint/listitems/get_grouped.py
@@ -0,0 +1,31 @@
+"""
+Demonstrates how to return distinct values from a List for the specific column, where:
+ - render_list_data is used to returns the data for the specified query view
+
+"""
+
+import json
+
+from office365.sharepoint.client_context import ClientContext
+from tests import test_client_credentials, test_team_site_url
+
+view_xml = """
+   <View>
+       <Query>
+          <GroupBy Collapse="TRUE" GroupLimit="100">
+             <FieldRef Name="Author"/>
+          </GroupBy>
+       </Query>
+       <ViewFields>
+           <FieldRef Name="Author"/>
+       </ViewFields>
+       <RowLimit Paged="TRUE">100</RowLimit>
+   </View>
+   """
+
+ctx = ClientContext(test_team_site_url).with_credentials(test_client_credentials)
+lib = ctx.web.lists.get_by_title("Site Pages")
+result = lib.render_list_data(view_xml).execute_query()
+data = json.loads(result.value)
+for item in data.get("Row"):
+    print(item.get("Author.title"))
diff --git a/office365/onedrive/workbooks/worksheets/worksheet.py b/office365/onedrive/workbooks/worksheets/worksheet.py
index da137f37..ae7e74a6 100644
--- a/office365/onedrive/workbooks/worksheets/worksheet.py
+++ b/office365/onedrive/workbooks/worksheets/worksheet.py
@@ -25,6 +25,20 @@ def __repr__(self):
     def __str__(self):
         return self.name or self.entity_type_name
 
+    def cell(self, row, column):
+        """Gets the range object containing the single cell based on row and column numbers.
+        The cell can be outside the bounds of its parent range, so long as it's stays within the worksheet grid.
+        :param int row: Row number of the cell to be retrieved. Zero-indexed.
+        :param int column: Column number of the cell to be retrieved. Zero-indexed.
+        """
+        return_type = WorkbookRange(
+            self.context, ResourcePath("range", self.resource_path)
+        )
+        params = {"row": row, "column": column}
+        qry = FunctionQuery(self, "cell", method_params=params, return_type=return_type)
+        self.context.add_query(qry)
+        return return_type
+
     def range(self, address=None):
         """Gets the range object specified by the address or name."""
         return_type = WorkbookRange(
diff --git a/office365/sharepoint/lists/list.py b/office365/sharepoint/lists/list.py
index dfa0e988..eb3dbfcf 100644
--- a/office365/sharepoint/lists/list.py
+++ b/office365/sharepoint/lists/list.py
@@ -301,7 +301,7 @@ def start_recycle(self):
 
     def render_list_data(self, view_xml):
         """
-        Returns the data for the specified query view.<56> The result is implementation-specific, used for
+        Returns the data for the specified query view. The result is implementation-specific, used for
         providing data to a user interface.
 
         :param str view_xml:  Specifies the query as XML that conforms to the ViewDefinition type as specified in