Merge pull request #1194 from RogerSelwyn/doc_updates

Doc updates

Author: alejcas

docs/source/getting_started.rst

@@ -59,13 +59,13 @@ A common pattern to check for authentication and use the library is this one:
 
 .. code-block:: python
 
-   scopes = ['my_required_scopes']  # you can use scope helpers here (see Permissions and Scopes section)
+   requested_scopes = ['my_required_scopes']  # you can use scope helpers here (see Permissions and Scopes section)
 
    account = Account(credentials)
 
    if not account.is_authenticated:  # will check if there is a token and has not expired
       # ask for a login using console based authentication. See Authentication for other flows
-      if account.authenticate(scopes=scopes) is False:
+      if account.authenticate(requested_scopes=requeated_scopes) is False:
          raise RuntimeError('Authentication Failed')
 
    # now we are authenticated
@@ -228,7 +228,7 @@ To authenticate (login) you can use :ref:`different_interfaces`. On the followin
           # the default authentication method will be "on behalf of a user"
 
           account = Account(credentials)
-          if account.authenticate(scopes=['basic', 'message_all']):
+          if account.authenticate(requested_scopes=['basic', 'message_all']):
              print('Authenticated!')
 
           # 'basic' adds: 'https://graph.microsoft.com/User.Read'
@@ -281,7 +281,7 @@ To accomplish the authentication you can basically use different approaches. The
    You can authenticate using a console. The best way to achieve this is by using the authenticate method of the Account class.
 
    account = Account(credentials)
-   account.authenticate(scopes=['basic', 'message_all'])
+   account.authenticate(requested_scopes=['basic', 'message_all'])
    The authenticate method will print into the console an url that you will have to visit to achieve authentication. Then after visiting the link and authenticate you will have to paste back the resulting url into the console. The method will return True and print a message if it was succesful.
 
    **Tip:** When using macOS the console is limited to 1024 characters. If your url has multiple scopes it can exceed this limit. To solve this. Just import readline at the top of your script.
@@ -370,14 +370,14 @@ For example your application can have Calendar.Read, Mail.ReadWrite and Mail.Sen
 
    credentials = ('client_id', 'client_secret')
 
-   scopes = ['Mail.ReadWrite', 'Mail.Send']
+   requested_scopes = ['Mail.ReadWrite', 'Mail.Send']
 
-   account = Account(credentials, scopes=scopes)
+   account = Account(credentials, requested_scopes=requested_scopes)
    account.authenticate()
 
    # The latter is exactly the same as passing scopes to the authenticate method like so:
    # account = Account(credentials)
-   # account.authenticate(scopes=scopes)
+   # account.authenticate(requested_scopes=requested_scopes)
 
 Scope implementation depends on the protocol used. So by using protocol data you can automatically set the scopes needed. This is implemented by using 'scope helpers'. Those are little helpers that group scope functionality and abstract the protocol used.
 
@@ -419,7 +419,7 @@ You can get the same scopes as before using protocols and scope helpers like thi
    scopes_graph = protocol.get_scopes_for('message_all')
    # scopes here are: ['https://graph.microsoft.com/Mail.ReadWrite', 'https://graph.microsoft.com/Mail.Send']
 
-   account = Account(credentials, scopes=scopes_graph)
+   account = Account(credentials, requested_scopes=scopes_graph)
 
 .. note::
 

docs/source/usage/account.rst

