diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 99cd07df..28c3d69f 100644 --- a/docs/source/getting_started.rst +++ b/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:: diff --git a/docs/source/usage/account.rst b/docs/source/usage/account.rst index 6a139f60..fb21c4f5 100644 --- a/docs/source/usage/account.rst +++ b/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() diff --git a/docs/source/usage/addressbook.rst b/docs/source/usage/addressbook.rst index ec721b00..f0c829fd 100644 --- a/docs/source/usage/addressbook.rst +++ b/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) diff --git a/docs/source/usage/calendar.rst b/docs/source/usage/calendar.rst index 668f2bb5..67b56955 100644 --- a/docs/source/usage/calendar.rst +++ b/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. diff --git a/docs/source/usage/mailbox.rst b/docs/source/usage/mailbox.rst index 4c8418f1..056b4e86 100644 --- a/docs/source/usage/mailbox.rst +++ b/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 diff --git a/docs/source/usage/utils/query.rst b/docs/source/usage/utils/query.rst index 237eb531..13d497b8 100644 --- a/docs/source/usage/utils/query.rst +++ b/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": diff --git a/docs/source/usage/utils/utils.rst b/docs/source/usage/utils/utils.rst index 3f986191..5007b340 100644 --- a/docs/source/usage/utils/utils.rst +++ b/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)