From ff6bc15285c53f6d9a2a36bba44bb82108e53fce Mon Sep 17 00:00:00 2001
From: Alejandro Casanovas <janscas@users.noreply.github.com>
Date: Wed, 3 Apr 2019 21:37:13 +0200
Subject: [PATCH] Added search capabilities as asked on #211. Updated Readme
 with the Query.search documentation.

---
 O365/utils/utils.py | 44 ++++++++++++++++++++++++++++++++++++++------
 README.md           | 18 +++++++++++++++---
 2 files changed, 53 insertions(+), 9 deletions(-)

diff --git a/O365/utils/utils.py b/O365/utils/utils.py
index e3ae30f5fc0f..cd74f45973b7 100644
--- a/O365/utils/utils.py
+++ b/O365/utils/utils.py
@@ -10,7 +10,6 @@
 from .windows_tz import get_iana_tz, get_windows_tz
 from .decorators import fluent
 
-
 ME_RESOURCE = 'me'
 USERS_RESOURCE = 'users'
 
@@ -570,12 +569,14 @@ def __init__(self, attribute=None, *, protocol):
         self._order_by = OrderedDict()
         self._selects = set()
         self._expands = set()
+        self._search = None
 
     def __str__(self):
-        return 'Filter: {}\nOrder: {}\nSelect: {}\nExpand: {}'.format(self.get_filters(),
-                                                                      self.get_order(),
-                                                                      self.get_selects(),
-                                                                      self.get_expands())
+        return 'Filter: {}\nOrder: {}\nSelect: {}\nExpand: {}\nSearch: {}'.format(self.get_filters(),
+                                                                                  self.get_order(),
+                                                                                  self.get_selects(),
+                                                                                  self.get_expands(),
+                                                                                  self._search)
 
     def __repr__(self):
         return self.__str__()
@@ -622,8 +623,29 @@ def expand(self, *relationships):
 
         return self
 
+    @fluent
+    def search(self, text):
+        """
+        Perform a search.
+        Not from 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.
+        :param str text: the text to search
+        :return: the Query instance
+        """
+        if text is None:
+            self._search = None
+        else:
+            # filters an order are not allowed
+            self.clear_filters()
+            self.clear_order()
+            self._search = '"{}"'.format(text)
+
+        return self
+
     def as_params(self):
-        """ Returns the filters and orders as query parameters
+        """ Returns the filters, orders, select, expands and search as query parameters
 
         :rtype: dict
         """
@@ -636,6 +658,10 @@ def as_params(self):
             params['$select'] = self.get_selects()
         if self.has_expands:
             params['$expand'] = self.get_expands()
+        if self._search:
+            params['$search'] = self._search
+            params.pop('$filter', None)
+            params.pop('$orderby', None)
         return params
 
     @property
@@ -767,6 +793,10 @@ def clear_filters(self):
         """ Clear filters """
         self._filters = []
 
+    def clear_order(self):
+        """ Clears any order commands """
+        self._order_by = OrderedDict()
+
     @fluent
     def clear(self):
         """ Clear everything
@@ -779,6 +809,8 @@ def clear(self):
         self._negation = False
         self._attribute = None
         self._chain = None
+        self._search = None
+
         return self
 
     @fluent
diff --git a/README.md b/README.md
index 18c0be4099e8..ae3ebad47271 100644
--- a/README.md
+++ b/README.md
@@ -785,16 +785,16 @@ for message in messages:  # 100 loops with 4 requests to the api server
 
 #### The Query helper
 
-When using the Office 365 API you can filter some fields.
+When using the Office 365 API you can filter, order, select, expand or search on some fields.
 This filtering is tedious as is using [Open Data Protocol (OData)](http://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part2-url-conventions/odata-v4.0-errata03-os-part2-url-conventions-complete.html).
 
 Every `ApiComponent` (such as `MailBox`) implements a new_query method that will return a `Query` instance.
-This `Query` instance can handle the filtering (and sorting and selecting) very easily.
+This `Query` instance can handle the filtering, sorting, selecting, expanding and search very easily.
 
 For example:
 
 ```python
-query = mailbox.new_query()
+query = mailbox.new_query()  # you can use the shorthand: mailbox.q()
 
 query = query.on_attribute('subject').contains('george best').chain('or').startswith('quotes')
 
@@ -821,6 +821,18 @@ query = mailbox.new_query().select('subject', 'to_recipients', 'created_date_tim
 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.
+
+```python
+# searching is the easy part ;)
+query = mailbox.q().search('george best is da boss')
+messages = mailbox.get_messages(query=query)
+```
+
 #### Request Error Handling
 
 Whenever a Request error raises, the connection object will raise an exception.