reviewboard.hostingsvcs.base.paginator¶

Paginators for iterating over API results.

class APIPaginatorPageData[source]¶

Bases: TypedDict

Data that can be returned from an APIPaginator.

New in version 6.0.

data: NotRequired[Any]¶

The data from the page (generally as a list).

Type:

object

headers: NotRequired[HTTPHeaders]¶

The HTTP headers from the page response.

Type:

dict

next_url: NotRequired[Optional[str]]¶

The optional URL to the next page.

Type:

str

per_page: NotRequired[Optional[int]]¶

The optional limit on the number of items fetched on each page.

Type:

int

prev_url: NotRequired[Optional[str]]¶

The optional URL to the previous page.

Type:

str

response: NotRequired[object]¶

The API response data.

Type:

object

total_count: NotRequired[Optional[int]]¶

The optional total number of items across all pages.

Type:

int

__annotations__ = {'data': ForwardRef('NotRequired[Any]', module='reviewboard.hostingsvcs.base.paginator'), 'headers': ForwardRef('NotRequired[HTTPHeaders]', module='reviewboard.hostingsvcs.base.paginator'), 'next_url': ForwardRef('NotRequired[Optional[str]]', module='reviewboard.hostingsvcs.base.paginator'), 'per_page': ForwardRef('NotRequired[Optional[int]]', module='reviewboard.hostingsvcs.base.paginator'), 'prev_url': ForwardRef('NotRequired[Optional[str]]', module='reviewboard.hostingsvcs.base.paginator'), 'response': ForwardRef('NotRequired[object]', module='reviewboard.hostingsvcs.base.paginator'), 'total_count': ForwardRef('NotRequired[Optional[int]]', module='reviewboard.hostingsvcs.base.paginator')}¶

__closed__ = False¶

__extra_items__ = None¶

__mutable_keys__ = frozenset({'data', 'headers', 'next_url', 'per_page', 'prev_url', 'response', 'total_count'})¶

__optional_keys__ = frozenset({})¶

__orig_bases__ = (<function TypedDict>,)¶

__readonly_keys__ = frozenset({})¶

__required_keys__ = frozenset({'data', 'headers', 'next_url', 'per_page', 'prev_url', 'response', 'total_count'})¶

__total__ = True¶

exception InvalidPageError[source]¶

Bases: Exception

An error representing an invalid page access.

Changed in version 6.0:

• Moved from reviewboard.hostingsvcs.utils.paginator to reviewboard.hostingsvcs.base.paginator.

class BasePaginator(start: Optional[int] = None, per_page: Optional[int] = None, request_kwargs: Optional[KwargsDict] = None)[source]¶

Bases: Generic[_PageDataItemT, _PageDataT]

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.

Changed in version 6.0:

• Moved from reviewboard.hostingsvcs.utils.paginator to reviewboard.hostingsvcs.base.paginator.

• This is now a generic, supporting typing for page data and items.

__init__(start: Optional[int] = None, per_page: Optional[int] = None, request_kwargs: Optional[KwargsDict] = None) → 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.

start: Optional[int]¶

The starting page.

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

Type:

int

per_page: Optional[int]¶

The number of items to fetch per page.

Type:

int

page_data: Optional[_PageDataT]¶

The data for the current page.

This is implementation-dependent, but will usually be a list. It must operate as a sequence of some kind.

Type:

object

total_count: Optional[int]¶

The total number of results across all pages.

This will be None if the value isn’t known.

Type:

int

request_kwargs: KwargsDict¶

Keyword arguments to pass when making HTTP requests.

Type:

dict

property has_prev: bool[source]¶

Whether there’s a previous page available.

Subclasses must override this to provide a meaningful value.

Type:

bool

property has_next: bool[source]¶

Whether there’s a next page available.

Subclasses must override this to provide a meaningful value.

Type:

bool

