Utils

class O365.utils.utils.ApiComponent(*, protocol=None, main_resource=None, **kwargs)

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)

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)

Builds the base url of this ApiComponent :param str resource: the resource to build the base url

build_url(endpoint)

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)

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)

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)

Bases: Enum

A Enum that converts the value to a snake_case casing

classmethod from_value(value)

Gets a member by a snaked-case provided value

class O365.utils.utils.ChainOperator(*values)

Bases: Enum

AND = 'and'

OR = 'or'

class O365.utils.utils.HandleRecipientsMixin

Bases: object

class O365.utils.utils.ImportanceLevel(*values)

Bases: CaseEnum

High = 'high'

Low = 'low'

Normal = 'normal'

class O365.utils.utils.OneDriveWellKnowFolderNames(*values)

Bases: Enum

APP_ROOT = 'approot'

ATTACHMENTS = 'attachments'

CAMERA_ROLL = 'cameraroll'

DOCUMENTS = 'documents'

MUSIC = 'music'

PHOTOS = 'photos'

class O365.utils.utils.OutlookWellKnowFolderNames(*values)

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)

Bases: ApiComponent

Utility class that allows batching requests to the server

__init__(*, parent=None, data=None, constructor=None, next_link=None, limit=None, **kwargs)

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)

Bases: object

Helper to conform OData filters

__init__(attribute=None, *, protocol)

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)

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 function or operation inside the iterable

Return type:

Query

Note

This method is part of fluent api and can be chained

any(*, collection, word, attribute=None, func=None, operation=None, negation=False)

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 function or operation inside the iterable

Return type:

Query

Note

This method is part of fluent api and can be chained

as_params()

Returns the filters, orders, select, expands and search as query parameters

Return type:

dict

chain(operation=ChainOperator.AND)

Start a chain operation

Parameters:

operation (ChainOperator, str) – how to combine with a new one

Return type:

Query

Note

This method is part of fluent api and can be chained

clear()

Clear everything

Return type:

Query

Note

This method is part of fluent api and can be chained

clear_filters()

Clear filters

clear_order()

Clears any order commands

close_group()

Closes a grouping for previous filters

contains(word)

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)

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)

Add an 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)

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:

Query

Note

This method is part of fluent api and can be chained

function(function_name, word)

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

Returns the result expand clause

Return type:

str or None

get_filter_by_attribute(attribute)

Returns a filter word applied to an attribute

get_filters()

Returns the result filters

Return type:

str or None

get_order()

Returns the result order by clauses

Return type:

str or None

get_selects()

Returns the result select clause

Return type:

str or None

greater(word)

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)

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

iterable(iterable_name, *, collection, word, attribute=None, func=None, operation=None, negation=False)

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 function or operation inside the iterable

Return type:

Query

Note

This method is part of fluent api and can be chained

less(word)

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)

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)

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

Apply a not operator

Return type:

Query

Note

This method is part of fluent api and can be chained

new(attribute, operation=ChainOperator.AND)

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)

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)

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

Applies a precedence grouping in the next filters

order_by(attribute=None, *, ascending=True)

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)

Removes a filter given the attribute name

search(text)

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)

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)

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)

Add an unequals 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

protocol

Protocol to use.

   Type: protocol

class O365.utils.utils.Recipient(address=None, name=None, parent=None, field=None)

Bases: object

A single Recipient

__init__(address=None, name=None, parent=None, field=None)

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)

Bases: object

A Sequence of Recipients

__init__(recipients=None, parent=None, field=None)

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)

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

Clear the list of recipients

get_first_recipient_with_address()

Returns the first recipient found with a non blank address

Returns:

First Recipient

Return type:

Recipient

remove(address)

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)

Bases: set

__init__(*args, casing=None, **kwargs)

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

Parameters:

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

add(value)

Add an element to a set.

This has no effect if the element is already present.

remove(value)

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

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