Pagination helper#

Although it is possible to fetch an entire result set using limit=0, that is not recommended as it would potentially lead very long response times and storing a lot of data in memory.

Most Argus API endpoints that return mutiple results support pagination through the limit and offset parameters and argus-api provides helper functions that makes using them more convenient:

Basic usage#

The pagination helper can be imported with:

from argus_api.pagination import offset_paginated

It is a function that takes an argus-api function as its only argument, and returns a decoration version of that function that handles pagination.

Let’s assume we want to fetch all open cases that are in the “pending Mnemonic” state. the following will fetch the first 25 results (limit defaults to 25):

from argus_api.lib.cases.v2.case import advanced_case_search

cases = advanced_case_search(status="pendingSoc")["data"]
print(cases)

In order to get all results, one could set limit=0 (NOT RECOMMENDED):

from argus_api.lib.cases.v2.case import advanced_case_search

cases = advanced_case_search(status="pendingSoc", limit=0)["data"]  # NOT RECOMMENDED
print(cases)

Instead, the pagination helper can and should be used :

from argus_api.pagination import offset_paginated
from argus_api.lib.cases.v2.case import advanced_case_search

for page in offset_paginated(advanced_case_search)(status="pendingSoc"):
    page_cases = page["data"]  # contains 25 results
    print(page_cases)

Setting the page size#

The size of pages is determined by the value of the argument parameter. Setting that argument on a function decorated with offset_paginated will therefore set the amount of results to fetch per page :

from argus_api.pagination import offset_paginated
from argus_api.lib.cases.v2.case import advanced_case_search

for page in offset_paginated(advanced_case_search)(status="pendingSoc", limit=100):
    page_cases = page["data"]  # contains 100 results
    print(page_cases)

Iterating over items#

func:~argus_api.pagination.offset_paginated provides an iterator over pages, but the most common use cases is to paginate over results within a page. The paginated_items() is provided for that purpose. It can be used instead of offset_paginated:

from argus_api.pagination import paginated_items
from argus_api.lib.cases.v2.case import advanced_case_search

for case in paginated_items(advanced_case_search)(status="pendingSoc"):
    print(case["subject"])

Which is exactly equivalent to:

from argus_api.pagination import offset_paginated
from argus_api.lib.cases.v2.case import advanced_case_search

for page in offset_paginated(advanced_case_search)(status="pendingSoc"):
    for case in page["data"]:
        print(case["subject"])