@@ -88,11 +88,11 @@ Setting Scopes
 
     # Full permission to your mail
     account = Account(credentials=('my_client_id', 'my_client_secret'),
-                      scopes=['message_all'])
+                      requested_scopes=['message_all'])
 
     # Why change every time, add all at a time :)
     account = Account(credentials=('my_client_id', 'my_client_secret'),
-                      scopes=['message_all', 'message_all_shared', 'address_book_all',
+                      requested_scopes=['message_all', 'message_all_shared', 'address_book_all',
                               'address_book_all_shared',
                               'calendar', 'users', 'onedrive', 'sharepoint_dl'])
 
@@ -143,8 +143,8 @@ You can work only with the required pieces:
     from O365.mailbox import MailBox
 
     protocol = MSGraphProtocol()
-    scopes = ['...']
-    con = Connection(('client_id', 'client_secret'), scopes=scopes)
+    requested_scopes = ['...']
+    con = Connection(('client_id', 'client_secret'), requested_scopes=requested_scopes)
 
     message = Message(con=con, protocol=protocol)
     # ...
@@ -186,7 +186,7 @@ It's also easy to implement a custom Class. Just Inherit from ApiComponent, defi
     from O365 import Connection, MSGraphProtocol
 
     protocol = MSGraphProtocol()  # or maybe a user defined protocol
-    con = Connection(('client_id', 'client_secret'), scopes=protocol.get_scopes_for(['...']))
+    con = Connection(('client_id', 'client_secret'), requested_scopes=protocol.get_scopes_for(['...']))
     custom_class = CustomClass(con=con, protocol=protocol)
 
     custom_class.do_some_stuff()

docs/source/usage/addressbook.rst

@@ -64,15 +64,16 @@ Without admin consent you can only access a few properties of each user such as
 To search the Global Address List (Users API):
 
 .. code-block:: python
-
+    
     global_address_list = account.directory()
 
     # for backwards compatibility only this also works and returns a Directory object:
     # global_address_list = account.address_book(address_book='gal')
 
     # start a new query:
-    q = global_address_list.new_query('display_name')
-    q.startswith('George Best')
+    builder = global_address_list.new_query()
+    query = builder.select('display_name')
+    query = query & builder.startswith('subject', 'George Best')
 
     for user in global_address_list.get_users(query=q):
         print(user)

docs/source/usage/calendar.rst

@@ -46,12 +46,13 @@ Working with Calendar instances:
 
     calendar = schedule.get_calendar(calendar_name='Birthdays')
 
+    builder = calendar.new_query()
     calendar.name = 'Football players birthdays'
     calendar.update()
 
     
-    start_q = calendar.new_query('start').greater_equal(dt.datetime(2018, 5, 20))
-    end_q = calendar.new_query('start').less_equal(dt.datetime(2018, 5, 24))
+    start_q = builder.greater_equal('start', dt.datetime(2018, 5, 20))
+    end_q = builder.greater_equal('start', dt.datetime(2018, 5, 24))
 
     birthdays = calendar.get_events(
         include_recurring=True, # include_recurring=True will include repeated events on the result set.

docs/source/usage/mailbox.rst

@@ -87,7 +87,8 @@ MailboxSettings.ReadWrite  mailbox_settings                         To read and
 .. .. code-block:: python
 
 ..     # All child folders whose name startswith 'Top'
-..     mail_folders = mailbox.get_folders(query=mailbox.new_query('displayName').startswith('Top'))
+..     builder = mailbox.new_query()
+..     mail_folders = mailbox.get_folders(query=builder.startswith('displayName', 'Top'))
 
 Mailbox and Messages
 """"""""""""""""""""
@@ -152,8 +153,9 @@ Creating a draft message is as easy as this:
 **Working with saved emails is also easy**
 
 .. code-block:: python
-
-    query = mailbox.new_query().on_attribute('subject').contains('george best')  # see Query object in Utils
+    
+    builder = mailbox.new_query()
+    query = builder.chain_or(builder.contains('subject', 'george best'), builder.startswith('subject', 'quotes')  # see Query object in Utils
     messages = mailbox.get_messages(limit=25, query=query)
 
     message = messages[0]  # get the first one

docs/source/usage/utils/query.rst

@@ -12,8 +12,7 @@ For example:
 
 .. code-block:: python
 
-    from O365.utils import QueryBuilder
-    builder = QueryBuilder(protocol=account.protocol)
+    builder = mailbox.new_query()
 
     query = builder.chain_or(builder.contains('subject', 'george best'), builder.startswith('subject', 'quotes')
 
@@ -27,7 +26,7 @@ For example:
     # 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:
+    # To use Query objects 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":

docs/source/usage/utils/utils.rst

@@ -49,14 +49,14 @@ For example:
 
 .. code-block:: python
 
-    query = mailbox.new_query()  # you can use the shorthand: mailbox.q()
+    builder = mailbox.new_query()  # you can use the shorthand: mailbox.q()
 
-    query = query.on_attribute('subject').contains('george best').chain('or').startswith('quotes')
+    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.chain('and').on_attribute('created_date_time').greater(datetime(2018, 3, 21))
+    query = query & builder.greater('created_date_time', datetime(2018, 3, 21))
 
     print(query)