Skip to content

Commit b1e76e3

Browse files
RogerSelwynRogerSelwyn
committed
Added usage for FileSystemTokenBackend
1 parent cfe5764 commit b1e76e3

3 files changed

Lines changed: 131 additions & 87 deletions

File tree

‎docs/source/usage/utils.rst‎

Lines changed: 6 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,91 +1,10 @@
1+
=====
12
Utils
23
=====
3-
Pagination
4-
----------
5-
When using certain methods, it is possible that you request more items than the api can return in a single api call. In this case the Api, returns a "next link" url where you can pull more data.
6-
7-
When this is the case, the methods in this library will return a ``Pagination`` object which abstracts all this into a single iterator. The pagination object will request "next links" as soon as they are needed.
8-
9-
For example:
10-
11-
.. code-block:: python
12-
13-
mailbox = account.mailbox()
14-
15-
messages = mailbox.get_messages(limit=1500) # the MS Graph API have a 999 items limit returned per api call.
16-
17-
# Here messages is a Pagination instance. It's an Iterator so you can iterate over.
18-
19-
# The first 999 iterations will be normal list iterations, returning one item at a time.
20-
# When the iterator reaches the 1000 item, the Pagination instance will call the api again requesting exactly 500 items
21-
# or the items specified in the batch parameter (see later).
22-
23-
for message in messages:
24-
print(message.subject)
25-
26-
When using certain methods you will have the option to specify not only a limit option (the number of items to be returned) but a batch option. This option will indicate the method to request data to the api in batches until the limit is reached or the data consumed. This is useful when you want to optimize memory or network latency.
27-
28-
For example:
29-
30-
.. code-block:: python
31-
32-
messages = mailbox.get_messages(limit=100, batch=25)
33-
34-
# messages here is a Pagination instance
35-
# when iterating over it will call the api 4 times (each requesting 25 items).
36-
37-
for message in messages: # 100 loops with 4 requests to the api server
38-
print(message.subject)
39-
40-
Query helper
41-
------------
42-
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.
43-
44-
For example:
45-
46-
.. code-block:: python
47-
48-
query = mailbox.new_query() # you can use the shorthand: mailbox.q()
49-
50-
query = query.on_attribute('subject').contains('george best').chain('or').startswith('quotes')
51-
52-
# 'created_date_time' will automatically be converted to the protocol casing.
53-
# For example when using MS Graph this will become 'createdDateTime'.
54-
55-
query = query.chain('and').on_attribute('created_date_time').greater(datetime(2018, 3, 21))
56-
57-
print(query)
58-
59-
# contains(subject, 'george best') or startswith(subject, 'quotes') and createdDateTime gt '2018-03-21T00:00:00Z'
60-
# 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
61-
62-
# To use Query objetcs just pass it to the query parameter:
63-
filtered_messages = mailbox.get_messages(query=query)
64-
65-
You can also specify specific data to be retrieved with "select":
66-
67-
.. code-block:: python
68-
69-
# select only some properties for the retrieved messages:
70-
query = mailbox.new_query().select('subject', 'to_recipients', 'created_date_time')
71-
72-
messages_with_selected_properties = mailbox.get_messages(query=query)
73-
74-
You can also search content. As said in the graph docs:
75-
76-
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.
77-
78-
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.
79-
80-
.. code-block:: python
81-
82-
# searching is the easy part ;)
83-
query = mailbox.q().search('george best is da boss')
84-
messages = mailbox.get_messages(query=query)
854

86-
Request Error Handling
87-
----------------------
88-
Whenever a Request error raises, the connection object will raise an exception. Then the exception will be captured and logged it to the stdout with its message, and return Falsy (None, False, [], etc...)
5+
.. toctree::
6+
:maxdepth: 2
7+
:caption: Contents:
898

90-
HttpErrors 4xx (Bad Request) and 5xx (Internal Server Error) are considered exceptions and
91-
raised also by the connection. You can tell the ``Connection`` to not raise http errors by passing ``raise_http_errors=False`` (defaults to True).
9+
utils/token
10+
utils/utils

