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:

Parameters:	client (reviewboard.hostingsvcs.service.HostingServiceClient) – The hosting service client used to make requests. url (unicode) – The URL used to make requests. query_params (dict) – The query parameters to append to the URL for requests. This will be updated with `start_query_param` and `per_page_query_param`, if set. args (tuple) – Positional arguments for the parent constructor. kwargs (dict*) – Keyword arguments for the parent constructor.

client (reviewboard.hostingsvcs.service.HostingServiceClient) – The hosting service client used to make requests.
url (unicode) – The URL used to make requests.
query_params (dict) – The query parameters to append to the URL for requests. This will be updated with start_query_param and per_page_query_param, if set.
*args (tuple) – Positional arguments for the parent constructor.
**kwargs (dict) – Keyword arguments for the parent constructor.

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