============================
 Collections and Pagination
============================

All collections automatically support pagination.  You can use this to limit
the number of items of the collection that get returned, and you can page
through the results by incrementing the page counter.

For example, let's say we have 50 mailing lists.

    >>> from mailman.app.lifecycle import create_list
    >>> for i in range(50):
    ...     mlist = create_list('list{:02d}@example.com'.format(i))
    >>> transaction.commit()

We can get the first 10 lists by asking for the first page of items.

    >>> json = call_http('http://localhost:9001/3.0/lists?count=10&page=1')
    >>> for entry in json['entries']:
    ...     print(entry['list_id'])
    list00.example.com
    list01.example.com
    list02.example.com
    list03.example.com
    list04.example.com
    list05.example.com
    list06.example.com
    list07.example.com
    list08.example.com
    list09.example.com

We can also ask for the third set of 10 mailing lists.

    >>> json = call_http('http://localhost:9001/3.0/lists?count=10&page=3')
    >>> for entry in json['entries']:
    ...     print(entry['list_id'])
    list20.example.com
    list21.example.com
    list22.example.com
    list23.example.com
    list24.example.com
    list25.example.com
    list26.example.com
    list27.example.com
    list28.example.com
    list29.example.com

Of course, we can also adjust the page size and ask for the tenth page of 5
mailing lists.

    >>> json = call_http('http://localhost:9001/3.0/lists?count=5&page=10')
    >>> for entry in json['entries']:
    ...     print(entry['list_id'])
    list45.example.com
    list46.example.com
    list47.example.com
    list48.example.com
    list49.example.com


The size of a collection
========================

This same idiom allows you to get just the size of the collection.  You do
this by asking for a page of size zero.

    >>> dump_json('http://localhost:9001/3.0/lists?count=0&page=1')
    http_etag: ...
    start: 0
    total_size: 50


Page start
==========

Notice the `start` element in the returned JSON.  This tells you which item of
the collection the page starts on.

    >>> dump_json('http://localhost:9001/3.0/lists?count=2&page=15')
    entry 0:
        display_name: List28
        ...
    entry 1:
        display_name: List29
        ...
    http_etag: ...
    start: 28
    total_size: 50