prev() → Optional[_PageDataT][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() → Optional[_PageDataT][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: Optional[int] = None) → Iterator[_PageDataItemT][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: Optional[int] = None) → Iterator[Optional[_PageDataT]][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__() → Iterator[Optional[_PageDataT]][source]¶

Iterate through pages of results.

This is a simple wrapper for iter_pages().

Yields:

object – The parsed payload for each page.

__annotations__ = {'page_data': 'Optional[_PageDataT]', 'per_page': 'Optional[int]', 'request_kwargs': 'KwargsDict', 'start': 'Optional[int]', 'total_count': 'Optional[int]'}¶

__orig_bases__ = (typing.Generic[~_PageDataItemT, ~_PageDataT],)¶

__parameters__ = (~_PageDataItemT, ~_PageDataT)¶

class APIPaginator(client: HostingServiceClient, url: str, query_params: QueryArgs = {}, *args, **kwargs)[source]¶

Bases: BasePaginator[_PageDataItemT, _PageDataT]

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.

Changed in version 6.0:

• Moved from reviewboard.hostingsvcs.utils.paginator to reviewboard.hostingsvcs.base.paginator.

• This is now a generic, supporting typing for page data and items.

start_query_param: Optional[str] = None¶

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.

Type:

str

per_page_query_param: Optional[str] = None¶

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.

Type:

str

__init__(client: HostingServiceClient, url: str, query_params: QueryArgs = {}, *args, **kwargs) → None[source]¶

Initialize the paginator.

Once initialized, the first page will be fetched automatically.

Parameters:

• client (reviewboard.hostingsvcs.base.client.HostingServiceClient) – The hosting service client used to make requests.

• url (str) – 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: HostingServiceClient¶

The hosting service client used to make requests.

Type:

reviewboard.hostingsvcs.base.client.HostingServiceClient

url: Optional[str]¶

The URL used to fetch the current page of data.

Type:

str

prev_url: Optional[str]¶

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

Type:

str

next_url: Optional[str]¶

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

Type:

str

page_headers: Optional[HTTPHeaders]¶

HTTP headers returned for the current page.

Type:

dict

property has_prev: bool[source]¶

Whether there’s a previous page available.

Type:

bool

property has_next: bool[source]¶

Whether there’s a next page available.

Type:

bool

prev() → Optional[_PageDataT][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() → Optional[_PageDataT][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: str) → APIPaginatorPageData[source]¶

Fetch the URL, returning information on the page.

This must be implemented by subclasses.

Parameters:

url (str) – The URL to fetch.

Returns:

The pagination information with the above fields.

See APIPaginatorPageData for the supported fields.

Return type:

dict

__annotations__ = {'client': 'HostingServiceClient', 'next_url': 'Optional[str]', 'page_data': 'Optional[_PageDataT]', 'page_headers': 'Optional[HTTPHeaders]', 'per_page': 'Optional[int]', 'per_page_query_param': 'Optional[str]', 'prev_url': 'Optional[str]', 'request_kwargs': 'KwargsDict', 'start': 'Optional[int]', 'start_query_param': 'Optional[str]', 'total_count': 'Optional[int]', 'url': 'Optional[str]'}¶

__orig_bases__ = (reviewboard.hostingsvcs.base.paginator.BasePaginator[~_PageDataItemT, ~_PageDataT],)¶

__parameters__ = (~_PageDataItemT, ~_PageDataT)¶

class ProxyPaginator(paginator: BasePaginator[Any, Any], normalize_page_data_func: Optional[Callable[[Optional[Any]], Optional[_PageDataT]]] = None)[source]¶

Bases: BasePaginator[_PageDataItemT, _PageDataT]

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 BaseHostingService wants to return a paginator to callers that represents data in a structured way, using an APIPaginator’s raw payloads as a backing.

Changed in version 6.0:

• Moved from reviewboard.hostingsvcs.utils.paginator to reviewboard.hostingsvcs.base.paginator.

• This is now a generic, supporting typing for page data and items.

__annotations__ = {'normalize_page_data_func': 'Optional[_ProxyNormalizePageDataFunc]', 'paginator': 'BasePaginator[Any, Any]'}¶

__init__(paginator: BasePaginator[Any, Any], normalize_page_data_func: Optional[Callable[[Optional[Any]], Optional[_PageDataT]]] = None) → 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.

__orig_bases__ = (reviewboard.hostingsvcs.base.paginator.BasePaginator[~_PageDataItemT, ~_PageDataT],)¶

__parameters__ = (~_PageDataItemT, ~_PageDataT)¶

paginator: BasePaginator[Any, Any]¶

The paginator that this is a proxy for.

Type:

BasePaginator

normalize_page_data_func: Optional[_ProxyNormalizePageDataFunc]¶

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

Type:

callable

property has_prev: bool[source]¶

Whether there’s a previous page available.

Type:

bool

property has_next: bool[source]¶

Whether there’s a next page available.

Type:

bool

property per_page: Optional[int][source]¶

The number of items requested per page.

Type:

int

property total_count: Optional[int][source]¶

The number of items across all pages, if known.

Type:

int

prev() → Optional[_PageDataT][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() → Optional[_PageDataT][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: Optional[Any]) → Optional[_PageDataT][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