Jump to >

reviewboard.hostingsvcs.utils.paginator

Paginators for iterating over API results.

exception InvalidPageError[source]

Bases: exceptions.Exception

An error representing an invalid page access.

class BasePaginator(start=None, per_page=None, request_kwargs=None)[source]

Bases: object

Base class for a paginator used in the hosting services code.

This provides the basic state and stubbed functions for a simple paginator. Subclasses can build upon this to offer more advanced functionality.

page_data

The data for the current page. This is implementation-dependent, but will usually be a list.

Type:object
per_page

The number of items to fetch per page.

Type:int
request_kwargs

Keyword arguments to pass when making HTTP requests.

Type:dict
start

The starting page. Whether this is 0-based or 1-based depends on the hosting service.

Type:int
total_count

The total number of results across all pages. This will be None if the value isn’t known.

Type:int
__init__(start=None, per_page=None, request_kwargs=None)[source]

Initialize the paginator.

Parameters:
  • start (int, optional) – The starting page. Whether this is 0-based or 1-based depends on the hosting service.
  • per_page (int, optional) – The number of items per page.
  • request_kwargs (dict, optional) – Keyword arguments to pass when making a request.
has_prev[source]

Whether there’s a previous page available.

Subclasses must override this to provide a meaningful value.

has_next[source]

Whether there’s a next page available.

Subclasses must override this to provide a meaningful value.

prev()[source]

Fetch the previous page, returning the page data.

Subclasses must override this to provide the logic for fetching pages.

Returns:The resulting page data. This will usually be a list, but is implementation-dependent.
Return type:object
Raises:InvalidPageError – There was no previous page to fetch.
next()[source]

Fetch the next page, returning the page data.

Subclasses must override this to provide the logic for fetching pages.

Returns:The resulting page data. This will usually be a list, but is implementation-dependent.
Return type:object
Raises:InvalidPageError – There was no next page to fetch.
iter_items(max_pages=None)[source]

Iterate through all items across pages.

This will repeatedly fetch pages, iterating through all items and providing them to the caller.

The maximum number of pages can be capped, to limit the impact on the server.

Parameters:max_pages (int, optional) – The maximum number of pages to iterate through.
Yields:object – Each item from each page’s payload.
iter_pages(max_pages=None)[source]

Iterate through pages of results.

This will repeatedly fetch pages, providing each parsed page payload to the caller.

The maximum number of pages can be capped, to limit the impact on the server.

Parameters:max_pages (int, optional) – The maximum number of pages to iterate through.
Yields:object – The parsed payload for each page.
__iter__()[source]

Iterate through pages of results.

This is a simple wrapper for iter_pages().

Yields:object – The parsed payload for each page.
class APIPaginator(client, url, query_params={}, *args, **kwargs)[source]

Bases: reviewboard.hostingsvcs.utils.paginator.BasePaginator

Handles pagination for API requests to a hosting service.

Hosting services may provide subclasses of APIPaginator that can handle paginating their specific APIs. These make it easy to fetch pages of data from the API, and also works as a bridge for Review Board’s web API resources.

All APIPaginators are expected to take an instance of a HostingServiceClient subclass, and the starting URL (without any arguments for pagination).

Subclasses can access the HostingServiceClient through the client member of the paginator in order to perform requests against the hosting service.

client

The hosting service client used to make requests.

Type:reviewboard.hostingsvcs.service.HostingServiceClient
next_url

The URL for the next set of results in the page.

Type:unicode
page_headers

HTTP headers returned for the current page.

Type:dict
prev_url

The URL for the previous set of results in the page.

Type:unicode
url

The URL used to fetch the current page of data.

Type:unicode
start_query_param = None[source]

Query parameter name for the start page in a request.

This is optional. Clients can specify this to provide this as part of pagination queries.

per_page_query_param = None[source]

Query parameter name for the requested number of results per page.

This is optional. Clients can specify this to provide this as part of pagination queries.

__init__(client, url, query_params={}, *args, **kwargs)[source]

Initialize the paginator.

Once initialized, the first page will be fetched automatically.

Parameters:
has_prev[source]

Whether there’s a previous page available.

has_next[source]

Whether there’s a next page available.

prev()[source]

Fetch the previous page, returning the page data.

Returns:The resulting page data. This will usually be a list, but is implementation-dependent.
Return type:object
Raises:InvalidPageError – There was no previous page to fetch.
next()[source]

Fetch the next page, returning the page data.

Returns:The resulting page data. This will usually be a list, but is implementation-dependent.
Return type:object
Raises:InvalidPageError – There was no next page to fetch.
fetch_url(url)[source]

Fetch the URL, returning information on the page.

This must be implemented by subclasses. It must return a dictionary with the following fields:

data (object)
The data from the page (generally as a list).
headers (dict)
The headers from the page response.
total_count (int, optional)
The optional total number of items across all pages.
per_page (int, optional)
The optional limit on the number of items fetched on each page.
prev_url (unicode, optional)
The optional URL to the previous page.
next_url (unicode, optional)
The optional URL to the next page.
Parameters:url (unicode) – The URL to fetch.
Returns:The pagination information with the above fields.
Return type:dict
class ProxyPaginator(paginator, normalize_page_data_func=None)[source]

Bases: reviewboard.hostingsvcs.utils.paginator.BasePaginator

A paginator that proxies to another paginator, transforming data.

This attaches to another paginator, forwarding all requests and proxying all data.

ProxyPaginator can take the data returned from the other paginator and normalize it, transforming it into a new form.

This is useful when a HostingService wants to return a paginator to callers that represents data in a structured way, using an APIPaginator’s raw payloads as a backing.

paginator

The paginator that this is a proxy for.

Type:BasePaginator
normalize_page_data_func

A function used to normalize a page of results from the paginator.

Type:callable
__init__(paginator, normalize_page_data_func=None)[source]

Initialize the paginator.

Parameters:
  • paginator (BasePaginator) – The paginator that this is a proxy for.
  • normalize_page_data_func (callable, optional) – A function used to normalize a page of results from the paginator.
has_prev[source]

Whether there’s a previous page available.

has_next[source]

Whether there’s a next page available.

per_page[source]

The number of items requested per page.

total_count[source]

The number of items across all pages, if known.

prev()[source]

Fetch the previous page, returning the page data.

Returns:The resulting page data. This will usually be a list, but is implementation-dependent.
Return type:object
Raises:InvalidPageError – There was no previous page to fetch.
next()[source]

Fetch the next page, returning the page data.

Returns:The resulting page data. This will usually be a list, but is implementation-dependent.
Return type:object
Raises:InvalidPageError – There was no next page to fetch.
normalize_page_data(data)[source]

Normalize a page of data.

If normalize_page_data_func was passed on construction, this will call it, passing in the page data. That will then be returned.

This can be overridden by subclasses that want to do more complex processing without requiring normalize_page_data_func to be passed in.

Parameters:data (object) – The data to normalize.
Returns:The resulting data.
Return type:object