feat: add search suggestions example

examples/sharepoint/search/README.md

@@ -58,7 +58,8 @@ Results respect the requesting user's permissions.
 | **7** | Sort by managed property | [`query_with_sort.py`](./query_with_sort.py) | Read access to content | [Search REST API](https://learn.microsoft.com/en-us/sharepoint/dev/general-development/sharepoint-search-rest-api-overview) |
 | **8** | Refinement / faceted drill-down | [`query_with_refinement.py`](./query_with_refinement.py) | Read access to content | [Search REST API](https://learn.microsoft.com/en-us/sharepoint/dev/general-development/sharepoint-search-rest-api-overview) |
 | **9** | Paginate through results | [`query_paged.py`](./query_paged.py) | Read access to content | [Search REST API](https://learn.microsoft.com/en-us/sharepoint/dev/general-development/sharepoint-search-rest-api-overview) |
-| **10** | Export search reports | [`export_reports.py`](./export_reports.py) | Search admin | [Search REST API](https://learn.microsoft.com/en-us/sharepoint/dev/general-development/sharepoint-search-rest-api-overview) |
+| **10** | Search suggestions (type-ahead) | [`query_suggestions.py`](./query_suggestions.py) | Read access to content | [Search REST API](https://learn.microsoft.com/en-us/sharepoint/dev/general-development/sharepoint-search-rest-api-overview) |
+| **11** | Export search reports | [`export_reports.py`](./export_reports.py) | Search admin | [Search REST API](https://learn.microsoft.com/en-us/sharepoint/dev/general-development/sharepoint-search-rest-api-overview) |
 
 ---
 

examples/sharepoint/search/query_suggestions.py

@@ -0,0 +1,35 @@
+"""
+Search-as-you-type suggestions: query keywords, people names, and popular results.
+
+Uses the SharePoint Search suggest API to power autocomplete/search-as-you-type
+scenarios — the same API PnP Modern Search calls for its suggestion provider.
+
+https://learn.microsoft.com/en-us/sharepoint/dev/general-development/sharepoint-search-rest-api-overview
+"""
+
+from office365.sharepoint.client_context import ClientContext
+from tests import test_client_id, test_password, test_site_url, test_tenant, test_username
+
+ctx = ClientContext(test_site_url).with_username_and_password(
+    tenant=test_tenant,
+    client_id=test_client_id,
+    username=test_username,
+    password=test_password,
+)
+
+# Partial query — as a user types "guide" the suggest API returns completions
+result = ctx.search.suggest("guide").execute_query()
+suggestions = result.value
+
+print("=== Query Suggestions ===")
+for q in suggestions.Queries:
+    source = "personal" if q.IsPersonal else "global"
+    print(f"  [{source}] {q.Query}")
+
+print("\n=== People Name Suggestions ===")
+for name in suggestions.PeopleNames:
+    print(f"  {name}")
+
+print("\n=== Popular Results ===")
+for item in suggestions.PopularResults:
+    print(f"  {item.Title} — {item.Url}")

office365/runtime/odata/request.py

@@ -77,7 +77,9 @@ def process_response(self, response: Response, query: ClientQuery) -> None:
         if isinstance(return_type, ClientObject):
             return_type.clear_state()
 
-        if response.headers.get("Content-Type", "").lower().split(";")[0] != "application/json":
+        content_type = response.headers.get("Content-Type", "").lower().split(";")[0]
+
+        if content_type != "application/json" or self._is_content_download(query):
             if isinstance(return_type, ClientResult):
                 return_type.set_property("__value", response.content)
         else:
@@ -87,6 +89,14 @@ def process_response(self, response: Response, query: ClientQuery) -> None:
 
             self.map_json(response.json(), return_type, json_format)
 
+    @staticmethod
+    def _is_content_download(query: ClientQuery) -> bool:
+        """Check if the query is a raw content download (file content, not OData metadata)."""
+        if isinstance(query, FunctionQuery):
+            name = query.name
+            return name in ("content", "$value")
+        return False
+
     def map_json(
         self,
         json: Any,