Query

class O365.utils.query.ChainFilter(operation: str, filter_instances: list[QueryFilter])[source]

Bases: OperationQueryFilter

__init__(operation: str, filter_instances: list[QueryFilter])[source]
render(item_name: str | None = None) → str[source]
class O365.utils.query.CompositeFilter(*, filters: QueryFilter | None = None, search: SearchFilter | None = None, order_by: OrderByFilter | None = None, select: SelectFilter | None = None, expand: ExpandFilter | None = None)[source]

Bases: QueryBase

A Query object that holds all query parameters.

__init__(*, filters: QueryFilter | None = None, search: SearchFilter | None = None, order_by: OrderByFilter | None = None, select: SelectFilter | None = None, expand: ExpandFilter | None = None)[source]
as_params() → dict[source]
clear_filters() → None[source]

Removes all filters from the query

render() → str[source]
expand: ExpandFilter | None
filters: QueryFilter | None
property has_expands: bool

Returns if this CompositeFilter has expands

property has_filters: bool

Returns if this CompositeFilter has filters

property has_only_filters: bool

Returns true if it only has filters

property has_order_by: bool

Returns if this CompositeFilter has order_by

Returns if this CompositeFilter has search

property has_selects: bool

Returns if this CompositeFilter has selects

order_by: OrderByFilter | None
search: SearchFilter | None
select: SelectFilter | None
class O365.utils.query.ContainerQueryFilter(*args: str | tuple[str, SelectFilter])[source]

Bases: QueryBase

__init__(*args: str | tuple[str, SelectFilter])[source]
append(item: str | tuple[str, SelectFilter]) → None[source]
as_params() → dict[source]
render() → str[source]
class O365.utils.query.ExpandFilter(*args: str | tuple[str, SelectFilter])[source]

Bases: ContainerQueryFilter

__init__(*args: str | tuple[str, SelectFilter])[source]
render() → str[source]
class O365.utils.query.FunctionFilter(operation: str, attribute: str, word: str)[source]

Bases: LogicalFilter

render(item_name: str | None = None) → str[source]
class O365.utils.query.GroupFilter(filter_instance: QueryFilter)[source]

Bases: ModifierQueryFilter

render(item_name: str | None = None) → str[source]
class O365.utils.query.IterableFilter(operation: str, collection: str, filter_instance: QueryFilter, *, item_name: str = 'a')[source]

Bases: OperationQueryFilter

__init__(operation: str, collection: str, filter_instance: QueryFilter, *, item_name: str = 'a')[source]
render(item_name: str | None = None) → str[source]
class O365.utils.query.LogicalFilter(operation: str, attribute: str, word: str)[source]

Bases: OperationQueryFilter

__init__(operation: str, attribute: str, word: str)[source]
render(item_name: str | None = None) → str[source]
class O365.utils.query.ModifierQueryFilter(filter_instance: QueryFilter)[source]

Bases: QueryFilter, ABC

__init__(filter_instance: QueryFilter)[source]
class O365.utils.query.NegateFilter(filter_instance: QueryFilter)[source]

Bases: ModifierQueryFilter

render(item_name: str | None = None) → str[source]
class O365.utils.query.OperationQueryFilter(operation: str)[source]

Bases: QueryFilter, ABC

__init__(operation: str)[source]
class O365.utils.query.OrderByFilter[source]

Bases: QueryBase

__init__()[source]
add(attribute: str, ascending: bool = True) → None[source]
as_params() → dict[source]
render() → str[source]
class O365.utils.query.QueryBase[source]

Bases: ABC

abstractmethod as_params() → dict[source]
get_filter_by_attribute(attribute: str) → str | None[source]

Returns a filter value by attribute name. It will match the attribute to the start of each filter attribute and return the first found.

Parameters:

attribute – the attribute you want to search

Returns:

The value applied to that attribute or None

abstractmethod render() → str[source]
class O365.utils.query.QueryBuilder(protocol: Protocol | Type[Protocol])[source]

Bases: object

static group(filter_instance: CompositeFilter) → CompositeFilter[source]

Applies a grouping to the provided filter_instance

static negate(filter_instance: CompositeFilter) → CompositeFilter[source]

Apply a not operator to the provided QueryFilter :param filter_instance: a CompositeFilter instance :return: a CompositeFilter with its filter negated

static orderby(*attributes: tuple[str | tuple[str, bool]]) → CompositeFilter[source]

Returns an ‘order by’ query param This is useful to order the result set of query from a resource. Note that not all attributes can be sorted and that all resources have different sort capabilities

Parameters:

attributes – the attributes to orderby

Returns:

a CompositeFilter instance that can render the OData order by operation

__init__(protocol: Protocol | Type[Protocol])[source]

Build a query to apply OData filters https://docs.microsoft.com/en-us/graph/query-parameters

Parameters:

protocol (Protocol) – protocol to retrieve the timezone from

all(collection: str, filter_instance: CompositeFilter, *, item_name: str = 'a') → CompositeFilter[source]

Performs a filter with the OData ‘all’ keyword on the collection

For example: q.all(collection=’email_addresses’, filter_instance=q.equals(‘address’, ‘george@best.com’))

will transform to a filter such as:

emailAddresses/all(a:a/address eq ‘george@best.com’)

Parameters:

  • collection – the collection to apply the iterable operation on

  • filter_instance – a CompositeFilter Instance on which you will apply the iterable operation

  • item_name – the name of the collection item to be used on the filter_instance

Returns:

a CompositeFilter instance that can render the OData iterable operation

any(collection: str, filter_instance: CompositeFilter, *, item_name: str = 'a') → CompositeFilter[source]

Performs a filter with the OData ‘any’ keyword on the collection

For example: q.any(collection=’email_addresses’, filter_instance=q.equals(‘address’, ‘george@best.com’))

will transform to a filter such as:

emailAddresses/any(a:a/address eq ‘george@best.com’)

Parameters:

  • collection – the collection to apply the iterable operation on

  • filter_instance – a CompositeFilter Instance on which you will apply the iterable operation

  • item_name – the name of the collection item to be used on the filter_instance

Returns:

a CompositeFilter instance that can render the OData iterable operation

chain_and(*filter_instances: CompositeFilter, group: bool = False) → CompositeFilter[source]

Start a chain ‘and’ operation

Parameters:

  • filter_instances – a list of other CompositeFilter you want to combine with the ‘and’ operation

  • group – will group this chain operation if True

Returns:

a CompositeFilter with the filter instances combined with an ‘and’ operation

chain_or(*filter_instances: CompositeFilter, group: bool = False) → CompositeFilter[source]

Start a chain ‘or’ operation. Will automatically apply a grouping.

Parameters:

  • filter_instances – a list of other CompositeFilter you want to combine with the ‘or’ operation

  • group – will group this chain operation if True

Returns:

a CompositeFilter with the filter instances combined with an ‘or’ operation

contains(attribute: str, word: str | bool | None | date | int | float) → CompositeFilter[source]

Adds a contains word check

Parameters:

  • attribute – the name of the attribute on which to apply the function

  • word – value to feed the function

Returns:

a CompositeFilter instance that can render the OData function operation

endswith(attribute: str, word: str | bool | None | date | int | float) → CompositeFilter[source]

Adds a endswith word check

Parameters:

  • attribute – the name of the attribute on which to apply the function

  • word – value to feed the function

Returns:

a CompositeFilter instance that can render the OData function operation

equals(attribute: str, word: str | bool | None | date | int | float) → CompositeFilter[source]

Return an equals check

Parameters:

  • attribute – attribute to compare word with

  • word – word to compare with

Returns:

a CompositeFilter instance that can render the OData this logical operation

expand(relationship: str, select: CompositeFilter | None = None) → CompositeFilter[source]

Returns an ‘expand’ query param Important: If the ‘expand’ is a relationship (e.g. “event” or “attachments”), then the ApiComponent using this query should know how to handle the relationship (e.g. 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:

  • relationship – a relationship that will be expanded

  • select – a CompositeFilter instance to select attributes on the expanded relationship

Returns:

a CompositeFilter instance that can render the OData expand operation

function_operation(operation: str, attribute: str, word: str | bool | None | date | int | float) → CompositeFilter[source]

Apply a function operation

Parameters:

  • operation – function name to operate on attribute

  • attribute – the name of the attribute on which to apply the function

  • word – value to feed the function

Returns:

a CompositeFilter instance that can render the OData function operation

greater(attribute: str, word: str | bool | None | date | int | float) → CompositeFilter[source]

Return a ‘greater than’ check

Parameters:

  • attribute – attribute to compare word with

  • word – word to compare with

Returns:

a CompositeFilter instance that can render the OData this logical operation

greater_equal(attribute: str, word: str | bool | None | date | int | float) → CompositeFilter[source]

Return a ‘greater than or equal to’ check

Parameters:

  • attribute – attribute to compare word with

  • word – word to compare with

Returns:

a CompositeFilter instance that can render the OData this logical operation

iterable_operation(operation: str, collection: str, filter_instance: CompositeFilter, *, item_name: str = 'a') → CompositeFilter[source]

Performs the provided filter operation on a collection by iterating over it.

For example:

q.iterable(
    operation='any',
    collection='email_addresses',
    filter_instance=q.equals('address', 'george@best.com')
)

will transform to a filter such as: emailAddresses/any(a:a/address eq ‘george@best.com’)

Parameters:

  • operation – the iterable operation name

  • collection – the collection to apply the iterable operation on

  • filter_instance – a CompositeFilter instance on which you will apply the iterable operation

  • item_name – the name of the collection item to be used on the filter_instance

Returns:

a CompositeFilter instance that can render the OData iterable operation

less(attribute: str, word: str | bool | None | date | int | float) → CompositeFilter[source]

Return a ‘less than’ check

Parameters:

  • attribute – attribute to compare word with

  • word – word to compare with

Returns:

a CompositeFilter instance that can render the OData this logical operation

less_equal(attribute: str, word: str | bool | None | date | int | float) → CompositeFilter[source]

Return a ‘less than or equal to’ check

Parameters:

  • attribute – attribute to compare word with

  • word – word to compare with

Returns:

a CompositeFilter instance that can render the OData this logical operation

logical_operation(operation: str, attribute: str, word: str | bool | None | date | int | float) → CompositeFilter[source]

Apply a logical operation like equals, less than, etc.

Parameters:

  • operation – how to combine with a new one

  • attribute – attribute to compare word with

  • word – value to compare the attribute with

Returns:

a CompositeFilter instance that can render the OData logical operation

search(word: str | int | bool, attribute: str | None = None) → CompositeFilter[source]

Perform a search. Note 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:

  • word – the text to search

  • attribute – the attribute to search the word on

Returns:

a CompositeFilter instance that can render the OData search operation

select(*attributes: str) → CompositeFilter[source]

Returns a ‘select’ query param This is useful to return a limited set of attributes from a resource or return attributes that are not returned by default by the resource.

Parameters:

attributes – a tuple of attribute names to select

Returns:

a CompositeFilter instance that can render the OData select operation

startswith(attribute: str, word: str | bool | None | date | int | float) → CompositeFilter[source]

Adds a startswith word check

Parameters:

  • attribute – the name of the attribute on which to apply the function

  • word – value to feed the function

Returns:

a CompositeFilter instance that can render the OData function operation

unequal(attribute: str, word: str | bool | None | date | int | float) → CompositeFilter[source]

Return an unequal check

Parameters:

  • attribute – attribute to compare word with

  • word – word to compare with

Returns:

a CompositeFilter instance that can render the OData this logical operation

class O365.utils.query.QueryFilter[source]

Bases: QueryBase, ABC

as_params() → dict[source]
abstractmethod render(item_name: str | None = None) → str[source]
class O365.utils.query.SearchFilter(word: str | int | bool | None = None, attribute: str | None = None)[source]

Bases: QueryBase

__init__(word: str | int | bool | None = None, attribute: str | None = None)[source]
as_params() → dict[source]
render() → str[source]
class O365.utils.query.SelectFilter(*args: str)[source]

Bases: ContainerQueryFilter

__init__(*args: str)[source]