Utility: Pagination, Blurhash, Other Utilities

Pagination

These functions allow for convenient retrieval of paginated data.

Mastodon.fetch_next(previous_page: PaginatableList[_T] | _T | PaginationInfo) → PaginatableList[_T] | _T | None

Fetches the next page of results of a paginated request. Pass in the previous page in its entirety, or the pagination information dict returned as a part of that pages last status (‘_pagination_next’).

Returns the next page or None if no further data is available.

Mastodon.fetch_previous(next_page: PaginatableList[_T] | _T | PaginationInfo) → PaginatableList[_T] | _T | None

Fetches the previous page of results of a paginated request. Pass in the previous page in its entirety, or the pagination information dict returned as a part of that pages first status (‘_pagination_prev’).

Returns the previous page or None if no further data is available.

Mastodon.fetch_remaining(first_page: PaginatableList[_T]) → PaginatableList[_T]

Fetches all the remaining pages of a paginated request starting from a first page and returns the entire set of results (including the first page that was passed in) as a big list.

Be careful, as this might generate a lot of requests, depending on what you are fetching, and might cause you to run into rate limits very quickly.

Does not work with grouped notifications, since they use a somewhat weird, inside-out pagination scheme. If you need to access these in a paginated way, use fetch_next and fetch_previous directly.

Mastodon.pagination_iterator(start_page: PaginatableList[_T] | PaginationInfo, direction: str = 'next', return_pagination_info: bool = False) → Iterator[_T]

Returns an iterator that will yield all entries in a paginated request, starting from the given start_page (can also be just the PaginationInfo, in which case the first returned thing will be the result of fetch_next or fetch_previous, depending on the direction). and fetching new pages as needed, and breaks when no more pages are available.

Set direction to “next” to iterate forward, or “previous” to iterate backwards.

If return_pagination_info is True, the iterator will instead yield tuples of (Entity, PaginationInfo), where PaginationInfo is a dictionary containing pagination information for the current page and direction.

Does not work with grouped notifications, since they use a somewhat weird, inside-out pagination scheme. If you need to access these in a paginated way, use fetch_next and fetch_previous directly.

Mastodon.get_pagination_info(page: PaginatableList[Entity], pagination_direction: str) → PaginationInfo | None

Extracts pagination information from a paginated response.

Returns a PaginationInfo dictionary containing pagination information, or None if not available.

The resulting PaginationInfo is best treated as opaque, though is unlikely to change.

Blurhash decoding

This function allows for easy basic decoding of blurhash strings to images. This requires Mastodon.pys optional “blurhash” feature dependencies.

Mastodon.decode_blurhash(media_dict: MediaAttachment, out_size: Tuple[int, int] = (16, 16), size_per_component: bool = True, return_linear: bool = True) → List[List[List[float]]]

Basic media-dict blurhash decoding.

out_size is the desired result size in pixels, either absolute or per blurhash component (this is the default).

By default, this function will return the image as linear RGB, ready for further scaling operations. If you want to display the image directly, set return_linear to False.

Returns the decoded blurhash image as a three-dimensional list: [height][width][3], with the last dimension being RGB colours.

For further info and tips for advanced usage, refer to the documentation for the blurhash module: https://github.com/halcy/blurhash-python

Cache control

Mastodon.clear_caches()

Clear cached data for astodon version and streaming base URL. Most programs should not have to call this.

Other utilities

Mastodon.get_approx_server_time() → <module 'datetime' from '/home/docs/.asdf/installs/python/3.12.10/lib/python3.12/datetime.py'>

Retrieve the approximate server time

We parse this from the hopefully present “Date” header, but make no effort to compensate for latency.

static Mastodon.get_status_length(text: str, spoiler_text: str = '') → int

For a given status text and spoiler_text, return how many characters this status counts as when computing the status length and comparing it against the limit.

Note that there are other limits you may run into, such as the maximum length of a URL, or the maximum length of a usernames domain part. But as long as you do normal things, this function will return the correct length for the status text.