Utils
- class O365.utils.utils.ApiComponent(*, protocol=None, main_resource=None, **kwargs)[source]
Bases:
object
Base class for all object interactions with the Cloud Service API
Exposes common access methods to the api protocol within all Api objects
- __init__(*, protocol=None, main_resource=None, **kwargs)[source]
Object initialization
- Parameters:
protocol (Protocol) – A protocol class or instance to be used with this connection
main_resource (str) – main_resource to be used in these API communications
- build_base_url(resource)[source]
Builds the base url of this ApiComponent :param str resource: the resource to build the base url
- build_url(endpoint)[source]
Returns a url for a given endpoint using the protocol service url
- Parameters:
endpoint (str) – endpoint to build the url for
- Returns:
final url
- Return type:
str
- new_query(attribute=None)[source]
Create a new query to filter results
- Parameters:
attribute (str) – attribute to apply the query for
- Returns:
new Query
- Return type:
- q(attribute=None)
Create a new query to filter results
- Parameters:
attribute (str) – attribute to apply the query for
- Returns:
new Query
- Return type:
- set_base_url(resource)[source]
Sets the base urls for this ApiComponent :param str resource: the resource to build the base url
- main_resource
The main resource for the components.
Type: str
- class O365.utils.utils.CaseEnum(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
Bases:
Enum
A Enum that converts the value to a snake_case casing
- class O365.utils.utils.ImportanceLevel(*values)[source]
Bases:
CaseEnum
- High = 'high'
- Low = 'low'
- Normal = 'normal'
- class O365.utils.utils.OneDriveWellKnowFolderNames(*values)[source]
Bases:
Enum
- APP_ROOT = 'approot'
- ATTACHMENTS = 'attachments'
- CAMERA_ROLL = 'cameraroll'
- DOCUMENTS = 'documents'
- MUSIC = 'music'
- PHOTOS = 'photos'
- class O365.utils.utils.OutlookWellKnowFolderNames(*values)[source]
Bases:
Enum
- ARCHIVE = 'Archive'
- CLUTTER = 'clutter'
- CONFLICTS = 'conflicts'
- CONVERSATIONHISTORY = 'conversationhistory'
- DELETED = 'DeletedItems'
- DRAFTS = 'Drafts'
- INBOX = 'Inbox'
- JUNK = 'JunkEmail'
- LOCALFAILURES = 'localfailures'
- OUTBOX = 'Outbox'
- RECOVERABLEITEMSDELETIONS = 'recoverableitemsdeletions'
- SCHEDULED = 'scheduled'
- SEARCHFOLDERS = 'searchfolders'
- SENT = 'SentItems'
- SERVERFAILURES = 'serverfailures'
- SYNCISSUES = 'syncissues'
- class O365.utils.utils.Pagination(*, parent=None, data=None, constructor=None, next_link=None, limit=None, **kwargs)[source]
Bases:
ApiComponent
Utility class that allows batching requests to the server
- __init__(*, parent=None, data=None, constructor=None, next_link=None, limit=None, **kwargs)[source]
Returns an iterator that returns data until it’s exhausted. Then will request more data (same amount as the original request) to the server until this data is exhausted as well. Stops when no more data exists or limit is reached.
- Parameters:
parent – the parent class. Must implement attributes: con, api_version, main_resource
data – the start data to be return
constructor – the data constructor for the next batch. It can be a function.
next_link (str) – the link to request more data to
limit (int) – when to stop retrieving more data
kwargs – any extra key-word arguments to pass to the constructor.
- constructor
The constructor.
Type: any
- data_count
Data count.
Type: int
- extra_args
Extra args.
Type: dict
- limit
The limit of when to stop.
Type: int
- next_link
The next link for the pagination.
Type: str
- parent
The parent.
Type: any
- state
State.
Type: int
- total_count
Total count.
Type: int
- class O365.utils.utils.Query(attribute=None, *, protocol)[source]
Bases:
object
Helper to conform OData filters
- __init__(attribute=None, *, protocol)[source]
Build a query to apply OData filters https://docs.microsoft.com/en-us/graph/query-parameters
- Parameters:
attribute (str) – attribute to apply the query for
protocol (Protocol) – protocol to use for connecting
- all(*, collection, word, attribute=None, func=None, operation=None, negation=False)[source]
Performs a filter with the OData ‘all’ keyword on the collection
For example: q.any(collection=’email_addresses’, attribute=’address’, operation=’eq’, word=’george@best.com’)
will transform to a filter such as:
emailAddresses/all(a:a/address eq ‘george@best.com’)
- Parameters:
collection (str) – the collection to apply the any keyword on
word (str) – the word to check
attribute (str) – the attribute of the collection to check
func (str) – the logical function to apply to the attribute inside the collection
operation (str) – the logical operation to apply to the attribute inside the collection
negation (bool) – negate the funcion or operation inside the iterable
- Return type:
Note
This method is part of fluent api and can be chained
- any(*, collection, word, attribute=None, func=None, operation=None, negation=False)[source]
Performs a filter with the OData ‘any’ keyword on the collection
For example: q.any(collection=’email_addresses’, attribute=’address’, operation=’eq’, word=’george@best.com’)
will transform to a filter such as:
emailAddresses/any(a:a/address eq ‘george@best.com’)
- Parameters:
collection (str) – the collection to apply the any keyword on
word (str) – the word to check
attribute (str) – the attribute of the collection to check
func (str) – the logical function to apply to the attribute inside the collection
operation (str) – the logical operation to apply to the attribute inside the collection
negation (bool) – negates the funcion or operation inside the iterable
- Return type:
Note
This method is part of fluent api and can be chained
- as_params()[source]
Returns the filters, orders, select, expands and search as query parameters
- Return type:
dict
- chain(operation=ChainOperator.AND)[source]
Start a chain operation
- Parameters:
operation (ChainOperator, str) – how to combine with a new one
- Return type:
Note
This method is part of fluent api and can be chained
- clear()[source]
Clear everything
- Return type:
Note
This method is part of fluent api and can be chained
- contains(word)[source]
Adds a contains word check
- Parameters:
word (str) – word to check
- Return type:
Note
This method is part of fluent api and can be chained
- endswith(word)[source]
Adds a endswith word check
- Parameters:
word (str) – word to check
- Return type:
Note
This method is part of fluent api and can be chained
- equals(word)[source]
Add an equals check
- Parameters:
word – word to compare with
- Return type:
Note
This method is part of fluent api and can be chained
- expand(*relationships)[source]
Adds the relationships (e.g. “event” or “attachments”) that should be expanded with the $expand parameter Important: The ApiComponent using this should know how to handle this relationships.
eg: Message knows how to handle attachments, and event (if it’s an EventMessage)
Important: When using expand on multi-value relationships a max of 20 items will be returned.
- Parameters:
relationships (str) – the relationships tuple to expand.
- Return type:
Note
This method is part of fluent api and can be chained
- function(function_name, word)[source]
Apply a function on given word
- Parameters:
function_name (str) – function to apply
word (str) – word to apply function on
- Return type:
Note
This method is part of fluent api and can be chained
- greater(word)[source]
Add a greater than check
- Parameters:
word – word to compare with
- Return type:
Note
This method is part of fluent api and can be chained
- greater_equal(word)[source]
Add a greater than or equal to check
- Parameters:
word – word to compare with
- Return type:
Note
This method is part of fluent api and can be chained
- iterable(iterable_name, *, collection, word, attribute=None, func=None, operation=None, negation=False)[source]
Performs a filter with the OData ‘iterable_name’ keyword on the collection
For example: q.iterable(‘any’, collection=’email_addresses’, attribute=’address’, operation=’eq’, word=’george@best.com’)
will transform to a filter such as: emailAddresses/any(a:a/address eq ‘george@best.com’)
- Parameters:
iterable_name (str) – the OData name of the iterable
collection (str) – the collection to apply the any keyword on
word (str) – the word to check
attribute (str) – the attribute of the collection to check
func (str) – the logical function to apply to the attribute inside the collection
operation (str) – the logical operation to apply to the attribute inside the collection
negation (bool) – negate the funcion or operation inside the iterable
- Return type:
Note
This method is part of fluent api and can be chained
- less(word)[source]
Add a less than check
- Parameters:
word – word to compare with
- Return type:
Note
This method is part of fluent api and can be chained
- less_equal(word)[source]
Add a less than or equal to check
- Parameters:
word – word to compare with
- Return type:
Note
This method is part of fluent api and can be chained
- logical_operator(operation, word)[source]
Apply a logical operator
- Parameters:
operation (str) – how to combine with a new one
word – other parameter for the operation (a = b) would be like a.logical_operator(‘eq’, ‘b’)
- Return type:
Note
This method is part of fluent api and can be chained
- negate()[source]
Apply a not operator
- Return type:
Note
This method is part of fluent api and can be chained
- new(attribute, operation=ChainOperator.AND)[source]
Combine with a new query
- Parameters:
attribute (str) – attribute of new query
operation (ChainOperator) – operation to combine to new query
- Return type:
Note
This method is part of fluent api and can be chained
- on_attribute(attribute)[source]
Apply query on attribute, to be used along with chain()
- Parameters:
attribute (str) – attribute name
- Return type:
Note
This method is part of fluent api and can be chained
- on_list_field(field)[source]
Apply query on a list field, to be used along with chain()
- Parameters:
field (str) – field name (note: name is case sensitive)
- Return type:
Note
This method is part of fluent api and can be chained
- order_by(attribute=None, *, ascending=True)[source]
Applies a order_by clause
- Parameters:
attribute (str) – attribute to apply on
ascending (bool) – should it apply ascending order or descending
- Return type:
Note
This method is part of fluent api and can be chained
- search(text)[source]
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.
- Parameters:
text (str) – the text to search
- Returns:
the Query instance
Note
This method is part of fluent api and can be chained
- select(*attributes)[source]
Adds the attribute to the $select parameter
- Parameters:
attributes (str) – the attributes tuple to select. If empty, the on_attribute previously set is added.
- Return type:
Note
This method is part of fluent api and can be chained
- startswith(word)[source]
Adds a startswith word check
- Parameters:
word (str) – word to check
- Return type:
Note
This method is part of fluent api and can be chained
- unequal(word)[source]
Add an unequals check
- Parameters:
word – word to compare with
- Return type:
Note
This method is part of fluent api and can be chained
- property has_expands
Whether the query has relationships that should be expanded or not
- Return type:
bool
- property has_filters
Whether the query has filters or not
- Return type:
bool
- property has_order
Whether the query has order_by or not
- Return type:
bool
- property has_selects
Whether the query has select filters or not
- Return type:
bool
- protocol
Protocol to use.
Type: protocol
- class O365.utils.utils.Recipient(address=None, name=None, parent=None, field=None)[source]
Bases:
object
A single Recipient
- __init__(address=None, name=None, parent=None, field=None)[source]
Create a recipient with provided information
- Parameters:
address (str) – email address of the recipient
name (str) – name of the recipient
parent (HandleRecipientsMixin) – parent recipients handler
field (str) – name of the field to update back
- property address
Email address of the recipient
- Getter:
Get the email address
- Setter:
Set and update the email address
- Type:
str
- property name
Name of the recipient
- Getter:
Get the name
- Setter:
Set and update the name
- Type:
str
- class O365.utils.utils.Recipients(recipients=None, parent=None, field=None)[source]
Bases:
object
A Sequence of Recipients
- __init__(recipients=None, parent=None, field=None)[source]
Recipients must be a list of either address strings or tuples (name, address) or dictionary elements
- Parameters:
recipients (list[str] or list[tuple] or list[dict] or list[Recipient]) – list of either address strings or tuples (name, address) or dictionary elements
parent (HandleRecipientsMixin) – parent recipients handler
field (str) – name of the field to update back
- add(recipients)[source]
Add the supplied recipients to the exiting list
- Parameters:
recipients (list[str] or list[tuple] or list[dict]) – list of either address strings or tuples (name, address) or dictionary elements