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.

Async refreshes

Some API responses may include an Mastodon-Async-Refresh header, indicating that the server is still fetching additional data in the background. These functions allow you to check the status of such a refresh, wait for it to complete, or extract the async refresh information from an API result.

Note that this functionality is considered experimental by the Mastodon project and may be subject to changes in the future.

Mastodon.get_async_refresh_info(result) → Tuple[AsyncRefresh, int] | None

Extract async refresh information from an API result, if present.

Returns a tuple of (AsyncRefresh, retry_seconds) where the entity contains the id, status (always "running"), and optionally result_count, and retry_seconds is the server-suggested polling interval in seconds.

Returns None if the result has no async refresh information.

Mastodon.get_async_refresh_status(result_or_id: str | int | MaybeSnowflakeIdType | datetime | AsyncRefresh | AttribAccessDict) → AsyncRefresh

Get the status of an async refresh by its ID. The ID can be obtained from a previous API response that included the Mastodon-Async-Refresh header, accessible via get_async_refresh_info().

You can pass in an async refresh ID, an AsyncRefresh entity (e.g. from a previous call to this function or from get_async_refresh_info()), or an API result that has async refresh information (i.e. a previous API result that had the header set).

Returns an AsyncRefresh dict.

Added: Mastodon v4.4.0, last changed: Mastodon v4.4.0 (parameters), Mastodon v4.4.0 (return value)

Mastodon.await_async_refresh(result, timeout: float = 0.0, max_attempts: int = -1) → AttribAccessDict | None

Wait for an async refresh to finish, then re-fetch and return the original resource.

Polls the async refresh endpoint with backoff as indicated by the server’s retry hint. Once the refresh is finished, re-issues the original API request and returns the refreshed result entity.

result should be a previous API result that has async refresh information (i.e. the server returned a Mastodon-Async-Refresh header with that response). If no such information is present, or the refresh info indicates the refresh is already finished, this function will return the original result as is immediately.

timeout is the maximum total time in seconds to wait for the async refresh to complete. Set to 0 for no timeout. Default is 0 (wait until done).

max_attempts is the maximum number of polling attempts. Set to 0 or negative for no limit. Default is -1 (wait until done).

Returns the re-fetched original entity on success, or None if the timeout or max attempts was exceeded before the refresh finished.

Raises MastodonIllegalArgumentError if the passed object has async refresh information but is missing the original request information needed to re-fetch. Raises MastodonAPIError if any of the API requests made during the process fail with an error response.

Added: Mastodon v4.4.0, last changed: Mastodon v4.4.0

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.12/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.