‎docs/source/usage/utils/token.rst‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
Token
2+
=====
3+
4+
When initiating the account connection you may wish to store the token for ongoing usage, removing the need to re-authenticate every time. There are a variety of storage mechanisms available which are shown in the detailed api.
5+
6+
FileSystemTokenBackend
7+
----------------------
8+
To store the token in your local file system, you can use the ``FileSystemTokenBackend``. This takes a path and a file name as parameters.
9+
10+
For example:
11+
12+
.. code-block:: python
13+
14+
from O365 import Account, FileSystemTokenBackend
15+
16+
token_backend = FileSystemTokenBackend(token_path=token_path, token_filename=token_filename)
17+
18+
account = Account(credentials=('my_client_id', 'my_client_secret'), token_backend=token_backend)
19+
20+
The methods are similar for the other token backends.
21+
22+
You can also pass in a cryptography manager to the token backend so encrypt the token in the store, and to decrypt on retrieval. The cryptography manager must support the ``encrypt`` and ``decrypt`` methods.
23+
24+
.. code-block:: python
25+
26+
from O365 import Account, FileSystemTokenBackend
27+
from xxx import CryptoManager
28+
29+
key = "my really secret key"
30+
mycryptomanager = CryptoManager(key)
31+
32+
token_backend = FileSystemTokenBackend(token_path=token_path, token_filename=token_filename, cryptography_manager=mycryptomanager)
33+
34+
account = Account(credentials=('my_client_id', 'my_client_secret'), token_backend=token_backend)

‎docs/source/usage/utils/utils.rst‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
Utils
2+
=====
3+
Pagination
4+
----------
5+
When using certain methods, it is possible that you request more items than the api can return in a single api call. In this case the Api, returns a "next link" url where you can pull more data.
6+
7+
When this is the case, the methods in this library will return a ``Pagination`` object which abstracts all this into a single iterator. The pagination object will request "next links" as soon as they are needed.
8+
9+
For example:
10+
11+
.. code-block:: python
12+
13+
mailbox = account.mailbox()
14+
15+
messages = mailbox.get_messages(limit=1500) # the MS Graph API have a 999 items limit returned per api call.
16+
17+
# Here messages is a Pagination instance. It's an Iterator so you can iterate over.
18+
19+
# The first 999 iterations will be normal list iterations, returning one item at a time.
20+
# When the iterator reaches the 1000 item, the Pagination instance will call the api again requesting exactly 500 items
21+
# or the items specified in the batch parameter (see later).
22+
23+
for message in messages:
24+
print(message.subject)
25+
26+
When using certain methods you will have the option to specify not only a limit option (the number of items to be returned) but a batch option. This option will indicate the method to request data to the api in batches until the limit is reached or the data consumed. This is useful when you want to optimize memory or network latency.
27+
28+
For example:
29+
30+
.. code-block:: python
31+
32+
messages = mailbox.get_messages(limit=100, batch=25)
33+
34+
# messages here is a Pagination instance
35+
# when iterating over it will call the api 4 times (each requesting 25 items).
36+
37+
for message in messages: # 100 loops with 4 requests to the api server
38+
print(message.subject)
39+
40+
Query helper
41+
------------
42+
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.
43+
44+
For example:
45+
46+
.. code-block:: python
47+
48+
query = mailbox.new_query() # you can use the shorthand: mailbox.q()
49+
50+
query = query.on_attribute('subject').contains('george best').chain('or').startswith('quotes')
51+
52+
# 'created_date_time' will automatically be converted to the protocol casing.
53+
# For example when using MS Graph this will become 'createdDateTime'.
54+
55+
query = query.chain('and').on_attribute('created_date_time').greater(datetime(2018, 3, 21))
56+
57+
print(query)
58+
59+
# contains(subject, 'george best') or startswith(subject, 'quotes') and createdDateTime gt '2018-03-21T00:00:00Z'
60+
# 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
61+
62+
# To use Query objetcs just pass it to the query parameter:
63+
filtered_messages = mailbox.get_messages(query=query)
64+
65+
You can also specify specific data to be retrieved with "select":
66+
67+
.. code-block:: python
68+
69+
# select only some properties for the retrieved messages:
70+
query = mailbox.new_query().select('subject', 'to_recipients', 'created_date_time')
71+
72+
messages_with_selected_properties = mailbox.get_messages(query=query)
73+
74+
You can also search content. As said in the graph docs:
75+
76+
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.
77+
78+
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.
79+
80+
.. code-block:: python
81+
82+
# searching is the easy part ;)
83+
query = mailbox.q().search('george best is da boss')
84+
messages = mailbox.get_messages(query=query)
85+
86+
Request Error Handling
87+
----------------------
88+
Whenever a Request error raises, the connection object will raise an exception. Then the exception will be captured and logged it to the stdout with its message, and return Falsy (None, False, [], etc...)
89+
90+
HttpErrors 4xx (Bad Request) and 5xx (Internal Server Error) are considered exceptions and
91+
raised also by the connection. You can tell the ``Connection`` to not raise http errors by passing ``raise_http_errors=False`` (defaults to True).

0 commit comments

Comments
 (0)