Merge pull request #1173 from RogerSelwyn/query-docs

Added docs for query builder
Update docs build to use uv

Author: alejcas

.github/workflows/build_pages.yml

@@ -14,14 +14,18 @@ jobs:
       - name: "Set up Python"
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
-          cache: "pip"
+          python-version-file: "pyproject.toml"
 
-      - name: "Install requirements"
-        run: python3 -m pip install -r requirements-pages.txt
+      - name: Install uv
+        uses: astral-sh/setup-uv@v1
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync 
 
       - name: "Build pages"
-        run: sphinx-build -b html -c ./docs/source/ ./docs/source/ ./docs/latest/ 
+        run: uv run sphinx-build -b html -c ./docs/source/ ./docs/source/ ./docs/latest/ 
 
       - name: "Pull any updates"
         shell: bash

O365/excel.py

@@ -1954,7 +1954,7 @@ def update_cells(self, address, rows):
         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.
+        containing a single row (list) containing a single cell worth of data.
         """
         if isinstance(address, str):
             address = self.get_range(address)

docs/source/usage/sharepoint.rst

@@ -11,8 +11,8 @@ Sites.Read.All             sharepoint                               To only read
 Sites.ReadWrite.All        sharepoint_dl                            To read and save sites, lists and items
 =========================  =======================================  =======================================
 
-Note that using the *.All scopes is way less secure than granting permissions to specific sites and using
-Sites.Selected scope.
+Note that using the :code:`.All` scopes is way less secure than granting permissions to specific sites and using
+:code:`Sites.Selected scope`.
 
 Assuming an authenticated account, create a Sharepoint instance, and connect
 to a Sharepoint site.

docs/source/usage/utils/query.rst

@@ -1,7 +1,53 @@
 Query
 =====
 
+.. _query_builder:
+
 Query Builder
 -------------
 
+A query can be created for every ``ApiComponent`` (such as ``MailBox``). The ``Query`` can be used to handle the filtering, sorting, selecting, expanding and search very easily.
+
+For example:
+
+.. code-block:: python
+
+    from O365.utils import QueryBuilder
+    builder = QueryBuilder(protocol=account.protocol)
+
+    query = builder.chain_or(builder.contains('subject', 'george best'), builder.startswith('subject', 'quotes')
+
+    # 'created_date_time' will automatically be converted to the protocol casing.
+    # For example when using MS Graph this will become 'createdDateTime'.
+
+    query = query & builder.greater('created_date_time', datetime(2018, 3, 21))
+
+    print(query)
+
+    # contains(subject, 'george best') or startswith(subject, 'quotes') and createdDateTime gt '2018-03-21T00:00:00Z'
+    # note you can pass naive datetimes and those will be converted to you local timezone and then send to the api as UTC in iso8601 format
+
+    # To use Query objetcs just pass it to the query parameter:
+    filtered_messages = mailbox.get_messages(query=query)
+
+You can also specify specific data to be retrieved with "select":
+
+.. code-block:: python
+
+    # select only some properties for the retrieved messages:
+    query = builder.select('subject', 'to_recipients', 'created_date_time)
+
+    messages_with_selected_properties = mailbox.get_messages(query=query)
+
+You can also search content. As said in the graph docs:
+
+    You can currently search only message and person collections. A $search request returns up to 250 results. You cannot use $filter or $orderby in a search request.
+    
+    If you do a search on messages and specify only a value without specific message properties, the search is carried out on the default search properties of from, subject, and body.
+
+    .. code-block:: python
+
+        # searching is the easy part ;)
+        query = builder.search('george best is da boss')
+        messages = mailbox.get_messages(query=query)
 

docs/source/usage/utils/utils.rst

@@ -39,6 +39,10 @@ For example:
 
 Query helper
 ------------
+.. note::
+
+    This method of creating queries is now deprecated, queries shoould now be created using the ExperimentalQuery methods - :ref:`query_builder`
+
 Every ``ApiComponent`` (such as ``MailBox``) implements a new_query method that will return a ``Query`` instance. This ``Query`` instance can handle the filtering, sorting, selecting, expanding and search very easily.
 
 For example: