rsm – Result Set Management (XEP-0059)

This module provides the XSO model for other parts of aioxmpp and applications which wish to work with XEP-0059 (Result Set Management).

New in version 0.8.

XSO

class aioxmpp.rsm.xso.ResultSetMetadata

Represent the result set or query metadata.

For requests, the following attributes are relevant:

after

Either None or a After object.

Generally mutually exclusive with index.

before

Either None or a Before object.

Generally mutually exclusive with index.

index

The index of the first result to return, or None.

Generally mutually exclusive with after and before.

max

The maximum number of items to return or None.

Setting max to zero will make the peer return a ResultSetMetadata with the total number of items in the count field.

These methods are useful when constructing queries:

classmethod fetch_page(index, max_=None)

Return a query set which requests a specific page.

Parameters

• index (int) – Index of the first element of the page to fetch.

• max (int or None) – Maximum number of elements to fetch

Return type

ResultSetMetadata

Returns

A new request set up to request a page starting with the element indexed by index.

Note

This way of retrieving items may be approximate. See XEP-0059 and the embedding protocol for which RSM is used for specifics.

limit(max_)

Limit the result set to a given number of items.

Parameters

max (int or None) – Maximum number of items to return.

Return type

ResultSetMetadata

Returns

A new request set up to request at most max_ items.

This method can be called on the class and on objects. When called on objects, it returns a copy of the object with max_ set accordingly. When called on the class, it creates a fresh object with max_ set accordingly.

classmethod last_page(max_=None)

Return a query set which requests the last page.

Parameters

max (int or None) – Maximum number of items to return.

Return type

ResultSetMetadata

Returns

A new request set up to request the last page.

For responses, the following attributes are relevant:

first

Either None or a First object.

last

Either None or a Last object.

count

Either None or the number of elements in the result set.

If this is a response to a query with max set to zero, this is the total number of elements in the queried data.

These methods are useful to construct a new request from a previous response:

next_page(max_=None)

Return a query set which requests the page after this response.

Parameters

max (int or None) – Maximum number of items to return.

Return type

ResultSetMetadata

Returns

A new request set up to request the next page.

Must be called on a result set which has last set.

previous_page(max_=None)

Return a query set which requests the page before this response.

Parameters

max (int or None) – Maximum number of items to return.

Return type

ResultSetMetadata

Returns

A new request set up to request the previous page.

Must be called on a result set which has first set.

class aioxmpp.rsm.xso.After(*args, **kwargs)

value

Identifier of the element which serves as a range limit for the query.

class aioxmpp.rsm.xso.Before(*args, **kwargs)

value

Identifier of the element which serves as a range limit for the query.

class aioxmpp.rsm.xso.First(*args, **kwargs)

value

Identifier of the first element in the result set.

index

Approximate index of the first element in the result set.

Can be used with ResultSetMetadata.index and ResultSetMetadata.fetch_page() to approximately re-retrieve the page.

See also

fetch_page()

for hints on caveats and inaccuracies

class aioxmpp.rsm.xso.Last(*args, **kwargs)

value

Identifier of the last element in the result set.