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: Query

q(attribute=None)¶

Create a new query to filter results

Parameters: attribute (str) – attribute to apply the query for
Returns: new Query
Return type: Query

set_base_url(resource)[source]¶: Sets the base urls for this ApiComponent :param str resource: the resource to build the base url

class O365.utils.utils.CaseEnum(value)[source]¶

Bases: enum.Enum

A Enum that converts the value to a snake_case casing

classmethod from_value(value)[source]¶: Gets a member by a snaked-case provided value

class O365.utils.utils.ChainOperator(value)[source]¶

Bases: enum.Enum

An enumeration.

AND = 'and'¶

OR = 'or'¶

class O365.utils.utils.HandleRecipientsMixin[source]¶: Bases: object

class O365.utils.utils.ImportanceLevel(value)[source]¶

Bases: O365.utils.utils.CaseEnum

An enumeration.

High = 'high'¶

Low = 'low'¶

Normal = 'normal'¶

class O365.utils.utils.OneDriveWellKnowFolderNames(value)[source]¶

Bases: enum.Enum

An enumeration.

APP_ROOT = 'approot'¶

ATTACHMENTS = 'attachments'¶

CAMERA_ROLL = 'cameraroll'¶

DOCUMENTS = 'documents'¶

MUSIC = 'music'¶

PHOTOS = 'photos'¶

class O365.utils.utils.OutlookWellKnowFolderNames(value)[source]¶

Bases: enum.Enum

An enumeration.

ARCHIVE = 'Archive'¶

DELETED = 'DeletedItems'¶

DRAFTS = 'Drafts'¶

INBOX = 'Inbox'¶

JUNK = 'JunkEmail'¶

OUTBOX = 'Outbox'¶

SENT = 'SentItems'¶

class O365.utils.utils.Pagination(*, parent=None, data=None, constructor=None, next_link=None, limit=None, **kwargs)[source]¶

Bases: O365.utils.utils.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 construtctor.

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)[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

Return type

Query

Note

This method is part of fluent api and can be chained

any(*, collection, word, attribute=None, func=None, operation=None)[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

Return type

Query

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: 'and'>)[source]¶

Start a chain operation

Parameters: str operation (ChainOperator,) – how to combine with a new one
Return type: Query

Note

This method is part of fluent api and can be chained

clear()[source]¶

Clear everything

Return type: Query

Note

This method is part of fluent api and can be chained

clear_filters()[source]¶: Clear filters

clear_order()[source]¶: Clears any order commands

close_group()[source]¶: Closes a grouping for previous filters

contains(word)[source]¶

Adds a contains word check

Parameters: word (str) – word to check
Return type: Query

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: Query

Note

This method is part of fluent api and can be chained

equals(word)[source]¶

Add a equals check

Parameters: word – word to compare with
Return type: Query

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. :param str relationships: the relationships tuple to expand. :rtype: Query

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

Query

Note

This method is part of fluent api and can be chained

get_expands()[source]¶

Returns the result expand clause

Return type: str or None

get_filters()[source]¶

Returns the result filters

Return type: str or None

get_order()[source]¶

Returns the result order by clauses

Return type: str or None

get_selects()[source]¶

Returns the result select clause

Return type: str or None

greater(word)[source]¶

Add a greater than check

Parameters: word – word to compare with
Return type: Query

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: Query

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

iterable(iterable_name, *, collection, word, attribute=None, func=None, operation=None)[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

Return type

Query

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: Query

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: Query

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

Query

Note

This method is part of fluent api and can be chained

negate()[source]¶

Apply a not operator

Return type: Query

Note

This method is part of fluent api and can be chained

new(attribute, operation=<ChainOperator.AND: 'and'>)[source]¶

Combine with a new query

Parameters

attribute (str) – attribute of new query
operation (ChainOperator) – operation to combine to new query

Return type

Query

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: Query

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: Query

Note

This method is part of fluent api and can be chained

open_group()[source]¶: Applies a precedence grouping in the next filters

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

Query

Note

This method is part of fluent api and can be chained

remove_filter(filter_attr)[source]¶: Removes a filter given the attribute name

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: Query

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: Query

Note

This method is part of fluent api and can be chained

unequal(word)[source]¶

Add a unequals check

Parameters: word – word to compare with
Return type: Query

Note

This method is part of fluent api and can be chained

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

clear()[source]¶: Clear the list of recipients

get_first_recipient_with_address()[source]¶

Returns the first recipient found with a non blank address

Returns: First Recipient
Return type: Recipient

remove(address)[source]¶

Remove an address or multiple addresses

Parameters: address (str or list[str]) – list of addresses to remove

class O365.utils.utils.TrackerSet(*args, casing=None, **kwargs)[source]¶

Bases: set

__init__(*args, casing=None, **kwargs)[source]¶

A Custom Set that changes the casing of it’s keys

Parameters: casing (func) – a function to convert into specified case

add(value)[source]¶

Add an element to a set.

This has no effect if the element is already present.

remove(value)[source]¶

Remove an element from a set; it must be a member.

If the element is not a member, raise a KeyError.