# `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.