From 9b77278b81358d27903b5d879a5203e961ea693b Mon Sep 17 00:00:00 2001 From: halcy Date: Tue, 20 Jun 2023 00:35:03 +0300 Subject: [PATCH] very massive commit that adds type annotations everywhere and breaks all the tests lol --- mastodon/Mastodon.py | 81 +- mastodon/accounts.py | 148 +- mastodon/admin.py | 153 +- mastodon/authentication.py | 51 +- mastodon/conversations.py | 24 +- mastodon/endorsements.py | 12 +- mastodon/favourites.py | 36 +- mastodon/hashtags.py | 22 +- mastodon/instance.py | 83 +- mastodon/internals.py | 154 +- mastodon/lists.py | 53 +- mastodon/media.py | 28 +- mastodon/notifications.py | 23 +- mastodon/polls.py | 25 +- mastodon/preferences.py | 19 +- mastodon/push.py | 94 +- mastodon/relationships.py | 67 +- mastodon/reports.py | 22 +- mastodon/search.py | 29 +- mastodon/statuses.py | 141 +- mastodon/streaming.py | 20 +- mastodon/streaming_endpoints.py | 12 +- mastodon/suggestions.py | 16 +- mastodon/timeline.py | 49 +- mastodon/trends.py | 26 +- mastodon/types.py | 5021 ++++++++++ mastodon/types_base.py | 347 + mastodon/utility.py | 89 +- mastodon/versions.py | 49 +- srcgen/return_types_all_current_fixed.json | 169 +- srcgen/return_types_all_current_fixed_bu.json | 8547 +++++++++++++++++ tests/test_account.py | 10 +- tests/test_instance.py | 16 +- 33 files changed, 14810 insertions(+), 826 deletions(-) create mode 100644 mastodon/types.py create mode 100644 mastodon/types_base.py create mode 100644 srcgen/return_types_all_current_fixed_bu.json diff --git a/mastodon/Mastodon.py b/mastodon/Mastodon.py index e4ec656..a5f3409 100644 --- a/mastodon/Mastodon.py +++ b/mastodon/Mastodon.py @@ -16,18 +16,19 @@ import re import copy -from .compat import IMPL_HAS_CRYPTO, IMPL_HAS_ECE, IMPL_HAS_BLURHASH -from .compat import cryptography, default_backend, ec, serialization -from .compat import http_ece -from .compat import blurhash -from .compat import urlparse +from mastodon.compat import IMPL_HAS_CRYPTO, IMPL_HAS_ECE, IMPL_HAS_BLURHASH +from mastodon.compat import cryptography, default_backend, ec, serialization +from mastodon.compat import http_ece +from mastodon.compat import blurhash +from mastodon.compat import urlparse -from .utility import parse_version_string, max_version, api_version -from .utility import AttribAccessDict, AttribAccessDict -from .utility import Mastodon as Utility +from mastodon.utility import parse_version_string, max_version, api_version +from mastodon.utility import Mastodon as MastoUtility -from .errors import * -from .versions import _DICT_VERSION_APPLICATION, _DICT_VERSION_MENTION, _DICT_VERSION_MEDIA, _DICT_VERSION_ACCOUNT, _DICT_VERSION_POLL, \ +from mastodon.types import * +from mastodon.errors import * + +from mastodon.versions import _DICT_VERSION_APPLICATION, _DICT_VERSION_MENTION, _DICT_VERSION_MEDIA, _DICT_VERSION_ACCOUNT, _DICT_VERSION_POLL, \ _DICT_VERSION_STATUS, _DICT_VERSION_INSTANCE, _DICT_VERSION_HASHTAG, _DICT_VERSION_EMOJI, _DICT_VERSION_RELATIONSHIP, \ _DICT_VERSION_NOTIFICATION, _DICT_VERSION_CONTEXT, _DICT_VERSION_LIST, _DICT_VERSION_CARD, _DICT_VERSION_SEARCHRESULT, \ _DICT_VERSION_ACTIVITY, _DICT_VERSION_REPORT, _DICT_VERSION_PUSH, _DICT_VERSION_PUSH_NOTIF, _DICT_VERSION_FILTER, \ @@ -36,33 +37,33 @@ from .versions import _DICT_VERSION_APPLICATION, _DICT_VERSION_MENTION, _DICT_VE _DICT_VERSION_FAMILIAR_FOLLOWERS, _DICT_VERSION_ADMIN_DOMAIN_BLOCK, _DICT_VERSION_ADMIN_MEASURE, _DICT_VERSION_ADMIN_DIMENSION, \ _DICT_VERSION_ADMIN_RETENTION -from .defaults import _DEFAULT_TIMEOUT, _DEFAULT_SCOPES, _DEFAULT_STREAM_TIMEOUT, _DEFAULT_STREAM_RECONNECT_WAIT_SEC -from .defaults import _SCOPE_SETS +from mastodon.defaults import _DEFAULT_TIMEOUT, _DEFAULT_SCOPES, _DEFAULT_STREAM_TIMEOUT, _DEFAULT_STREAM_RECONNECT_WAIT_SEC +from mastodon.defaults import _SCOPE_SETS -from .internals import Mastodon as Internals -from .authentication import Mastodon as Authentication -from .accounts import Mastodon as Accounts -from .instance import Mastodon as Instance -from .timeline import Mastodon as Timeline -from .statuses import Mastodon as Statuses -from .media import Mastodon as Media -from .polls import Mastodon as Polls -from .notifications import Mastodon as Notifications -from .conversations import Mastodon as Conversations -from .hashtags import Mastodon as Hashtags -from .filters import Mastodon as Filters -from .suggestions import Mastodon as Suggestions -from .endorsements import Mastodon as Endorsements -from .relationships import Mastodon as Relationships -from .lists import Mastodon as Lists -from .trends import Mastodon as Trends -from .search import Mastodon as Search -from .favourites import Mastodon as Favourites -from .reports import Mastodon as Reports -from .preferences import Mastodon as Preferences -from .push import Mastodon as Push -from .admin import Mastodon as Admin -from .streaming_endpoints import Mastodon as Streaming +from mastodon.internals import Mastodon as Internals +from mastodon.authentication import Mastodon as MastoAuthentication +from mastodon.accounts import Mastodon as MastoAccounts +from mastodon.instance import Mastodon as MastoInstance +from mastodon.timeline import Mastodon as MastoTimeline +from mastodon.statuses import Mastodon as MastoStatuses +from mastodon.media import Mastodon as MastoMedia +from mastodon.polls import Mastodon as MastoPolls +from mastodon.notifications import Mastodon as MastoNotifications +from mastodon.conversations import Mastodon as MastoConversations +from mastodon.hashtags import Mastodon as MastoHashtags +from mastodon.filters import Mastodon as MastoFilters +from mastodon.suggestions import Mastodon as MastoSuggestions +from mastodon.endorsements import Mastodon as MastoEndorsements +from mastodon.relationships import Mastodon as MastoRelationships +from mastodon.lists import Mastodon as MastoLists +from mastodon.trends import Mastodon as MastoTrends +from mastodon.search import Mastodon as MastoSearch +from mastodon.favourites import Mastodon as MastoFavourites +from mastodon.reports import Mastodon as MastoReports +from mastodon.preferences import Mastodon as MastoPreferences +from mastodon.push import Mastodon as MastoPush +from mastodon.admin import Mastodon as MastoAdmin +from mastodon.streaming_endpoints import Mastodon as MastoStreaming ### @@ -70,9 +71,9 @@ from .streaming_endpoints import Mastodon as Streaming # # Almost all code is now imported from smaller files to make editing a bit more pleasant ### -class Mastodon(Utility, Authentication, Accounts, Instance, Timeline, Statuses, Polls, Notifications, Hashtags, - Filters, Suggestions, Endorsements, Relationships, Lists, Trends, Search, Favourites, Reports, - Preferences, Push, Admin, Conversations, Media, Streaming): +class Mastodon(MastoUtility, MastoAuthentication, MastoAccounts, MastoInstance, MastoTimeline, MastoStatuses, MastoPolls, MastoNotifications, MastoHashtags, + MastoFilters, MastoSuggestions, MastoEndorsements, MastoRelationships, MastoLists, MastoTrends, MastoSearch, MastoFavourites, MastoReports, + MastoPreferences, MastoPush, MastoAdmin, MastoConversations, MastoMedia, MastoStreaming): """ Thorough and easy to use Mastodon API wrapper in Python. @@ -83,7 +84,7 @@ class Mastodon(Utility, Authentication, Accounts, Instance, Timeline, Statuses, __SUPPORTED_MASTODON_VERSION = "3.5.5" @staticmethod - def get_supported_version(): + def get_supported_version() -> str: """ Retrieve the maximum version of Mastodon supported by this version of Mastodon.py """ diff --git a/mastodon/accounts.py b/mastodon/accounts.py index e781923..6ad4ac8 100644 --- a/mastodon/accounts.py +++ b/mastodon/accounts.py @@ -2,17 +2,22 @@ import collections -from .versions import _DICT_VERSION_ACCOUNT, _DICT_VERSION_STATUS, _DICT_VERSION_RELATIONSHIP, _DICT_VERSION_LIST, _DICT_VERSION_FAMILIAR_FOLLOWERS, _DICT_VERSION_HASHTAG -from .defaults import _DEFAULT_SCOPES, _SCOPE_SETS -from .errors import MastodonIllegalArgumentError, MastodonAPIError, MastodonNotFoundError -from .utility import api_version +from mastodon.versions import _DICT_VERSION_ACCOUNT, _DICT_VERSION_STATUS, _DICT_VERSION_RELATIONSHIP, _DICT_VERSION_LIST, _DICT_VERSION_FAMILIAR_FOLLOWERS, _DICT_VERSION_HASHTAG +from mastodon.defaults import _DEFAULT_SCOPES, _SCOPE_SETS +from mastodon.errors import MastodonIllegalArgumentError, MastodonAPIError, MastodonNotFoundError +from mastodon.utility import api_version -from .internals import Mastodon as Internals +from mastodon.internals import Mastodon as Internals +from typing import Union, Optional, Tuple, List +from mastodon.types import AccountCreationError, Account, IdType, Status, PaginatableList, NonPaginatableList, UserList, Relationship, FamiliarFollowers, Tag, IdType, PathOrFile +from datetime import datetime class Mastodon(Internals): @api_version("2.7.0", "2.7.0", "3.4.0") - def create_account(self, username, password, email, agreement=False, reason=None, locale="en", scopes=_DEFAULT_SCOPES, to_file=None, return_detailed_error=False): + def create_account(self, username: str, password: str, email: str, agreement: bool = False, reason: Optional[str] = None, + locale: str = "en", scopes: List[str] = _DEFAULT_SCOPES, to_file: Optional[str] = None, + return_detailed_error: bool = False) -> Union[Optional[str], Tuple[Optional[str], AccountCreationError]]: """ Creates a new user account with the given username, password and email. "agreement" must be set to true (after showing the user the instance's user agreement and having @@ -75,7 +80,7 @@ class Mastodon(Internals): if "error" in response: if return_detailed_error: return None, response - raise MastodonIllegalArgumentError(f'Invalid request: {e}') + raise MastodonIllegalArgumentError(f'Invalid request: {response["error"]}') self.access_token = response['access_token'] self.__set_refresh_token(response.get('refresh_token')) self.__set_token_expired(int(response.get('expires_in', 0))) @@ -119,28 +124,24 @@ class Mastodon(Internals): # Reading data: Accounts ### @api_version("1.0.0", "1.0.0", _DICT_VERSION_ACCOUNT) - def account(self, id): + def account(self, id: Union[Account, IdType]) -> Account: """ Fetch account information by user `id`. Does not require authentication for publicly visible accounts. - - Returns a :ref:`account dict `. """ id = self.__unpack_id(id) return self.__api_request('GET', f'/api/v1/accounts/{id}') @api_version("1.0.0", "2.1.0", _DICT_VERSION_ACCOUNT) - def account_verify_credentials(self): + def account_verify_credentials(self) -> Account: """ - Fetch logged-in user's account information. - - Returns a :ref:`account dict ` (Starting from 2.1.0, with an additional "source" field). + Fetch logged-in user's account information. Returns the version of the Account object with `source` field. """ return self.__api_request('GET', '/api/v1/accounts/verify_credentials') @api_version("1.0.0", "2.1.0", _DICT_VERSION_ACCOUNT) - def me(self): + def me(self) -> Account: """ Get this user's account. Synonym for `account_verify_credentials()`, does exactly the same thing, just exists because `account_verify_credentials()` has a confusing @@ -149,7 +150,10 @@ class Mastodon(Internals): return self.account_verify_credentials() @api_version("1.0.0", "2.8.0", _DICT_VERSION_STATUS) - def account_statuses(self, id, only_media=False, pinned=False, exclude_replies=False, exclude_reblogs=False, tagged=None, max_id=None, min_id=None, since_id=None, limit=None): + def account_statuses(self, id: Union[Account, IdType], only_media: bool = False, pinned: bool = False, exclude_replies: bool = False, + exclude_reblogs: bool = False, tagged: Optional[str] = None, max_id: Optional[Union[Status, IdType, datetime]] = None, + min_id: Optional[Union[Status, IdType, datetime]] = None, since_id: Optional[Union[Status, IdType, datetime]] = None, + limit: Optional[int] = None) -> PaginatableList[Status]: """ Fetch statuses by user `id`. Same options as :ref:`timeline() ` are permitted. Returned toots are from the perspective of the logged-in user, i.e. @@ -165,8 +169,6 @@ class Mastodon(Internals): Does not require authentication for Mastodon versions after 2.7.0 (returns publicly visible statuses in that case), for publicly visible accounts. - - Returns a list of :ref:`status dicts `. """ id = self.__unpack_id(id) if max_id is not None: @@ -191,66 +193,65 @@ class Mastodon(Internals): return self.__api_request('GET', f'/api/v1/accounts/{id}/statuses', params) @api_version("1.0.0", "2.6.0", _DICT_VERSION_ACCOUNT) - def account_following(self, id, max_id=None, min_id=None, since_id=None, limit=None): + def account_following(self, id: Union[Account, IdType], max_id: Optional[Union[Account, IdType]] = None, + min_id: Optional[Union[Account, IdType]] = None, since_id: Optional[Union[Account, IdType]] = None, + limit: Optional[int] = None) -> PaginatableList[Account]: """ Fetch users the given user is following. - - Returns a list of :ref:`account dicts `. """ id = self.__unpack_id(id) if max_id is not None: - max_id = self.__unpack_id(max_id, dateconv=True) + max_id = self.__unpack_id(max_id) if min_id is not None: - min_id = self.__unpack_id(min_id, dateconv=True) + min_id = self.__unpack_id(min_id) if since_id is not None: - since_id = self.__unpack_id(since_id, dateconv=True) + since_id = self.__unpack_id(since_id) params = self.__generate_params(locals(), ['id']) return self.__api_request('GET', f'/api/v1/accounts/{id}/following', params) @api_version("1.0.0", "2.6.0", _DICT_VERSION_ACCOUNT) - def account_followers(self, id, max_id=None, min_id=None, since_id=None, limit=None): + def account_followers(self, id: Union[Account, IdType], max_id: Optional[Union[Account, IdType]] = None, + min_id: Optional[Union[Account, IdType]] = None, since_id: Optional[Union[Account, IdType]] = None, + limit: Optional[int] = None) -> PaginatableList[Account]: """ Fetch users the given user is followed by. - - Returns a list of :ref:`account dicts `. """ id = self.__unpack_id(id) if max_id is not None: - max_id = self.__unpack_id(max_id, dateconv=True) + max_id = self.__unpack_id(max_id) if min_id is not None: - min_id = self.__unpack_id(min_id, dateconv=True) + min_id = self.__unpack_id(min_id) if since_id is not None: - since_id = self.__unpack_id(since_id, dateconv=True) + since_id = self.__unpack_id(since_id) params = self.__generate_params(locals(), ['id']) return self.__api_request('GET', f'/api/v1/accounts/{id}/followers', params) @api_version("1.0.0", "1.4.0", _DICT_VERSION_RELATIONSHIP) - def account_relationships(self, id): + def account_relationships(self, id: Union[List[Union[Account, IdType]], Union[Account, IdType]]) -> NonPaginatableList[Relationship]: """ Fetch relationship (following, followed_by, blocking, follow requested) of the logged in user to a given account. `id` can be a list. - - Returns a list of :ref:`relationship dicts `. """ id = self.__unpack_id(id) params = self.__generate_params(locals()) return self.__api_request('GET', '/api/v1/accounts/relationships', params) - @api_version("1.0.0", "2.3.0", _DICT_VERSION_ACCOUNT) - def account_search(self, q, limit=None, following=False, resolve=False): + @api_version("1.0.0", "2.8.0", _DICT_VERSION_ACCOUNT) + def account_search(self, q: str, limit: Optional[int] = None, following: bool = False, resolve: bool = False, offset: Optional[int] = None) -> NonPaginatableList[Account]: """ Fetch matching accounts. Will lookup an account remotely if the search term is in the username@domain format and not yet in the database. Set `following` to True to limit the search to users the logged-in user follows. - Returns a list of :ref:`account dicts `. + Paginated in a weird way ("limit" / "offset"), if you want to fetch all results + here please do it yourself for now. """ params = self.__generate_params(locals()) @@ -260,55 +261,46 @@ class Mastodon(Internals): return self.__api_request('GET', '/api/v1/accounts/search', params) @api_version("2.1.0", "2.1.0", _DICT_VERSION_LIST) - def account_lists(self, id): + def account_lists(self, id: Union[Account, IdType]) -> NonPaginatableList[UserList]: """ Get all of the logged-in user's lists which the specified user is a member of. - - Returns a list of :ref:`list dicts `. """ id = self.__unpack_id(id) params = self.__generate_params(locals(), ['id']) return self.__api_request('GET', f'/api/v1/accounts/{id}/lists', params) @api_version("3.4.0", "3.4.0", _DICT_VERSION_ACCOUNT) - def account_lookup(self, acct): + def account_lookup(self, acct: str) -> Account: """ Look up an account from user@instance form (@instance allowed but not required for local accounts). Will only return accounts that the instance already knows about, and not do any webfinger requests. Use `account_search` if you need to resolve users through webfinger from remote. - - Returns an :ref:`account dict `. """ return self.__api_request('GET', '/api/v1/accounts/lookup', self.__generate_params(locals())) @api_version("3.5.0", "3.5.0", _DICT_VERSION_FAMILIAR_FOLLOWERS) - def account_familiar_followers(self, id): + def account_familiar_followers(self, id: Union[List[Union[Account, IdType]], Union[Account, IdType]]) -> NonPaginatableList[FamiliarFollowers]: """ Find followers for the account given by id (can be a list) that also follow the logged in account. - - Returns a list of :ref:`familiar follower dicts ` """ - if not isinstance(id, list): - id = [id] - for i in range(len(id)): - id[i] = self.__unpack_id(id[i]) + id = self.__unpack_id(id, listify = True) return self.__api_request('GET', '/api/v1/accounts/familiar_followers', {'id': id}, use_json=True) ### # Writing data: Accounts ### @api_version("1.0.0", "3.3.0", _DICT_VERSION_RELATIONSHIP) - def account_follow(self, id, reblogs=True, notify=False): + def account_follow(self, id: Union[Account, IdType], reblogs: bool =True, notify: bool = False) -> Relationship: """ Follow a user. Set `reblogs` to False to hide boosts by the followed user. Set `notify` to True to get a notification every time the followed user posts. - Returns a :ref:`relationship dict ` containing the updated relationship to the user. + The returned object reflects the updated relationship with the user. """ id = self.__unpack_id(id) params = self.__generate_params(locals(), ["id"]) @@ -319,7 +311,7 @@ class Mastodon(Internals): return self.__api_request('POST', f'/api/v1/accounts/{id}/follow', params) @api_version("1.0.0", "2.1.0", _DICT_VERSION_ACCOUNT) - def follows(self, uri): + def follows(self, uri: str) -> Relationship: """ Follow a remote user with username given in username@domain form. @@ -334,48 +326,48 @@ class Mastodon(Internals): return self.account_follow(acct) @api_version("1.0.0", "1.4.0", _DICT_VERSION_RELATIONSHIP) - def account_unfollow(self, id): + def account_unfollow(self, id: Union[Account, IdType]) -> Relationship: """ Unfollow a user. - Returns a :ref:`relationship dict ` containing the updated relationship to the user. + The returned object reflects the updated relationship with the user. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/accounts/{id}/unfollow') @api_version("3.5.0", "3.5.0", _DICT_VERSION_RELATIONSHIP) - def account_remove_from_followers(self, id): + def account_remove_from_followers(self, id: Union[Account, IdType]) -> Relationship: """ Remove a user from the logged in users followers (i.e. make them unfollow the logged in user / "softblock" them). - Returns a :ref:`relationship dict ` reflecting the updated following status. + The returned object reflects the updated relationship with the user. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/accounts/{id}/remove_from_followers') @api_version("1.0.0", "1.4.0", _DICT_VERSION_RELATIONSHIP) - def account_block(self, id): + def account_block(self, id: Union[Account, IdType]) -> Relationship: """ Block a user. - Returns a :ref:`relationship dict ` containing the updated relationship to the user. + The returned object reflects the updated relationship with the user. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/accounts/{id}/block') @api_version("1.0.0", "1.4.0", _DICT_VERSION_RELATIONSHIP) - def account_unblock(self, id): + def account_unblock(self, id: Union[Account, IdType]) -> Relationship: """ Unblock a user. - Returns a :ref:`relationship dict ` containing the updated relationship to the user. + The returned object reflects the updated relationship with the user. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/accounts/{id}/unblock') @api_version("1.1.0", "2.4.3", _DICT_VERSION_RELATIONSHIP) - def account_mute(self, id, notifications=True, duration=None): + def account_mute(self, id: Union[Account, IdType], notifications: bool = True, duration: Optional[int] = None) -> Relationship: """ Mute a user. @@ -383,28 +375,28 @@ class Mastodon(Internals): muted from timelines. Pass a `duration` in seconds to have Mastodon automatically lift the mute after that many seconds. - Returns a :ref:`relationship dict ` containing the updated relationship to the user. + The returned object reflects the updated relationship with the user. """ id = self.__unpack_id(id) params = self.__generate_params(locals(), ['id']) return self.__api_request('POST', f'/api/v1/accounts/{id}/mute', params) @api_version("1.1.0", "1.4.0", _DICT_VERSION_RELATIONSHIP) - def account_unmute(self, id): + def account_unmute(self, id: Union[Account, IdType]) -> Relationship: """ Unmute a user. - Returns a :ref:`relationship dict ` containing the updated relationship to the user. + The returned object reflects the updated relationship with the user. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/accounts/{id}/unmute') @api_version("1.1.1", "3.1.0", _DICT_VERSION_ACCOUNT) - def account_update_credentials(self, display_name=None, note=None, - avatar=None, avatar_mime_type=None, - header=None, header_mime_type=None, - locked=None, bot=None, - discoverable=None, fields=None): + def account_update_credentials(self, display_name: Optional[str] = None, note: Optional[str] = None, + avatar: Optional[PathOrFile] = None, avatar_mime_type: Optional[str] = None, + header: Optional[PathOrFile] = None, header_mime_type: Optional[str] = None, + locked: Optional[bool] = None, bot: Optional[bool] = None, + discoverable: Optional[bool] = None, fields: Optional[List[Tuple[str, str]]] = None) -> Account: """ Update the profile for the currently logged-in user. @@ -422,7 +414,7 @@ class Mastodon(Internals): `fields` can be a list of up to four name-value pairs (specified as tuples) to appear as semi-structured information in the user's profile. - Returns the updated `account dict` of the logged-in user. + The returned object reflects the updated account. """ params_initial = collections.OrderedDict(locals()) @@ -453,42 +445,40 @@ class Mastodon(Internals): return self.__api_request('PATCH', '/api/v1/accounts/update_credentials', params, files=files) @api_version("2.5.0", "2.5.0", _DICT_VERSION_RELATIONSHIP) - def account_pin(self, id): + def account_pin(self, id: Union[Account, IdType]) -> Relationship: """ Pin / endorse a user. - Returns a :ref:`relationship dict ` containing the updated relationship to the user. + The returned object reflects the updated relationship with the user. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/accounts/{id}/pin') @api_version("2.5.0", "2.5.0", _DICT_VERSION_RELATIONSHIP) - def account_unpin(self, id): + def account_unpin(self, id: Union[Account, IdType]) -> Relationship: """ Unpin / un-endorse a user. - Returns a :ref:`relationship dict ` containing the updated relationship to the user. + The returned object reflects the updated relationship with the user. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/accounts/{id}/unpin') @api_version("3.2.0", "3.2.0", _DICT_VERSION_RELATIONSHIP) - def account_note_set(self, id, comment): + def account_note_set(self, id: Union[Account, IdType], comment: str) -> Account: """ Set a note (visible to the logged in user only) for the given account. - Returns a :ref:`status dict ` with the `note` updated. + The returned object contains the updated note. """ id = self.__unpack_id(id) params = self.__generate_params(locals(), ["id"]) return self.__api_request('POST', f'/api/v1/accounts/{id}/note', params) @api_version("3.3.0", "3.3.0", _DICT_VERSION_HASHTAG) - def account_featured_tags(self, id): + def account_featured_tags(self, id: Union[Account, IdType]) -> NonPaginatableList[Tag]: """ Get an account's featured hashtags. - - Returns a list of :ref:`hashtag dicts ` (NOT `featured tag dicts`_). """ id = self.__unpack_id(id) return self.__api_request('GET', f'/api/v1/accounts/{id}/featured_tags') diff --git a/mastodon/admin.py b/mastodon/admin.py index d40118f..351f8ef 100644 --- a/mastodon/admin.py +++ b/mastodon/admin.py @@ -1,20 +1,25 @@ # admin.py - admin / moderation endpoints -from .versions import _DICT_VERSION_ADMIN_ACCOUNT, _DICT_VERSION_REPORT, _DICT_VERSION_HASHTAG, _DICT_VERSION_STATUS, _DICT_VERSION_CARD, \ +from mastodon.versions import _DICT_VERSION_ADMIN_ACCOUNT, _DICT_VERSION_REPORT, _DICT_VERSION_HASHTAG, _DICT_VERSION_STATUS, _DICT_VERSION_CARD, \ _DICT_VERSION_ADMIN_DOMAIN_BLOCK, _DICT_VERSION_ADMIN_MEASURE, _DICT_VERSION_ADMIN_DIMENSION, _DICT_VERSION_ADMIN_RETENTION -from .errors import MastodonIllegalArgumentError -from .utility import api_version - -from .internals import Mastodon as Internals +from mastodon.errors import MastodonIllegalArgumentError +from mastodon.utility import api_version +from mastodon.internals import Mastodon as Internals +from typing import Optional, List, Union +from mastodon.types import IdType, PrimitiveIdType, Account, AdminAccount, AdminReport, PaginatableList, NonPaginatableList, Status, Tag,\ + PreviewCard, AdminDomainBlock, AdminMeasure, AdminDimension, AdminRetention +from datetime import datetime class Mastodon(Internals): ### # Moderation API ### @api_version("2.9.1", "4.0.0", _DICT_VERSION_ADMIN_ACCOUNT) - def admin_accounts_v2(self, origin=None, by_domain=None, status=None, username=None, display_name=None, email=None, ip=None, - permissions=None, invited_by=None, role_ids=None, max_id=None, min_id=None, since_id=None, limit=None): + def admin_accounts_v2(self, origin: Optional[str] = None, by_domain: Optional[str] = None, status: Optional[str] = None, username: Optional[str] = None, + display_name: Optional[str] = None, email: Optional[str] = None, ip: Optional[str] = None, permissions: Optional[str] = None, + invited_by: Union[Account, IdType] = None, role_ids: Optional[List[IdType]] = None, max_id: Optional[IdType] = None, min_id: Optional[IdType] = None, + since_id: Optional[IdType] = None, limit: Optional[int] = None) -> AdminAccount: """ Fetches a list of accounts that match given criteria. By default, local accounts are returned. @@ -30,15 +35,17 @@ class Mastodon(Internals): * Set `role_ids` to a list of role IDs to get only accounts with those roles. Returns a list of :ref:`admin account dicts `. + + Pagination on this is a bit weird, so I would recommend not doing that and instead manually fetching. """ if max_id is not None: - max_id = self.__unpack_id(max_id, dateconv=True) + max_id = self.__unpack_id(max_id) if min_id is not None: - min_id = self.__unpack_id(min_id, dateconv=True) + min_id = self.__unpack_id(min_id) if since_id is not None: - since_id = self.__unpack_id(since_id, dateconv=True) + since_id = self.__unpack_id(since_id) if role_ids is not None: if not isinstance(role_ids, list): @@ -64,11 +71,16 @@ class Mastodon(Internals): return self.__api_request('GET', '/api/v2/admin/accounts', params) @api_version("2.9.1", "2.9.1", _DICT_VERSION_ADMIN_ACCOUNT) - def admin_accounts(self, remote=False, by_domain=None, status='active', username=None, display_name=None, email=None, ip=None, staff_only=False, max_id=None, min_id=None, since_id=None, limit=None): + def admin_accounts(self, remote: bool = False, by_domain: Optional[str] = None, status: str = 'active', username: Optional[str] = None, + display_name: Optional[str] = None, email: Optional[str] = None, ip: Optional[str] = None, staff_only: bool = False, + max_id: Optional[IdType] = None, min_id: Optional[IdType] = None, since_id: Optional[IdType] = None, + limit: Optional[int] = None): """ Currently a synonym for admin_accounts_v1, now deprecated. You are strongly encouraged to use admin_accounts_v2 instead, since this one is kind of bad. !!!!! This function may be switched to calling the v2 API in the future. This is your warning. If you want to keep using v1, use it explicitly. !!!!! + + Pagination on this is a bit weird, so I would recommend not doing that and instead manually fetching. """ return self.admin_accounts_v1( remote=remote, @@ -85,7 +97,10 @@ class Mastodon(Internals): ) @api_version("2.9.1", "2.9.1", _DICT_VERSION_ADMIN_ACCOUNT) - def admin_accounts_v1(self, remote=False, by_domain=None, status='active', username=None, display_name=None, email=None, ip=None, staff_only=False, max_id=None, min_id=None, since_id=None, limit=None): + def admin_accounts_v1(self, remote: bool = False, by_domain: Optional[str] = None, status: str = 'active', username: Optional[str] = None, + display_name: Optional[str] = None, email: Optional[str] = None, ip: Optional[str] = None, staff_only: bool = False, + max_id: Optional[IdType] = None, min_id: Optional[IdType] = None, since_id: Optional[IdType] = None, + limit: Optional[int] = None) -> AdminAccount: """ Fetches a list of accounts that match given criteria. By default, local accounts are returned. @@ -104,15 +119,17 @@ class Mastodon(Internals): Deprecated in Mastodon version 3.5.0. Returns a list of :ref:`admin account dicts `. + + Pagination on this is a bit weird, so I would recommend not doing that and instead manually fetching. """ if max_id is not None: - max_id = self.__unpack_id(max_id, dateconv=True) + max_id = self.__unpack_id(max_id) if min_id is not None: - min_id = self.__unpack_id(min_id, dateconv=True) + min_id = self.__unpack_id(min_id) if since_id is not None: - since_id = self.__unpack_id(since_id, dateconv=True) + since_id = self.__unpack_id(since_id) params = self.__generate_params(locals(), ['remote', 'status', 'staff_only']) @@ -136,87 +153,86 @@ class Mastodon(Internals): return self.__api_request('GET', '/api/v1/admin/accounts', params) @api_version("2.9.1", "2.9.1", _DICT_VERSION_ADMIN_ACCOUNT) - def admin_account(self, id): + def admin_account(self, id: Union[Account, AdminAccount, IdType]) -> AdminAccount: """ Fetches a single :ref:`admin account dict ` for the user with the given id. - - Returns that dict. """ id = self.__unpack_id(id) return self.__api_request('GET', f'/api/v1/admin/accounts/{id}') @api_version("2.9.1", "2.9.1", _DICT_VERSION_ADMIN_ACCOUNT) - def admin_account_enable(self, id): + def admin_account_enable(self, id: Union[Account, AdminAccount, IdType]) -> AdminAccount: """ Reenables login for a local account for which login has been disabled. - Returns the updated :ref:`admin account dict `. + The returned object reflects the updates to the account. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/admin/accounts/{id}/enable') @api_version("2.9.1", "2.9.1", _DICT_VERSION_ADMIN_ACCOUNT) - def admin_account_approve(self, id): + def admin_account_approve(self, id: Union[Account, AdminAccount, IdType]) -> AdminAccount: """ Approves a pending account. - Returns the updated :ref:`admin account dict `. + The returned object reflects the updates to the account. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/admin/accounts/{id}/approve') @api_version("2.9.1", "2.9.1", _DICT_VERSION_ADMIN_ACCOUNT) - def admin_account_reject(self, id): + def admin_account_reject(self, id: Union[Account, AdminAccount, IdType]) -> AdminAccount: """ Rejects and deletes a pending account. - Returns the updated :ref:`admin account dict ` for the account that is now gone. + The returned object is that of the now-deleted account. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/admin/accounts/{id}/reject') @api_version("2.9.1", "2.9.1", _DICT_VERSION_ADMIN_ACCOUNT) - def admin_account_unsilence(self, id): + def admin_account_unsilence(self, id: Union[Account, AdminAccount, IdType]) -> AdminAccount: """ Unsilences an account. - Returns the updated :ref:`admin account dict `. + The returned object reflects the updates to the account. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/admin/accounts/{id}/unsilence') @api_version("2.9.1", "2.9.1", _DICT_VERSION_ADMIN_ACCOUNT) - def admin_account_unsuspend(self, id): + def admin_account_unsuspend(self, id: Union[Account, AdminAccount, IdType]) -> AdminAccount: """ Unsuspends an account. - Returns the updated :ref:`admin account dict `. + The returned object reflects the updates to the account. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/admin/accounts/{id}/unsuspend') @api_version("3.3.0", "3.3.0", _DICT_VERSION_ADMIN_ACCOUNT) - def admin_account_delete(self, id): + def admin_account_delete(self, id: Union[Account, AdminAccount, IdType]) -> AdminAccount: """ Delete a local user account. - The deleted accounts :ref:`admin account dict `. + The returned object reflects the updates to the account. """ id = self.__unpack_id(id) return self.__api_request('DELETE', f'/api/v1/admin/accounts/{id}') @api_version("3.3.0", "3.3.0", _DICT_VERSION_ADMIN_ACCOUNT) - def admin_account_unsensitive(self, id): + def admin_account_unsensitive(self, id: Union[Account, AdminAccount, IdType]) -> AdminAccount: """ Unmark an account as force-sensitive. - Returns the updated :ref:`admin account dict `. + The returned object reflects the updates to the account. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/admin/accounts/{id}/unsensitive') @api_version("2.9.1", "2.9.1", "2.9.1") - def admin_account_moderate(self, id, action=None, report_id=None, warning_preset_id=None, text=None, send_email_notification=True): + def admin_account_moderate(self, id: Union[Account, AdminAccount, IdType], action: Optional[str] = None, report_id: Optional[Union[AdminReport, PrimitiveIdType]] = None, + warning_preset_id: Optional[PrimitiveIdType] = None, text: Optional[str] = None, send_email_notification: Optional[bool] = True): """ Perform a moderation action on an account. @@ -252,7 +268,9 @@ class Mastodon(Internals): self.__api_request('POST', f'/api/v1/admin/accounts/{id}/action', params) @api_version("2.9.1", "2.9.1", _DICT_VERSION_REPORT) - def admin_reports(self, resolved=False, account_id=None, target_account_id=None, max_id=None, min_id=None, since_id=None, limit=None): + def admin_reports(self, resolved: Optional[bool] = False, account_id = Optional[Union[Account, AdminAccount, IdType]], + target_account_id: Optional[Union[Account, AdminAccount, IdType]] = None, max_id: Optional[IdType] = None, + min_id: Optional[IdType] = None, since_id: Optional[IdType] = None, limit: Optional[int] = None) -> PaginatableList[AdminReport]: """ Fetches the list of reports. @@ -262,13 +280,13 @@ class Mastodon(Internals): Returns a list of :ref:`report dicts `. """ if max_id is not None: - max_id = self.__unpack_id(max_id, dateconv=True) + max_id = self.__unpack_id(max_id) if min_id is not None: - min_id = self.__unpack_id(min_id, dateconv=True) + min_id = self.__unpack_id(min_id) if since_id is not None: - since_id = self.__unpack_id(since_id, dateconv=True) + since_id = self.__unpack_id(since_id) if account_id is not None: account_id = self.__unpack_id(account_id) @@ -283,90 +301,86 @@ class Mastodon(Internals): return self.__api_request('GET', '/api/v1/admin/reports', params) @api_version("2.9.1", "2.9.1", _DICT_VERSION_REPORT) - def admin_report(self, id): + def admin_report(self, id: Union[AdminReport, IdType]) -> AdminReport: """ Fetches the report with the given id. - - Returns a :ref:`report dict `. """ id = self.__unpack_id(id) return self.__api_request('GET', f'/api/v1/admin/reports/{id}') @api_version("2.9.1", "2.9.1", _DICT_VERSION_REPORT) - def admin_report_assign(self, id): + def admin_report_assign(self, id: Union[AdminReport, IdType]) -> AdminReport: """ Assigns the given report to the logged-in user. - Returns the updated :ref:`report dict `. + The returned object reflects the updates to the report. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/admin/reports/{id}/assign_to_self') @api_version("2.9.1", "2.9.1", _DICT_VERSION_REPORT) - def admin_report_unassign(self, id): + def admin_report_unassign(self, id: Union[AdminReport, IdType]) -> AdminReport: """ Unassigns the given report from the logged-in user. - Returns the updated :ref:`report dict `. + The returned object reflects the updates to the report. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/admin/reports/{id}/unassign') @api_version("2.9.1", "2.9.1", _DICT_VERSION_REPORT) - def admin_report_reopen(self, id): + def admin_report_reopen(self, id: Union[AdminReport, IdType]) -> AdminReport: """ Reopens a closed report. - Returns the updated :ref:`report dict `. + The returned object reflects the updates to the report. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/admin/reports/{id}/reopen') @api_version("2.9.1", "2.9.1", _DICT_VERSION_REPORT) - def admin_report_resolve(self, id): + def admin_report_resolve(self, id: Union[AdminReport, IdType]) -> AdminReport: """ Marks a report as resolved (without taking any action). - Returns the updated :ref:`report dict `. + The returned object reflects the updates to the report. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/admin/reports/{id}/resolve') @api_version("3.5.0", "3.5.0", _DICT_VERSION_HASHTAG) - def admin_trending_tags(self, limit=None): + def admin_trending_tags(self, limit: Optional[int] = None) -> NonPaginatableList[Tag]: """ Admin version of :ref:`trending_tags() `. Includes unapproved tags. - Returns a list of :ref:`hashtag dicts `, sorted by the instance's trending algorithm, - descending. + The returned list is sorted, descending, by the instance's trending algorithm. """ params = self.__generate_params(locals()) return self.__api_request('GET', '/api/v1/admin/trends/tags', params) @api_version("3.5.0", "3.5.0", _DICT_VERSION_STATUS) - def admin_trending_statuses(self): + def admin_trending_statuses(self) -> NonPaginatableList[Status]: """ Admin version of :ref:`trending_statuses() `. Includes unapproved tags. - Returns a list of :ref:`status dicts `, sorted by the instance's trending algorithm, - descending. + The returned list is sorted, descending, by the instance's trending algorithm. """ params = self.__generate_params(locals()) return self.__api_request('GET', '/api/v1/admin/trends/statuses', params) @api_version("3.5.0", "3.5.0", _DICT_VERSION_CARD) - def admin_trending_links(self): + def admin_trending_links(self) -> NonPaginatableList[PreviewCard]: """ Admin version of :ref:`trending_links() `. Includes unapproved tags. - Returns a list of :ref:`card dicts `, sorted by the instance's trending algorithm, - descending. + The returned list is sorted, descending, by the instance's trending algorithm. """ params = self.__generate_params(locals()) return self.__api_request('GET', '/api/v1/admin/trends/links', params) @api_version("4.0.0", "4.0.0", _DICT_VERSION_ADMIN_DOMAIN_BLOCK) - def admin_domain_blocks(self, id=None, max_id=None, min_id=None, since_id=None, limit=None): + def admin_domain_blocks(self, id: Optional[IdType] = None, max_id: Optional[IdType] = None, min_id: Optional[IdType] = None, + since_id: Optional[IdType] = None, limit: Optional[int] = None) -> PaginatableList[AdminDomainBlock]: """ Fetches a list of blocked domains. Requires scope `admin:read:domain_blocks`. @@ -391,7 +405,9 @@ class Mastodon(Internals): return self.__api_request('GET', '/api/v1/admin/domain_blocks/', params) @api_version("4.0.0", "4.0.0", _DICT_VERSION_ADMIN_DOMAIN_BLOCK) - def admin_create_domain_block(self, domain:str, severity:str=None, reject_media:bool=None, reject_reports:bool=None, private_comment:str=None, public_comment:str=None, obfuscate:bool=None): + def admin_create_domain_block(self, domain: str, severity: Optional[str] = None, reject_media: Optional[bool] = None, + reject_reports: Optional[bool] = None, private_comment: Optional[str] = None, + public_comment: Optional[str] = None, obfuscate: Optional[bool] = None) -> AdminDomainBlock: """ Perform a moderation action on a domain. Requires scope `admin:write:domain_blocks`. @@ -416,7 +432,8 @@ class Mastodon(Internals): return self.__api_request('POST', '/api/v1/admin/domain_blocks/', params) @api_version("4.0.0", "4.0.0", _DICT_VERSION_ADMIN_DOMAIN_BLOCK) - def admin_update_domain_block(self, id, severity:str=None, reject_media:bool=None, reject_reports:bool=None, private_comment:str=None, public_comment:str=None, obfuscate:bool=None): + def admin_update_domain_block(self, id, severity: Optional[str] = None, reject_media: Optional[bool] = None, reject_reports: Optional[bool] = None, + private_comment: Optional[str] = None, public_comment: Optional[str] = None, obfuscate: Optional[bool] = None) -> AdminDomainBlock: """ Modify existing moderation action on a domain. Requires scope `admin:write:domain_blocks`. @@ -442,7 +459,7 @@ class Mastodon(Internals): return self.__api_request('PUT', f'/api/v1/admin/domain_blocks/{id}', params) @api_version("4.0.0", "4.0.0", _DICT_VERSION_ADMIN_DOMAIN_BLOCK) - def admin_delete_domain_block(self, id=None): + def admin_delete_domain_block(self, id = Union[AdminDomainBlock, IdType]): """ Removes moderation action against a given domain. Requires scope `admin:write:domain_blocks`. @@ -457,9 +474,10 @@ class Mastodon(Internals): raise AttributeError("You must provide an id of an existing domain block to remove it.") @api_version("3.5.0", "3.5.0", _DICT_VERSION_ADMIN_MEASURE) - def admin_measures(self, start_at, end_at, active_users=False, new_users=False, interactions=False, opened_reports = False, resolved_reports=False, - tag_accounts=None, tag_uses=None, tag_servers=None, instance_accounts=None, instance_media_attachments=None, instance_reports=None, - instance_statuses=None, instance_follows=None, instance_followers=None): + def admin_measures(self, start_at, end_at, active_users: bool = False, new_users: bool = False, interactions: bool = False, opened_reports: bool = False, resolved_reports: bool = False, + tag_accounts: Optional[Union[Tag, IdType]] = None, tag_uses: Optional[Union[Tag, IdType]] = None, tag_servers: Optional[Union[Tag, IdType]] = None, + instance_accounts: Optional[str] = None, instance_media_attachments: Optional[str] = None, instance_reports: Optional[str] = None, + instance_statuses: Optional[str] = None, instance_follows: Optional[str] = None, instance_followers: Optional[str] = None) -> NonPaginatableList[AdminMeasure]: """ Retrieves numerical instance information for the time period (at day granularity) between `start_at` and `end_at`. @@ -512,8 +530,9 @@ class Mastodon(Internals): return self.__api_request('POST', '/api/v1/admin/measures', params, use_json=True) @api_version("3.5.0", "3.5.0", _DICT_VERSION_ADMIN_DIMENSION) - def admin_dimensions(self, start_at, end_at, limit=None, languages=False, sources=False, servers=False, space_usage=False, software_versions=False, - tag_servers=None, tag_languages=None, instance_accounts=None, instance_languages=None): + def admin_dimensions(self, start_at: datetime, end_at: datetime, limit: Optional[int] = None, languages: bool = False, sources: bool = False, + servers: bool = False, space_usag: bool = False, software_versions: bool = False, tag_servers: Optional[Union[Tag, IdType]] = None, + tag_languages: Optional[Union[Tag, IdType]] = None, instance_accounts: Optional[str] = None, instance_languages: Optional[str] = None) -> NonPaginatableList[AdminDimension]: """ Retrieves primarily categorical instance information for the time period (at day granularity) between `start_at` and `end_at`. @@ -564,7 +583,7 @@ class Mastodon(Internals): return self.__api_request('POST', '/api/v1/admin/dimensions', params, use_json=True) @api_version("3.5.0", "3.5.0", _DICT_VERSION_ADMIN_RETENTION) - def admin_retention(self, start_at, end_at, frequency="day"): + def admin_retention(self, start_at: datetime, end_at: datetime, frequency: str = "day") -> AdminRetention: """ Gets user retention statistics (at `frequency` - "day" or "month" - granularity) between `start_at` and `end_at`. diff --git a/mastodon/authentication.py b/mastodon/authentication.py index 77ae836..0696ec4 100644 --- a/mastodon/authentication.py +++ b/mastodon/authentication.py @@ -7,21 +7,25 @@ import os import time import collections -from .errors import MastodonIllegalArgumentError, MastodonNetworkError, MastodonVersionError, MastodonAPIError -from .versions import _DICT_VERSION_APPLICATION -from .defaults import _DEFAULT_SCOPES, _SCOPE_SETS, _DEFAULT_TIMEOUT, _DEFAULT_USER_AGENT -from .utility import parse_version_string, api_version - -from .internals import Mastodon as Internals +from mastodon.errors import MastodonIllegalArgumentError, MastodonNetworkError, MastodonVersionError, MastodonAPIError +from mastodon.versions import _DICT_VERSION_APPLICATION +from mastodon.defaults import _DEFAULT_SCOPES, _SCOPE_SETS, _DEFAULT_TIMEOUT, _DEFAULT_USER_AGENT +from mastodon.utility import parse_version_string, api_version +from mastodon.internals import Mastodon as Internals +from mastodon.utility import Mastodon as Utility +from typing import List, Optional, Union, Tuple +from mastodon.types import Application +from mastodon.compat import PurePath class Mastodon(Internals): ### # Registering apps ### @staticmethod - def create_app(client_name, scopes=_DEFAULT_SCOPES, redirect_uris=None, website=None, to_file=None, - api_base_url=None, request_timeout=_DEFAULT_TIMEOUT, session=None, user_agent=_DEFAULT_USER_AGENT): + def create_app(client_name, scopes: List[str] = _DEFAULT_SCOPES, redirect_uris: Optional[Union[str, List[str]]] = None, website: Optional[str] = None, + to_file: Optional[Union[str, PurePath]] = None, api_base_url: Optional[str] = None, request_timeout: float = _DEFAULT_TIMEOUT, + session: Optional[requests.Session] = None, user_agent: str = _DEFAULT_USER_AGENT) -> Tuple[str, str]: """ Create a new app with given `client_name` and `scopes` (The basic scopes are "read", "write", "follow" and "push" - more granular scopes are available, please refer to Mastodon documentation for which) on the instance given @@ -42,7 +46,6 @@ class Mastodon(Internals): Presently, app registration is open by default, but this is not guaranteed to be the case for all Mastodon instances in the future. - Returns `client_id` and `client_secret`, both as strings. """ if api_base_url is None: @@ -87,9 +90,11 @@ class Mastodon(Internals): ### # Authentication, including constructor ### - def __init__(self, client_id=None, client_secret=None, access_token=None, api_base_url=None, debug_requests=False, - ratelimit_method="wait", ratelimit_pacefactor=1.1, request_timeout=_DEFAULT_TIMEOUT, mastodon_version=None, - version_check_mode="created", session=None, feature_set="mainline", user_agent=_DEFAULT_USER_AGENT, lang=None): + def __init__(self, client_id: Optional[Union[str, PurePath]] = None, client_secret: Optional[str] = None, + access_token: Optional[Union[str, PurePath]] = None, api_base_url: Optional[str] = None, debug_requests: bool = False, + ratelimit_method: str = "wait", ratelimit_pacefactor: float = 1.1, request_timeout: float = _DEFAULT_TIMEOUT, + mastodon_version: Optional[str] =None, version_check_mode: str = "created", session: Optional[requests.Session] = None, + feature_set: str = "mainline", user_agent: str = _DEFAULT_USER_AGENT, lang: Optional[str] = None): """ Create a new API wrapper instance based on the given `client_secret` and `client_id` on the instance given by `api_base_url`. If you give a `client_id` and it is not a file, you must @@ -247,7 +252,9 @@ class Mastodon(Internals): if ratelimit_method not in ["throw", "wait", "pace"]: raise MastodonIllegalArgumentError("Invalid ratelimit method.") - def auth_request_url(self, client_id=None, redirect_uris="urn:ietf:wg:oauth:2.0:oob", scopes=_DEFAULT_SCOPES, force_login=False, state=None, lang=None): + def auth_request_url(self, client_id: Optional[Union[str, PurePath]] = None, redirect_uris: str = "urn:ietf:wg:oauth:2.0:oob", + scopes: List[str] =_DEFAULT_SCOPES, force_login: bool = False, state: Optional[str] = None, + lang: Optional[str] = None) -> str: """ Returns the URL that a client needs to request an OAuth grant from the server. @@ -256,8 +263,9 @@ class Mastodon(Internals): `scopes` are as in :ref:`log_in() `, redirect_uris is where the user should be redirected to after authentication. Note that `redirect_uris` must be one of the URLs given during - app registration. When using urn:ietf:wg:oauth:2.0:oob, the code is simply displayed, - otherwise it is added to the given URL as the "code" request parameter. + app registration, and that despite the plural-like name, you only get to use one here. + When using urn:ietf:wg:oauth:2.0:oob, the code is simply displayed, otherwise it is added + to the given URL as the "code" request parameter. Pass force_login if you want the user to always log in even when already logged into web Mastodon (i.e. when registering multiple different accounts in an app). @@ -269,6 +277,7 @@ class Mastodon(Internals): Pass an ISO 639-1 (two letter) or, for languages that do not have one, 639-3 (three letter) language code as `lang` to control the display language for the oauth form. """ + assert self.api_base_url is not None if client_id is None: client_id = self.client_id else: @@ -287,7 +296,9 @@ class Mastodon(Internals): formatted_params = urlencode(params) return "".join([self.api_base_url, "/oauth/authorize?", formatted_params]) - def log_in(self, username=None, password=None, code=None, redirect_uri="urn:ietf:wg:oauth:2.0:oob", refresh_token=None, scopes=_DEFAULT_SCOPES, to_file=None): + def log_in(self, username: Optional[str] = None, password: Optional[str] = None, code: Optional[str] = None, + redirect_uri: str = "urn:ietf:wg:oauth:2.0:oob", refresh_token: Optional[str] = None, scopes: List[str] = _DEFAULT_SCOPES, + to_file = Union[str, PurePath]) -> str: """ Get the access token for a user. @@ -346,12 +357,14 @@ class Mastodon(Internals): raise MastodonAPIError('Granted scopes "' + " ".join(received_scopes) + '" do not contain all of the requested scopes "' + " ".join(scopes) + '".') if to_file is not None: + assert self.api_base_url is not None + assert self.client_id is not None and isinstance(self.client_id, str) + assert self.client_secret is not None with open(to_file, 'w') as token_file: token_file.write(response['access_token'] + "\n") token_file.write(self.api_base_url + "\n") token_file.write(self.client_id + "\n") token_file.write(self.client_secret + "\n") - self.__logged_in_id = None # Retry version check if needed (might be required in limited federation mode) @@ -383,10 +396,8 @@ class Mastodon(Internals): # Reading data: Apps ### @api_version("2.0.0", "2.7.2", _DICT_VERSION_APPLICATION) - def app_verify_credentials(self): + def app_verify_credentials(self) -> Application: """ Fetch information about the current application. - - Returns an :ref:`application dict `. """ return self.__api_request('GET', '/api/v1/apps/verify_credentials') diff --git a/mastodon/conversations.py b/mastodon/conversations.py index 302acad..b25f21a 100644 --- a/mastodon/conversations.py +++ b/mastodon/conversations.py @@ -1,30 +1,30 @@ # conversations.py - conversation endpoints -from .versions import _DICT_VERSION_CONVERSATION -from .utility import api_version - -from .internals import Mastodon as Internals +from mastodon.versions import _DICT_VERSION_CONVERSATION +from mastodon.utility import api_version +from mastodon.internals import Mastodon as Internals +from typing import Union, Optional +from mastodon.types import IdType, PaginatableList, Conversation class Mastodon(Internals): ### # Reading data: Conversations ### @api_version("2.6.0", "2.6.0", _DICT_VERSION_CONVERSATION) - def conversations(self, max_id=None, min_id=None, since_id=None, limit=None): + def conversations(self, max_id: Optional[Union[Conversation, IdType]] = None, min_id: Optional[Union[Conversation, IdType]] = None, since_id: + Optional[Union[Conversation, IdType]] = None, limit: Optional[int] = None) -> PaginatableList[Conversation]: """ Fetches a user's conversations. - - Returns a list of :ref:`conversation dicts `. """ if max_id is not None: - max_id = self.__unpack_id(max_id, dateconv=True) + max_id = self.__unpack_id(max_id) if min_id is not None: - min_id = self.__unpack_id(min_id, dateconv=True) + min_id = self.__unpack_id(min_id) if since_id is not None: - since_id = self.__unpack_id(since_id, dateconv=True) + since_id = self.__unpack_id(since_id) params = self.__generate_params(locals()) return self.__api_request('GET', "/api/v1/conversations/", params) @@ -33,11 +33,11 @@ class Mastodon(Internals): # Writing data: Conversations ### @api_version("2.6.0", "2.6.0", _DICT_VERSION_CONVERSATION) - def conversations_read(self, id): + def conversations_read(self, id: Union[Conversation, IdType]): """ Marks a single conversation as read. - Returns the updated :ref:`conversation dict `. + The returned object reflects the conversation's new read status. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/conversations/{id}/read') diff --git a/mastodon/endorsements.py b/mastodon/endorsements.py index ed1569a..23d7a97 100644 --- a/mastodon/endorsements.py +++ b/mastodon/endorsements.py @@ -1,20 +1,18 @@ # notifications.py - endorsement endpoints -from .versions import _DICT_VERSION_ACCOUNT -from .utility import api_version - -from .internals import Mastodon as Internals +from mastodon.versions import _DICT_VERSION_ACCOUNT +from mastodon.utility import api_version +from mastodon.internals import Mastodon as Internals +from mastodon.types import Account, NonPaginatableList class Mastodon(Internals): ### # Reading data: Endorsements ### @api_version("2.5.0", "2.5.0", _DICT_VERSION_ACCOUNT) - def endorsements(self): + def endorsements(self) -> NonPaginatableList[Account]: """ Fetch list of users endorsed by the logged-in user. - - Returns a list of :ref:`account dicts `. """ return self.__api_request('GET', '/api/v1/endorsements') diff --git a/mastodon/favourites.py b/mastodon/favourites.py index 02d3d03..680675d 100644 --- a/mastodon/favourites.py +++ b/mastodon/favourites.py @@ -1,35 +1,36 @@ # favourites.py - favourites and also bookmarks -from .versions import _DICT_VERSION_STATUS -from .utility import api_version +from mastodon.versions import _DICT_VERSION_STATUS +from mastodon.utility import api_version -from .internals import Mastodon as Internals +from mastodon.internals import Mastodon as Internals +from mastodon.types import Status, IdType, PaginatableList +from typing import Optional, Union class Mastodon(Internals): ### # Reading data: Favourites ### @api_version("1.0.0", "2.6.0", _DICT_VERSION_STATUS) - def favourites(self, max_id=None, min_id=None, since_id=None, limit=None): + def favourites(self, max_id: Optional[IdType] = None, min_id: Optional[IdType] = None, + since_id: Optional[IdType] = None, limit: Optional[int] = None) -> PaginatableList[Status]: """ Fetch the logged-in user's favourited statuses. This endpoint uses internal ids for pagination, passing status ids to - `max_id`, `min_id`, or `since_id` will not work. Pagination functions - :ref:`fetch_next() ` - and :ref:`fetch_previous() ` should be used instead. + `max_id`, `min_id`, or `since_id` will not work. Returns a list of :ref:`status dicts `. """ if max_id is not None: - max_id = self.__unpack_id(max_id, dateconv=True) + max_id = self.__unpack_id(max_id) if min_id is not None: - min_id = self.__unpack_id(min_id, dateconv=True) + min_id = self.__unpack_id(min_id) if since_id is not None: - since_id = self.__unpack_id(since_id, dateconv=True) + since_id = self.__unpack_id(since_id) params = self.__generate_params(locals()) return self.__api_request('GET', '/api/v1/favourites', params) @@ -38,25 +39,22 @@ class Mastodon(Internals): # Reading data: Bookmarks ### @api_version("3.1.0", "3.1.0", _DICT_VERSION_STATUS) - def bookmarks(self, max_id=None, min_id=None, since_id=None, limit=None): + def bookmarks(self, max_id: Optional[IdType] = None, min_id: Optional[IdType] = None, + since_id: Optional[IdType] = None, limit: Optional[int] = None) -> PaginatableList[Status]: """ Get a list of statuses bookmarked by the logged-in user. This endpoint uses internal ids for pagination, passing status ids to - `max_id`, `min_id`, or `since_id` will not work. Pagination functions - :ref:`fetch_next() ` - and :ref:`fetch_previous() ` should be used instead. - - Returns a list of :ref:`status dicts `. + `max_id`, `min_id`, or `since_id` will not work. """ if max_id is not None: - max_id = self.__unpack_id(max_id, dateconv=True) + max_id = self.__unpack_id(max_id) if min_id is not None: - min_id = self.__unpack_id(min_id, dateconv=True) + min_id = self.__unpack_id(min_id) if since_id is not None: - since_id = self.__unpack_id(since_id, dateconv=True) + since_id = self.__unpack_id(since_id) params = self.__generate_params(locals()) return self.__api_request('GET', '/api/v1/bookmarks', params) diff --git a/mastodon/hashtags.py b/mastodon/hashtags.py index f550c7b..ddcbd87 100644 --- a/mastodon/hashtags.py +++ b/mastodon/hashtags.py @@ -1,31 +1,29 @@ # hashtags.py - hashtag and featured-hashtag endpoints -from .versions import _DICT_VERSION_FEATURED_TAG, _DICT_VERSION_HASHTAG -from .utility import api_version +from mastodon.versions import _DICT_VERSION_FEATURED_TAG, _DICT_VERSION_HASHTAG +from mastodon.utility import api_version -from .internals import Mastodon as Internals +from mastodon.internals import Mastodon as Internals +from mastodon.types import Tag, NonPaginatableList, FeaturedTag, IdType +from typing import Union class Mastodon(Internals): ### # Reading data: Featured hashtags ### @api_version("3.0.0", "3.0.0", _DICT_VERSION_FEATURED_TAG) - def featured_tags(self): + def featured_tags(self) -> NonPaginatableList[Tag]: """ Return the hashtags the logged-in user has set to be featured on their profile as a list of :ref:`featured tag dicts `. - - Returns a list of :ref:`featured tag dicts `. """ return self.__api_request('GET', '/api/v1/featured_tags') @api_version("3.0.0", "3.0.0", _DICT_VERSION_HASHTAG) - def featured_tag_suggestions(self): + def featured_tag_suggestions(self) -> NonPaginatableList[Tag]: """ Returns the logged-in user's 10 most commonly-used hashtags. - - Returns a list of :ref:`hashtag dicts `. """ return self.__api_request('GET', '/api/v1/featured_tags/suggestions') @@ -33,17 +31,17 @@ class Mastodon(Internals): # Writing data: Featured hashtags ### @api_version("3.0.0", "3.0.0", _DICT_VERSION_FEATURED_TAG) - def featured_tag_create(self, name): + def featured_tag_create(self, name: str) -> FeaturedTag: """ Creates a new featured hashtag displayed on the logged-in user's profile. - Returns a :ref:`featured tag dict ` with the newly featured tag. + The returned object is the newly featured tag. """ params = self.__generate_params(locals()) return self.__api_request('POST', '/api/v1/featured_tags', params) @api_version("3.0.0", "3.0.0", _DICT_VERSION_FEATURED_TAG) - def featured_tag_delete(self, id): + def featured_tag_delete(self, id: Union[FeaturedTag, IdType]): """ Deletes one of the logged-in user's featured hashtags. """ diff --git a/mastodon/instance.py b/mastodon/instance.py index f8f170a..97f43ba 100644 --- a/mastodon/instance.py +++ b/mastodon/instance.py @@ -1,49 +1,74 @@ # instance.py - instance-level endpoints, directory, emoji, announcements -from .versions import _DICT_VERSION_INSTANCE, _DICT_VERSION_ACTIVITY, _DICT_VERSION_ACCOUNT, _DICT_VERSION_EMOJI, _DICT_VERSION_ANNOUNCEMENT -from .errors import MastodonIllegalArgumentError, MastodonNotFoundError -from .utility import api_version -from .compat import urlparse +from mastodon.versions import _DICT_VERSION_INSTANCE, _DICT_VERSION_ACTIVITY, _DICT_VERSION_ACCOUNT, _DICT_VERSION_EMOJI, _DICT_VERSION_ANNOUNCEMENT +from mastodon.errors import MastodonIllegalArgumentError, MastodonNotFoundError +from mastodon.utility import api_version +from mastodon.compat import urlparse -from .internals import Mastodon as Internals +from mastodon.internals import Mastodon as Internals +from mastodon.types import Instance, InstanceV2, NonPaginatableList, Activity, Nodeinfo, AttribAccessDict, Rule, Announcement, CustomEmoji, Account, IdType +from typing import Union, Optional class Mastodon(Internals): ### # Reading data: Instances ### @api_version("1.1.0", "2.3.0", _DICT_VERSION_INSTANCE) - def instance(self): + def instance_v1(self) -> Instance: """ Retrieve basic information about the instance, including the URI and administrative contact email. Does not require authentication unless locked down by the administrator. + This is the explicit v1 version of this function. The v2 version is available through instance_v2(). + It contains a bit more information than this one, but does not include whether invites are enabled. + Returns an :ref:`instance dict `. """ return self.__instance() def __instance(self): """ - Internal, non-version-checking helper that does the same as instance() + Internal, non-version-checking helper that does the same as instance_v1() """ instance = self.__api_request('GET', '/api/v1/instance/') return instance + @api_version("4.0.0", "4.0.0", _DICT_VERSION_INSTANCE) + def instance_v2(self) -> InstanceV2: + """ + Retrieve basic information about the instance, including the URI and administrative contact email. + + Does not require authentication unless locked down by the administrator. This is the explicit v2 variant. + + Returns an :ref:`instance dict `. + """ + return self.__api_request('GET', '/api/v2/instance/') + + @api_version("1.1.0", "4.0.0", _DICT_VERSION_INSTANCE) + def instance(self) -> Union[Instance, InstanceV2]: + """ + Retrieve basic information about the instance, including the URI and administrative contact email. + + Does not require authentication unless locked down by the administrator. + + Returns an :ref:`instance dict `. + """ + return self.__api_request('GET', '/api/v2/instance/') + @api_version("2.1.2", "2.1.2", _DICT_VERSION_ACTIVITY) - def instance_activity(self): + def instance_activity(self) -> NonPaginatableList[Activity]: """ Retrieve activity stats about the instance. May be disabled by the instance administrator - throws a MastodonNotFoundError in that case. Activity is returned for 12 weeks going back from the current week. - - Returns a list of :ref:`activity dicts `. """ return self.__api_request('GET', '/api/v1/instance/activity') @api_version("2.1.2", "2.1.2", "2.1.2") - def instance_peers(self): + def instance_peers(self) -> NonPaginatableList[str]: """ Retrieve the instances that this instance knows about. May be disabled by the instance administrator - throws a MastodonNotFoundError in that case. @@ -53,7 +78,7 @@ class Mastodon(Internals): return self.__api_request('GET', '/api/v1/instance/peers') @api_version("3.0.0", "3.0.0", "3.0.0") - def instance_health(self): + def instance_health(self) -> bool: """ Basic health check. Returns True if healthy, False if not. """ @@ -61,13 +86,15 @@ class Mastodon(Internals): return status in ["OK", "success"] @api_version("3.0.0", "3.0.0", "3.0.0") - def instance_nodeinfo(self, schema="http://nodeinfo.diaspora.software/ns/schema/2.0"): + def instance_nodeinfo(self, schema: str = "http://nodeinfo.diaspora.software/ns/schema/2.0") -> Union[Nodeinfo, AttribAccessDict]: """ Retrieves the instance's nodeinfo information. For information on what the nodeinfo can contain, see the nodeinfo specification: https://github.com/jhass/nodeinfo . By default, - Mastodon.py will try to retrieve the version 2.0 schema nodeinfo. + Mastodon.py will try to retrieve the version 2.0 schema nodeinfo, for which + we have a well defined return object. If you go outside of that, all bets + are off. To override the schema, specify the desired schema with the `schema` parameter. @@ -90,11 +117,9 @@ class Mastodon(Internals): return self.__api_request('GET', parse.path + parse.params + parse.query + parse.fragment) @api_version("3.4.0", "3.4.0", _DICT_VERSION_INSTANCE) - def instance_rules(self): + def instance_rules(self) -> NonPaginatableList[Rule]: """ Retrieve instance rules. - - Returns a list of `id` + `text` dicts, same as the `rules` field in the :ref:`instance dicts `. """ return self.__api_request('GET', '/api/v1/instance/rules') @@ -102,7 +127,8 @@ class Mastodon(Internals): # Reading data: Directory ### @api_version("3.0.0", "3.0.0", _DICT_VERSION_ACCOUNT) - def directory(self, offset=None, limit=None, order=None, local=None): + def directory(self, offset: Optional[int] = None, limit: Optional[int] = None, + order: Optional[str] = None, local: Optional[bool] = None) -> NonPaginatableList[Account]: """ Fetch the contents of the profile directory, if enabled on the server. @@ -110,13 +136,13 @@ class Mastodon(Internals): `limit` how many accounts to load. Default 40. - `order` "active" to sort by most recently posted statuses (default) or + `order` "active" to sort by most recently posted statuses (usually the default) or "new" to sort by most recently created profiles. `local` True to return only local accounts. - Returns a list of :ref:`account dicts `. - + Uses offset/limit pagination, not currently handled by the pagination utility functions, + do it manually if you have to. """ params = self.__generate_params(locals()) return self.__api_request('GET', '/api/v1/directory', params) @@ -125,13 +151,11 @@ class Mastodon(Internals): # Reading data: Emoji ### @api_version("2.1.0", "2.1.0", _DICT_VERSION_EMOJI) - def custom_emojis(self): + def custom_emojis(self) -> NonPaginatableList[CustomEmoji]: """ Fetch the list of custom emoji the instance has installed. Does not require authentication unless locked down by the administrator. - - Returns a list of :ref:`emoji dicts `. """ return self.__api_request('GET', '/api/v1/custom_emojis') @@ -139,7 +163,7 @@ class Mastodon(Internals): # Reading data: Announcements ## @api_version("3.1.0", "3.1.0", _DICT_VERSION_ANNOUNCEMENT) - def announcements(self): + def announcements(self) -> NonPaginatableList[Announcement]: """ Fetch currently active announcements. @@ -151,16 +175,15 @@ class Mastodon(Internals): # Writing data: Annoucements ### @api_version("3.1.0", "3.1.0", "3.1.0") - def announcement_dismiss(self, id): + def announcement_dismiss(self, id: Union[Announcement, IdType]): """ Set the given annoucement to read. """ id = self.__unpack_id(id) - self.__api_request('POST', f'/api/v1/announcements/{id}/dismiss') @api_version("3.1.0", "3.1.0", "3.1.0") - def announcement_reaction_create(self, id, reaction): + def announcement_reaction_create(self, id: Union[Announcement, IdType], reaction: str): """ Add a reaction to an announcement. `reaction` can either be a unicode emoji or the name of one of the instances custom emoji. @@ -170,16 +193,14 @@ class Mastodon(Internals): reaction that a different user added is legal and increments the count). """ id = self.__unpack_id(id) - self.__api_request('PUT', f'/api/v1/announcements/{id}/reactions/{reaction}') @api_version("3.1.0", "3.1.0", "3.1.0") - def announcement_reaction_delete(self, id, reaction): + def announcement_reaction_delete(self, id: Union[Announcement, IdType], reaction: str): """ Remove a reaction to an announcement. Will throw an API error if the reaction does not exist. """ id = self.__unpack_id(id) - self.__api_request('DELETE', f'/api/v1/announcements/{id}/reactions/{reaction}') diff --git a/mastodon/internals.py b/mastodon/internals.py index ad54f54..61cac86 100644 --- a/mastodon/internals.py +++ b/mastodon/internals.py @@ -1,6 +1,6 @@ # internals.py - many internal helpers -import datetime +from datetime import timezone, datetime from contextlib import closing import mimetypes import threading @@ -14,20 +14,22 @@ import re import collections import base64 import os +import inspect -from .utility import AttribAccessDict, AttribAccessList, parse_version_string -from .errors import MastodonNetworkError, MastodonIllegalArgumentError, MastodonRatelimitError, MastodonNotFoundError, \ +from mastodon.versions import parse_version_string +from mastodon.errors import MastodonNetworkError, MastodonIllegalArgumentError, MastodonRatelimitError, MastodonNotFoundError, \ MastodonUnauthorizedError, MastodonInternalServerError, MastodonBadGatewayError, MastodonServiceUnavailableError, \ MastodonGatewayTimeoutError, MastodonServerError, MastodonAPIError, MastodonMalformedEventError -from .compat import urlparse, magic, PurePath, Path -from .defaults import _DEFAULT_STREAM_TIMEOUT, _DEFAULT_STREAM_RECONNECT_WAIT_SEC - +from mastodon.compat import urlparse, magic, PurePath, Path +from mastodon.defaults import _DEFAULT_STREAM_TIMEOUT, _DEFAULT_STREAM_RECONNECT_WAIT_SEC +from mastodon.types import AttribAccessDict, try_cast_recurse +from mastodon.types import * ### # Internal helpers, dragons probably ### class Mastodon(): - def __datetime_to_epoch(self, date_time): + def __datetime_to_epoch(self, date_time: datetime) -> float: """ Converts a python datetime to unix epoch, accounting for time zones and such. @@ -35,7 +37,7 @@ class Mastodon(): Assumes UTC if timezone is not given. """ if date_time.tzinfo is None: - date_time = date_time.replace(tzinfo=datetime.timezone.utc) + date_time = date_time.replace(tzinfo=timezone.utc) return date_time.timestamp() def __get_logged_in_id(self): @@ -47,94 +49,48 @@ class Mastodon(): return self.__logged_in_id @staticmethod - def __json_allow_dict_attrs(json_object): - """ - Makes it possible to use attribute notation to access a dicts - elements, while still allowing the dict to act as a dict. - """ - if isinstance(json_object, dict): - return AttribAccessDict(json_object) - return json_object - - @staticmethod - def __json_date_parse(json_object): - """ - Parse dates in certain known json fields, if possible. - """ - known_date_fields = ["created_at", "week", "day", "expires_at", "scheduled_at", - "updated_at", "last_status_at", "starts_at", "ends_at", "published_at", "edited_at", "date", "period"] - mark_delete = [] - for k, v in json_object.items(): - if k in known_date_fields: - if v is not None: - try: - if isinstance(v, int): - json_object[k] = datetime.datetime.fromtimestamp(v, datetime.timezone.utc) - else: - json_object[k] = dateutil.parser.parse(v) - except: - # When we can't parse a date, we just leave the field out - mark_delete.append(k) - # Two step process because otherwise python gets very upset - for k in mark_delete: - del json_object[k] - return json_object - - @staticmethod - def __json_truefalse_parse(json_object): - """ - Parse 'True' / 'False' strings in certain known fields - """ - for key in ('follow', 'favourite', 'reblog', 'mention', 'confirmed', 'suspended', 'silenced', 'disabled', 'approved', 'all_day'): - if (key in json_object and isinstance(json_object[key], six.text_type)): - if json_object[key].lower() == 'true': - json_object[key] = True - if json_object[key].lower() == 'false': - json_object[key] = False - return json_object - - @staticmethod - def __json_strnum_to_bignum(json_object): - """ - Converts json string numerals to native python bignums. - """ - for key in ('id', 'week', 'in_reply_to_id', 'in_reply_to_account_id', 'logins', 'registrations', 'statuses', - 'day', 'last_read_id', 'value', 'frequency', 'rate', 'invited_by_account_id', 'count'): - if (key in json_object and isinstance(json_object[key], six.text_type)): - try: - json_object[key] = int(json_object[key]) - except ValueError: - pass - - return json_object - - @staticmethod - def __json_hooks(json_object): - """ - All the json hooks. Used in request parsing. - """ - json_object = Mastodon.__json_strnum_to_bignum(json_object) - json_object = Mastodon.__json_date_parse(json_object) - json_object = Mastodon.__json_truefalse_parse(json_object) - json_object = Mastodon.__json_allow_dict_attrs(json_object) - return json_object - - @staticmethod - def __consistent_isoformat_utc(datetime_val): + def __consistent_isoformat_utc(datetime_val: datetime) -> str: """ Function that does what isoformat does but it actually does the same every time instead of randomly doing different things on some systems and also it represents that time as the equivalent UTC time. """ - isotime = datetime_val.astimezone(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%S%z") + isotime = datetime_val.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S%z") if isotime[-2] != ":": isotime = isotime[:-2] + ":" + isotime[-2:] return isotime + def __try_cast_to_type(self, value, override_type = None): + """ + Tries to cast a value to the type of the function two levels up in the call stack. + Tries to cast to AttribAccessDict if it doesn't know what to cast to. + + This is used internally inside of __api_request. + """ + try: + if override_type is None: + # Find type of function two frames up + caller_frame = inspect.currentframe().f_back.f_back + caller_function = caller_frame.f_code + caller_func_name = caller_function.co_name + func_obj = getattr(self, caller_func_name) + + # Very carefully try to find what we need to cast to + return_type = AttribAccessDict + if func_obj is not None: + return_type = func_obj.__annotations__.get('return', AttribAccessDict) + else: + return_type = override_type + except: + return_type = AttribAccessDict + return try_cast_recurse(return_type, value) + def __api_request(self, method, endpoint, params={}, files={}, headers={}, access_token_override=None, base_url_override=None, - do_ratelimiting=True, use_json=False, parse=True, return_response_object=False, skip_error_check=False, lang_override=None): + do_ratelimiting=True, use_json=False, parse=True, return_response_object=False, skip_error_check=False, lang_override=None, override_type=None): """ Internal API request helper. + + Does a large amount of different things that I should document one day, but not today. """ response = None remaining_wait = 0 @@ -248,7 +204,7 @@ class Mastodon(): if not response_object.ok: try: - response = response_object.json(object_hook=self.__json_hooks) + response = self.__try_cast_to_type(response_object.json(), override_type = override_type) # TODO actually cast to an error type if isinstance(response, dict) and 'error' in response: error_msg = response['error'] elif isinstance(response, str): @@ -301,12 +257,16 @@ class Mastodon(): if parse: try: - response = response_object.json(object_hook=self.__json_hooks) - except: + # The new parsing is very basic, type conversion happens later, + # within the new type system. This should be overall more robust. + response = response_object.json() + except Exception as e: raise MastodonAPIError( f"Could not parse response as JSON, response code was {response_object.status_code}, " - f"bad json content was {response_object.content!r}." + f"bad json content was {response_object.content!r}.", + f"Exception was: {e}" ) + response = self.__try_cast_to_type(response, override_type = override_type) else: response = response_object.content @@ -391,10 +351,10 @@ class Mastodon(): # Will be removed in future if isinstance(response[0], AttribAccessDict): response[0]._pagination_prev = prev_params - + return response - def __get_streaming_base(self): + def __get_streaming_base(self) -> str: """ Internal streaming API helper. @@ -415,6 +375,7 @@ class Mastodon(): ) else: url = self.api_base_url + assert not url is None return url def __stream(self, endpoint, listener, params={}, run_async=False, timeout=_DEFAULT_STREAM_TIMEOUT, reconnect_async=False, reconnect_async_wait_sec=_DEFAULT_STREAM_RECONNECT_WAIT_SEC): @@ -570,7 +531,7 @@ class Mastodon(): return params - def __unpack_id(self, id, dateconv=False): + def __unpack_id(self, id, dateconv = False, listify = False): """ Internal object-to-id converter @@ -579,10 +540,18 @@ class Mastodon(): the id straight. Also unpacks datetimes to snowflake IDs if requested. + + TODO: Rework this to use the new type system. """ + if not isinstance(id, list) and listify: + id = [id] + if isinstance(id, list): + for i in range(len(id)): + id[i] = self.__unpack_id(id[i], dateconv = dateconv, listify = False) + return id if isinstance(id, dict) and "id" in id: id = id["id"] - if dateconv and isinstance(id, datetime.datetime): + if dateconv and isinstance(id, datetime): id = (int(id.timestamp()) << 16) * 1000 return id @@ -623,6 +592,7 @@ class Mastodon(): return mime_type def __load_media_file(self, media_file, mime_type=None, file_name=None): + """Internal helper to load a media file""" if isinstance(media_file, PurePath): media_file = str(media_file) if isinstance(media_file, str): diff --git a/mastodon/lists.py b/mastodon/lists.py index ccfa5c0..1dd001e 100644 --- a/mastodon/lists.py +++ b/mastodon/lists.py @@ -1,51 +1,49 @@ # list.py - list endpoints -from .versions import _DICT_VERSION_LIST, _DICT_VERSION_ACCOUNT -from .utility import api_version +from mastodon.versions import _DICT_VERSION_LIST, _DICT_VERSION_ACCOUNT +from mastodon.utility import api_version -from .internals import Mastodon as Internals +from mastodon.internals import Mastodon as Internals +from mastodon.types import NonPaginatableList, UserList, IdType, PaginatableList, Account +from typing import List, Union, Optional class Mastodon(Internals): ### # Reading data: Lists ### @api_version("2.1.0", "2.1.0", _DICT_VERSION_LIST) - def lists(self): + def lists(self) -> NonPaginatableList[UserList]: """ Fetch a list of all the Lists by the logged-in user. - - Returns a list of :ref:`list dicts `. """ return self.__api_request('GET', '/api/v1/lists') @api_version("2.1.0", "2.1.0", _DICT_VERSION_LIST) - def list(self, id): + def list(self, id: Union[UserList, IdType]) -> UserList: """ Fetch info about a specific list. - - Returns a :ref:`list dict `. """ id = self.__unpack_id(id) return self.__api_request('GET', f'/api/v1/lists/{id}') @api_version("2.1.0", "2.6.0", _DICT_VERSION_ACCOUNT) - def list_accounts(self, id, max_id=None, min_id=None, since_id=None, limit=None): + def list_accounts(self, id: Union[UserList, IdType], max_id: Optional[Union[UserList, IdType]] = None, + min_id: Optional[Union[UserList, IdType]] = None, since_id: Optional[Union[UserList, IdType]] = None, + limit: Optional[int] = None) -> PaginatableList[Account]: """ Get the accounts that are on the given list. - - Returns a list of :ref:`account dicts `. """ id = self.__unpack_id(id) if max_id is not None: - max_id = self.__unpack_id(max_id, dateconv=True) + max_id = self.__unpack_id(max_id) if min_id is not None: - min_id = self.__unpack_id(min_id, dateconv=True) + min_id = self.__unpack_id(min_id) if since_id is not None: - since_id = self.__unpack_id(since_id, dateconv=True) + since_id = self.__unpack_id(since_id) params = self.__generate_params(locals(), ['id']) return self.__api_request('GET', f'/api/v1/lists/{id}/accounts', params) @@ -54,28 +52,26 @@ class Mastodon(Internals): # Writing data: Lists ### @api_version("2.1.0", "2.1.0", _DICT_VERSION_LIST) - def list_create(self, title): + def list_create(self, title: str) -> UserList: """ Create a new list with the given `title`. - - Returns the :ref:`list dict ` of the created list. """ params = self.__generate_params(locals()) return self.__api_request('POST', '/api/v1/lists', params) @api_version("2.1.0", "2.1.0", _DICT_VERSION_LIST) - def list_update(self, id, title): + def list_update(self, id: Union[UserList, IdType], title: str) -> UserList: """ Update info about a list, where "info" is really the lists `title`. - Returns the :ref:`list dict ` of the modified list. + The returned object reflects the updated list. """ id = self.__unpack_id(id) params = self.__generate_params(locals(), ['id']) return self.__api_request('PUT', f'/api/v1/lists/{id}', params) @api_version("2.1.0", "2.1.0", "2.1.0") - def list_delete(self, id): + def list_delete(self, id: Union[UserList, IdType]): """ Delete a list. """ @@ -83,29 +79,22 @@ class Mastodon(Internals): self.__api_request('DELETE', f'/api/v1/lists/{id}') @api_version("2.1.0", "2.1.0", "2.1.0") - def list_accounts_add(self, id, account_ids): + def list_accounts_add(self, id: Union[UserList, IdType], account_ids: List[Union[Account, IdType]]): """ Add the account(s) given in `account_ids` to the list. """ id = self.__unpack_id(id) - - if not isinstance(account_ids, list): - account_ids = [account_ids] - account_ids = [self.__unpack_id(x) for x in account_ids] + account_ids = self.__unpack_id(account_ids, listify = True) params = self.__generate_params(locals(), ['id']) self.__api_request('POST', f'/api/v1/lists/{id}/accounts', params) @api_version("2.1.0", "2.1.0", "2.1.0") - def list_accounts_delete(self, id, account_ids): + def list_accounts_delete(self, id: Union[UserList, IdType], account_ids: List[Union[Account, IdType]]): """ Remove the account(s) given in `account_ids` from the list. """ id = self.__unpack_id(id) - - if not isinstance(account_ids, list): - account_ids = [account_ids] - account_ids = [self.__unpack_id(x) for x in account_ids] - + account_ids = self.__unpack_id(account_ids, listify = True) params = self.__generate_params(locals(), ['id']) self.__api_request('DELETE', f'/api/v1/lists/{id}/accounts', params) diff --git a/mastodon/media.py b/mastodon/media.py index 6d8674a..f8a95f8 100644 --- a/mastodon/media.py +++ b/mastodon/media.py @@ -2,19 +2,21 @@ import time -from .versions import _DICT_VERSION_MEDIA -from .errors import MastodonVersionError, MastodonAPIError -from .utility import api_version +from mastodon.versions import _DICT_VERSION_MEDIA +from mastodon.errors import MastodonVersionError, MastodonAPIError +from mastodon.utility import api_version -from .internals import Mastodon as Internals +from mastodon.internals import Mastodon as Internals +from mastodon.types import MediaAttachment, PathOrFile, IdType +from typing import Optional, Union, Tuple, List, Dict, Any class Mastodon(Internals): ### # Reading data: Media ### @api_version("3.1.4", "3.1.4", _DICT_VERSION_MEDIA) - def media(self, id): + def media(self, id: Union[MediaAttachment, IdType]) -> MediaAttachment: """ Get the updated JSON for one non-attached / in progress media upload belonging to the logged-in user. @@ -26,7 +28,10 @@ class Mastodon(Internals): # Writing data: Media ### @api_version("1.0.0", "3.2.0", _DICT_VERSION_MEDIA) - def media_post(self, media_file, mime_type=None, description=None, focus=None, file_name=None, thumbnail=None, thumbnail_mime_type=None, synchronous=False): + def media_post(self, media_file: PathOrFile, mime_type: Optional[str] = None, description: Optional[str] = None, + focus: Optional[Tuple[float, float]] = None, file_name: Optional[str] = None, + thumbnail: Optional[PathOrFile] = None, thumbnail_mime_type: Optional[str] = None, + synchronous: bool = False) -> MediaAttachment: """ Post an image, video or audio file. `media_file` can either be data or a file name. If data is passed directly, the mime type has to be specified @@ -63,8 +68,7 @@ class Mastodon(Internals): if thumbnail is not None: if not self.verify_minimum_version("3.2.0", cached=True): raise MastodonVersionError('Thumbnail requires version > 3.2.0') - files["thumbnail"] = self.__load_media_file( - thumbnail, thumbnail_mime_type) + files["thumbnail"] = self.__load_media_file(thumbnail, thumbnail_mime_type) # Disambiguate URL by version if self.verify_minimum_version("3.1.4", cached=True): @@ -90,12 +94,14 @@ class Mastodon(Internals): return ret_dict @api_version("2.3.0", "3.2.0", _DICT_VERSION_MEDIA) - def media_update(self, id, description=None, focus=None, thumbnail=None, thumbnail_mime_type=None): + def media_update(self, id: Union[MediaAttachment, IdType], description: Optional[str] = None, + focus: Optional[Tuple[float, float]] = None, thumbnail: Optional[PathOrFile] = None, + thumbnail_mime_type=None) -> MediaAttachment: """ Update the metadata of the media file with the given `id`. `description` and `focus` and `thumbnail` are as in :ref:`media_post() ` . - - Returns the updated :ref:`media dict `. + + The returned dict reflects the updates to the media attachment. """ id = self.__unpack_id(id) diff --git a/mastodon/notifications.py b/mastodon/notifications.py index e2c6a17..017731e 100644 --- a/mastodon/notifications.py +++ b/mastodon/notifications.py @@ -1,18 +1,21 @@ # notifications.py - notification endpoints -from .versions import _DICT_VERSION_NOTIFICATION -from .errors import MastodonIllegalArgumentError -from .utility import api_version - -from .internals import Mastodon as Internals +from mastodon.versions import _DICT_VERSION_NOTIFICATION +from mastodon.errors import MastodonIllegalArgumentError +from mastodon.utility import api_version +from mastodon.internals import Mastodon as Internals +from mastodon.types import Notification, IdType, PaginatableList, Account +from typing import Union, Optional, List class Mastodon(Internals): ### # Reading data: Notifications ### @api_version("1.0.0", "3.5.0", _DICT_VERSION_NOTIFICATION) - def notifications(self, id=None, account_id=None, max_id=None, min_id=None, since_id=None, limit=None, exclude_types=None, types=None, mentions_only=None): + def notifications(self, id: Optional[Union[Notification, IdType]] = None, account_id: Optional[Union[Account, IdType]] = None, max_id: Optional[Union[Notification, IdType]] = None, + min_id: Optional[Union[Notification, IdType]] = None, since_id: Optional[Union[Notification, IdType]] = None, limit: Optional[int] = None, + exclude_types: Optional[List[str]] = None, types: Optional[List[str]] = None, mentions_only: Optional[bool] = None) -> PaginatableList[Notification]: """ Fetch notifications (mentions, favourites, reblogs, follows) for the logged-in user. Pass `account_id` to get only notifications originating from the given account. @@ -49,13 +52,13 @@ class Mastodon(Internals): del mentions_only if max_id is not None: - max_id = self.__unpack_id(max_id, dateconv=True) + max_id = self.__unpack_id(max_id) if min_id is not None: - min_id = self.__unpack_id(min_id, dateconv=True) + min_id = self.__unpack_id(min_id) if since_id is not None: - since_id = self.__unpack_id(since_id, dateconv=True) + since_id = self.__unpack_id(since_id) if account_id is not None: account_id = self.__unpack_id(account_id) @@ -78,7 +81,7 @@ class Mastodon(Internals): self.__api_request('POST', '/api/v1/notifications/clear') @api_version("1.3.0", "2.9.2", "2.9.2") - def notifications_dismiss(self, id): + def notifications_dismiss(self, id: Union[Notification, IdType]): """ Deletes a single notification """ diff --git a/mastodon/polls.py b/mastodon/polls.py index feb766a..20a1d87 100644 --- a/mastodon/polls.py +++ b/mastodon/polls.py @@ -1,21 +1,20 @@ # polls.py - poll related endpoints and tooling -from .versions import _DICT_VERSION_POLL -from .utility import api_version - -from .internals import Mastodon as Internals +from mastodon.versions import _DICT_VERSION_POLL +from mastodon.utility import api_version +from mastodon.internals import Mastodon as Internals +from mastodon.types import Poll, IdType +from typing import Union, List class Mastodon(Internals): ### # Reading data: Polls ### @api_version("2.8.0", "2.8.0", _DICT_VERSION_POLL) - def poll(self, id): + def poll(self, id: Union[Poll, IdType]) -> Poll: """ Fetch information about the poll with the given id - - Returns a :ref:`poll dict `. """ id = self.__unpack_id(id) return self.__api_request('GET', f'/api/v1/polls/{id}') @@ -24,7 +23,7 @@ class Mastodon(Internals): # Writing data: Polls ### @api_version("2.8.0", "2.8.0", _DICT_VERSION_POLL) - def poll_vote(self, id, choices): + def poll_vote(self, id: Union[Poll, IdType], choices: Union[int, List[int]]) -> Poll: """ Vote in the given poll. @@ -37,7 +36,7 @@ class Mastodon(Internals): single-option polls, or only once per option in case of multi-option polls. - Returns the updated :ref:`poll dict ` + The returned object will reflect the updated votes. """ id = self.__unpack_id(id) if not isinstance(choices, list): @@ -46,12 +45,14 @@ class Mastodon(Internals): return self.__api_request('POST', f'/api/v1/polls/{id}/votes', params) - def make_poll(self, options, expires_in, multiple=False, hide_totals=False): + @api_version("2.8.0", "2.8.0", _DICT_VERSION_POLL) + def make_poll(self, options: List[str], expires_in: int, multiple: bool = False, hide_totals: bool = False) -> Poll: """ Generate a poll object that can be passed as the `poll` option when posting a status. - options is an array of strings with the poll options (Maximum, by default: 4), - expires_in is the time in seconds for which the poll should be open. + `options` is an array of strings with the poll options (Maximum, by default: 4 - see + the instance configuration for the actual value on any given instance, if stated). + `expires_in` is the time in seconds for which the poll should be open. Set multiple to True to allow people to choose more than one answer. Set hide_totals to True to hide the results of the poll until it has expired. """ diff --git a/mastodon/preferences.py b/mastodon/preferences.py index 0011eb1..291dae1 100644 --- a/mastodon/preferences.py +++ b/mastodon/preferences.py @@ -2,19 +2,20 @@ import collections -from .versions import _DICT_VERSION_PREFERENCES, _DICT_VERSION_MARKER -from .errors import MastodonIllegalArgumentError -from .utility import api_version - -from .internals import Mastodon as Internals +from mastodon.versions import _DICT_VERSION_PREFERENCES, _DICT_VERSION_MARKER +from mastodon.errors import MastodonIllegalArgumentError +from mastodon.utility import api_version +from mastodon.internals import Mastodon as Internals +from mastodon.types import Preferences, Marker, Status, IdType +from typing import Union, List, Dict class Mastodon(Internals): ### # Reading data: Preferences ### @api_version("2.8.0", "2.8.0", _DICT_VERSION_PREFERENCES) - def preferences(self): + def preferences(self) -> Preferences: """ Fetch the user's preferences, which can be used to set some default options. As of 2.8.0, apps can only fetch, not update preferences. @@ -27,7 +28,7 @@ class Mastodon(Internals): # Reading data: Read markers ## @api_version("3.0.0", "3.0.0", _DICT_VERSION_MARKER) - def markers_get(self, timeline=["home"]): + def markers_get(self, timeline: Union[str, List[str]] = ["home"]) -> List[Marker]: """ Get the last-read-location markers for the specified timelines. Valid timelines are the same as in :ref:`timeline() ` @@ -46,13 +47,13 @@ class Mastodon(Internals): # Writing data: Read markers ## @api_version("3.0.0", "3.0.0", _DICT_VERSION_MARKER) - def markers_set(self, timelines, last_read_ids): + def markers_set(self, timelines: Union[str, List[str]], last_read_ids: Union[Status, IdType, List[Status], List[IdType]]) -> Dict[str, Marker]: """ Set the "last read" marker(s) for the given timeline(s) to the given id(s) Note that if you give an invalid timeline name, this will silently do nothing. - Returns a dict with the updated :ref:`read marker dicts `, keyed by timeline name. + Returns a dict with the updated markers, keyed by timeline name. """ if not isinstance(timelines, (list, tuple)): timelines = [timelines] diff --git a/mastodon/push.py b/mastodon/push.py index 8d63349..c3d345e 100644 --- a/mastodon/push.py +++ b/mastodon/push.py @@ -4,36 +4,39 @@ import base64 import os import json -from .versions import _DICT_VERSION_PUSH, _DICT_VERSION_PUSH_NOTIF -from .errors import MastodonIllegalArgumentError -from .utility import api_version -from .compat import IMPL_HAS_CRYPTO, ec, serialization, default_backend -from .compat import IMPL_HAS_ECE, http_ece - -from .internals import Mastodon as Internals +from mastodon.versions import _DICT_VERSION_PUSH, _DICT_VERSION_PUSH_NOTIF +from mastodon.errors import MastodonIllegalArgumentError +from mastodon.utility import api_version +from mastodon.compat import IMPL_HAS_CRYPTO, ec, serialization, default_backend +from mastodon.compat import IMPL_HAS_ECE, http_ece +from mastodon.internals import Mastodon as Internals +from mastodon.types import WebpushCryptoParamsPubkey, WebpushCryptoParamsPrivkey, WebPushSubscription, PushNotification, try_cast_recurse +from typing import Optional, Tuple class Mastodon(Internals): ### # Reading data: Webpush subscriptions ### @api_version("2.4.0", "2.4.0", _DICT_VERSION_PUSH) - def push_subscription(self): + def push_subscription(self) -> WebPushSubscription: """ Fetch the current push subscription the logged-in user has for this app. - Returns a :ref:`push subscription dict `. + Only one webpush subscription can be active at a time for any given app. """ return self.__api_request('GET', '/api/v1/push/subscription') ### # Writing data: Push subscriptions ### - @api_version("2.4.0", "2.4.0", _DICT_VERSION_PUSH) - def push_subscription_set(self, endpoint, encrypt_params, follow_events=None, - favourite_events=None, reblog_events=None, - mention_events=None, poll_events=None, - follow_request_events=None, status_events=None, policy='all'): + @api_version("2.4.0", "4..0", _DICT_VERSION_PUSH) + def push_subscription_set(self, endpoint: str, encrypt_params: WebpushCryptoParamsPubkey, follow_events: Optional[bool] = None, + favourite_events: Optional[bool] = None, reblog_events: Optional[bool] = None, + mention_events: Optional[bool] = None, poll_events: Optional[bool] = None, + follow_request_events: Optional[bool] = None, status_events: Optional[bool] = None, + policy: str = 'all', update_events: Optional[bool] = None, admin_sign_up_events: Optional[bool] = None, + admin_report_events: Optional[bool] = None) -> WebPushSubscription: """ Sets up or modifies the push subscription the logged-in user has for this app. @@ -47,6 +50,18 @@ class Mastodon(Internals): `all`, `none`, `follower` and `followed`. The rest of the parameters controls what kind of events you wish to subscribe to. + Events whose names start with "admin" require admin privileges to subscribe to. + + * `follow_events` controls whether you receive events when someone follows the logged in user. + * `favourite_events` controls whether you receive events when someone favourites one of the logged in users statuses. + * `reblog_events` controls whether you receive events when someone boosts one of the logged in users statuses. + * `mention_events` controls whether you receive events when someone mentions the logged in user in a status. + * `poll_events` controls whether you receive events when a poll the logged in user has voted in has ended. + * `follow_request_events` controls whether you receive events when someone requests to follow the logged in user. + * `status_events` controls whether you receive events when someone the logged in user has subscribed to notifications for posts a new status. + * `update_events` controls whether you receive events when a status that the logged in user has boosted has been edited. + * `admin_sign_up_events` controls whether you receive events when a new user signs up. + * `admin_report_events` controls whether you receive events when a new report is received. Returns a :ref:`push subscription dict `. """ @@ -86,22 +101,37 @@ class Mastodon(Internals): if follow_request_events is not None: params['data[alerts][status]'] = status_events + if update_events is not None: + params['data[alerts][update]'] = update_events + + if admin_sign_up_events is not None: + params['data[alerts][admin.sign_up]'] = admin_sign_up_events + + if admin_report_events is not None: + params['data[alerts][admin.report]'] = admin_report_events + # Canonicalize booleans params = self.__generate_params(params) return self.__api_request('POST', '/api/v1/push/subscription', params) @api_version("2.4.0", "2.4.0", _DICT_VERSION_PUSH) - def push_subscription_update(self, follow_events=None, - favourite_events=None, reblog_events=None, - mention_events=None, poll_events=None, - follow_request_events=None): + def push_subscription_update(self, follow_events: Optional[bool] = None, + favourite_events: Optional[bool] = None, reblog_events: Optional[bool] = None, + mention_events: Optional[bool] = None, poll_events: Optional[bool] = None, + follow_request_events: Optional[bool] = None, status_events: Optional[bool] = None, + policy: Optional[str] = 'all', update_events: Optional[bool] = None, admin_sign_up_events: Optional[bool] = None, + admin_report_events: Optional[bool] = None) -> WebPushSubscription: """ Modifies what kind of events the app wishes to subscribe to. - Returns the updated :ref:`push subscription dict `. + Parameters are as in :ref:`push_subscription_create() `. + + Returned object reflects the updated push subscription. """ params = {} + if policy is not None: + params['policy'] = policy if follow_events is not None: params['data[alerts][follow]'] = follow_events @@ -121,6 +151,18 @@ class Mastodon(Internals): if follow_request_events is not None: params['data[alerts][follow_request]'] = follow_request_events + if follow_request_events is not None: + params['data[alerts][status]'] = status_events + + if update_events is not None: + params['data[alerts][update]'] = update_events + + if admin_sign_up_events is not None: + params['data[alerts][admin.sign_up]'] = admin_sign_up_events + + if admin_report_events is not None: + params['data[alerts][admin.report]'] = admin_report_events + # Canonicalize booleans params = self.__generate_params(params) @@ -136,7 +178,7 @@ class Mastodon(Internals): ### # Push subscription crypto utilities ### - def push_subscription_generate_keys(self): + def push_subscription_generate_keys(self) -> Tuple[WebpushCryptoParamsPubkey, WebpushCryptoParamsPrivkey]: """ Generates a private key, public key and shared secret for use in webpush subscriptions. @@ -144,8 +186,7 @@ class Mastodon(Internals): public key and shared secret. """ if not IMPL_HAS_CRYPTO: - raise NotImplementedError( - 'To use the crypto tools, please install the webpush feature dependencies.') + raise NotImplementedError('To use the crypto tools, please install the webpush feature dependencies.') push_key_pair = ec.generate_private_key(ec.SECP256R1(), default_backend()) push_key_priv = push_key_pair.private_numbers().private_value @@ -172,17 +213,14 @@ class Mastodon(Internals): return priv_dict, pub_dict @api_version("2.4.0", "2.4.0", _DICT_VERSION_PUSH_NOTIF) - def push_subscription_decrypt_push(self, data, decrypt_params, encryption_header, crypto_key_header): + def push_subscription_decrypt_push(self, data: bytes, decrypt_params: WebpushCryptoParamsPrivkey, encryption_header: str, crypto_key_header: str) -> PushNotification: """ Decrypts `data` received in a webpush request. Requires the private key dict from :ref:`push_subscription_generate_keys() ` (`decrypt_params`) as well as the Encryption and server Crypto-Key headers from the received webpush - - Returns the decoded webpush as a :ref:`push notification dict `. """ if (not IMPL_HAS_ECE) or (not IMPL_HAS_CRYPTO): - raise NotImplementedError( - 'To use the crypto tools, please install the webpush feature dependencies.') + raise NotImplementedError('To use the crypto tools, please install the webpush feature dependencies.') salt = self.__decode_webpush_b64(encryption_header.split("salt=")[1].strip()) dhparams = self.__decode_webpush_b64(crypto_key_header.split("dh=")[1].split(";")[0].strip()) @@ -199,4 +237,4 @@ class Mastodon(Internals): version="aesgcm" ) - return json.loads(decrypted.decode('utf-8'), object_hook=Mastodon.__json_hooks) + return try_cast_recurse(PushNotification, json.loads(decrypted.decode('utf-8'))) diff --git a/mastodon/relationships.py b/mastodon/relationships.py index a33ee2d..b560949 100644 --- a/mastodon/relationships.py +++ b/mastodon/relationships.py @@ -1,49 +1,48 @@ # relationships.py - endpoints for user and domain blocks and mutes as well as follow requests -from .versions import _DICT_VERSION_ACCOUNT, _DICT_VERSION_RELATIONSHIP -from .utility import api_version - -from .internals import Mastodon as Internals +from mastodon.versions import _DICT_VERSION_ACCOUNT, _DICT_VERSION_RELATIONSHIP +from mastodon.utility import api_version +from mastodon.internals import Mastodon as Internals +from mastodon.types import Account, Relationship, PaginatableList, IdType +from typing import Optional, Union class Mastodon(Internals): ### # Reading data: Mutes and Blocks ### @api_version("1.1.0", "2.6.0", _DICT_VERSION_ACCOUNT) - def mutes(self, max_id=None, min_id=None, since_id=None, limit=None): + def mutes(self, max_id: Optional[IdType] = None, min_id: Optional[IdType] = None, since_id: + Optional[IdType] = None, limit: Optional[int] = None) -> PaginatableList[Account]: """ Fetch a list of users muted by the logged-in user. - - Returns a list of :ref:`account dicts `. """ if max_id is not None: - max_id = self.__unpack_id(max_id, dateconv=True) + max_id = self.__unpack_id(max_id) if min_id is not None: - min_id = self.__unpack_id(min_id, dateconv=True) + min_id = self.__unpack_id(min_id) if since_id is not None: - since_id = self.__unpack_id(since_id, dateconv=True) + since_id = self.__unpack_id(since_id) params = self.__generate_params(locals()) return self.__api_request('GET', '/api/v1/mutes', params) @api_version("1.0.0", "2.6.0", _DICT_VERSION_ACCOUNT) - def blocks(self, max_id=None, min_id=None, since_id=None, limit=None): + def blocks(self, max_id: Optional[IdType] = None, min_id: Optional[IdType] = None, since_id: + Optional[IdType] = None, limit: Optional[int] = None) -> PaginatableList[Account]: """ Fetch a list of users blocked by the logged-in user. - - Returns a list of :ref:`account dicts `. """ if max_id is not None: - max_id = self.__unpack_id(max_id, dateconv=True) + max_id = self.__unpack_id(max_id) if min_id is not None: - min_id = self.__unpack_id(min_id, dateconv=True) + min_id = self.__unpack_id(min_id) if since_id is not None: - since_id = self.__unpack_id(since_id, dateconv=True) + since_id = self.__unpack_id(since_id) params = self.__generate_params(locals()) return self.__api_request('GET', '/api/v1/blocks', params) @@ -52,20 +51,19 @@ class Mastodon(Internals): # Reading data: Follow requests ### @api_version("1.0.0", "2.6.0", _DICT_VERSION_ACCOUNT) - def follow_requests(self, max_id=None, min_id=None, since_id=None, limit=None): + def follow_requests(self, max_id: Optional[IdType] = None, min_id: Optional[IdType] = None, since_id: + Optional[IdType] = None, limit: Optional[int] = None) -> PaginatableList[Account]: """ Fetch the logged-in user's incoming follow requests. - - Returns a list of :ref:`account dicts `. """ if max_id is not None: - max_id = self.__unpack_id(max_id, dateconv=True) + max_id = self.__unpack_id(max_id) if min_id is not None: - min_id = self.__unpack_id(min_id, dateconv=True) + min_id = self.__unpack_id(min_id) if since_id is not None: - since_id = self.__unpack_id(since_id, dateconv=True) + since_id = self.__unpack_id(since_id) params = self.__generate_params(locals()) return self.__api_request('GET', '/api/v1/follow_requests', params) @@ -74,20 +72,21 @@ class Mastodon(Internals): # Reading data: Domain blocks ### @api_version("1.4.0", "2.6.0", "1.4.0") - def domain_blocks(self, max_id=None, min_id=None, since_id=None, limit=None): + def domain_blocks(self, max_id: Optional[IdType] = None, min_id: Optional[IdType] = None, since_id: + Optional[IdType] = None, limit: Optional[int] = None) -> PaginatableList[str]: """ Fetch the logged-in user's blocked domains. Returns a list of blocked domain URLs (as strings, without protocol specifier). """ if max_id is not None: - max_id = self.__unpack_id(max_id, dateconv=True) + max_id = self.__unpack_id(max_id) if min_id is not None: - min_id = self.__unpack_id(min_id, dateconv=True) + min_id = self.__unpack_id(min_id) if since_id is not None: - since_id = self.__unpack_id(since_id, dateconv=True) + since_id = self.__unpack_id(since_id) params = self.__generate_params(locals()) return self.__api_request('GET', '/api/v1/domain_blocks', params) @@ -96,21 +95,17 @@ class Mastodon(Internals): # Writing data: Follow requests ### @api_version("1.0.0", "3.0.0", _DICT_VERSION_RELATIONSHIP) - def follow_request_authorize(self, id): + def follow_request_authorize(self, id: Union[Account, IdType]) -> Relationship: """ - Accept an incoming follow request. - - Returns the updated :ref:`relationship dict ` for the requesting account. + Accept an incoming follow request from the given Account and returns the updated Relationship. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/follow_requests/{id}/authorize') @api_version("1.0.0", "3.0.0", _DICT_VERSION_RELATIONSHIP) - def follow_request_reject(self, id): + def follow_request_reject(self, id: Union[Account, IdType]) -> Relationship: """ - Reject an incoming follow request. - - Returns the updated :ref:`relationship dict ` for the requesting account. + Reject an incoming follow request from the given Account and returns the updated Relationship. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/follow_requests/{id}/reject') @@ -119,7 +114,7 @@ class Mastodon(Internals): # Writing data: Domain blocks ### @api_version("1.4.0", "1.4.0", "1.4.0") - def domain_block(self, domain=None): + def domain_block(self, domain: str): """ Add a block for all statuses originating from the specified domain for the logged-in user. """ @@ -127,7 +122,7 @@ class Mastodon(Internals): self.__api_request('POST', '/api/v1/domain_blocks', params) @api_version("1.4.0", "1.4.0", "1.4.0") - def domain_unblock(self, domain=None): + def domain_unblock(self, domain: str): """ Remove a domain block for the logged-in user. """ diff --git a/mastodon/reports.py b/mastodon/reports.py index 775878b..9554133 100644 --- a/mastodon/reports.py +++ b/mastodon/reports.py @@ -1,28 +1,27 @@ # reports.py - report endpoints -from .versions import _DICT_VERSION_REPORT -from .errors import MastodonVersionError -from .utility import api_version - -from .internals import Mastodon as Internals +from mastodon.versions import _DICT_VERSION_REPORT +from mastodon.errors import MastodonVersionError, MastodonIllegalArgumentError +from mastodon.utility import api_version +from mastodon.internals import Mastodon as Internals +from mastodon.types import NonPaginatableList, Report, Account, IdType, Status, Rule +from typing import Union, Optional, List class Mastodon(Internals): ### # Reading data: Reports ### @api_version("1.1.0", "1.1.0", _DICT_VERSION_REPORT) - def reports(self): + def reports(self) -> NonPaginatableList[Report]: """ Fetch a list of reports made by the logged-in user. - Returns a list of :ref:`report dicts `. - Warning: This method has now finally been removed, and will not work on Mastodon versions 2.5.0 and above. """ - if self.verify_minimum_version("2.5.0", cached=True): + if self.verify_minimum_version("2.5.0", cached = True): raise MastodonVersionError("API removed in Mastodon 2.5.0") return self.__api_request('GET', '/api/v1/reports') @@ -30,7 +29,8 @@ class Mastodon(Internals): # Writing data: Reports ### @api_version("1.1.0", "3.5.0", _DICT_VERSION_REPORT) - def report(self, account_id, status_ids=None, comment=None, forward=False, category=None, rule_ids=None): + def report(self, account_id: Union[Account, IdType], status_ids: Optional[Union[Status, IdType]] = None, comment: Optional[str] = None, + forward: bool = False, category: Optional[str] = None, rule_ids: Optional[List[Union[Rule, IdType]]] = None) -> Report: """ Report statuses to the instances administrators. @@ -42,8 +42,6 @@ class Mastodon(Internals): Set `forward` to True to forward a report of a remote user to that users instance as well as sending it to the instance local administrators. - - Returns a :ref:`report dict `. """ if category is not None and not category in ["spam", "violation", "other"]: raise MastodonIllegalArgumentError("Invalid report category (must be spam, violation or other)") diff --git a/mastodon/search.py b/mastodon/search.py index 37bd920..bf6e4e3 100644 --- a/mastodon/search.py +++ b/mastodon/search.py @@ -1,11 +1,12 @@ # search.py - search endpoints -from .versions import _DICT_VERSION_SEARCHRESULT -from .errors import MastodonVersionError -from .utility import api_version - -from .internals import Mastodon as Internals +from mastodon.versions import _DICT_VERSION_SEARCHRESULT +from mastodon.errors import MastodonVersionError +from mastodon.utility import api_version +from mastodon.internals import Mastodon as Internals +from mastodon.types import Search, SearchV2, Account, IdType +from typing import Union, Optional class Mastodon(Internals): ### @@ -21,7 +22,10 @@ class Mastodon(Internals): raise MastodonVersionError("Advanced search parameters require Mastodon 2.8.0+") @api_version("1.1.0", "2.8.0", _DICT_VERSION_SEARCHRESULT) - def search(self, q, resolve=True, result_type=None, account_id=None, offset=None, min_id=None, max_id=None, exclude_unreviewed=True): + def search(self, q: str, resolve: bool = True, result_type: Optional[str] = None, + account_id: Optional[Union[Account, IdType]] = None, offset: Optional[int] = None, + min_id: Optional[IdType] = None, max_id: Optional[IdType] = None, + exclude_unreviewed: bool = True) -> Union[Search, SearchV2]: """ Fetch matching hashtags, accounts and statuses. Will perform webfinger lookups if resolve is True. Full-text search is only enabled if @@ -44,17 +48,15 @@ class Mastodon(Internals): on Mastodon 2.8.0 or above - this function will throw a MastodonVersionError if you try to use them on versions before that. Note that the cached version number will be used for this to avoid uneccesary requests. - - Returns a :ref:`search result dict `, with tags as `hashtag dicts`_. """ if self.verify_minimum_version("2.4.1", cached=True): - return self.search_v2(q, resolve=resolve, result_type=result_type, account_id=account_id, offset=offset, min_id=min_id, max_id=max_id, exclude_unreviewed=exclude_unreviewed) + return self.search_v2(q, resolve=resolve, result_type=result_type, account_id=account_id, offset=offset, min_id=min_id, max_id=max_id, exclude_unreviewed=exclude_unreviewed, override_type=SearchV2) else: self.__ensure_search_params_acceptable(account_id, offset, min_id, max_id) - return self.search_v1(q, resolve=resolve) + return self.search_v1(q, resolve=resolve, override_type=Search) @api_version("1.1.0", "2.1.0", "2.1.0") - def search_v1(self, q, resolve=False): + def search_v1(self, q: str, resolve: bool = False) -> Search: """ Identical to `search_v2()`, except in that it does not return tags as :ref:`hashtag dicts `. @@ -67,7 +69,10 @@ class Mastodon(Internals): return self.__api_request('GET', '/api/v1/search', params) @api_version("2.4.1", "2.8.0", _DICT_VERSION_SEARCHRESULT) - def search_v2(self, q, resolve=True, result_type=None, account_id=None, offset=None, min_id=None, max_id=None, exclude_unreviewed=True): + def search_v2(self, q, resolve: bool = True, result_type: Optional[str] = None, + account_id: Optional[Union[Account, IdType]] = None, offset: Optional[int] = None, + min_id: Optional[IdType] = None, max_id: Optional[IdType] = None, + exclude_unreviewed: bool = True) -> SearchV2: """ Identical to `search_v1()`, except in that it returns tags as :ref:`hashtag dicts `, has more parameters, and resolves by default. diff --git a/mastodon/statuses.py b/mastodon/statuses.py index 6d167ce..fbe4fba 100644 --- a/mastodon/statuses.py +++ b/mastodon/statuses.py @@ -1,33 +1,35 @@ # statuses.py - status endpoints (regular and scheduled) import collections +from datetime import datetime -from .versions import _DICT_VERSION_STATUS, _DICT_VERSION_CARD, _DICT_VERSION_CONTEXT, _DICT_VERSION_ACCOUNT, _DICT_VERSION_SCHEDULED_STATUS, \ +from mastodon.versions import _DICT_VERSION_STATUS, _DICT_VERSION_CARD, _DICT_VERSION_CONTEXT, _DICT_VERSION_ACCOUNT, _DICT_VERSION_SCHEDULED_STATUS, \ _DICT_VERSION_STATUS_EDIT -from .errors import MastodonIllegalArgumentError -from .utility import api_version +from mastodon.errors import MastodonIllegalArgumentError +from mastodon.utility import api_version -from .internals import Mastodon as Internals +from mastodon.internals import Mastodon as Internals +from mastodon.types import Status, IdType, ScheduledStatus, PreviewCard, Context, NonPaginatableList, Account,\ + MediaAttachment, Poll, StatusSource +from typing import Union, Optional, List class Mastodon(Internals): ### # Reading data: Statuses ### @api_version("1.0.0", "2.0.0", _DICT_VERSION_STATUS) - def status(self, id): + def status(self, id: Union[Status, IdType]) -> Status: """ Fetch information about a single toot. Does not require authentication for publicly visible statuses. - - Returns a :ref:`status dict `. """ id = self.__unpack_id(id) return self.__api_request('GET', f'/api/v1/statuses/{id}') @api_version("1.0.0", "3.0.0", _DICT_VERSION_CARD) - def status_card(self, id): + def status_card(self, id: Union[Status, IdType]) -> PreviewCard: """ Fetch a card associated with a status. A card describes an object (such as an external video or link) embedded into a status. @@ -38,8 +40,6 @@ class Mastodon(Internals): exist anymore - you should just use the "card" field of the status dicts instead. Mastodon.py will try to mimic the old behaviour, but this is somewhat inefficient and not guaranteed to be the case forever. - - Returns a :ref:`card dict `. """ if self.verify_minimum_version("3.0.0", cached=True): return self.status(id).card @@ -48,37 +48,31 @@ class Mastodon(Internals): return self.__api_request('GET', f'/api/v1/statuses/{id}/card') @api_version("1.0.0", "1.0.0", _DICT_VERSION_CONTEXT) - def status_context(self, id): + def status_context(self, id: Union[Status, IdType]) -> Context: """ Fetch information about ancestors and descendants of a toot. Does not require authentication for publicly visible statuses. - - Returns a :ref:`context dict `. """ id = self.__unpack_id(id) return self.__api_request('GET', f'/api/v1/statuses/{id}/context') @api_version("1.0.0", "2.1.0", _DICT_VERSION_ACCOUNT) - def status_reblogged_by(self, id): + def status_reblogged_by(self, id: Union[Status, IdType]) -> NonPaginatableList[Account]: """ Fetch a list of users that have reblogged a status. Does not require authentication for publicly visible statuses. - - Returns a list of :ref:`account dicts `. """ id = self.__unpack_id(id) return self.__api_request('GET', f'/api/v1/statuses/{id}/reblogged_by') @api_version("1.0.0", "2.1.0", _DICT_VERSION_ACCOUNT) - def status_favourited_by(self, id): + def status_favourited_by(self, id: Union[Status, IdType]) -> NonPaginatableList[Account]: """ Fetch a list of users that have favourited a status. Does not require authentication for publicly visible statuses. - - Returns a list of :ref:`account dicts `. """ id = self.__unpack_id(id) return self.__api_request('GET', f'/api/v1/statuses/{id}/favourited_by') @@ -87,20 +81,16 @@ class Mastodon(Internals): # Reading data: Scheduled statuses ### @api_version("2.7.0", "2.7.0", _DICT_VERSION_SCHEDULED_STATUS) - def scheduled_statuses(self): + def scheduled_statuses(self) -> NonPaginatableList[ScheduledStatus]: """ Fetch a list of scheduled statuses - - Returns a list of :ref:`scheduled status dicts `. """ return self.__api_request('GET', '/api/v1/scheduled_statuses') @api_version("2.7.0", "2.7.0", _DICT_VERSION_SCHEDULED_STATUS) - def scheduled_status(self, id): + def scheduled_status(self, id: Union[ScheduledStatus, IdType]) -> ScheduledStatus: """ Fetch information about the scheduled status with the given id. - - Returns a :ref:`scheduled status dict `. """ id = self.__unpack_id(id) return self.__api_request('GET', f'/api/v1/scheduled_statuses/{id}') @@ -108,10 +98,14 @@ class Mastodon(Internals): ### # Writing data: Statuses ### - def __status_internal(self, status, in_reply_to_id=None, media_ids=None, - sensitive=False, visibility=None, spoiler_text=None, - language=None, idempotency_key=None, content_type=None, - scheduled_at=None, poll=None, quote_id=None, edit=False): + + def __status_internal(self, status: Optional[str], in_reply_to_id: Optional[Union[Status, IdType]] = None, media_ids: Optional[List[Union[MediaAttachment, IdType]]] = None, + sensitive: Optional[bool] = False, visibility: Optional[str] = None, spoiler_text: Optional[str] = None, language: Optional[str] = None, + idempotency_key: Optional[str] = None, content_type: Optional[str] = None, scheduled_at: Optional[datetime] = None, + poll: Optional[Union[Poll, IdType]] = None, quote_id: Optional[Union[Status, IdType]] = None, edit: Optional[bool] = False) -> Union[Status, ScheduledStatus]: + """ + Internal statuses poster helper + """ if quote_id is not None: if self.feature_set != "fedibird": raise MastodonIllegalArgumentError('quote_id is only available with feature set fedibird') @@ -151,7 +145,7 @@ class Mastodon(Internals): del params_initial['language'] if params_initial['sensitive'] is False: - del [params_initial['sensitive']] + del params_initial['sensitive'] headers = {} if idempotency_key is not None: @@ -177,18 +171,21 @@ class Mastodon(Internals): use_json = True params = self.__generate_params(params_initial, ['idempotency_key', 'edit']) + cast_type = Status + if scheduled_at is not None: + cast_type = ScheduledStatus if edit is None: # Post - return self.__api_request('POST', '/api/v1/statuses', params, headers=headers, use_json=use_json) + return self.__api_request('POST', '/api/v1/statuses', params, headers=headers, use_json=use_json, override_type=cast_type) else: # Edit - return self.__api_request('PUT', f'/api/v1/statuses/{self.__unpack_id(edit)}', params, headers=headers, use_json=use_json) + return self.__api_request('PUT', f'/api/v1/statuses/{self.__unpack_id(edit)}', params, headers=headers, use_json=use_json, override_type=cast_type) @api_version("1.0.0", "2.8.0", _DICT_VERSION_STATUS) - def status_post(self, status, in_reply_to_id=None, media_ids=None, - sensitive=False, visibility=None, spoiler_text=None, - language=None, idempotency_key=None, content_type=None, - scheduled_at=None, poll=None, quote_id=None): + def status_post(self, status: str, in_reply_to_id: Optional[Union[Status, IdType]] = None, media_ids: Optional[List[Union[MediaAttachment, IdType]]] = None, + sensitive: bool = False, visibility: Optional[str] = None, spoiler_text: Optional[str] = None, language: Optional[str] = None, + idempotency_key: Optional[str] = None, content_type: Optional[str] = None, scheduled_at: Optional[datetime] = None, + poll: Optional[Union[Poll, IdType]] = None, quote_id: Optional[Union[Status, IdType]] = None) -> Union[Status, ScheduledStatus]: """ Post a status. Can optionally be in reply to another status and contain media. @@ -262,23 +259,25 @@ class Mastodon(Internals): ) @api_version("1.0.0", "2.8.0", _DICT_VERSION_STATUS) - def toot(self, status): + def toot(self, status: str) -> Status: """ Synonym for :ref:`status_post() ` that only takes the status text as input. Usage in production code is not recommended. - - Returns a :ref:`status dict ` with the new status. """ return self.status_post(status) @api_version("3.5.0", "3.5.0", _DICT_VERSION_STATUS) - def status_update(self, id, status=None, spoiler_text=None, sensitive=None, media_ids=None, poll=None): + def status_update(self, id: Union[Status, IdType], status: Optional[str] = None, spoiler_text: Optional[str] = None, + sensitive: Optional[bool] = None, media_ids: Optional[List[Union[MediaAttachment, IdType]]] = None, + poll: Optional[Union[Poll, IdType]] = None) -> Status: """ Edit a status. The meanings of the fields are largely the same as in :ref:`status_post() `, though not every field can be edited. Note that editing a poll will reset the votes. + + TODO: Currently doesn't support editing media descriptions, implement that. """ return self.__status_internal( status=status, @@ -290,9 +289,9 @@ class Mastodon(Internals): ) @api_version("3.5.0", "3.5.0", _DICT_VERSION_STATUS_EDIT) - def status_history(self, id): + def status_history(self, id: Union[Status, IdType]) -> NonPaginatableList[Status]: """ - Returns the edit history of a status as a list of :ref:`status edit dicts `, starting + Returns the edit history of a status as a list of Status objects, starting from the original form. Note that this means that a status that has been edited once will have *two* entries in this list, a status that has been edited twice will have three, and so on. @@ -300,7 +299,7 @@ class Mastodon(Internals): id = self.__unpack_id(id) return self.__api_request('GET', f"/api/v1/statuses/{id}/history") - def status_source(self, id): + def status_source(self, id: Union[Status, IdType]) -> StatusSource: """ Returns the source of a status for editing. @@ -312,10 +311,10 @@ class Mastodon(Internals): return self.__api_request('GET', f"/api/v1/statuses/{id}/source") @api_version("1.0.0", "2.8.0", _DICT_VERSION_STATUS) - def status_reply(self, to_status, status, in_reply_to_id=None, media_ids=None, - sensitive=False, visibility=None, spoiler_text=None, - language=None, idempotency_key=None, content_type=None, - scheduled_at=None, poll=None, untag=False): + def status_reply(self, to_status: Union[Status, IdType], status: str, media_ids: Optional[List[Union[MediaAttachment, IdType]]] = None, + sensitive: bool = False, visibility: Optional[str] = None, spoiler_text: Optional[str] = None, language: Optional[str] = None, + idempotency_key: Optional[str] = None, content_type: Optional[str] = None, scheduled_at: Optional[datetime] = None, + poll: Optional[Union[Poll, IdType]] = None, quote_id: Optional[Union[Status, IdType]] = None, untag: bool = False) -> Status: """ Helper function - acts like status_post, but prepends the name of all the users that are being replied to the status text and retains @@ -362,7 +361,7 @@ class Mastodon(Internals): return self.status_post(**keyword_args) @api_version("1.0.0", "1.0.0", "1.0.0") - def status_delete(self, id): + def status_delete(self, id: Union[Status, IdType]) -> Status: """ Delete a status @@ -374,14 +373,14 @@ class Mastodon(Internals): return self.__api_request('DELETE', f'/api/v1/statuses/{id}') @api_version("1.0.0", "2.0.0", _DICT_VERSION_STATUS) - def status_reblog(self, id, visibility=None): + def status_reblog(self, id: Union[Status, IdType], visibility: Optional[str] = None) -> Status: """ Reblog / boost a status. The visibility parameter functions the same as in :ref:`status_post() ` and allows you to reduce the visibility of a reblogged status. - Returns a :ref:`status dict ` with a new status that wraps around the reblogged one. + Returns a new Status that wraps around the reblogged status. """ params = self.__generate_params(locals(), ['id']) valid_visibilities = ['private', 'public', 'unlisted', 'direct'] @@ -394,91 +393,91 @@ class Mastodon(Internals): return self.__api_request('POST', f'/api/v1/statuses/{id}/reblog', params) @api_version("1.0.0", "2.0.0", _DICT_VERSION_STATUS) - def status_unreblog(self, id): + def status_unreblog(self, id: Union[Status, IdType]) -> Status: """ Un-reblog a status. - Returns a :ref:`status dict ` with the status that used to be reblogged. + Returns the status that used to be reblogged. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/statuses/{id}/unreblog') @api_version("1.0.0", "2.0.0", _DICT_VERSION_STATUS) - def status_favourite(self, id): + def status_favourite(self, id: Union[Status, IdType]) -> Status: """ Favourite a status. - Returns a :ref:`status dict ` with the favourited status. + Returns the favourited status. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/statuses/{id}/favourite') @api_version("1.0.0", "2.0.0", _DICT_VERSION_STATUS) - def status_unfavourite(self, id): + def status_unfavourite(self, id: Union[Status, IdType]) -> Status: """ Un-favourite a status. - Returns a :ref:`status dict ` with the un-favourited status. + Returns the un-favourited status. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/statuses/{id}/unfavourite') @api_version("1.4.0", "2.0.0", _DICT_VERSION_STATUS) - def status_mute(self, id): + def status_mute(self, id: Union[Status, IdType]) -> Status: """ Mute notifications for a status. - Returns a :ref:`status dict ` with the now muted status + Returns the now muted status """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/statuses/{id}/mute') @api_version("1.4.0", "2.0.0", _DICT_VERSION_STATUS) - def status_unmute(self, id): + def status_unmute(self, id: Union[Status, IdType]) -> Status: """ Unmute notifications for a status. - Returns a :ref:`status dict ` with the status that used to be muted. + Returns the status that used to be muted. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/statuses/{id}/unmute') @api_version("2.1.0", "2.1.0", _DICT_VERSION_STATUS) - def status_pin(self, id): + def status_pin(self, id: Union[Status, IdType]) -> Status: """ Pin a status for the logged-in user. - Returns a :ref:`status dict ` with the now pinned status + Returns the now pinned status """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/statuses/{id}/pin') @api_version("2.1.0", "2.1.0", _DICT_VERSION_STATUS) - def status_unpin(self, id): + def status_unpin(self, id: Union[Status, IdType]) -> Status: """ Unpin a pinned status for the logged-in user. - Returns a :ref:`status dict ` with the status that used to be pinned. + Returns the status that used to be pinned. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/statuses/{id}/unpin') @api_version("3.1.0", "3.1.0", _DICT_VERSION_STATUS) - def status_bookmark(self, id): + def status_bookmark(self, id: Union[Status, IdType]) -> Status: """ Bookmark a status as the logged-in user. - Returns a :ref:`status dict ` with the now bookmarked status + Returns the now bookmarked status """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/statuses/{id}/bookmark') @api_version("3.1.0", "3.1.0", _DICT_VERSION_STATUS) - def status_unbookmark(self, id): + def status_unbookmark(self, id: Union[Status, IdType]) -> Status: """ Unbookmark a bookmarked status for the logged-in user. - Returns a :ref:`status dict ` with the status that used to be bookmarked. + Returns the status that used to be bookmarked. """ id = self.__unpack_id(id) return self.__api_request('POST', f'/api/v1/statuses/{id}/unbookmark') @@ -487,13 +486,13 @@ class Mastodon(Internals): # Writing data: Scheduled statuses ### @api_version("2.7.0", "2.7.0", _DICT_VERSION_SCHEDULED_STATUS) - def scheduled_status_update(self, id, scheduled_at): + def scheduled_status_update(self, id: Union[Status, IdType], scheduled_at: datetime) -> ScheduledStatus: """ Update the scheduled time of a scheduled status. New time must be at least 5 minutes into the future. - Returns a :ref:`scheduled status dict ` + Returned object reflects the updates to the scheduled status. """ scheduled_at = self.__consistent_isoformat_utc(scheduled_at) id = self.__unpack_id(id) @@ -501,7 +500,7 @@ class Mastodon(Internals): return self.__api_request('PUT', f'/api/v1/scheduled_statuses/{id}', params) @api_version("2.7.0", "2.7.0", "2.7.0") - def scheduled_status_delete(self, id): + def scheduled_status_delete(self, id: Union[Status, IdType]): """ Deletes a scheduled status. """ diff --git a/mastodon/streaming.py b/mastodon/streaming.py index e3ce8c3..c9cf2e3 100644 --- a/mastodon/streaming.py +++ b/mastodon/streaming.py @@ -12,8 +12,9 @@ except: from mastodon import Mastodon from mastodon.Mastodon import MastodonMalformedEventError, MastodonNetworkError, MastodonReadTimeout -from requests.exceptions import ChunkedEncodingError, ReadTimeout, ConnectionError +from mastodon.types import AttribAccessDict, Status, Notification, IdType, Conversation, Announcement, StreamReaction, try_cast_recurse +from requests.exceptions import ChunkedEncodingError, ReadTimeout, ConnectionError class StreamListener(object): """Callbacks for the streaming API. Create a subclass, override the on_xxx @@ -21,6 +22,19 @@ class StreamListener(object): of your subclass to Mastodon.user_stream(), Mastodon.public_stream(), or Mastodon.hashtag_stream().""" + __EVENT_NAME_TO_TYPE = { + "update": Status, + "delete": IdType, + "notification": Notification, + "filters_changed": None, + "conversation": Conversation, + "announcement": Announcement, + "announcement_reaction": StreamReaction, + "announcement_delete": IdType, + "status_update": Status, + "encrypted_message": AttribAccessDict, + } + def on_update(self, status): """A new status has appeared. `status` is the parsed `status dict` describing the status.""" @@ -179,7 +193,9 @@ class StreamListener(object): for_stream = json.loads(event['stream']) except: for_stream = None - payload = json.loads(data, object_hook=Mastodon._Mastodon__json_hooks) + payload = json.loads(data) + cast_type = self.__EVENT_NAME_TO_TYPE.get(name, AttribAccessDict) + payload = try_cast_recurse(cast_type, payload) except KeyError as err: exception = MastodonMalformedEventError( 'Missing field', err.args[0], event) diff --git a/mastodon/streaming_endpoints.py b/mastodon/streaming_endpoints.py index 5f09ec3..84e8bcb 100644 --- a/mastodon/streaming_endpoints.py +++ b/mastodon/streaming_endpoints.py @@ -1,11 +1,11 @@ # relationships.py - endpoints for user and domain blocks and mutes as well as follow requests -from .versions import _DICT_VERSION_STATUS -from .errors import MastodonIllegalArgumentError -from .defaults import _DEFAULT_STREAM_TIMEOUT, _DEFAULT_STREAM_RECONNECT_WAIT_SEC -from .utility import api_version +from mastodon.versions import _DICT_VERSION_STATUS +from mastodon.errors import MastodonIllegalArgumentError +from mastodon.defaults import _DEFAULT_STREAM_TIMEOUT, _DEFAULT_STREAM_RECONNECT_WAIT_SEC +from mastodon.utility import api_version -from .internals import Mastodon as Internals +from mastodon.internals import Mastodon as Internals class Mastodon(Internals): @@ -79,7 +79,7 @@ class Mastodon(Internals): return self.__stream('/api/v1/streaming/direct', listener, run_async=run_async, timeout=timeout, reconnect_async=reconnect_async, reconnect_async_wait_sec=reconnect_async_wait_sec) @api_version("2.5.0", "2.5.0", "2.5.0") - def stream_healthy(self): + def stream_healthy(self) -> bool: """ Returns without True if streaming API is okay, False or raises an error otherwise. """ diff --git a/mastodon/suggestions.py b/mastodon/suggestions.py index fff1fe2..e9872ec 100644 --- a/mastodon/suggestions.py +++ b/mastodon/suggestions.py @@ -1,22 +1,20 @@ # suggestions.py - follow suggestion endpoints -from .versions import _DICT_VERSION_ACCOUNT -from .utility import api_version - -from .internals import Mastodon as Internals +from mastodon.versions import _DICT_VERSION_ACCOUNT +from mastodon.utility import api_version +from mastodon.internals import Mastodon as Internals +from mastodon.types import NonPaginatableList, Account, IdType +from typing import Union class Mastodon(Internals): ### # Reading data: Follow suggestions ### @api_version("2.4.3", "2.4.3", _DICT_VERSION_ACCOUNT) - def suggestions(self): + def suggestions(self) -> NonPaginatableList[Account]: """ Fetch follow suggestions for the logged-in user. - - Returns a list of :ref:`account dicts `. - """ return self.__api_request('GET', '/api/v1/suggestions') @@ -24,7 +22,7 @@ class Mastodon(Internals): # Writing data: Follow suggestions ### @api_version("2.4.3", "2.4.3", _DICT_VERSION_ACCOUNT) - def suggestion_delete(self, account_id): + def suggestion_delete(self, account_id: Union[Account, IdType]): """ Remove the user with the given `account_id` from the follow suggestions. """ diff --git a/mastodon/timeline.py b/mastodon/timeline.py index 9bde25c..a9908d7 100644 --- a/mastodon/timeline.py +++ b/mastodon/timeline.py @@ -1,19 +1,23 @@ # timeline.py - endpoints for reading various different timelines -from .versions import _DICT_VERSION_STATUS, _DICT_VERSION_CONVERSATION -from .errors import MastodonIllegalArgumentError, MastodonNotFoundError -from .utility import api_version - -from .internals import Mastodon as Internals +from mastodon.versions import _DICT_VERSION_STATUS, _DICT_VERSION_CONVERSATION +from mastodon.errors import MastodonIllegalArgumentError, MastodonNotFoundError +from mastodon.utility import api_version +from mastodon.internals import Mastodon as Internals +from mastodon.types import Status, IdType, PaginatableList, UserList +from typing import Union, Optional +from datetime import datetime class Mastodon(Internals): ### # Reading data: Timelines ## @api_version("1.0.0", "3.1.4", _DICT_VERSION_STATUS) - def timeline(self, timeline="home", max_id=None, min_id=None, since_id=None, limit=None, only_media=False, local=False, remote=False): - """ + def timeline(self, timeline: str = "home", max_id: Optional[Union[Status, IdType, datetime]] = None, min_id: Optional[Union[Status, IdType, datetime]] = None, + since_id: Optional[Union[Status, IdType, datetime]] = None, limit: Optional[int] = None, only_media: bool = False, local: bool = False, + remote: bool = False) -> PaginatableList[Status]: + """ Fetch statuses, most recent ones first. `timeline` can be 'home', 'local', 'public', 'tag/hashtag' or 'list/id'. See the following functions documentation for what those do. @@ -23,8 +27,6 @@ class Mastodon(Internals): and `remote` to only get remote statuses. Some options are mutually incompatible as dictated by logic. May or may not require authentication depending on server settings and what is specifically requested. - - Returns a list of :ref:`status dicts `. """ if max_id is not None: max_id = self.__unpack_id(max_id, dateconv=True) @@ -54,39 +56,38 @@ class Mastodon(Internals): return self.__api_request('GET', f'/api/v1/timelines/{timeline}', params) @api_version("1.0.0", "3.1.4", _DICT_VERSION_STATUS) - def timeline_home(self, max_id=None, min_id=None, since_id=None, limit=None, only_media=False, local=False, remote=False): + def timeline_home(self, max_id: Optional[Union[Status, IdType, datetime]] = None, min_id: Optional[Union[Status, IdType, datetime]] = None, + since_id: Optional[Union[Status, IdType, datetime]] = None, limit: Optional[int] = None, only_media: bool = False, local: bool = False, + remote: bool = False) -> PaginatableList[Status]: """ Convenience method: Fetches the logged-in user's home timeline (i.e. followed users and self). Params as in `timeline()`. - - Returns a list of :ref:`status dicts `. """ return self.timeline('home', max_id=max_id, min_id=min_id, since_id=since_id, limit=limit, only_media=only_media, local=local, remote=remote) @api_version("1.0.0", "3.1.4", _DICT_VERSION_STATUS) - def timeline_local(self, max_id=None, min_id=None, since_id=None, limit=None, only_media=False): + def timeline_local(self, max_id: Optional[Union[Status, IdType, datetime]] = None, min_id: Optional[Union[Status, IdType, datetime]] = None, + since_id: Optional[Union[Status, IdType, datetime]] = None, limit: Optional[int] = None, only_media: bool = False) -> PaginatableList[Status]: """ Convenience method: Fetches the local / instance-wide timeline, not including replies. Params as in `timeline()`. - - Returns a list of :ref:`status dicts `. """ return self.timeline('local', max_id=max_id, min_id=min_id, since_id=since_id, limit=limit, only_media=only_media) @api_version("1.0.0", "3.1.4", _DICT_VERSION_STATUS) - def timeline_public(self, max_id=None, min_id=None, since_id=None, limit=None, only_media=False, local=False, remote=False): + def timeline_public(self, max_id: Optional[Union[Status, IdType, datetime]] = None, min_id: Optional[Union[Status, IdType, datetime]] = None, + since_id: Optional[Union[Status, IdType, datetime]] = None, limit: Optional[int] = None, only_media: bool = False, local: bool = False, + remote: bool = False) -> PaginatableList[Status]: """ Convenience method: Fetches the public / visible-network / federated timeline, not including replies. Params as in `timeline()`. - - Returns a list of :ref:`status dicts `. """ return self.timeline('public', max_id=max_id, min_id=min_id, since_id=since_id, limit=limit, only_media=only_media, local=local, remote=remote) @api_version("1.0.0", "3.1.4", _DICT_VERSION_STATUS) - def timeline_hashtag(self, hashtag, local=False, max_id=None, min_id=None, since_id=None, limit=None, only_media=False, remote=False): + def timeline_hashtag(self, hashtag: str, local: bool = False, max_id: Optional[Union[Status, IdType, datetime]] = None, min_id: Optional[Union[Status, IdType, datetime]] = None, + since_id: Optional[Union[Status, IdType, datetime]] = None, limit: Optional[int] = None, only_media: bool = False, + remote: bool = False) -> PaginatableList[Status]: """ Convenience method: Fetch a timeline of toots with a given hashtag. The hashtag parameter should not contain the leading #. Params as in `timeline()`. - - Returns a list of :ref:`status dicts `. """ if hashtag.startswith("#"): raise MastodonIllegalArgumentError( @@ -94,11 +95,11 @@ class Mastodon(Internals): return self.timeline(f'tag/{hashtag}', max_id=max_id, min_id=min_id, since_id=since_id, limit=limit, only_media=only_media, local=local, remote=remote) @api_version("2.1.0", "3.1.4", _DICT_VERSION_STATUS) - def timeline_list(self, id, max_id=None, min_id=None, since_id=None, limit=None, only_media=False, local=False, remote=False): + def timeline_list(self, id: Union[UserList, IdType], max_id: Optional[Union[Status, IdType, datetime]] = None, min_id: Optional[Union[Status, IdType, datetime]] = None, + since_id: Optional[Union[Status, IdType, datetime]] = None, limit: Optional[int] = None, only_media: bool = False, local: bool = False, + remote: bool = False) -> PaginatableList[Status]: """ Convenience method: Fetches a timeline containing all the toots by users in a given list. Params as in `timeline()`. - - Returns a list of :ref:`status dicts `. """ id = self.__unpack_id(id) return self.timeline(f'list/{id}', max_id=max_id, min_id=min_id, since_id=since_id, limit=limit, only_media=only_media, local=local, remote=remote) diff --git a/mastodon/trends.py b/mastodon/trends.py index 67f5c6e..9aedc16 100644 --- a/mastodon/trends.py +++ b/mastodon/trends.py @@ -1,17 +1,18 @@ # trends.py - trend-related endpoints -from .versions import _DICT_VERSION_HASHTAG, _DICT_VERSION_STATUS, _DICT_VERSION_CARD -from .utility import api_version - -from .internals import Mastodon as Internals +from mastodon.versions import _DICT_VERSION_HASHTAG, _DICT_VERSION_STATUS, _DICT_VERSION_CARD +from mastodon.utility import api_version +from mastodon.internals import Mastodon as Internals +from mastodon.types import Tag, Status, PreviewCard, NonPaginatableList +from typing import Optional, Union class Mastodon(Internals): ### # Reading data: Trends ### @api_version("2.4.3", "3.5.0", _DICT_VERSION_HASHTAG) - def trends(self, limit=None): + def trends(self, limit: Optional[int] = None): """ Old alias for :ref:`trending_tags() ` @@ -20,7 +21,7 @@ class Mastodon(Internals): return self.trending_tags(limit=limit) @api_version("3.5.0", "3.5.0", _DICT_VERSION_HASHTAG) - def trending_tags(self, limit=None, lang=None): + def trending_tags(self, limit: Optional[int] = None, lang: Optional[str] = None) -> NonPaginatableList[Tag]: """ Fetch trending-hashtag information, if the instance provides such information. @@ -34,8 +35,7 @@ class Mastodon(Internals): Pass `lang` to override the global locale parameter, which may affect trend ordering. - Returns a list of :ref:`hashtag dicts `, sorted by the instance's trending algorithm, - descending. + The results are sorted by the instances's trending algorithm, descending. """ params = self.__generate_params(locals()) if "lang" in params: @@ -47,7 +47,7 @@ class Mastodon(Internals): return self.__api_request('GET', '/api/v1/trends', params, lang_override=lang) @api_version("3.5.0", "3.5.0", _DICT_VERSION_STATUS) - def trending_statuses(self, limit=None, lang=None): + def trending_statuses(self, limit: Optional[int] = None, lang: Optional[str] = None) -> NonPaginatableList[Status]: """ Fetch trending-status information, if the instance provides such information. @@ -56,8 +56,7 @@ class Mastodon(Internals): Pass `lang` to override the global locale parameter, which may affect trend ordering. - Returns a list of :ref:`status dicts `, sorted by the instances's trending algorithm, - descending. + The results are sorted by the instances's trending algorithm, descending. """ params = self.__generate_params(locals()) if "lang" in params: @@ -65,15 +64,14 @@ class Mastodon(Internals): return self.__api_request('GET', '/api/v1/trends/statuses', params, lang_override=lang) @api_version("3.5.0", "3.5.0", _DICT_VERSION_CARD) - def trending_links(self, limit=None, lang=None): + def trending_links(self, limit: Optional[int] = None, lang: Optional[str] = None) -> NonPaginatableList[PreviewCard]: """ Fetch trending-link information, if the instance provides such information. Specify `limit` to limit how many results are returned (the maximum number of results is 10, the endpoint is not paginated). - Returns a list of :ref:`card dicts `, sorted by the instances's trending algorithm, - descending. + The results are sorted by the instances's trending algorithm, descending. """ params = self.__generate_params(locals()) if "lang" in params: diff --git a/mastodon/types.py b/mastodon/types.py new file mode 100644 index 0000000..318fb51 --- /dev/null +++ b/mastodon/types.py @@ -0,0 +1,5021 @@ +from datetime import datetime +from typing import Union, Optional, Tuple, List, IO, Dict +from mastodon.types_base import AttribAccessDict, IdType, MaybeSnowflakeIdType, PrimitiveIdType, EntityList, PaginatableList, NonPaginatableList, PathOrFile, WebpushCryptoParamsPubkey, WebpushCryptoParamsPrivkey, try_cast_recurse, try_cast + +class Account(AttribAccessDict): + """ + A user acccount, local or remote. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Account/ + """ + + id: "MaybeSnowflakeIdType" + """ + The accounts id. + + Version history: + * 0.1.0: added + """ + + username: "str" + """ + The username, without the domain part. + + Version history: + * 0.1.0: added + """ + + acct: "str" + """ + The user's account name as username@domain (@domain omitted for local users). + + Version history: + * 0.1.0: added + """ + + display_name: "str" + """ + The user's display name. + + Version history: + * 0.1.0: added + """ + + discoverable: "Optional[bool]" + """ + Indicates whether or not a user is visible on the discovery page. (nullable) + + Version history: + * 3.1.0: added + """ + + group: "bool" + """ + A boolean indicating whether the account represents a group rather than an individual. + + Version history: + * 3.1.0: added + """ + + locked: "bool" + """ + Denotes whether the account can be followed without a follow request. + + Version history: + * 0.1.0: added + """ + + created_at: "datetime" + """ + The accounts creation time. + + Version history: + * 0.1.0: added + * 3.4.0: now resolves to midnight instead of an exact time + """ + + following_count: "int" + """ + How many accounts this account follows. + + Version history: + * 0.1.0: added + """ + + followers_count: "int" + """ + How many followers this account has. + + Version history: + * 0.1.0: added + """ + + statuses_count: "int" + """ + How many statuses this account has created, excluding: 1) later deleted posts 2) direct messages / 'mentined users only' posts, except in earlier versions mastodon. + + Version history: + * 0.1.0: added + * 2.4.2: no longer includes direct / mentioned-only visibility statuses + """ + + note: "str" + """ + The users bio / profile text / 'note'. + + Version history: + * 0.1.0: added + """ + + url: "str" + """ + A URL pointing to this users profile page (can be remote). + Should contain (as text): URL + + Version history: + * 0.1.0: added + """ + + avatar: "str" + """ + URL for this users avatar, can be animated. + Should contain (as text): URL + + Version history: + * 0.1.0: added + """ + + header: "str" + """ + URL for this users header image, can be animated. + Should contain (as text): URL + + Version history: + * 0.1.0: added + """ + + avatar_static: "str" + """ + URL for this users avatar, never animated. + Should contain (as text): URL + + Version history: + * 1.1.2: added + """ + + header_static: "str" + """ + URL for this users header image, never animated. + Should contain (as text): URL + + Version history: + * 1.1.2: added + """ + + moved_to_account: "Optional[Account]" + """ + If set, Account that this user has set up as their moved-to address. (optional) + + Version history: + * 2.1.0: added + """ + + suspended: "Optional[bool]" + """ + Boolean indicating whether the user has been suspended. (optional) + + Version history: + * 3.3.0: added + """ + + limited: "Optional[bool]" + """ + Boolean indicating whether the user has been silenced. (optional) + + Version history: + * 3.5.3: added + """ + + bot: "bool" + """ + Boolean indicating whether this account is automated. + + Version history: + * 2.4.0: added + """ + + fields: "EntityList[AccountField]" + """ + List of up to four (by default) AccountFields. + + Version history: + * 2.4.0: added + """ + + emojis: "EntityList[CustomEmoji]" + """ + List of custom emoji used in name, bio or fields. + + Version history: + * 2.4.0: added + """ + + last_status_at: "Optional[datetime]" + """ + When the most recent status was posted. (nullable) + + Version history: + * 3.0.0: added + * 3.1.0: now returns date only, no time + """ + + noindex: "Optional[bool]" + """ + Whether the local user has opted out of being indexed by search engines. (nullable) + + Version history: + * 4.0.0: added + """ + + roles: "EntityList" + """ + THIS FIELD IS DEPRECATED. IT IS RECOMMENDED THAT YOU DO NOT USE IT. + + Deprecated. Was a list of strings with the users roles. Now just an empty list. Mastodon.py makes no attempt to fill it, and the field may be removed if Mastodon removes it. Use the `role` field instead. + + Version history: + * 0.1.0: added + * 4.0.0: deprecated + """ + + role: "Optional[Role]" + """ + The users role. Only present for account returned from account_verify_credentials(). (optional) + + Version history: + * 4.0.0: added + """ + + source: "Optional[CredentialAccountSource]" + """ + Additional information about the account, useful for profile editing. Only present for account returned from account_verify_credentials(). (optional) + + Version history: + * 2.4.0: added + """ + + mute_expires_at: "Optional[datetime]" + """ + If the user is muted by the logged in user with a timed mute, when the mute expires. (nullable) + + Version history: + * 3.3.0: added + """ + + _version = "4.0.0" + +class AccountField(AttribAccessDict): + """ + A field, displayed on a users profile (e.g. "Pronouns", "Favorite color"). + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Account/ + """ + + name: "str" + """ + The key of a given field's key-value pair. + + Version history: + * 2.4.0: added + """ + + value: "str" + """ + The value associated with the `name` key. + + Version history: + * 2.4.0: added + """ + + verified_at: "Optional[str]" + """ + Timestamp of when the server verified a URL value for a rel="me" link. (nullable) + + Version history: + * 2.6.0: added + """ + + _version = "2.6.0" + +class Role(AttribAccessDict): + """ + A role granting a user a set of permissions. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Role/ + """ + + id: "IdType" + """ + The ID of the Role in the database. + + Version history: + * 4.0.0: added + """ + + name: "str" + """ + The name of the role. + + Version history: + * 4.0.0: added + """ + + permissions: "str" + """ + A bitmask that represents the sum of all permissions granted to the role. + + Version history: + * 4.0.0: added + """ + + color: "str" + """ + The hex code assigned to this role. If no hex code is assigned, the string will be empty. + + Version history: + * 4.0.0: added + """ + + highlighted: "bool" + """ + Whether the role is publicly visible as a badge on user profiles. + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class CredentialAccountSource(AttribAccessDict): + """ + Source values useful for editing a user's profile. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Account/ + """ + + privacy: "str" + """ + The user's default visibility setting ("private", "unlisted" or "public"). + + Version history: + * 1.5.0: added + """ + + sensitive: "bool" + """ + Denotes whether user media should be marked sensitive by default. + + Version history: + * 1.5.0: added + """ + + note: "str" + """ + Plain text version of the user's bio. + + Version history: + * 1.5.0: added + """ + + language: "str" + """ + The default posting language for new statuses. + Should contain (as text): TwoLetterLanguageCodeEnum + + Version history: + * 2.4.2: added + """ + + fields: "EntityList[AccountField]" + """ + Metadata about the account. + + Version history: + * 2.4.0: added + """ + + follow_requests_count: "int" + """ + The number of pending follow requests. + + Version history: + * 3.0.0: added + """ + + _version = "3.0.0" + +class Status(AttribAccessDict): + """ + A single status / toot / post. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Status/ + """ + + id: "MaybeSnowflakeIdType" + """ + Id of this status. + + Version history: + * 0.1.0: added + """ + + uri: "str" + """ + Descriptor for the status. Mastodon, for example, may use something like: 'tag:mastodon.social,2016-11-25:objectId=:objectType=Status'. + + Version history: + * 0.1.0: added + """ + + url: "Optional[str]" + """ + URL of the status. (nullable) + Should contain (as text): URL + + Version history: + * 0.1.0: added + """ + + account: "Account" + """ + Account which posted the status. + + Version history: + * 0.1.0: added + """ + + in_reply_to_id: "Optional[MaybeSnowflakeIdType]" + """ + Id of the status this status is in response to. (nullable) + + Version history: + * 0.1.0: added + """ + + in_reply_to_account_id: "Optional[MaybeSnowflakeIdType]" + """ + Id of the account this status is in response to. (nullable) + + Version history: + * 0.1.0: added + """ + + reblog: "Optional[Status]" + """ + Denotes whether the status is a reblog. If so, set to the original status. (nullable) + + Version history: + * 0.1.0: added + """ + + content: "str" + """ + Content of the status, as HTML: '

Hello from Python

'. + Should contain (as text): HTML + + Version history: + * 0.1.0: added + """ + + created_at: "datetime" + """ + Creation time. + + Version history: + * 0.1.0: added + """ + + reblogs_count: "int" + """ + Number of reblogs. + + Version history: + * 0.1.0: added + """ + + favourites_count: "int" + """ + Number of favourites. + + Version history: + * 0.1.0: added + """ + + reblogged: "Optional[bool]" + """ + Denotes whether the logged in user has boosted this status. (optional) + + Version history: + * 0.1.0: added + """ + + favourited: "Optional[bool]" + """ + Denotes whether the logged in user has favourited this status. (optional) + + Version history: + * 0.1.0: added + """ + + sensitive: "bool" + """ + Denotes whether media attachments to the status are marked sensitive. + + Version history: + * 0.9.9: added + """ + + spoiler_text: "str" + """ + Warning text that should be displayed before the status content. + + Version history: + * 1.0.0: added + """ + + visibility: "str" + """ + Toot visibility. + Should contain (as text): VisibilityEnum + + Version history: + * 0.9.9: added + """ + + mentions: "EntityList[Account]" + """ + A list Mentions this status includes. + + Version history: + * 0.6.0: added + """ + + media_attachments: "EntityList[MediaAttachment]" + """ + List files attached to this status. + + Version history: + * 0.6.0: added + """ + + emojis: "EntityList[CustomEmoji]" + """ + A list of CustomEmoji used in the status. + + Version history: + * 2.0.0: added + """ + + tags: "EntityList[Tag]" + """ + A list of Tags used in the status. + + Version history: + * 0.6.0: added + """ + + bookmarked: "Optional[bool]" + """ + True if the status is bookmarked by the logged in user, False if not. (optional) + + Version history: + * 3.1.0: added + """ + + application: "Optional[Application]" + """ + Application for the client used to post the status (Does not federate and is therefore always None for remote statuses, can also be None for local statuses for some legacy applications registered before this field was introduced). (optional) + + Version history: + * 0.9.9: added + """ + + language: "Optional[str]" + """ + The language of the status, if specified by the server, as ISO 639-1 (two-letter) language code. (nullable) + Should contain (as text): TwoLetterLanguageCodeEnum + + Version history: + * 1.4.0: added + """ + + muted: "Optional[bool]" + """ + Boolean denoting whether the user has muted this status by way of conversation muting. (optional) + + Version history: + * 1.4.0: added + """ + + pinned: "Optional[bool]" + """ + Boolean denoting whether or not the status is currently pinned for the associated account. (optional) + + Version history: + * 1.6.0: added + """ + + replies_count: "int" + """ + The number of replies to this status. + + Version history: + * 2.5.0: added + """ + + card: "Optional[PreviewCard]" + """ + A preview card for links from the status, if present at time of delivery. (nullable) + + Version history: + * 2.6.0: added + """ + + poll: "Optional[Poll]" + """ + A poll object if a poll is attached to this status. (nullable) + + Version history: + * 2.8.0: added + """ + + edited_at: "Optional[datetime]" + """ + Time the status was last edited. (nullable) + + Version history: + * 3.5.0: added + """ + + filtered: "Optional[EntityList[FilterResult]]" + """ + If present, a list of filter application results that indicate which of the users filters matched and what actions should be taken. (optional) + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class StatusEdit(AttribAccessDict): + """ + An object representing a past version of an edited status. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/StatusEdit/ + """ + + content: "str" + """ + Content for this version of the status. + + Version history: + * 3.5.0: added + """ + + spoiler_text: "str" + """ + CW / Spoiler text for this version of the status. + + Version history: + * 3.5.0: added + """ + + sensitive: "bool" + """ + Whether media in this version of the status is marked as sensitive. + + Version history: + * 3.5.0: added + """ + + created_at: "datetime" + """ + Time at which this version of the status was posted. + + Version history: + * 3.5.0: added + """ + + account: "Account" + """ + Account object of the user that posted the status. + + Version history: + * 3.5.0: added + """ + + media_attachments: "EntityList[MediaAttachment]" + """ + List of MediaAttachment objects with the attached media for this version of the status. + + Version history: + * 3.5.0: added + """ + + emojis: "EntityList[CustomEmoji]" + """ + List of custom emoji used in this version of the status. + + Version history: + * 3.5.0: added + """ + + poll: "Poll" + """ + The current state of the poll options at this revision. Note that edits changing the poll options will be collapsed together into one edit, since this action resets the poll. + + Version history: + * 3.5.0: added + """ + + _version = "3.5.0" + +class FilterResult(AttribAccessDict): + """ + A filter action that should be taken on a status. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/FilterResult/ + """ + + filter: "Union[Filter, FilterV2]" + """ + The filter that was matched. + + Version history: + * 4.0.0: added + """ + + keyword_matches: "Optional[EntityList[str]]" + """ + The keyword within the filter that was matched. (nullable) + + Version history: + * 4.0.0: added + """ + + status_matches: "Optional[EntityList]" + """ + The status ID within the filter that was matched. (nullable) + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class StatusMention(AttribAccessDict): + """ + A mention of a user within a status. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Mention/ + """ + + url: "str" + """ + Mentioned user's profile URL (potentially remote). + Should contain (as text): URL + + Version history: + * 0.6.0: added + """ + + username: "str" + """ + Mentioned user's user name (not including domain). + + Version history: + * 0.6.0: added + """ + + acct: "str" + """ + Mentioned user's account name (including domain). + + Version history: + * 0.6.0: added + """ + + id: "IdType" + """ + Mentioned user's (local) account ID. + + Version history: + * 0.6.0: added + """ + + _version = "0.6.0" + +class ScheduledStatus(AttribAccessDict): + """ + A scheduled status / toot to be eventually posted. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/ScheduledStatus/ + """ + + id: "IdType" + """ + Scheduled status ID (note: Not the id of the status once it gets posted!). + + Version history: + * 2.7.0: added + """ + + scheduled_at: "datetime" + """ + datetime object describing when the status is to be posted. + + Version history: + * 2.7.0: added + """ + + params: "ScheduledStatusParams" + """ + Parameters for the scheduled status, specifically. + + Version history: + * 2.7.0: added + """ + + media_attachments: "EntityList" + """ + Array of MediaAttachment objects for the attachments to the scheduled status. + + Version history: + * 2.7.0: added + """ + + _version = "2.7.0" + +class ScheduledStatusParams(AttribAccessDict): + """ + Parameters for a status / toot to be posted in the future. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/ScheduledStatus/ + """ + + text: "str" + """ + Toot text. + + Version history: + * 2.7.0: added + """ + + in_reply_to_id: "Optional[MaybeSnowflakeIdType]" + """ + ID of the status this one is a reply to. (nullable) + + Version history: + * 2.7.0: added + """ + + media_ids: "Optional[EntityList[str]]" + """ + IDs of media attached to this status. (nullable) + + Version history: + * 2.7.0: added + """ + + sensitive: "Optional[bool]" + """ + Whether this status is sensitive or not. (nullable) + + Version history: + * 2.7.0: added + """ + + visibility: "str" + """ + Visibility of the status. + + Version history: + * 2.7.0: added + """ + + idempotency: "Optional[str]" + """ + Idempotency key for the scheduled status. (nullable) + + Version history: + * 2.7.0: added + """ + + scheduled_at: "Optional[datetime]" + """ + Present, but generally "None". Unsure what this is for - the actual scheduled_at is in the ScheduledStatus object, not here. If you know, let me know. (nullable) + + Version history: + * 2.7.0: added + """ + + spoiler_text: "Optional[str]" + """ + CW text for this status. (nullable) + + Version history: + * 2.7.0: added + """ + + application_id: "IdType" + """ + ID of the application that scheduled the status. + + Version history: + * 2.7.0: added + """ + + poll: "Optional[Poll]" + """ + Poll parameters. (nullable) + + Version history: + * 2.8.0: added + """ + + language: "Optional[str]" + """ + The language that will be used for the status. (nullable) + Should contain (as text): TwoLetterLanguageCodeEnum + + Version history: + * 2.7.0: added + """ + + allowed_mentions: "Optional[EntityList[str]]" + """ + Undocumented. If you know what this does, please let me know. (nullable) + + Version history: + * 2.7.0: added + """ + + with_rate_limit: "bool" + """ + Whether the status should be rate limited. It is unclear to me what this does. If you know, please let met know. + + Version history: + * 2.7.0: added + """ + + _version = "2.8.0" + +class Poll(AttribAccessDict): + """ + A poll attached to a status. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Poll/ + """ + + id: "IdType" + """ + The polls ID. + + Version history: + * 2.8.0: added + """ + + expires_at: "Optional[datetime]" + """ + The time at which the poll is set to expire. (nullable) + + Version history: + * 2.8.0: added + """ + + expired: "bool" + """ + Boolean denoting whether users can still vote in this poll. + + Version history: + * 2.8.0: added + """ + + multiple: "bool" + """ + Boolean indicating whether it is allowed to vote for more than one option. + + Version history: + * 2.8.0: added + """ + + votes_count: "int" + """ + Total number of votes cast in this poll. + + Version history: + * 2.8.0: added + """ + + voted: "bool" + """ + Boolean indicating whether the logged-in user has already voted in this poll. + + Version history: + * 2.8.0: added + """ + + options: "EntityList[PollOption]" + """ + The poll options. + + Version history: + * 2.8.0: added + """ + + emojis: "EntityList[CustomEmoji]" + """ + List of CustomEmoji used in answer strings,. + + Version history: + * 2.8.0: added + """ + + own_votes: "EntityList[int]" + """ + The logged-in users votes, as a list of indices to the options. + + Version history: + * 2.8.0: added + """ + + voters_count: "Optional[int]" + """ + How many unique accounts have voted on a multiple-choice poll. (nullable) + + Version history: + * 2.8.0: added + """ + + _version = "2.8.0" + +class PollOption(AttribAccessDict): + """ + A poll option within a poll. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Poll/ + """ + + title: "str" + """ + Text of the option. + + Version history: + * 2.8.0: added + """ + + votes_count: "Optional[int]" + """ + Count of votes for the option. Can be None if the poll creator has chosen to hide vote totals until the poll expires and it hasn't yet. (nullable) + + Version history: + * 2.8.0: added + """ + + _version = "2.8.0" + +class Conversation(AttribAccessDict): + """ + A conversation (using direct / mentions-only visibility) between two or more users. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Conversation/ + """ + + id: "IdType" + """ + The ID of this conversation object. + + Version history: + * 2.6.0: added + """ + + unread: "bool" + """ + Boolean indicating whether this conversation has yet to be read by the user. + + Version history: + * 2.6.0: added + """ + + accounts: "EntityList[Account]" + """ + List of accounts (other than the logged-in account) that are part of this conversation. + + Version history: + * 2.6.0: added + """ + + last_status: "Optional[Status]" + """ + The newest status in this conversation. (nullable) + + Version history: + * 2.6.0: added + """ + + _version = "2.6.0" + +class Tag(AttribAccessDict): + """ + A hashtag, as part of a status or on its own (e.g. trending). + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Tag/ + """ + + name: "str" + """ + Hashtag name (not including the #). + + Version history: + * 0.9.0: added + """ + + url: "str" + """ + Hashtag URL (can be remote). + Should contain (as text): URL + + Version history: + * 0.9.0: added + """ + + history: "Optional[EntityList[TagHistory]]" + """ + List of TagHistory for up to 7 days. Not present in statuses. (optional) + + Version history: + * 2.4.1: added + """ + + following: "Optional[bool]" + """ + Boolean indicating whether the logged-in user is following this tag. (optional) + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class TagHistory(AttribAccessDict): + """ + Usage history for a hashtag. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Tag/ + """ + + day: "datetime" + """ + Date of the day this TagHistory is for. + Should contain (as text): datetime + + Version history: + * 2.4.1: added + """ + + uses: "str" + """ + Number of statuses using this hashtag on that day. + + Version history: + * 2.4.1: added + """ + + accounts: "str" + """ + Number of accounts using this hashtag in at least one status on that day. + + Version history: + * 2.4.1: added + """ + + _version = "2.4.1" + +class CustomEmoji(AttribAccessDict): + """ + A custom emoji. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/CustomEmoji/ + """ + + shortcode: "str" + """ + Emoji shortcode, without surrounding colons. + + Version history: + * 2.0.0: added + """ + + url: "str" + """ + URL for the emoji image, can be animated. + Should contain (as text): URL + + Version history: + * 2.0.0: added + """ + + static_url: "str" + """ + URL for the emoji image, never animated. + Should contain (as text): URL + + Version history: + * 2.0.0: added + """ + + visible_in_picker: "bool" + """ + True if the emoji is enabled, False if not. + + Version history: + * 2.0.0: added + """ + + category: "str" + """ + The category to display the emoji under (not present if none is set). + + Version history: + * 3.0.0: added + """ + + _version = "3.0.0" + +class Application(AttribAccessDict): + """ + Information about an app (in terms of the API). + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Application/ + """ + + name: "str" + """ + The applications name. + + Version history: + * 0.9.9: added + """ + + website: "Optional[str]" + """ + The applications website. (nullable) + + Version history: + * 0.9.9: added + * 3.5.1: this property is now nullable + """ + + vapid_key: "str" + """ + A vapid key that can be used in web applications. + + Version history: + * 2.8.0: added + """ + + _version = "3.5.1" + +class Relationship(AttribAccessDict): + """ + Information about the relationship between two users. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Relationship/ + """ + + id: "IdType" + """ + ID of the relationship object. + + Version history: + * 0.6.0: added + """ + + following: "bool" + """ + Boolean denoting whether the logged-in user follows the specified user. + + Version history: + * 0.6.0: added + """ + + followed_by: "bool" + """ + Boolean denoting whether the specified user follows the logged-in user. + + Version history: + * 0.6.0: added + """ + + blocking: "bool" + """ + Boolean denoting whether the logged-in user has blocked the specified user. + + Version history: + * 0.6.0: added + """ + + blocked_by: "bool" + """ + Boolean denoting whether the logged-in user has been blocked by the specified user, if information is available. + + Version history: + * 2.8.0: added + """ + + muting: "bool" + """ + Boolean denoting whether the logged-in user has muted the specified user. + + Version history: + * 1.1.0: added + """ + + muting_notifications: "bool" + """ + Boolean denoting wheter the logged-in user has muted notifications related to the specified user. + + Version history: + * 2.1.0: added + """ + + requested: "bool" + """ + Boolean denoting whether the logged-in user has sent the specified user a follow request. + + Version history: + * 0.9.9: added + """ + + domain_blocking: "bool" + """ + Boolean denoting whether the logged-in user has blocked the specified users domain. + + Version history: + * 1.4.0: added + """ + + showing_reblogs: "bool" + """ + Boolean denoting whether the specified users reblogs show up on the logged-in users Timeline. + + Version history: + * 2.1.0: added + """ + + endorsed: "bool" + """ + Boolean denoting wheter the specified user is being endorsed / featured by the logged-in user. + + Version history: + * 2.5.0: added + """ + + note: "str" + """ + A free text note the logged in user has created for this account (not publicly visible). + + Version history: + * 3.2.0: added + """ + + notifying: "bool" + """ + Boolean indicating whether the logged-in user has enabled notifications for this users posts. + + Version history: + * 3.3.0: added + """ + + languages: "Optional[EntityList[str]]" + """ + List of languages that the logged in user is following this user for (if any). (nullable) + Should contain (as text): TwoLetterLanguageCodeEnum + + Version history: + * 4.0.0: added + """ + + requested_by: "bool" + """ + Boolean indicating whether the specified user has sent the logged-in user a follow request. + + Version history: + * 0.9.9: added + """ + + _version = "4.0.0" + +class Filter(AttribAccessDict): + """ + Information about a keyword / status filter. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/V1_Filter/ + """ + + id: "IdType" + """ + Id of the filter. + + Version history: + * 2.4.3: added + """ + + phrase: "str" + """ + Filtered keyword or phrase. + + Version history: + * 2.4.3: added + """ + + context: "EntityList[str]" + """ + List of places where the filters are applied. + Should contain (as text): FilterContextEnum + + Version history: + * 2.4.3: added + * 3.1.0: added `account` + """ + + expires_at: "Optional[datetime]" + """ + Expiry date for the filter. (nullable) + + Version history: + * 2.4.3: added + """ + + irreversible: "bool" + """ + Boolean denoting if this filter is executed server-side or if it should be ran client-side. + + Version history: + * 2.4.3: added + """ + + whole_word: "bool" + """ + Boolean denoting whether this filter can match partial words. + + Version history: + * 2.4.3: added + """ + + _version = "3.1.0" + +class FilterV2(AttribAccessDict): + """ + Information about a keyword / status filter. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Filter/ + """ + + id: "IdType" + """ + Id of the filter. + + Version history: + * 4.0.0: added + """ + + context: "EntityList[str]" + """ + List of places where the filters are applied. + Should contain (as text): FilterContextEnum + + Version history: + * 4.0.0: added + """ + + expires_at: "Optional[datetime]" + """ + Expiry date for the filter. (nullable) + + Version history: + * 4.0.0: added + """ + + title: "str" + """ + Name the user has chosen for this filter. + + Version history: + * 4.0.0: added + """ + + filter_action: "str" + """ + The action to be taken when a status matches this filter. + Should contain (as text): FilterActionEnum + + Version history: + * 4.0.0: added + """ + + keywords: "EntityList[FilterKeyword]" + """ + A list of keywords that will trigger this filter. + + Version history: + * 4.0.0: added + """ + + statuses: "EntityList[FilterStatus]" + """ + A list of statuses that will trigger this filter. + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class Notification(AttribAccessDict): + """ + A notification about some event, like a new reply or follower. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Notification/ + """ + + id: "IdType" + """ + id of the notification. + + Version history: + * 0.9.9: added + """ + + type: "str" + """ + "mention", "reblog", "favourite", "follow", "poll" or "follow_request". + Should contain (as text): NotificationTypeEnum + + Version history: + * 0.9.9: added + * 2.8.0: added `poll` + * 3.1.0: added `follow_request` + * 3.3.0: added `status` + * 3.5.0: added `update` and `admin.sign_up` + * 4.0.0: added `admin.report` + """ + + created_at: "datetime" + """ + The time the notification was created. + + Version history: + * 0.9.9: added + """ + + account: "Account" + """ + Account of the user from whom the notification originates. + + Version history: + * 0.9.9: added + """ + + status: "Status" + """ + In case of "mention", the mentioning status In case of reblog / favourite, the reblogged / favourited status. + + Version history: + * 0.9.9: added + """ + + _version = "4.0.0" + +class Context(AttribAccessDict): + """ + The conversation context for a given status, i.e. its predecessors (that it replies to) and successors (that reply to it). + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Context/ + """ + + ancestors: "EntityList[Status]" + """ + A list of Statuses that the Status with this Context is a reply to. + + Version history: + * 0.6.0: added + """ + + descendants: "EntityList[Status]" + """ + A list of Statuses that are replies to the Status with this Context. + + Version history: + * 0.6.0: added + """ + + _version = "0.6.0" + +class UserList(AttribAccessDict): + """ + A list of users. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/List/ + """ + + id: "IdType" + """ + id of the list. + + Version history: + * 2.1.0: added + """ + + title: "str" + """ + title of the list. + + Version history: + * 2.1.0: added + """ + + replies_policy: "str" + """ + Which replies should be shown in the list. + Should contain (as text): RepliesPolicyEnum + + Version history: + * 3.3.0: added + """ + + _version = "3.3.0" + +class MediaAttachment(AttribAccessDict): + """ + A piece of media (like an image, video, or audio file) that can be or has been attached to a status. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/MediaAttachment/ + """ + + id: "MaybeSnowflakeIdType" + """ + The ID of the attachment. + + Version history: + * 0.6.0: added + """ + + type: "str" + """ + Media type: 'image', 'video', 'gifv', 'audio' or 'unknown'. + + Version history: + * 0.6.0: added + * 2.9.1: added `audio` + """ + + url: "str" + """ + The URL for the image in the local cache. + Should contain (as text): URL + + Version history: + * 0.6.0: added + """ + + remote_url: "Optional[str]" + """ + The remote URL for the media (if the image is from a remote instance). (nullable) + Should contain (as text): URL + + Version history: + * 0.6.0: added + """ + + preview_url: "str" + """ + The URL for the media preview. + Should contain (as text): URL + + Version history: + * 0.6.0: added + """ + + text_url: "str" + """ + THIS FIELD IS DEPRECATED. IT IS RECOMMENDED THAT YOU DO NOT USE IT. + + Deprecated. The display text for the media (what shows up in text). May not be present in mastodon versions after 3.5.0. + Should contain (as text): URL + + Version history: + * 0.6.0: added + * 3.5.0: removed + """ + + meta: "MediaAttachmentMetadataContainer" + """ + MediaAttachmentMetadataContainer that contains metadata for 'original' and 'small' (preview) versions of the MediaAttachment. Either may be empty. May additionally contain an "fps" field giving a videos frames per second (possibly rounded), and a "length" field giving a videos length in a human-readable format. Note that a video may have an image as preview. May also contain a 'focus' object and a media 'colors' object. + + Version history: + * 1.5.0: added + * 2.3.0: added focus + * 4.0.0: added colors + """ + + blurhash: "str" + """ + The blurhash for the image, used for preview / placeholder generation. + Should contain (as text): Blurhash + + Version history: + * 2.8.1: added + """ + + description: "Optional[str]" + """ + If set, the user-provided description for this media. (nullable) + + Version history: + * 2.0.0: added + """ + + preview_remote_url: "Optional[str]" + """ + If set, the remote URL for the thumbnail of this media attachment on the or originating instance. (nullable) + Should contain (as text): URL + + Version history: + * 0.6.0: added + """ + + _version = "4.0.0" + +class MediaAttachmentMetadataContainer(AttribAccessDict): + """ + An object holding metadata about a media attachment and its thumbnail. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/MediaAttachment/ + """ + + original: "Union[MediaAttachmentImageMetadata, MediaAttachmentVideoMetadata, MediaAttachmentAudioMetadata]" + """ + Metadata for the original media attachment. + + Version history: + * 0.6.0: added + """ + + small: "MediaAttachmentImageMetadata" + """ + Metadata for the thumbnail of this media attachment. + + Version history: + * 0.6.0: added + """ + + colors: "MediaAttachmentColors" + """ + Information about accent colors for the media. + + Version history: + * 4.0.0: added + """ + + focus: "MediaAttachmentFocusPoint" + """ + Information about the focus point for the media. + + Version history: + * 3.3.0: added + """ + + _version = "4.0.0" + +class MediaAttachmentImageMetadata(AttribAccessDict): + """ + Metadata for an image media attachment. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/MediaAttachment/ + """ + + width: "int" + """ + Width of the image in pixels. + + Version history: + * 0.6.0: added + """ + + height: "int" + """ + Height of the image in pixels. + + Version history: + * 0.6.0: added + """ + + aspect: "float" + """ + Aspect ratio of the image as a floating point number. + + Version history: + * 0.6.0: added + """ + + size: "str" + """ + Textual representation of the image size in pixels, e.g. '800x600'. + + Version history: + * 0.6.0: added + """ + + _version = "0.6.0" + +class MediaAttachmentVideoMetadata(AttribAccessDict): + """ + Metadata for a video or gifv media attachment. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/MediaAttachment/ + """ + + width: "int" + """ + Width of the video in pixels. + + Version history: + * 0.6.0: added + """ + + height: "int" + """ + Height of the video in pixels. + + Version history: + * 0.6.0: added + """ + + frame_rate: "str" + """ + Exact frame rate of the video in frames per second. Can be an integer fraction (i.e. "20/7"). + + Version history: + * 0.6.0: added + """ + + duration: "float" + """ + Duration of the video in seconds. + + Version history: + * 0.6.0: added + """ + + bitrate: "int" + """ + Average bit-rate of the video in bytes per second. + + Version history: + * 0.6.0: added + """ + + _version = "0.6.0" + +class MediaAttachmentAudioMetadata(AttribAccessDict): + """ + Metadata for an audio media attachment. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/MediaAttachment/ + """ + + duration: "float" + """ + Duration of the audio file in seconds. + + Version history: + * 0.6.0: added + """ + + bitrate: "int" + """ + Average bit-rate of the audio file in bytes per second. + + Version history: + * 0.6.0: added + """ + + _version = "0.6.0" + +class MediaAttachmentFocusPoint(AttribAccessDict): + """ + The focus point for a media attachment, for cropping purposes. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/MediaAttachment/ + """ + + x: "float" + """ + Focus point x coordinate (between -1 and 1), with 0 being the center and -1 and 1 being the left and right edges respectively. + + Version history: + * 2.3.0: added + """ + + y: "float" + """ + Focus point x coordinate (between -1 and 1), with 0 being the center and -1 and 1 being the upper and lower edges respectively. + + Version history: + * 2.3.0: added + """ + + _version = "2.3.0" + +class MediaAttachmentColors(AttribAccessDict): + """ + Object describing the accent colors for a media attachment. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/MediaAttachment/ + """ + + foreground: "str" + """ + Estimated foreground colour for the attachment thumbnail, as a html format hex color (#rrggbb). + + Version history: + * 4.0.0: added + """ + + background: "str" + """ + Estimated background colour for the attachment thumbnail, as a html format hex color (#rrggbb). + + Version history: + * 4.0.0: added + """ + + accent: "str" + """ + Estimated accent colour for the attachment thumbnail. + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class PreviewCard(AttribAccessDict): + """ + A preview card attached to a status, e.g. for an embedded video or link. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/PreviewCard/ + """ + + url: "str" + """ + The URL of the card. + Should contain (as text): URL + + Version history: + * 1.0.0: added + """ + + title: "str" + """ + The title of the card. + + Version history: + * 1.0.0: added + """ + + description: "str" + """ + Description of the embedded content. + + Version history: + * 1.0.0: added + """ + + type: "str" + """ + Embed type: 'link', 'photo', 'video', or 'rich'. + + Version history: + * 1.3.0: added + """ + + image: "Optional[str]" + """ + (optional) The image associated with the card. (nullable) + Should contain (as text): URL + + Version history: + * 1.0.0: added + """ + + author_name: "str" + """ + Name of the embedded contents author. + + Version history: + * 1.3.0: added + """ + + author_url: "str" + """ + URL pointing to the embedded contents author. + Should contain (as text): URL + + Version history: + * 1.3.0: added + """ + + width: "int" + """ + Width of the embedded object. + + Version history: + * 1.3.0: added + """ + + height: "int" + """ + Height of the embedded object. + + Version history: + * 1.3.0: added + """ + + html: "str" + """ + HTML string representing the embed. + Should contain (as text): HTML + + Version history: + * 1.3.0: added + """ + + provider_name: "str" + """ + Name of the provider from which the embed originates. + + Version history: + * 1.3.0: added + """ + + provider_url: "str" + """ + URL pointing to the embeds provider. + Should contain (as text): URL + + Version history: + * 1.3.0: added + """ + + blurhash: "Optional[str]" + """ + Blurhash of the preview image. (nullable) + Should contain (as text): Blurhash + + Version history: + * 3.2.0: added + """ + + language: "Optional[str]" + """ + Language of the embedded content. (optional) + Should contain (as text): TwoLetterLanguageCodeEnum + + Version history: + * 1.3.0: added + """ + + embed_url: "str" + """ + Used for photo embeds, instead of custom `html`. + Should contain (as text): URL + + Version history: + * 2.1.0: added + """ + + _version = "3.2.0" + +class Search(AttribAccessDict): + """ + A search result, with accounts, hashtags and statuses. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Search/ + """ + + accounts: "EntityList[Account]" + """ + List of Accounts resulting from the query. + + Version history: + * 1.1.0: added + """ + + hashtags: "EntityList[str]" + """ + THIS FIELD IS DEPRECATED. IT IS RECOMMENDED THAT YOU DO NOT USE IT. + + List of Tags resulting from the query. + + Version history: + * 1.1.0: added + * 2.4.1: v1 search deprecated because it returns a list of strings. v2 search added which returns a list of tags. + * 3.0.0: v1 removed + """ + + statuses: "EntityList[Status]" + """ + List of Statuses resulting from the query. + + Version history: + * 1.1.0: added + """ + + _version = "3.0.0" + +class SearchV2(AttribAccessDict): + """ + A search result, with accounts, hashtags and statuses. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Search/ + """ + + accounts: "EntityList[Account]" + """ + List of Accounts resulting from the query. + + Version history: + * 1.1.0: added + """ + + hashtags: "EntityList[Tag]" + """ + List of Tags resulting from the query. + + Version history: + * 2.4.1: added + """ + + statuses: "EntityList[Status]" + """ + List of Statuses resulting from the query. + + Version history: + * 1.1.0: added + """ + + _version = "2.4.1" + +class Instance(AttribAccessDict): + """ + Information about an instance. V1 API version. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/V1_Instance/ + """ + + uri: "str" + """ + The instance's domain name. Moved to 'domain' for the v2 API, though Mastodon.py will mirror it here for backwards compatibility. + Should contain (as text): DomainName + + Version history: + * 1.1.0: added + """ + + title: "str" + """ + The instance's title. + + Version history: + * 1.1.0: added + """ + + short_description: "str" + """ + An very brief text only instance description. Moved to 'description' for the v2 API. + + Version history: + * 2.9.2: added + """ + + description: "str" + """ + THIS FIELD IS DEPRECATED. IT IS RECOMMENDED THAT YOU DO NOT USE IT. + + A brief instance description set by the admin. The V1 variant could contain html, but this is now deprecated. Likely to be empty on many instances. + Should contain (as text): HTML + + Version history: + * 1.1.0: added + * 4.0.0: deprecated - likely to be empty. + """ + + email: "str" + """ + The admin contact email. Moved to InstanceContacts for the v2 API, though Mastodon.py will mirror it here for backwards compatibility. + Should contain (as text): Email + + Version history: + * 1.1.0: added + """ + + version: "str" + """ + The instance's Mastodon version. For a more robust parsed major/minor/patch version see TODO IMPLEMENT FUNCTION TO RETURN VERSIONS. + + Version history: + * 1.3.0: added + """ + + urls: "InstanceURLs" + """ + Additional InstanceURLs, in the v1 api version likely to be just 'streaming_api' with the stream server websocket address. + + Version history: + * 1.4.2: added + """ + + stats: "Optional[InstanceStatistics]" + """ + InstanceStatistics containing three stats, user_count (number of local users), status_count (number of local statuses) and domain_count (number of known instance domains other than this one). This information is not present in the v2 API variant in this form - there is a 'usage' field instead. (optional) + + Version history: + * 1.6.0: added + """ + + thumbnail: "Optional[str]" + """ + Information about thumbnails to represent the instance. In the v1 API variant, simply an URL pointing to a banner image representing the instance. The v2 API provides a more complex structure with a list of thumbnails of different sizes in this field. (nullable) + Should contain (as text): URL + + Version history: + * 1.6.1: added + """ + + languages: "EntityList[str]" + """ + Array of ISO 639-1 (two-letter) language codes the instance has chosen to advertise. + Should contain (as text): TwoLetterLanguageCodeEnum + + Version history: + * 2.3.0: added + """ + + registrations: "bool" + """ + A boolean indication whether registrations on this instance are open (True) or not (False). The v2 API variant instead provides a dict with more information about possible registration requirements here. + + Version history: + * 1.6.0: added + """ + + approval_required: "bool" + """ + True if account approval is required when registering, False if not. Moved to InstanceRegistrations object for the v2 API. + + Version history: + * 2.9.2: added + """ + + invites_enabled: "bool" + """ + THIS FIELD IS DEPRECATED. IT IS RECOMMENDED THAT YOU DO NOT USE IT. + + Boolean indicating whether invites are enabled on this instance. Changed in 4.0.0 from being true when the instance setting to enable invites is true to be true when the default user role has invites enabled (i.e. everyone can invite people). The v2 API does not contain this field, and it is not clear whether it will stay around. + + Version history: + * 3.1.4: added + * 4.0.0: changed specifics of when field is true, deprecated + """ + + configuration: "InstanceConfiguration" + """ + Various instance configuration settings - especially various limits (character counts, media upload sizes, ...). + + Version history: + * 3.1.4: added + """ + + contact_account: "Account" + """ + Account of the primary contact for the instance. Moved to InstanceContacts for the v2 API. + + Version history: + * 1.1.0: added + """ + + rules: "EntityList[Rule]" + """ + List of Rules with `id` and `text` fields, one for each server rule set by the admin. + + Version history: + * 3.4.0: added + """ + + _version = "4.0.0" + _access_map = { + "uri": "domain", + "short_description": "description", + "email": "contact.email", + "urls": "configuration.urls", + "contact_account": "contact.account", + } + +class InstanceConfiguration(AttribAccessDict): + """ + Configuration values for this instance, especially limits and enabled features. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/methods/instance/ + """ + + accounts: "InstanceAccountConfiguration" + """ + Account-related instance configuration fields. + + Version history: + * 3.4.2: added + """ + + statuses: "InstanceStatusConfiguration" + """ + Status-related instance configuration fields. + + Version history: + * 3.4.2: added + """ + + media_attachments: "InstanceMediaConfiguration" + """ + Media-related instance configuration fields. + + Version history: + * 3.4.2: added + """ + + polls: "InstancePollConfiguration" + """ + Poll-related instance configuration fields. + + Version history: + * 3.4.2: added + """ + + _version = "3.4.2" + +class InstanceURLs(AttribAccessDict): + """ + A list of URLs related to an instance. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/V1_Instance/ + """ + + streaming_api: "str" + """ + The Websockets URL for connecting to the streaming API. Renamed to 'streaming' for the v2 API. + Should contain (as text): URL + + Version history: + * 3.4.2: added + """ + + _version = "3.4.2" + _access_map = { + "streaming_api": "streaming", + } + +class InstanceV2(AttribAccessDict): + """ + Information about an instance. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Instance/ + """ + + domain: "str" + """ + The instances domain name. + Should contain (as text): DomainName + + Version history: + * 4.0.0: added + """ + + title: "str" + """ + The instance's title. + + Version history: + * 4.0.0: added + """ + + version: "str" + """ + The instance's Mastodon version. For a more robust parsed major/minor/patch version see TODO IMPLEMENT FUNCTION TO RETURN VERSIONS. + + Version history: + * 4.0.0: added + """ + + source_url: "str" + """ + URL pointing to a copy of the source code that is used to run this instance. For Mastodon instances, the AGPL requires that this code be available. + Should contain (as text): URL + + Version history: + * 4.0.0: added + """ + + description: "str" + """ + A brief instance description set by the admin. Contains what in the v1 version was the short description. + Should contain (as text): HTML + + Version history: + * 4.0.0: added + """ + + usage: "InstanceUsage" + """ + Information about recent activity on this instance. + + Version history: + * 4.0.0: added + """ + + thumbnail: "Optional[InstanceThumbnail]" + """ + Information about thumbnails to represent the instance. (nullable) + + Version history: + * 4.0.0: added + """ + + languages: "EntityList[str]" + """ + Array of ISO 639-1 (two-letter) language codes the instance has chosen to advertise. + Should contain (as text): TwoLetterLanguageCodeEnum + + Version history: + * 4.0.0: added + """ + + configuration: "InstanceConfiguration" + """ + Various instance configuration settings - especially various limits (character counts, media upload sizes, ...). + + Version history: + * 3.1.4: added + """ + + registrations: "InstanceRegistrations" + """ + InstanceRegistrations object with information about how users can sign up on this instance. + + Version history: + * 4.0.0: added + """ + + contact: "InstanceContact" + """ + Contact information for this instance. + + Version history: + * 4.0.0: added + """ + + rules: "EntityList[Rule]" + """ + List of Rules with `id` and `text` fields, one for each server rule set by the admin. + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class InstanceConfigurationV2(AttribAccessDict): + """ + Configuration values for this instance, especially limits and enabled features. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/methods/instance/ + """ + + accounts: "InstanceAccountConfiguration" + """ + Account-related instance configuration fields. + + Version history: + * 3.4.2: added + """ + + statuses: "InstanceStatusConfiguration" + """ + Status-related instance configuration fields. + + Version history: + * 3.4.2: added + """ + + media_attachments: "InstanceMediaConfiguration" + """ + Media-related instance configuration fields. + + Version history: + * 3.4.2: added + """ + + polls: "InstancePollConfiguration" + """ + Poll-related instance configuration fields. + + Version history: + * 3.4.2: added + """ + + translation: "InstanceTranslationConfiguration" + """ + Translation-related instance configuration fields. Only present for the v2 API variant of the instance API. + + Version history: + * 4.0.0: added + """ + + urls: "InstanceURLsV2" + """ + Instance related URLs. Only present for the v2 API variant of the instance API. + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class InstanceURLsV2(AttribAccessDict): + """ + A list of URLs related to an instance. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Instance/ + """ + + streaming: "str" + """ + The Websockets URL for connecting to the streaming API. + Should contain (as text): URL + + Version history: + * 4.0.0: added + """ + + status: "Optional[str]" + """ + If present, a URL where the status and possibly current issues with the instance can be checked. (optional) + Should contain (as text): URL + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class InstanceThumbnail(AttribAccessDict): + """ + Extended information about an instances thumbnail. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/V1_Instance/ + """ + + url: "str" + """ + The URL for an image representing the instance. + Should contain (as text): URL + + Version history: + * 4.0.0: added + """ + + blurhash: "Optional[str]" + """ + The blurhash for the image representing the instance. (optional) + Should contain (as text): Blurhash + + Version history: + * 4.0.0: added + """ + + versions: "Optional[InstanceThumbnailVersions]" + """ + Different resolution versions of the image representing the instance. (optional) + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class InstanceThumbnailVersions(AttribAccessDict): + """ + Different resolution versions of the image representing the instance. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Instance/ + """ + + at1x: "Optional[str]" + """ + The URL for an image representing the instance, for devices with 1x resolution / 96 dpi. (optional) + Should contain (as text): URL + + Version history: + * 4.0.0: added + """ + + at2x: "Optional[str]" + """ + The URL for the image representing the instance, for devices with 2x resolution / 192 dpi. (optional) + Should contain (as text): URL + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + _rename_map = { + "at1x": "@1x", + "at2x": "@2x", + } + +class InstanceStatistics(AttribAccessDict): + """ + Usage statistics for an instance. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Instance/ + """ + + user_count: "int" + """ + The total number of accounts that have been created on this instance. + + Version history: + * 1.6.0: added + """ + + status_count: "int" + """ + The total number of local posts that have been made on this instance. + + Version history: + * 1.6.0: added + """ + + domain_count: "int" + """ + The total number of other instances that this instance is aware of. + + Version history: + * 1.6.0: added + """ + + _version = "1.6.0" + +class InstanceUsage(AttribAccessDict): + """ + Usage / recent activity information for this instance. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Instance/ + """ + + users: "InstanceUsageUsers" + """ + Information about user counts on this instance. + + Version history: + * 3.0.0: added + """ + + _version = "3.0.0" + +class InstanceUsageUsers(AttribAccessDict): + """ + Recent active user information about this instance. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Instance/ + """ + + active_month: "int" + """ + This instances most recent monthly active user count. + + Version history: + * 3.0.0: added + """ + + _version = "3.0.0" + +class Rule(AttribAccessDict): + """ + A rule that instance staff has specified users must follow on this instance. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Rule/ + """ + + id: "IdType" + """ + An identifier for the rule. + + Version history: + * 3.4.0: added + """ + + text: "str" + """ + The rule to be followed. + + Version history: + * 3.4.0: added + """ + + _version = "3.4.0" + +class InstanceRegistrations(AttribAccessDict): + """ + Registration information for this instance, like whether registrations are open and whether they require approval. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Instance/ + """ + + approval_required: "bool" + """ + Boolean indicating whether registrations on the instance require approval. + + Version history: + * 4.0.0: added + """ + + enabled: "bool" + """ + Boolean indicating whether registrations are enabled on this instance. + + Version history: + * 4.0.0: added + """ + + message: "Optional[str]" + """ + A message to be shown instead of the sign-up form when registrations are closed. (nullable) + Should contain (as text): HTML + + Version history: + * 4.0.0: added + """ + + url: "Optional[str]" + """ + Presumably, a registration related URL. It is unclear what this is for. (nullable) + Should contain (as text): URL + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class InstanceContact(AttribAccessDict): + """ + Contact information for this instances' staff. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Instance/ + """ + + account: "Account" + """ + Account that has been designated as the instances contact account. + + Version history: + * 4.0.0: added + """ + + email: "str" + """ + E-mail address that can be used to contact the instance staff. + Should contain (as text): Email + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class InstanceAccountConfiguration(AttribAccessDict): + """ + Configuration values relating to accounts. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/methods/instance/ + """ + + max_featured_tags: "int" + """ + The maximum number of featured tags that can be displayed on a profile. + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class InstanceStatusConfiguration(AttribAccessDict): + """ + Configuration values relating to statuses. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/methods/instance/ + """ + + max_characters: "int" + """ + Maximum number of characters in a status this instance allows local users to use. + + Version history: + * 3.4.2: added + """ + + max_media_attachments: "int" + """ + Maximum number of media attachments per status this instance allows local users to use. + + Version history: + * 3.4.2: added + """ + + characters_reserved_per_url: "int" + """ + Number of characters that this instance counts a URL as when counting charaters. + + Version history: + * 3.4.2: added + """ + + _version = "3.4.2" + +class InstanceTranslationConfiguration(AttribAccessDict): + """ + Configuration values relating to translation. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/methods/instance/ + """ + + enabled: "bool" + """ + Boolean indicating whether the translation API is enabled on this instance. + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class InstanceMediaConfiguration(AttribAccessDict): + """ + Configuration values relating to media attachments. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/methods/instance/ + """ + + supported_mime_types: "EntityList[str]" + """ + Mime types the instance accepts for media attachment uploads. + + Version history: + * 3.4.2: added + """ + + image_size_limit: "int" + """ + Maximum size (in bytes) the instance will accept for image uploads. + + Version history: + * 3.4.2: added + """ + + image_matrix_limit: "int" + """ + Maximum total number of pixels (i.e. width * height) the instance will accept for image uploads. + + Version history: + * 3.4.2: added + """ + + video_size_limit: "int" + """ + Maximum size (in bytes) the instance will accept for video uploads. + + Version history: + * 3.4.2: added + """ + + video_frame_rate_limit: "int" + """ + Maximum frame rate the instance will accept for video uploads. + + Version history: + * 3.4.2: added + """ + + video_matrix_limit: "int" + """ + Maximum total number of pixels (i.e. width * height) the instance will accept for video uploads. + + Version history: + * 3.4.2: added + """ + + _version = "3.4.2" + +class InstancePollConfiguration(AttribAccessDict): + """ + Configuration values relating to polls. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/methods/instance/ + """ + + max_options: "int" + """ + How many poll options this instance allows local users to use per poll. + + Version history: + * 3.4.2: added + """ + + max_characters_per_option: "int" + """ + Maximum number of characters this instance allows local users to use per poll option. + + Version history: + * 3.4.2: added + """ + + min_expiration: "int" + """ + The shortest allowed duration for a poll on this instance, in seconds. + + Version history: + * 3.4.2: added + """ + + max_expiration: "int" + """ + The longest allowed duration for a poll on this instance, in seconds. + + Version history: + * 3.4.2: added + """ + + _version = "3.4.2" + +class Nodeinfo(AttribAccessDict): + """ + The instances standardized NodeInfo data. + + See also (Mastodon API documentation): https://github.com/jhass/nodeinfo + """ + + version: "str" + """ + Version of the nodeinfo schema spec that was used for this response. + + Version history: + * 3.0.0: added + """ + + software: "NodeinfoSoftware" + """ + Information about the server software being used on this instance. + + Version history: + * 3.0.0: added + """ + + protocols: "EntityList[str]" + """ + A list of strings specifying the federation protocols this instance supports. Typically, just "activitypub". + + Version history: + * 3.0.0: added + """ + + services: "NodeinfoServices" + """ + Services that this instance can retrieve messages from or send messages to. + + Version history: + * 3.0.0: added + """ + + usage: "NodeinfoUsage" + """ + Information about recent activity on this instance. + + Version history: + * 3.0.0: added + """ + + openRegistrations: "bool" + """ + Bool indicating whether the instance is open for registrations. + + Version history: + * 3.0.0: added + """ + + metadata: "NodeinfoMetadata" + """ + Additional node metadata. On Mastodon, typically an empty object with no fields. + + Version history: + * 3.0.0: added + """ + + _version = "3.0.0" + +class NodeinfoSoftware(AttribAccessDict): + """ + NodeInfo software-related information. + + See also (Mastodon API documentation): https://github.com/jhass/nodeinfo + """ + + name: "str" + """ + Name of the software used by this instance. + + Version history: + * 3.0.0: added + """ + + version: "str" + """ + String indicating the version of the software used by this instance. + + Version history: + * 3.0.0: added + """ + + _version = "3.0.0" + +class NodeinfoServices(AttribAccessDict): + """ + Nodeinfo services-related information. + + See also (Mastodon API documentation): https://github.com/jhass/nodeinfo + """ + + outbound: "EntityList" + """ + List of services that this instance can send messages to. On Mastodon, typically an empty list. + + Version history: + * 3.0.0: added + """ + + inbound: "EntityList" + """ + List of services that this instance can retrieve messages from. On Mastodon, typically an empty list. + + Version history: + * 3.0.0: added + """ + + _version = "3.0.0" + +class NodeinfoUsage(AttribAccessDict): + """ + Nodeinfo usage-related information. + + See also (Mastodon API documentation): https://github.com/jhass/nodeinfo + """ + + users: "NodeinfoUsageUsers" + """ + Information about user counts on this instance. + + Version history: + * 3.0.0: added + """ + + localPosts: "int" + """ + The total number of local posts that have been made on this instance. + + Version history: + * 3.0.0: added + """ + + _version = "3.0.0" + +class NodeinfoUsageUsers(AttribAccessDict): + """ + Nodeinfo user count statistics. + + See also (Mastodon API documentation): https://github.com/jhass/nodeinfo + """ + + total: "int" + """ + The total number of accounts that have been created on this instance. + + Version history: + * 3.0.0: added + """ + + activeMonth: "int" + """ + Number of users that have been active, by some definition (Mastodon: Have logged in at least once) in the last month. + + Version history: + * 3.0.0: added + """ + + activeHalfyear: "int" + """ + Number of users that have been active, by some definition (Mastodon: Have logged in at least once) in the last half year. + + Version history: + * 3.0.0: added + """ + + _version = "3.0.0" + +class NodeinfoMetadata(AttribAccessDict): + """ + Nodeinfo extra metadata. + + See also (Mastodon API documentation): https://github.com/jhass/nodeinfo + """ + + _version = "0.0.0" + +class Activity(AttribAccessDict): + """ + Information about recent activity on an instance. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/methods/instance/#activity + """ + + week: "datetime" + """ + Date of the first day of the week the stats were collected for. + + Version history: + * 2.1.2: added + """ + + logins: "int" + """ + Number of users that logged in that week. + + Version history: + * 2.1.2: added + """ + + registrations: "int" + """ + Number of new users that week. + + Version history: + * 2.1.2: added + """ + + statuses: "int" + """ + Number of statuses posted that week. + + Version history: + * 2.1.2: added + """ + + _version = "2.1.2" + +class Report(AttribAccessDict): + """ + Information about a report that has been filed against a user. Currently largely pointless, as updated reports cannot be fetched. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Report/ + """ + + id: "IdType" + """ + Id of the report. + + Version history: + * 2.9.1: added + """ + + action_taken: "bool" + """ + True if a moderator or admin has processed the report, False otherwise. + + Version history: + * 2.9.1: added + """ + + comment: "str" + """ + Text comment submitted with the report. + + Version history: + * 2.9.1: added + """ + + created_at: "datetime" + """ + Time at which this report was created, as a datetime object. + + Version history: + * 2.9.1: added + """ + + target_account: "Account" + """ + Account that has been reported with this report. + + Version history: + * 2.9.1: added + """ + + status_ids: "EntityList[IdType]" + """ + List of status IDs attached to the report. + + Version history: + * 2.9.1: added + """ + + action_taken_at: "Optional[datetime]" + """ + When an action was taken, if this report is currently resolved. (nullable) + + Version history: + * 2.9.1: added + """ + + category: "str" + """ + The category under which the report is classified. + Should contain (as text): ReportReasonEnum + + Version history: + * 3.5.0: added + """ + + forwarded: "bool" + """ + Whether a report was forwarded to a remote instance. + + Version history: + * 4.0.0: added + """ + + rules_ids: "EntityList[IdType]" + """ + IDs of the rules selected for this report. + + Version history: + * 3.5.0: added + """ + + _version = "4.0.0" + +class AdminReport(AttribAccessDict): + """ + Information about a report that has been filed against a user. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Admin_Report/ + """ + + id: "IdType" + """ + Id of the report. + + Version history: + * 2.9.1: added + """ + + action_taken: "bool" + """ + True if a moderator or admin has processed the report, False otherwise. + + Version history: + * 2.9.1: added + """ + + comment: "str" + """ + Text comment submitted with the report. + + Version history: + * 2.9.1: added + """ + + created_at: "datetime" + """ + Time at which this report was created, as a datetime object. + + Version history: + * 2.9.1: added + """ + + updated_at: "datetime" + """ + Last time this report has been updated, as a datetime object. + + Version history: + * 2.9.1: added + """ + + account: "Account" + """ + Account of the user that filed this report. + + Version history: + * 2.9.1: added + """ + + target_account: "Account" + """ + Account that has been reported with this report. + + Version history: + * 2.9.1: added + """ + + assigned_account: "Optional[AdminAccount]" + """ + If the report as been assigned to an account, that Account (None if not). (nullable) + + Version history: + * 2.9.1: added + """ + + action_taken_by_account: "Optional[AdminAccount]" + """ + Account that processed this report. (nullable) + + Version history: + * 2.9.1: added + """ + + statuses: "EntityList[Status]" + """ + List of Statuses attached to the report. + + Version history: + * 2.9.1: added + """ + + action_taken_at: "Optional[datetime]" + """ + When an action was taken, if this report is currently resolved. (nullable) + + Version history: + * 2.9.1: added + """ + + category: "str" + """ + The category under which the report is classified. + Should contain (as text): ReportReasonEnum + + Version history: + * 3.5.0: added + """ + + forwarded: "bool" + """ + Whether a report was forwarded to a remote instance. + + Version history: + * 4.0.0: added + """ + + rules: "EntityList[Rule]" + """ + Rules attached to the report, for context. + + Version history: + * 3.5.0: added + """ + + _version = "4.0.0" + +class WebPushSubscription(AttribAccessDict): + """ + Information about the logged-in users web push subscription for the authenticated application. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/WebPushSubscription/ + """ + + id: "IdType" + """ + Id of the push subscription. + + Version history: + * 2.4.0: added + """ + + endpoint: "str" + """ + Endpoint URL for the subscription. + Should contain (as text): URL + + Version history: + * 2.4.0: added + """ + + server_key: "str" + """ + Server pubkey used for signature verification. + + Version history: + * 2.4.0: added + """ + + alerts: "WebPushSubscriptionAlerts" + """ + Subscribed events - object that may contain various keys, with value True if webpushes have been requested for those events. + + Version history: + * 2.4.0: added + * 2.8.0: added poll` + * 3.1.0: added follow_request` + * 3.3.0: added status + * 3.5.0: added update and admin.sign_up + * 4.0.0: added admin.report + """ + + policy: "str" + """ + Which sources should generate webpushes. + + Version history: + * 2.4.0: added + """ + + _version = "4.0.0" + +class WebPushSubscriptionAlerts(AttribAccessDict): + """ + Information about alerts as part of a push subscription. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/WebPushSubscription/ + """ + + follow: "bool" + """ + True if push subscriptions for follow events have been requested, false or not present otherwise. + + Version history: + * 2.4.0: added + """ + + favourite: "bool" + """ + True if push subscriptions for favourite events have been requested, false or not present otherwise. + + Version history: + * 2.4.0: added + """ + + reblog: "bool" + """ + True if push subscriptions for reblog events have been requested, false or not present otherwise. + + Version history: + * 2.4.0: added + """ + + mention: "bool" + """ + True if push subscriptions for mention events have been requested, false or not present otherwise. + + Version history: + * 2.4.0: added + """ + + poll: "bool" + """ + True if push subscriptions for poll events have been requested, false or not present otherwise. + + Version history: + * 2.8.0: added + """ + + follow_request: "bool" + """ + True if push subscriptions for follow request events have been requested, false or not present otherwise. + + Version history: + * 2.4.0: added + """ + + status: "bool" + """ + True if push subscriptions for status creation (watched users only) events have been requested, false or not present otherwise. + + Version history: + * 3.1.0: added + """ + + update: "bool" + """ + True if push subscriptions for status update (edit) events have been requested, false or not present otherwise. + + Version history: + * 3.3.0: added + """ + + admin_sign_up: "bool" + """ + True if push subscriptions for sign up events have been requested, false or not present otherwise. Admins only. + + Version history: + * 3.5.0: added + """ + + admin_report: "bool" + """ + True if push subscriptions for report creation events have been requested, false or not present otherwise. Admins only. + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class PushNotification(AttribAccessDict): + """ + A single Mastodon push notification received via WebPush, after decryption. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/WebPushSubscription/ + """ + + access_token: "str" + """ + Access token that can be used to access the API as the notified user. + + Version history: + * 2.4.0: added + """ + + body: "str" + """ + Text body of the notification. + + Version history: + * 2.4.0: added + """ + + icon: "str" + """ + URL to an icon for the notification. + Should contain (as text): URL + + Version history: + * 2.4.0: added + """ + + notification_id: "IdType" + """ + ID that can be passed to notification() to get the full notification object,. + + Version history: + * 2.4.0: added + """ + + notification_type: "str" + """ + String indicating the type of notification. + + Version history: + * 2.4.0: added + """ + + preferred_locale: "str" + """ + The user's preferred locale. + Should contain (as text): TwoLetterLanguageCodeEnum + + Version history: + * 2.4.0: added + """ + + title: "str" + """ + Title for the notification. + + Version history: + * 2.4.0: added + """ + + _version = "2.4.0" + +class Preferences(AttribAccessDict): + """ + The logged in users preferences. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Preferences/ + """ + + posting_default_visibility: "str" + """ + Default visibility for new posts. Also found in CredentialAccountSource as `privacy`. + + Version history: + * 2.8.0: added + """ + + posting_default_sensitive: "bool" + """ + Default sensitivity flag for new posts. Also found in CredentialAccountSource as `sensitive`. + + Version history: + * 2.8.0: added + """ + + posting_default_language: "Optional[str]" + """ + Default language for new posts. Also found in CredentialAccountSource as `language`. (nullable) + Should contain (as text): TwoLetterLanguageCodeEnum + + Version history: + * 2.8.0: added + """ + + reading_expand_media: "str" + """ + String indicating whether media attachments should be automatically displayed or blurred/hidden. + + Version history: + * 2.8.0: added + """ + + reading_expand_spoilers: "bool" + """ + Boolean indicating whether CWs should be expanded by default. + + Version history: + * 2.8.0: added + """ + + reading_autoplay_gifs: "bool" + """ + Boolean indicating whether gifs should be autoplayed (True) or not (False). + + Version history: + * 2.8.0: added + """ + + _version = "2.8.0" + _rename_map = { + "posting_default_visibility": "posting:default:visibility", + "posting_default_sensitive": "posting:default:sensitive", + "posting_default_language": "posting:default:language", + "reading_expand_media": "reading:expand:media", + "reading_expand_spoilers": "reading:expand:spoilers", + "reading_autoplay_gifs": "reading:autoplay:gifs", + } + +class FeaturedTag(AttribAccessDict): + """ + A tag featured on a users profile. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/FeaturedTag/ + """ + + id: "IdType" + """ + The featured tags id. + + Version history: + * 3.0.0: added + """ + + name: "str" + """ + The featured tags name (without leading #). + + Version history: + * 3.0.0: added + """ + + statuses_count: "str" + """ + Number of publicly visible statuses posted with this hashtag that this instance knows about. + + Version history: + * 3.0.0: added + """ + + last_status_at: "datetime" + """ + The last time a public status containing this hashtag was added to this instance's database (can be None if there are none). + + Version history: + * 3.0.0: added + """ + + url: "str" + """ + A link to all statuses by a user that contain this hashtag. + Should contain (as text): URL + + Version history: + * 3.3.0: added + """ + + _version = "3.3.0" + +class Marker(AttribAccessDict): + """ + A read marker indicating where the logged in user has left off reading a given timeline. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Marker/ + """ + + last_read_id: "IdType" + """ + ID of the last read object in the timeline. + + Version history: + * 3.0.0: added + """ + + version: "int" + """ + A counter that is incremented whenever the marker is set to a new status. + + Version history: + * 3.0.0: added + """ + + updated_at: "datetime" + """ + The time the marker was last set, as a datetime object. + + Version history: + * 3.0.0: added + """ + + _version = "3.0.0" + +class Announcement(AttribAccessDict): + """ + An announcement sent by the instances staff. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Announcement/ + """ + + id: "IdType" + """ + The annoucements id. + + Version history: + * 3.1.0: added + """ + + content: "str" + """ + The contents of the annoucement, as an html string. + Should contain (as text): HTML + + Version history: + * 3.1.0: added + """ + + starts_at: "Optional[datetime]" + """ + The annoucements start time, as a datetime object. Can be None. (nullable) + + Version history: + * 3.1.0: added + """ + + ends_at: "Optional[datetime]" + """ + The annoucements end time, as a datetime object. Can be None. (nullable) + + Version history: + * 3.1.0: added + """ + + all_day: "bool" + """ + Boolean indicating whether the annoucement represents an "all day" event. + + Version history: + * 3.1.0: added + """ + + published_at: "datetime" + """ + The annoucements publish time, as a datetime object. + + Version history: + * 3.1.0: added + """ + + updated_at: "datetime" + """ + The annoucements last updated time, as a datetime object. + + Version history: + * 3.1.0: added + """ + + read: "bool" + """ + A boolean indicating whether the logged in user has dismissed the annoucement. + + Version history: + * 3.1.0: added + """ + + mentions: "EntityList[StatusMention]" + """ + Users mentioned in the annoucement. + + Version history: + * 3.1.0: added + """ + + tags: "EntityList" + """ + Hashtags mentioned in the announcement. + + Version history: + * 3.1.0: added + """ + + emojis: "EntityList" + """ + Custom emoji used in the annoucement. + + Version history: + * 3.1.0: added + """ + + reactions: "EntityList[Reaction]" + """ + Reactions to the annoucement. + + Version history: + * 3.1.0: added + """ + + statuses: "EntityList" + """ + Statuses linked in the announcement text. + + Version history: + * 3.1.0: added + """ + + _version = "3.1.0" + +class Reaction(AttribAccessDict): + """ + A reaction to an announcement. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Reaction/ + """ + + name: "str" + """ + Name of the custom emoji or unicode emoji of the reaction. + + Version history: + * 3.1.0: added + """ + + count: "int" + """ + Reaction counter (i.e. number of users who have added this reaction). + + Version history: + * 3.1.0: added + """ + + me: "bool" + """ + True if the logged-in user has reacted with this emoji, false otherwise. + + Version history: + * 3.1.0: added + """ + + url: "str" + """ + URL for the custom emoji image. + Should contain (as text): URL + + Version history: + * 3.1.0: added + """ + + static_url: "str" + """ + URL for a never-animated version of the custom emoji image. + Should contain (as text): URL + + Version history: + * 3.1.0: added + """ + + _version = "3.1.0" + +class StreamReaction(AttribAccessDict): + """ + A reaction to an announcement. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/methods/streaming/ + """ + + name: "str" + """ + Name of the custom emoji or unicode emoji of the reaction. + + Version history: + * 3.1.0: added + """ + + count: "int" + """ + Reaction counter (i.e. number of users who have added this reaction). + + Version history: + * 3.1.0: added + """ + + announcement_id: "IdType" + """ + If of the announcement this reaction was for. + + Version history: + * 3.1.0: added + """ + + _version = "3.1.0" + +class FamiliarFollowers(AttribAccessDict): + """ + A follower of a given account that is also followed by the logged-in user. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/FamiliarFollowers/ + """ + + id: "IdType" + """ + ID of the account for which the familiar followers are being returned. + + Version history: + * 3.5.0: added + """ + + accounts: "EntityList[Account]" + """ + List of Accounts of the familiar followers. + + Version history: + * 3.5.0: added + """ + + _version = "3.5.0" + +class AdminAccount(AttribAccessDict): + """ + Admin variant of the Account entity, with some additional information. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Admin_Account/ + """ + + id: "IdType" + """ + The users id,. + + Version history: + * 2.9.1: added + """ + + username: "str" + """ + The users username, no leading @. + + Version history: + * 2.9.1: added + """ + + domain: "Optional[str]" + """ + The users domain. (nullable) + + Version history: + * 2.9.1: added + """ + + created_at: "datetime" + """ + The time of account creation. + + Version history: + * 2.9.1: added + """ + + email: "str" + """ + For local users, the user's email. + Should contain (as text): Email + + Version history: + * 2.9.1: added + """ + + ip: "Optional[str]" + """ + For local users, the user's last known IP address. (nullable) + + Version history: + * 2.9.1: added + * 3.5.0: return type changed from String to [AdminIp]({{< relref "entities/Admin_Ip" >}}) due to a bug + * 4.0.0: bug fixed, return type is now a String again + """ + + role: "Role" + """ + The users role. + + Version history: + * 2.9.1: added, returns a String (enumerable, oneOf `user` `moderator` `admin`) + * 4.0.0: now uses Role entity + """ + + confirmed: "bool" + """ + For local users, False if the user has not confirmed their email, True otherwise. + + Version history: + * 2.9.1: added + """ + + suspended: "bool" + """ + Boolean indicating whether the user has been suspended. + + Version history: + * 2.9.1: added + """ + + silenced: "bool" + """ + Boolean indicating whether the user has been silenced. + + Version history: + * 2.9.1: added + """ + + disabled: "bool" + """ + For local users, boolean indicating whether the user has had their login disabled. + + Version history: + * 2.9.1: added + """ + + approved: "bool" + """ + For local users, False if the user is pending, True otherwise. + + Version history: + * 2.9.1: added + """ + + locale: "str" + """ + For local users, the locale the user has set,. + Should contain (as text): TwoLetterLanguageCodeEnum + + Version history: + * 2.9.1: added + """ + + invite_request: "Optional[str]" + """ + If the user requested an invite, the invite request comment of that user. (nullable) + + Version history: + * 2.9.1: added + """ + + account: "Account" + """ + The user's Account. + + Version history: + * 2.9.1: added + """ + + sensitized: "bool" + """ + Undocumented. If you know what this means, please let me know. + + Version history: + * 2.9.1: added + """ + + ips: "EntityList[AdminIp]" + """ + All known IP addresses associated with this account. + + Version history: + * 3.5.0: added + """ + + created_by_application_id: "Optional[IdType]" + """ + Present if the user was created by an application and set to the application id. (optional) + + Version history: + * 2.9.1: added + """ + + invited_by_account_id : "Optional[IdType]" + """ + Present if the user was created via invite and set to the inviting users id. (optional) + + Version history: + * 2.9.1: added + """ + + _version = "4.0.0" + +class AdminIp(AttribAccessDict): + """ + An IP address used by some user or other instance, visible as part of some admin APIs. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Admin_Ip/ + """ + + ip: "str" + """ + The IP address. + + Version history: + * 3.5.0: added + """ + + used_at: "str" + """ + The timestamp of when the IP address was last used for this account. + + Version history: + * 3.5.0: added + """ + + _version = "3.5.0" + +class AdminMeasure(AttribAccessDict): + """ + A measurement, such as the number of active users, as returned by the admin reporting API. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Admin_Measure/ + """ + + key: "str" + """ + Name of the measure returned. + Should contain (as text): AdminMeasureTypeEnum + + Version history: + * 3.5.0: added + """ + + unit: "Optional[str]" + """ + Unit for the measure, if available. (nullable) + + Version history: + * 3.5.0: added + """ + + total: "str" + """ + Value of the measure returned. + + Version history: + * 3.5.0: added + """ + + human_value: "str" + """ + Human readable variant of the measure returned. + + Version history: + * 3.5.0: added + """ + + previous_total: "Optional[str]" + """ + Previous measurement period value of the measure returned, if available. (nullable) + + Version history: + * 3.5.0: added + """ + + data: "EntityList[AdminMeasureData]" + """ + A list of AdminMeasureData with the measure broken down by date. + + Version history: + * 3.5.0: added + """ + + _version = "3.5.0" + +class AdminMeasureData(AttribAccessDict): + """ + A single row of data for an admin reporting api measurement. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Admin_Measure/ + """ + + date: "datetime" + """ + Date for this row. + + Version history: + * 3.5.0: added + """ + + value: "int" + """ + Value of the measure for this row. + + Version history: + * 3.5.0: added + """ + + _version = "3.5.0" + +class AdminDimension(AttribAccessDict): + """ + A qualitative measurement about the server, as returned by the admin reporting api. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Admin_Dimension/ + """ + + key: "str" + """ + Name of the dimension returned. + + Version history: + * 3.5.0: added + """ + + data: "EntityList[AdminDimensionData]" + """ + A list of data AdminDimensionData objects. + + Version history: + * 3.5.0: added + """ + + _version = "3.5.0" + +class AdminDimensionData(AttribAccessDict): + """ + A single row of data for qualitative measurements about the server, as returned by the admin reporting api. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Admin_Dimension/ + """ + + key: "str" + """ + category for this row. + + Version history: + * 3.5.0: added + """ + + human_key: "str" + """ + Human readable name for the category for this row, when available. + + Version history: + * 3.5.0: added + """ + + value: "int" + """ + Numeric value for the category. + + Version history: + * 3.5.0: added + """ + + _version = "3.5.0" + +class AdminRetention(AttribAccessDict): + """ + User retention data for a given cohort, as returned by the admin reporting api. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Admin_Cohort/ + """ + + period: "datetime" + """ + Starting time of the period that the data is being returned for. + + Version history: + * 3.5.0: added + """ + + frequency: "str" + """ + Time resolution (day or month) for the returned data. + + Version history: + * 3.5.0: added + """ + + data: "EntityList[AdminCohort]" + """ + List of AdminCohort objects. + + Version history: + * 3.5.0: added + """ + + _version = "3.5.0" + +class AdminCohort(AttribAccessDict): + """ + A single data point regarding user retention for a given cohort, as returned by the admin reporting api. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Admin_Cohort/ + """ + + date: "datetime" + """ + Date for this entry. + + Version history: + * 3.5.0: added + """ + + rate: "float" + """ + Fraction of users retained. + + Version history: + * 3.5.0: added + """ + + value: "int" + """ + Absolute number of users retained. + + Version history: + * 3.5.0: added + """ + + _version = "3.5.0" + +class AdminDomainBlock(AttribAccessDict): + """ + A domain block, as returned by the admin API. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Admin_DomainBlock/ + """ + + id: "IdType" + """ + The ID of the DomainBlock in the database. + + Version history: + * 4.0.0: added + """ + + domain: "str" + """ + The domain that is not allowed to federate. + + Version history: + * 4.0.0: added + """ + + created_at: "datetime" + """ + When the domain was blocked from federating. + + Version history: + * 4.0.0: added + """ + + severity: "str" + """ + The policy to be applied by this domain block. + Should contain (as text): AdminDomainLimitEnum + + Version history: + * 4.0.0: added + """ + + reject_media: "bool" + """ + Whether to reject media attachments from this domain. + + Version history: + * 4.0.0: added + """ + + reject_reports: "bool" + """ + Whether to reject reports from this domain. + + Version history: + * 4.0.0: added + """ + + private_comment: "Optional[str]" + """ + A private comment (visible only to other moderators) for the domain block. (nullable) + + Version history: + * 4.0.0: added + """ + + public_comment: "Optional[str]" + """ + A public comment (visible to either all users, or the whole world) for the domain block. (nullable) + + Version history: + * 4.0.0: added + """ + + obfuscate: "bool" + """ + Whether to obfuscate public displays of this domain block. + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class AdminCanonicalEmailBlock(AttribAccessDict): + """ + An e-mail block that has been set up to prevent certain e-mails to be used when signing up, via hash matching. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Admin_CanonicalEmailBlock + """ + + id: "IdType" + """ + The ID of the email block in the database. + + Version history: + * 4.0.0: added + """ + + canonical_email_hash: "str" + """ + The SHA256 hash of the canonical email address. + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class AdminDomainAllow(AttribAccessDict): + """ + The opposite of a domain block, specifically allowing a domain to federate when the instance is in allowlist mode. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Admin_DomainAllow + """ + + id: "IdType" + """ + The ID of the DomainAllow in the database. + + Version history: + * 4.0.0: added + """ + + domain: "str" + """ + The domain that is allowed to federate. + + Version history: + * 4.0.0: added + """ + + created_at: "datetime" + """ + When the domain was allowed to federate. + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class AdminEmailDomainBlock(AttribAccessDict): + """ + A block that has been set up to prevent e-mails from certain domains to be used when signing up. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Admin_EmailDomainBlock + """ + + id: "IdType" + """ + The ID of the EmailDomainBlock in the database. + + Version history: + * 4.0.0: added + """ + + domain: "str" + """ + The email domain that is not allowed to be used for signups. + + Version history: + * 4.0.0: added + """ + + created_at: "datetime" + """ + When the email domain was disallowed from signups. + + Version history: + * 4.0.0: added + """ + + history: "EntityList[AdminEmailDomainBlockHistory]" + """ + Usage statistics for given days (typically the past week). + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class AdminEmailDomainBlockHistory(AttribAccessDict): + """ + Historic data about attempted signups using e-mails from a given domain. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Admin_EmailDomainBlock + """ + + day: "datetime" + """ + The time (in day increments) for which this row of historical data is valid. + + Version history: + * 4.0.0: added + """ + + accounts: "int" + """ + The number of different account creation attempts that have been made. + + Version history: + * 4.0.0: added + """ + + uses: "int" + """ + The number of different ips used in account creation attempts. + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class AdminIpBlock(AttribAccessDict): + """ + An admin IP block, to prevent certain IP addresses or address ranges from accessing the instance. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Admin_IpBlock + """ + + id: "IdType" + """ + The ID of the DomainBlock in the database. + + Version history: + * 4.0.0: added + """ + + ip: "str" + """ + The IP address range that is not allowed to federate. + + Version history: + * 4.0.0: added + """ + + severity: "str" + """ + The associated policy with this IP block. + + Version history: + * 4.0.0: added + """ + + comment: "str" + """ + The recorded reason for this IP block. + + Version history: + * 4.0.0: added + """ + + created_at: "datetime" + """ + When the IP block was created. + + Version history: + * 4.0.0: added + """ + + expires_at: "Optional[datetime]" + """ + When the IP block will expire. (nullable) + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class DomainBlock(AttribAccessDict): + """ + A domain block that has been implemented by instance staff, limiting the way posts from the blocked instance are handled. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/DomainBlock + """ + + domain: "str" + """ + The domain which is blocked. This may be obfuscated or partially censored. + + Version history: + * 4.0.0: added + """ + + digest: "str" + """ + The SHA256 hash digest of the domain string. + + Version history: + * 4.0.0: added + """ + + severity: "str" + """ + The level to which the domain is blocked. + Should contain (as text): DomainLimitEnum + + Version history: + * 4.0.0: added + """ + + comment: "str" + """ + An optional reason for the domain block. + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class ExtendedDescription(AttribAccessDict): + """ + An extended instance description that can contain HTML. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/ExtendedDescription + """ + + updated_at: "datetime" + """ + A timestamp of when the extended description was last updated. + + Version history: + * 4.0.0: added + """ + + content: "str" + """ + The rendered HTML content of the extended description. + Should contain (as text): HTML + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class FilterKeyword(AttribAccessDict): + """ + A keyword that is being matched as part of a filter. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/FilterKeyword + """ + + id: "IdType" + """ + The ID of the FilterKeyword in the database. + + Version history: + * 4.0.0: added + """ + + keyword: "str" + """ + The phrase to be matched against. + + Version history: + * 4.0.0: added + """ + + whole_word: "bool" + """ + Should the filter consider word boundaries? See implementation guidelines for filters(). + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class FilterStatus(AttribAccessDict): + """ + A single status that is being matched as part of a filter. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/FilterStatus + """ + + id: "IdType" + """ + The ID of the FilterStatus in the database. + + Version history: + * 4.0.0: added + """ + + status_id: "MaybeSnowflakeIdType" + """ + The ID of the Status that will be filtered. + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class IdentityProof(AttribAccessDict): + """ + A cryptographic proof-of-identity. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/IdentityProof + """ + + provider: "str" + """ + The name of the identity provider. + + Version history: + * 2.8.0: added + """ + + provider_username: "str" + """ + The account owner's username on the identity provider's service. + + Version history: + * 2.8.0: added + """ + + updated_at: "datetime" + """ + When the identity proof was last updated. + + Version history: + * 2.8.0: added + """ + + proof_url: "str" + """ + A link to a statement of identity proof, hosted by the identity provider. + + Version history: + * 2.8.0: added + """ + + profile_url: "str" + """ + The account owner's profile URL on the identity provider. + + Version history: + * 2.8.0: added + """ + + _version = "2.8.0" + +class StatusSource(AttribAccessDict): + """ + The source data of a status, useful when editing a status. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/StatusSource + """ + + id: "IdType" + """ + ID of the status in the database. + + Version history: + * 3.5.0: added + """ + + text: "str" + """ + The plain text used to compose the status. + + Version history: + * 3.5.0: added + """ + + spoiler_text: "str" + """ + The plain text used to compose the status's subject or content warning. + + Version history: + * 3.5.0: added + """ + + _version = "3.5.0" + +class Suggestion(AttribAccessDict): + """ + A follow suggestion. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Suggestion + """ + + source: "str" + """ + The reason this account is being suggested. + + Version history: + * 3.4.0: added + """ + + account: "Account" + """ + The account being recommended to follow. + + Version history: + * 3.4.0: added + """ + + _version = "3.4.0" + +class Translation(AttribAccessDict): + """ + A translation of a status. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/entities/Translation + """ + + content: "str" + """ + The translated text of the status. + + Version history: + * 4.0.0: added + """ + + detected_source_language: "str" + """ + The language of the source text, as auto-detected by the machine translation provider. + + Version history: + * 4.0.0: added + """ + + provider: "str" + """ + The service that provided the machine translation. + + Version history: + * 4.0.0: added + """ + + _version = "4.0.0" + +class AccountCreationError(AttribAccessDict): + """ + An error response returned when creating an account fails. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/methods/accounts/#create + """ + + error: "str" + """ + The error as a localized string. + + Version history: + * 2.7.0: added + """ + + details: "AccountCreationErrorDetails" + """ + A dictionary giving more details about what fields caused errors and in which ways. + + Version history: + * 3.4.0: added + """ + + _version = "3.4.0" + +class AccountCreationErrorDetails(AttribAccessDict): + """ + An object containing detailed errors for different fields in the account creation attempt. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/methods/accounts/#create + """ + + username: "Optional[AccountCreationErrorDetailsField]" + """ + An object giving more details about an error caused by the username. (optional) + + Version history: + * 3.4.0: added + """ + + password: "Optional[AccountCreationErrorDetailsField]" + """ + An object giving more details about an error caused by the password. (optional) + + Version history: + * 3.4.0: added + """ + + email: "Optional[AccountCreationErrorDetailsField]" + """ + An object giving more details about an error caused by the e-mail. (optional) + + Version history: + * 3.4.0: added + """ + + agreement: "Optional[AccountCreationErrorDetailsField]" + """ + An object giving more details about an error caused by the usage policy agreement. (optional) + + Version history: + * 3.4.0: added + """ + + locale: "Optional[AccountCreationErrorDetailsField]" + """ + An object giving more details about an error caused by the locale. (optional) + + Version history: + * 3.4.0: added + """ + + reason: "Optional[AccountCreationErrorDetailsField]" + """ + An object giving more details about an error caused by the registration reason. (optional) + + Version history: + * 3.4.0: added + """ + + _version = "3.4.0" + +class AccountCreationErrorDetailsField(AttribAccessDict): + """ + An object giving details about what specifically is wrong with a given field in an account registration attempt. + + See also (Mastodon API documentation): https://docs.joinmastodon.org/methods/accounts/#create + """ + + error: "str" + """ + A machine readable string giving an error category. + + Version history: + * 3.4.0: added + """ + + description: "str" + """ + A description of the issue as a localized string. + + Version history: + * 3.4.0: added + """ + + _version = "3.4.0" diff --git a/mastodon/types_base.py b/mastodon/types_base.py new file mode 100644 index 0000000..a50f2fb --- /dev/null +++ b/mastodon/types_base.py @@ -0,0 +1,347 @@ +from typing import List, Union, Optional, Dict, Any, Tuple, Callable, get_type_hints, TypeVar, IO +from datetime import datetime, timezone +import dateutil +import dateutil.parser +from collections import OrderedDict +import inspect +import json +from mastodon.compat import PurePath + +# A type representing a file name as a PurePath or string, or a file-like object, for convenience +PathOrFile = Union[str, PurePath, IO[bytes]] + +BASE62_ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ' +def base62_to_int(base62: str) -> int: + """ + internal helper for *oma compat: convert a base62 string to an int since + that is what that software uses as ID type. + + we don't convert IDs in general, but this is needed for snowflake ID + calculations. + """ + str_len = len(base62) + val = 0 + base62 = base62.lower() + for idx, char in enumerate(base62): + power = (str_len - (idx + 1)) + val += BASE62_ALPHABET.index(char) * (62 ** power) + return val + +def int_to_base62(val: int) -> str: + """ + Internal helper to convert an int to a base62 string. + """ + if val == 0: + return BASE62_ALPHABET[0] + + base62 = [] + while val: + val, digit = divmod(val, 62) + base62.append(BASE62_ALPHABET[digit]) + return ''.join(reversed(base62)) + +""" +The base type for all non-snowflake IDs. This is a union of int and str +because while Mastodon mostly uses IDs that are ints, it doesn't guarantee +this and other implementations do not use integer IDs. + +In a change from previous versions, string IDs now take precedence over ints. +This is a breaking change, and I'm sorry about it, but this will make every piece +of software using Mastodon.py more robust in the long run. +""" +PrimitiveIdType = Union[str, int] + +class MaybeSnowflakeIdType(str): + """ + Represents, maybe, a snowflake ID. + + Contains what a regular ID can contain (int or str) and will convert to int if + containing an int or a str that naturally converts to an int (e.g. "123"). + + Can *also* contain a *datetime* which gets converted to + + It's also just *maybe* a snowflake ID, because some implementations may not use those. + + This may seem annoyingly complex, but the goal here is: + 1) If constructed with some ID, return that ID unchanged, so equality and hashing work + 2) Allow casting to int and str, just like a regular ID + 3) Halfway transparently convert to and from datetime with the correct format for the server we're talking to + """ + def __new__(cls, value, *args, **kwargs): + try: + return super(cls, cls).__new__(cls, value) + except: + return object.__new__(cls) + + def __init__(self, val: Union[PrimitiveIdType, datetime], assume_pleroma: bool = False): + try: + super(MaybeSnowflakeIdType, self).__init__() + except: + pass + if isinstance(val, (int, str)): + self.__val = val + elif isinstance(val, datetime): + self.__val = (int(val.timestamp()) << 16) * 1000 + if assume_pleroma: + self.__val = int_to_base62(self.__val) + else: + raise TypeError(f"Expected int or str, got {type(val).__name__}") + self.assume_pleroma = assume_pleroma + + def to_datetime(self) -> Optional[datetime]: + """ + Convert to datetime. This *can* fail because not every implementation of + the masto API is guaranteed to actually use snowflake IDs where masto uses + snowflake IDs, so it can in fact return None. + """ + val = self.__val + try: + # Pleroma ID compat. First, try to just cast to int. If that fails *or* + # if we are told to assume Pleroma, try to convert from base62. + if isinstance(self.__val, str): + try_base62 = False + try: + val = int(self.__val) + except: + try_base62 = True + if try_base62 or self.assume_pleroma: + val = base62_to_int(self.__val) + except: + return None + + # TODO: This matches the masto approach, whether this matches the + # Pleroma approach is to be verified. + timestamp_s = int(int(val) / 1000) >> 16 + return datetime.fromtimestamp(timestamp_s) + + def __str__(self) -> str: + """ + Return as string representation. + """ + return str(self.__val) + + def __int__(self) -> int: + """ + Return as int representation. + + This is not guaranteed to work, because the ID might be a string, + though on Mastodon it is generally going to be an int. + """ + if isinstance(self.__val, str): + return int(self.__val) + return self.__val + + def __repr__(self) -> str: + """ + Overriden so that the integer representation doesn't take precedence + """ + return str(self.__val) + +""" +IDs returned from Mastodon.py ar either primitive (int or str) or snowflake +(still int or str, but potentially convertible to datetime). +""" +IdType = Union[PrimitiveIdType, MaybeSnowflakeIdType] + +T = TypeVar('T') +class PaginatableList(List[T]): + """ + This is a list with pagination information attached. + + It is returned by the API when a list of items is requested, and the response contains + a Link header with pagination information. + """ + def __getattr__(self, attr): + if attr in self: + return self[attr] + else: + raise AttributeError(f"Attribute not found: {attr}") + + def __setattr__(self, attr, val): + if attr in self: + raise AttributeError("Attribute-style access is read only") + super(NonPaginatableList, self).__setattr__(attr, val) + # TODO add the pagination housekeeping stuff + +class NonPaginatableList(List[T]): + """ + This is just a list. I am subclassing the regular list out of pure paranoia about + potential oversights that might require me to add things to it later. + """ + pass + +# Lists in Mastodon.py are either regular or paginatable +EntityList = Union[NonPaginatableList[T], PaginatableList[T]] + +# Backwards compat alias +AttribAccessList = EntityList + +# Helper functions for typecasting attempts +def try_cast(t, value, retry = True): + """ + Base case casting function. Handles: + * Casting to any AttribAccessDict subclass (directly, no special handling) + * Casting to MaybeSnowflakeIdType (directly, no special handling) + * Casting to bool (with possible conversion from json bool strings) + * Casting to datetime (with possible conversion from all kinds of funny date formats because unfortunately this is the world we live in) + Gives up and returns as-is if none of the above work. + """ + try: + if issubclass(t, AttribAccessDict) or t is MaybeSnowflakeIdType: + try: + value = t(**value) + except: + try: + value = AttribAccessDict(**value) + except: + pass + elif isinstance(t, bool): + if isinstance(value, str): + if value.lower() == 'true': + value = True + elif value.lower() == 'false': + value = False + value = bool(value) + elif isinstance(t, datetime): + if isinstance(value, int): + value = datetime.fromtimestamp(value, timezone.utc) + elif isinstance(value, str): + try: + value_int = int(value) + value = datetime.fromtimestamp(value_int, timezone.utc) + except: + value = dateutil.parser.parse(value) + except: + value = try_cast(AttribAccessDict, value, False) + return value + +def try_cast_recurse(t, value): + """ + Non-dict compound type casting function. Handles: + * Casting to list, tuple, EntityList or (Non)PaginatableList, converting all elements to the correct type recursively + * Casting to Union, trying all types in the union until one works + Gives up and returns as-is if none of the above work. + """ + try: + orig_type = getattr(t, '__origin__') + if orig_type in (list, tuple, EntityList, NonPaginatableList, PaginatableList): + value_cast = [] + type_args = t.__args__ + if len(type_args) == 1: + type_args = type_args * len(value) + for element_type, v in zip(type_args, value): + value_cast.append(try_cast_recurse(element_type, v)) + value = orig_type(value_cast) + elif orig_type is Union: + for t in t.__args__: + value = try_cast_recurse(t, value) + if isinstance(value, t): + break + except Exception as e: + pass + return try_cast(t, value) + +class AttribAccessDict(OrderedDict[str, Any]): + """ + Base return object class for Mastodon.py. + + Inherits from dict, but allows access via attributes as well as if it was a dataclass. + + While the subclasses implement specific fields with proper typing, parsing and documentation, + they all inherit from this class, and parsing is extremely permissive to allow for forward and + backward compatibility as well as compatibility with other implementations of the Mastodon API. + """ + def __init__(self, **kwargs): + """ + Constructor that calls through to dict constructor and then sets attributes for all keys. + """ + super(AttribAccessDict, self).__init__() + if __annotations__ in self.__class__.__dict__: + for attr, _ in self.__class__.__annotations__.items(): + attr_name = attr + if hasattr(self.__class__, "_rename_map"): + attr_name = getattr(self.__class__, "_rename_map").get(attr, attr) + if attr_name in kwargs: + self[attr] = kwargs[attr_name] + assert not attr in kwargs, f"Duplicate attribute {attr}" + elif attr in kwargs: + self[attr] = kwargs[attr] + else: + self[attr] = None + for attr in kwargs: + if not attr in self: + self[attr] = kwargs[attr] + + def __getattribute__(self, attr): + """ + Override to force access of normal attributes to go through __getattr__ + """ + if attr == '__class__': + return super(AttribAccessDict, self).__getattribute__(attr) + if attr in self.__class__.__annotations__: + return self.__getattr__(attr) + return super(AttribAccessDict, self).__getattribute__(attr) + + def __getattr__(self, attr): + """ + Basic attribute getter that throws if attribute is not in dict and supports redirecting access. + """ + if not hasattr(self.__class__, "_access_map"): + # Base case: no redirecting + if attr in self: + return self[attr] + else: + raise AttributeError(f"Attribute not found: {attr}") + else: + if attr in self and self[attr] is not None: + return self[attr] + elif attr in getattr(self.__class__, "_access_map"): + try: + attr_path = getattr(self.__class__, "_access_map")[attr].split('.') + cur_attr = self + for attr_path_part in attr_path: + cur_attr = getattr(cur_attr, attr_path_part) + return cur_attr + except: + raise AttributeError(f"Attribute not found: {attr}") + else: + raise AttributeError(f"Attribute not found: {attr}") + + def __setattr__(self, attr, val): + """ + Attribute setter that calls through to dict setter but will throw if attribute is not in dict + """ + if attr in self: + self[attr] = val + else: + raise AttributeError(f"Attribute not found: {attr}") + + def __setitem__(self, key, val): + """ + Dict setter that also sets attributes and tries to typecast if we have an + AttribAccessDict or MaybeSnowflakeIdType type hint. + + For Unions, it will try the types in order. + """ + # Collate type hints that we may have + type_hints = get_type_hints(self.__class__) + init_hints = get_type_hints(self.__class__.__init__) + type_hints.update(init_hints) + + # Do typecasting, possibly iterating over a list or tuple + if key in type_hints: + type_hint = type_hints[key] + val = try_cast_recurse(type_hint, val) + + # Finally, call out to setattr and setitem proper + super(AttribAccessDict, self).__setattr__(key, val) + super(AttribAccessDict, self).__setitem__(key, val) + +"""An entity returned by the Mastodon API is either a dict or a list""" +Entity = Union[AttribAccessDict, EntityList] + +"""A type containing the parameters for a encrypting webpush data. Considered opaque / implementation detail.""" +WebpushCryptoParamsPubkey = Dict[str, str] + +"""A type containing the parameters for a derypting webpush data. Considered opaque / implementation detail.""" +WebpushCryptoParamsPrivkey = Dict[str, str] \ No newline at end of file diff --git a/mastodon/utility.py b/mastodon/utility.py index 815d9d5..2cd31a9 100644 --- a/mastodon/utility.py +++ b/mastodon/utility.py @@ -5,89 +5,14 @@ import dateutil import datetime import copy -from decorator import decorate -from .errors import MastodonVersionError, MastodonAPIError -from .compat import IMPL_HAS_BLURHASH, blurhash - -# Module level: - -### -# Version check functions, including decorator and parser -### -def parse_version_string(version_string): - """Parses a semver version string, stripping off "rc" stuff if present.""" - string_parts = version_string.split(".") - version_parts = ( - int(re.match("([0-9]*)", string_parts[0]).group(0)), - int(re.match("([0-9]*)", string_parts[1]).group(0)), - int(re.match("([0-9]*)", string_parts[2]).group(0)) - ) - return version_parts - - -def max_version(*version_strings): - """Returns the maximum version of all provided version strings.""" - return max(version_strings, key=parse_version_string) - - -def api_version(created_ver, last_changed_ver, return_value_ver): - """Version check decorator. Currently only checks Bigger Than.""" - def api_min_version_decorator(function): - def wrapper(function, self, *args, **kwargs): - if not self.version_check_mode == "none": - if self.version_check_mode == "created": - version = created_ver - else: - version = max_version(last_changed_ver, return_value_ver) - major, minor, patch = parse_version_string(version) - if major > self.mastodon_major: - raise MastodonVersionError(f"Version check failed (Need version {version})") - elif major == self.mastodon_major and minor > self.mastodon_minor: - raise MastodonVersionError(f"Version check failed (Need version {version})") - elif major == self.mastodon_major and minor == self.mastodon_minor and patch > self.mastodon_patch: - raise MastodonVersionError(f"Version check failed (Need version {version}, patch is {self.mastodon_patch})") - return function(self, *args, **kwargs) - function.__doc__ += f"\n\n *Added: Mastodon v{created_ver}, last changed: Mastodon v{last_changed_ver}*" - return decorate(function, wrapper) - return api_min_version_decorator - - -### -# Dict helper class. -# Defined at top level so it can be pickled. -### -class AttribAccessDict(dict): - def __getattr__(self, attr): - if attr in self: - return self[attr] - else: - raise AttributeError(f"Attribute not found: {attr}") - - def __setattr__(self, attr, val): - if attr in self: - raise AttributeError("Attribute-style access is read only") - super(AttribAccessDict, self).__setattr__(attr, val) - - -### -# List helper class. -# Defined at top level so it can be pickled. -### -class AttribAccessList(list): - def __getattr__(self, attr): - if attr in self: - return self[attr] - else: - raise AttributeError(f"Attribute not found: {attr}") - - def __setattr__(self, attr, val): - if attr in self: - raise AttributeError("Attribute-style access is read only") - super(AttribAccessList, self).__setattr__(attr, val) +from mastodon.errors import MastodonAPIError +from mastodon.compat import IMPL_HAS_BLURHASH, blurhash +from mastodon.internals import Mastodon as Internals +from mastodon.versions import parse_version_string, max_version, api_version # Class level: -class Mastodon(): +class Mastodon(Internals): def set_language(self, lang): """ Set the locale Mastodon will use to generate responses. Valid parameters are all ISO 639-1 (two letter) or, for languages that do @@ -104,11 +29,11 @@ class Mastodon(): try: version_str = self.__normalize_version_string(self.__instance()["version"]) self.version_check_worked = True - except: + except Exception as e: + print(e) # instance() was added in 1.1.0, so our best guess is 1.0.0. version_str = "1.0.0" self.version_check_worked = False - self.mastodon_major, self.mastodon_minor, self.mastodon_patch = parse_version_string(version_str) return version_str diff --git a/mastodon/versions.py b/mastodon/versions.py index 1c333e3..42e418f 100644 --- a/mastodon/versions.py +++ b/mastodon/versions.py @@ -1,9 +1,55 @@ # versions.py - versioning of return values -from .utility import max_version +import re +from decorator import decorate +from mastodon.errors import MastodonVersionError +### +# Version check functions, including decorator and parser +### +def parse_version_string(version_string): + """Parses a semver version string, stripping off "rc" stuff if present.""" + string_parts = version_string.split(".") + version_parts = ( + int(re.match("([0-9]*)", string_parts[0]).group(0)), # type: ignore + int(re.match("([0-9]*)", string_parts[1]).group(0)), # type: ignore + int(re.match("([0-9]*)", string_parts[2]).group(0)) # type: ignore + ) + return version_parts + + +def max_version(*version_strings): + """Returns the maximum version of all provided version strings.""" + return max(version_strings, key=parse_version_string) + + +def api_version(created_ver, last_changed_ver, return_value_ver): + """Version check decorator. Currently only checks Bigger Than.""" + def api_min_version_decorator(function): + def wrapper(function, self, *args, **kwargs): + if not self.version_check_mode == "none": + if self.version_check_mode == "created": + version = created_ver + else: + version = max_version(last_changed_ver, return_value_ver) + major, minor, patch = parse_version_string(version) + if major > self.mastodon_major: + raise MastodonVersionError(f"Version check failed (Need version {version})") + elif major == self.mastodon_major and minor > self.mastodon_minor: + raise MastodonVersionError(f"Version check failed (Need version {version})") + elif major == self.mastodon_major and minor == self.mastodon_minor and patch > self.mastodon_patch: + raise MastodonVersionError(f"Version check failed (Need version {version}, patch is {self.mastodon_patch})") + return function(self, *args, **kwargs) + function.__doc__ += f"\n\n *Added: Mastodon v{created_ver}, last changed: Mastodon v{last_changed_ver}*" + return decorate(function, wrapper) + return api_min_version_decorator + + +### # Dict versions +# TODO: Get rid of these +### _DICT_VERSION_APPLICATION = "2.7.2" _DICT_VERSION_MENTION = "1.0.0" _DICT_VERSION_MEDIA = "3.2.0" @@ -38,3 +84,4 @@ _DICT_VERSION_ADMIN_DOMAIN_BLOCK = "4.0.0" _DICT_VERSION_ADMIN_MEASURE = "3.5.0" _DICT_VERSION_ADMIN_DIMENSION = "3.5.0" _DICT_VERSION_ADMIN_RETENTION = "3.5.0" + diff --git a/srcgen/return_types_all_current_fixed.json b/srcgen/return_types_all_current_fixed.json index 8e89965..8035f2d 100644 --- a/srcgen/return_types_all_current_fixed.json +++ b/srcgen/return_types_all_current_fixed.json @@ -12,7 +12,7 @@ "fields": { "id": { "description": "The accounts id", - "field_type": "SnowflakeIdType", + "field_type": "MaybeSnowflakeIdType", "field_subtype": null, "is_optional": false, "is_nullable": false, @@ -318,7 +318,7 @@ }, "fields": { "description": "List of up to four (by default) AccountFields", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "AccountField", "is_optional": false, "is_nullable": false, @@ -332,7 +332,7 @@ }, "emojis": { "description": "List of custom emoji used in name, bio or fields", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "CustomEmoji", "is_optional": false, "is_nullable": false, @@ -379,7 +379,7 @@ "roles": { "description": "Deprecated. Was a list of strings with the users roles. Now just an empty list. Mastodon.py makes no attempt to fill it, and the field may be removed if Mastodon removes it. use role field instead.", "is_deprecated": true, - "field_type": "list", + "field_type": "EntityList", "field_subtype": null, "is_optional": false, "is_nullable": false, @@ -649,7 +649,7 @@ }, "fields": { "description": "Metadata about the account.", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "AccountField", "is_optional": false, "is_nullable": false, @@ -690,7 +690,7 @@ "fields": { "id": { "description": "Id of this status", - "field_type": "SnowflakeIdType", + "field_type": "MaybeSnowflakeIdType", "field_subtype": null, "is_optional": false, "is_nullable": false, @@ -746,7 +746,7 @@ }, "in_reply_to_id": { "description": "Id of the status this status is in response to", - "field_type": "SnowflakeIdType", + "field_type": "MaybeSnowflakeIdType", "field_subtype": null, "is_optional": false, "is_nullable": true, @@ -759,7 +759,7 @@ }, "in_reply_to_account_id": { "description": "Id of the account this status is in response to", - "field_type": "SnowflakeIdType", + "field_type": "MaybeSnowflakeIdType", "field_subtype": null, "is_optional": false, "is_nullable": true, @@ -916,7 +916,7 @@ }, "mentions": { "description": "A list Mentions this status includes", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "Account", "is_optional": false, "is_nullable": false, @@ -929,7 +929,7 @@ }, "media_attachments": { "description": "List files attached to this status", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "MediaAttachment", "is_optional": false, "is_nullable": false, @@ -943,7 +943,7 @@ }, "emojis": { "description": "A list of CustomEmoji used in the status", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "CustomEmoji", "is_optional": false, "is_nullable": false, @@ -956,7 +956,7 @@ }, "tags": { "description": "A list of Tags used in the status", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "Tag", "is_optional": false, "is_nullable": false, @@ -1088,7 +1088,7 @@ }, "filtered": { "description": "If present, a list of filter application results that indicate which of the users filters matched and what actions should be taken.", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "FilterResult", "is_optional": true, "is_nullable": false, @@ -1184,7 +1184,7 @@ }, "media_attachments": { "description": "List of MediaAttachment objects with the attached media for this version of the status", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "MediaAttachment", "is_optional": false, "is_nullable": false, @@ -1197,7 +1197,7 @@ }, "emojis": { "description": "List of custom emoji used in this version of the status.", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "CustomEmoji", "is_optional": false, "is_nullable": false, @@ -1251,7 +1251,7 @@ }, "keyword_matches": { "description": "The keyword within the filter that was matched.", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "str", "is_optional": false, "is_nullable": true, @@ -1265,7 +1265,7 @@ }, "status_matches": { "description": "The status ID within the filter that was matched.", - "field_type": "list", + "field_type": "EntityList", "field_subtype": null, "is_optional": false, "is_nullable": true, @@ -1353,7 +1353,7 @@ "name": "Scheduled status / toot", "python_name": "ScheduledStatus", "func_call": "mastodon.status_post(\"futureposting\", scheduled_at=the_future)", - "func_call_real": "mastodon.status_post(\"posting in the far future\", scheduled_at=datetime(9999,12,12))", + "func_call_real": "mastodon.status_post(\"posting in the far future\", scheduled_at=datetime(2100,12,12))", "masto_doc_link": "https://docs.joinmastodon.org/entities/ScheduledStatus/", "func_call_additional": null, "func_alternate_acc": false, @@ -1404,7 +1404,7 @@ }, "media_attachments": { "description": "Array of MediaAttachment objects for the attachments to the scheduled status", - "field_type": "list", + "field_type": "EntityList", "field_subtype": null, "is_optional": false, "is_nullable": false, @@ -1421,7 +1421,7 @@ "name": "Scheduled status / toot params", "python_name": "ScheduledStatusParams", "func_call": "mastodon.status_post(\"futureposting... 2\", scheduled_at=the_future).params", - "func_call_real": "mastodon.status_post(\"posting in the far future\", scheduled_at=datetime(9999,12,12)).params", + "func_call_real": "mastodon.status_post(\"posting in the far future\", scheduled_at=datetime(2100,12,12)).params", "masto_doc_link": "https://docs.joinmastodon.org/entities/ScheduledStatus/", "func_call_additional": null, "func_alternate_acc": false, @@ -1444,7 +1444,7 @@ }, "in_reply_to_id": { "description": "ID of the status this one is a reply to", - "field_type": "SnowflakeIdType", + "field_type": "MaybeSnowflakeIdType", "field_subtype": null, "is_optional": false, "is_nullable": true, @@ -1458,7 +1458,7 @@ }, "media_ids": { "description": "IDs of media attached to this status", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "str", "is_optional": false, "is_nullable": true, @@ -1587,7 +1587,7 @@ "allowed_mentions": { "description": "Undocumented. If you know what this does, please let me know.", "help_wanted": true, - "field_type": "list", + "field_type": "EntityList", "field_subtype": "str", "is_optional": false, "is_nullable": true, @@ -1712,7 +1712,7 @@ }, "options": { "description": "The poll options", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "PollOption", "is_optional": false, "is_nullable": false, @@ -1726,7 +1726,7 @@ }, "emojis": { "description": "List of CustomEmoji used in answer strings,", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "CustomEmoji", "is_optional": false, "is_nullable": false, @@ -1740,7 +1740,7 @@ }, "own_votes": { "description": "The logged-in users votes, as a list of indices to the options.", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "int", "is_optional": false, "is_nullable": false, @@ -1850,7 +1850,7 @@ }, "accounts": { "description": "List of accounts (other than the logged-in account) that are part of this conversation", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "Account", "is_optional": false, "is_nullable": false, @@ -1920,7 +1920,7 @@ }, "history": { "description": "List of TagHistory for up to 7 days. Not present in statuses.", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "TagHistory", "is_optional": true, "is_nullable": false, @@ -2342,7 +2342,7 @@ }, "languages": { "description": "List of languages that the logged in user is following this user for (if any)", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "str", "field_structuretype": "TwoLetterLanguageCodeEnum", "is_optional": false, @@ -2421,7 +2421,7 @@ }, "context": { "description": "List of places where the filters are applied.", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "str", "is_optional": false, "is_nullable": false, @@ -2532,7 +2532,7 @@ }, "keywords": { "description": "A list of keywords that will trigger this filter.", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "FilterKeyword", "is_optional": false, "is_nullable": false, @@ -2547,7 +2547,7 @@ }, "statuses": { "description": "A list of statuses that will trigger this filter.", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "FilterStatus", "is_optional": false, "is_nullable": false, @@ -2679,7 +2679,7 @@ "fields": { "ancestors": { "description": "A list of Statuses that the Status with this Context is a reply to", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "Status", "is_optional": false, "is_nullable": false, @@ -2693,7 +2693,7 @@ }, "descendants": { "description": "A list of Statuses that are replies to the Status with this Context", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "Status", "is_optional": false, "is_nullable": false, @@ -2776,7 +2776,7 @@ "fields": { "id": { "description": "The ID of the attachment.", - "field_type": "SnowflakeIdType", + "field_type": "MaybeSnowflakeIdType", "field_subtype": null, "is_optional": false, "is_nullable": false, @@ -3529,7 +3529,7 @@ "fields": { "accounts": { "description": "List of Accounts resulting from the query", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "Account", "is_optional": false, "is_nullable": false, @@ -3543,7 +3543,7 @@ }, "hashtags": { "description": "List of Tags resulting from the query", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "Union[str, Tag]", "is_optional": false, "is_nullable": false, @@ -3565,7 +3565,7 @@ }, "statuses": { "description": "List of Statuses resulting from the query", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "Status", "is_optional": false, "is_nullable": false, @@ -3583,10 +3583,10 @@ "name": "Instance", "python_name": "Instance", "func_call": "mastodon.instance()", + "func_call_additional": "mastodon.instance_v1()", "masto_doc_link": "https://docs.joinmastodon.org/entities/Instance/", "masto_doc_link_additional": "https://docs.joinmastodon.org/entities/V1_Instance/", "func_call_real": null, - "func_call_additional": null, "func_alternate_acc": false, "manual_update": false, "has_versions": [ @@ -3787,7 +3787,7 @@ }, "languages": { "description": "Array of ISO 639-1 (two-letter) language codes the instance has chosen to advertise.", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "str", "field_structuretype": "TwoLetterLanguageCodeEnum", "is_optional": false, @@ -3837,7 +3837,7 @@ }, "rules": { "description": "List of Rules with `id` and `text` fields, one for each server rule set by the admin", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "Rule", "is_optional": false, "is_nullable": false, @@ -3971,16 +3971,16 @@ "name": "Instance thumbnail versions", "python_name": "InstanceThumbnailVersions", "func_call": "mastodon.instance().thumbnail.versions", - "masto_doc_link": "https://docs.joinmastodon.org/entities/V1_Instance/", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Instance/", "func_call_real": null, "func_call_additional": null, "func_alternate_acc": false, "manual_update": false, "description": "Different resolution versions of the image representing the instance.", "fields": { - "1x": { + "@1x": { "description": "The URL for an image representing the instance, for devices with 1x resolution / 96 dpi", - "real_name": "@1x", + "python_name": "at1x", "field_type": "str", "field_subtype": null, "is_optional": true, @@ -3994,10 +3994,10 @@ ], "enum": null }, - "2x": { - "description": "The blurhash for the image representing the instance, for devices with 2x resolution / 192 dpi", + "@2x": { + "description": "The URL for the image representing the instance, for devices with 2x resolution / 192 dpi", "field_type": "str", - "real_name": "@2x", + "python_name": "at2x", "field_subtype": null, "is_optional": true, "is_nullable": false, @@ -4016,15 +4016,15 @@ "name": "Instance urls", "python_name": "InstanceURLs", "func_call": "mastodon.instance().configuration.urls", + "func_call_additional": "mastodon.instance_v1().urls", "masto_doc_link": "https://docs.joinmastodon.org/entities/V1_Instance/", "func_call_real": null, - "func_call_additional": null, "func_alternate_acc": false, "manual_update": false, "description": "A list of URLs related to an instance.", "fields": { - "streaming_api": { - "description": "The Websockets URL for connecting to the streaming API.", + "streaming": { + "description": "The Websockets URL for connecting to the streaming API. Was 'streaming_api' in v1", "field_type": "str", "field_subtype": null, "is_optional": false, @@ -4038,6 +4038,27 @@ ], "enum": null }, + "streaming_api": { + "description": "The Websockets URL for connecting to the streaming API. Only present in v1, though Mastodon.py will mirror the appropriate value from 'streaming' for the v2 API.", + "field_type": "str", + "moved_path": "streaming", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "is_deprecated": true, + "field_structuretype": "URL", + "version_history": [ + [ + "3.4.2", + "added" + ], + [ + "4.0.0", + "deprecated" + ] + ], + "enum": null + }, "status": { "description": "If present, a URL where the status and possibly current issues with the instance can be checked.", "field_type": "str", @@ -4478,7 +4499,7 @@ "manual_update": false, "description": "Configuration values relating to translation.", "fields": { - "max_characters": { + "enabled": { "description": "Boolean indicating whether the translation API is enabled on this instance.", "field_type": "bool", "field_subtype": null, @@ -4506,7 +4527,7 @@ "fields": { "supported_mime_types": { "description": "Mime types the instance accepts for media attachment uploads.", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "str", "is_optional": false, "is_nullable": false, @@ -4688,7 +4709,7 @@ }, "protocols": { "description": "A list of strings specifying the federation protocols this instance supports. Typically, just \"activitypub\".", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "str", "is_optional": false, "is_nullable": false, @@ -4805,7 +4826,7 @@ "fields": { "outbound": { "description": "List of services that this instance can send messages to. On Mastodon, typically an empty list.", - "field_type": "list", + "field_type": "EntityList", "field_subtype": null, "is_optional": false, "is_nullable": false, @@ -4818,7 +4839,7 @@ }, "inbound": { "description": "List of services that this instance can retrieve messages from. On Mastodon, typically an empty list.", - "field_type": "list", + "field_type": "EntityList", "field_subtype": null, "is_optional": false, "is_nullable": false, @@ -5135,7 +5156,7 @@ }, "statuses": { "description": "List of Statuses attached to the report", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "Status", "is_optional": false, "is_nullable": false, @@ -5192,7 +5213,7 @@ }, "rules": { "description": "Rules attached to the report, for context.", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "Rule", "is_optional": false, "is_nullable": false, @@ -5598,6 +5619,7 @@ "description": "The logged in users preferences.", "fields": { "posting:default:visibility": { + "python_name": "posting_default_visibility", "description": "Default visibility for new posts. Equivalent to CredentialAccount#source\\[privacy\\]().", "field_type": "str", "field_subtype": null, @@ -5617,6 +5639,7 @@ } }, "posting:default:sensitive": { + "python_name": "posting_default_sensitive", "description": "Default sensitivity flag for new posts. Equivalent to CredentialAccount#source\\[sensitive\\]().", "field_type": "bool", "field_subtype": null, @@ -5631,6 +5654,7 @@ "enum": null }, "posting:default:language": { + "python_name": "posting_default_language", "description": "Default language for new posts. Equivalent to CredentialAccount#source\\[language\\]()", "field_type": "str", "field_subtype": null, @@ -5646,6 +5670,7 @@ "enum": null }, "reading:expand:media": { + "python_name": "reading_expand_media", "description": "String indicating whether media attachments should be automatically displayed or blurred/hidden.", "field_type": "str", "field_subtype": null, @@ -5664,6 +5689,7 @@ } }, "reading:expand:spoilers": { + "python_name": "reading_expand_spoilers", "description": "Boolean indicating whether CWs should be expanded by default.", "field_type": "bool", "field_subtype": null, @@ -5678,6 +5704,7 @@ "enum": null }, "reading:autoplay:gifs": { + "python_name": "reading_autoplay_gifs", "description": "Boolean indicating whether gifs should be autoplayed (True) or not (False)", "field_type": "bool", "field_subtype": null, @@ -5957,7 +5984,7 @@ }, "mentions": { "description": "Users mentioned in the annoucement", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "Mention", "is_optional": false, "is_nullable": false, @@ -5971,7 +5998,7 @@ }, "tags": { "description": "Hashtags mentioned in the announcement", - "field_type": "list", + "field_type": "EntityList", "field_subtype": null, "is_optional": false, "is_nullable": false, @@ -5985,7 +6012,7 @@ }, "emojis": { "description": "Custom emoji used in the annoucement", - "field_type": "list", + "field_type": "EntityList", "field_subtype": null, "is_optional": false, "is_nullable": false, @@ -5999,7 +6026,7 @@ }, "reactions": { "description": "Reactions to the annoucement", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "Reaction", "is_optional": false, "is_nullable": false, @@ -6013,7 +6040,7 @@ }, "statuses": { "description": "Statuses linked in the announcement text.", - "field_type": "list", + "field_type": "EntityList", "field_subtype": null, "is_optional": false, "is_nullable": false, @@ -6139,7 +6166,7 @@ }, "accounts": { "description": "List of Accounts of the familiar followers", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "Account", "is_optional": false, "is_nullable": false, @@ -6418,7 +6445,7 @@ }, "ips": { "description": "All known IP addresses associated with this account.", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "AdminIp", "is_optional": false, "is_nullable": false, @@ -6600,7 +6627,7 @@ }, "data": { "description": "A list of AdminMeasureData with the measure broken down by date", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "AdminMeasureData", "is_optional": false, "is_nullable": false, @@ -6682,7 +6709,7 @@ }, "data": { "description": "A list of data AdminDimensionData objects", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "AdminDimensionData", "is_optional": false, "is_nullable": false, @@ -6790,7 +6817,7 @@ }, "data": { "description": "List of AdminCohort objects", - "field_type": "list", + "field_type": "EntityList", "field_subtype": "AdminCohort", "is_optional": false, "is_nullable": false, @@ -6956,7 +6983,7 @@ "enum": null }, "private_comment": { - "description": "", + "description": "A private comment (visible only to other moderators) for the domain block", "field_type": "str", "field_subtype": null, "is_optional": false, @@ -6970,7 +6997,7 @@ "enum": null }, "public_comment": { - "description": "", + "description": "A public comment (visible to either all users, or the whole world) for the domain block", "field_type": "str", "field_subtype": null, "is_optional": false, @@ -7165,7 +7192,7 @@ "added" ] ], - "field_type": "list", + "field_type": "EntityList", "field_subtype": "AdminEmailDomainBlockHistory", "field_structuretype": null, "is_optional": false, @@ -7550,7 +7577,7 @@ "added" ] ], - "field_type": "SnowflakeIdType", + "field_type": "MaybeSnowflakeIdType", "field_subtype": null, "field_structuretype": null, "is_optional": false, diff --git a/srcgen/return_types_all_current_fixed_bu.json b/srcgen/return_types_all_current_fixed_bu.json new file mode 100644 index 0000000..3409bf9 --- /dev/null +++ b/srcgen/return_types_all_current_fixed_bu.json @@ -0,0 +1,8547 @@ +[ + { + "name": "User / account", + "python_name": "Account", + "func_call": "mastodon.account()", + "func_call_real": "mastodon.account(23972)", + "func_call_additional": "mastodon.account_verify_credentials()", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Account/", + "func_alternate_acc": false, + "manual_update": false, + "description": "A user acccount, local or remote.", + "fields": { + "id": { + "description": "The accounts id", + "field_type": "MaybeSnowflakeIdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.1.0", + "added" + ] + ], + "enum": null + }, + "username": { + "description": "The username, without the domain part", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.1.0", + "added" + ] + ], + "enum": null + }, + "acct": { + "description": "The user's account name as username@domain (@domain omitted for local users)", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.1.0", + "added" + ] + ], + "enum": null + }, + "display_name": { + "description": "The user's display name", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.1.0", + "added" + ] + ], + "enum": null + }, + "discoverable": { + "description": "Indicates whether or not a user is visible on the discovery page", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + }, + "group": { + "description": "A boolean indicating whether the account represents a group rather than an individual.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + }, + "locked": { + "description": "Denotes whether the account can be followed without a follow request", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.1.0", + "added" + ] + ], + "enum": null + }, + "created_at": { + "description": "The accounts creation time", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.1.0", + "added" + ], + [ + "3.4.0", + "now resolves to midnight instead of an exact time" + ] + ], + "enum": null + }, + "following_count": { + "description": "How many accounts this account follows", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.1.0", + "added" + ] + ], + "enum": null + }, + "followers_count": { + "description": "How many followers this account has", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.1.0", + "added" + ] + ], + "enum": null + }, + "statuses_count": { + "description": "How many statuses this account has created, excluding: 1) later deleted posts 2) direct messages / 'mentined users only' posts, except in earlier versions mastodon.", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.1.0", + "added" + ], + [ + "2.4.2", + "no longer includes direct / mentioned-only visibility statuses" + ] + ], + "enum": null + }, + "note": { + "description": "The users bio / profile text / 'note'", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.1.0", + "added" + ] + ], + "enum": null + }, + "url": { + "description": "A URL pointing to this users profile page (can be remote)", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "0.1.0", + "added" + ] + ], + "enum": null + }, + "avatar": { + "description": "URL for this users avatar, can be animated", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "0.1.0", + "added" + ] + ], + "enum": null + }, + "header": { + "description": "URL for this users header image, can be animated", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "0.1.0", + "added" + ] + ], + "enum": null + }, + "avatar_static": { + "description": "URL for this users avatar, never animated", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "1.1.2", + "added" + ] + ], + "enum": null + }, + "header_static": { + "description": "URL for this users header image, never animated", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "1.1.2", + "added" + ] + ], + "enum": null + }, + "moved_to_account": { + "description": "If set, Account that this user has set up as their moved-to address.", + "field_type": "Account", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "2.1.0", + "added" + ] + ] + }, + "suspended": { + "description": "Boolean indicating whether the user has been suspended.", + "field_type": "bool", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "3.3.0", + "added" + ] + ], + "enum": null + }, + "limited": { + "description": "Boolean indicating whether the user has been silenced.", + "field_type": "bool", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "3.5.3", + "added" + ] + ], + "enum": null + }, + "bot": { + "description": "Boolean indicating whether this account is automated.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ] + ], + "enum": null + }, + "fields": { + "description": "List of up to four (by default) AccountFields", + "field_type": "EntityList", + "field_subtype": "AccountField", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ] + ], + "enum": null + }, + "emojis": { + "description": "List of custom emoji used in name, bio or fields", + "field_type": "EntityList", + "field_subtype": "CustomEmoji", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ] + ], + "enum": null + }, + "last_status_at": { + "description": "When the most recent status was posted.", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "3.0.0", + "added" + ], + [ + "3.1.0", + "now returns date only, no time" + ] + ], + "enum": null + }, + "noindex": { + "description": "Whether the local user has opted out of being indexed by search engines.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "roles": { + "description": "Deprecated. Was a list of strings with the users roles. Now just an empty list. Mastodon.py makes no attempt to fill it, and the field may be removed if Mastodon removes it. Use the `role` field instead.", + "is_deprecated": true, + "field_type": "EntityList", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.1.0", + "added" + ], + [ + "4.0.0", + "deprecated" + ] + ] + }, + "role": { + "description": "The users role. Only present for account returned from account_verify_credentials()", + "field_type": "Role", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + }, + "source": { + "description": "Additional information about the account, useful for profile editing. Only present for account returned from account_verify_credentials()", + "field_type": "CredentialAccountSource", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ] + ] + }, + "mute_expires_at": { + "description": "If the user is muted by the logged in user with a timed mute, when the mute expires.", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "3.3.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Account field", + "python_name": "AccountField", + "func_call": "mastodon.account().fields[0]", + "func_call_real": "mastodon.account(23972).fields[0]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Account/", + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "A field, displayed on a users profile (e.g. \"Pronouns\", \"Favorite color\").", + "fields": { + "name": { + "description": "The key of a given field's key-value pair.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ] + ], + "enum": null + }, + "value": { + "description": "The value associated with the `name` key.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ] + ], + "enum": null + }, + "verified_at": { + "description": "Timestamp of when the server verified a URL value for a rel=\"me\" link.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.6.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Account role", + "python_name": "Role", + "func_call": "mastodon.account_verify_credentials().role", + "func_call_real": "mastodon.account_verify_credentials().role", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Role/", + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "A role granting a user a set of permissions.", + "fields": { + "id": { + "description": "The ID of the Role in the database.", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "name": { + "description": "The name of the role.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "permissions": { + "description": "A bitmask that represents the sum of all permissions granted to the role.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "color": { + "description": "The hex code assigned to this role. If no hex code is assigned, the string will be empty.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "highlighted": { + "description": "Whether the role is publicly visible as a badge on user profiles.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "User / account source", + "python_name": "CredentialAccountSource", + "func_call": "mastodon.account_verify_credentials()[\"source\"]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Account/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Source values useful for editing a user's profile.", + "fields": { + "privacy": { + "description": "The user's default visibility setting (\"private\", \"unlisted\" or \"public\")", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.5.0", + "added" + ] + ], + "enum": { + "public": "Public post", + "unlisted": "Unlisted post", + "private": "Followers-only post", + "direct": "Direct post" + } + }, + "sensitive": { + "description": "Denotes whether user media should be marked sensitive by default", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.5.0", + "added" + ] + ], + "enum": null + }, + "note": { + "description": "Plain text version of the user's bio", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.5.0", + "added" + ] + ], + "enum": null + }, + "language": { + "description": "The default posting language for new statuses.", + "field_type": "str", + "field_subtype": null, + "field_structuretype": "TwoLetterLanguageCodeEnum", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.2", + "added" + ] + ], + "enum": null + }, + "fields": { + "description": "Metadata about the account.", + "field_type": "EntityList", + "field_subtype": "AccountField", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ] + ], + "enum": null + }, + "follow_requests_count": { + "description": "The number of pending follow requests.", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Toot / Status", + "python_name": "Status", + "func_call": "mastodon.toot(\"Hello from Python\")", + "func_call_real": "mastodon.status(110446223051565765)", + "func_call_additional": "mastodon.status(110446183735368325)", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Status/", + "func_alternate_acc": false, + "manual_update": false, + "description": "A single status / toot / post", + "fields": { + "id": { + "description": "Id of this status", + "field_type": "MaybeSnowflakeIdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.1.0", + "added" + ] + ], + "enum": null + }, + "uri": { + "description": "Descriptor for the status EG 'tag:mastodon.social,2016-11-25:objectId=:objectType=Status'", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.1.0", + "added" + ] + ], + "enum": null + }, + "url": { + "description": "URL of the status", + "field_type": "str", + "field_subtype": null, + "field_structuretype": "URL", + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "0.1.0", + "added" + ] + ] + }, + "account": { + "description": "Account which posted the status", + "field_type": "Account", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.1.0", + "added" + ] + ], + "enum": null + }, + "in_reply_to_id": { + "description": "Id of the status this status is in response to", + "field_type": "MaybeSnowflakeIdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "0.1.0", + "added" + ] + ] + }, + "in_reply_to_account_id": { + "description": "Id of the account this status is in response to", + "field_type": "MaybeSnowflakeIdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "0.1.0", + "added" + ] + ] + }, + "reblog": { + "description": "Denotes whether the status is a reblog. If so, set to the original status.", + "field_type": "Status", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "0.1.0", + "added" + ] + ] + }, + "content": { + "description": "Content of the status, as HTML: '

Hello from Python

'", + "field_structuretype": "HTML", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.1.0", + "added" + ] + ], + "enum": null + }, + "created_at": { + "description": "Creation time", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.1.0", + "added" + ] + ], + "enum": null + }, + "reblogs_count": { + "description": "Number of reblogs", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.1.0", + "added" + ] + ] + }, + "favourites_count": { + "description": "Number of favourites", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.1.0", + "added" + ] + ] + }, + "reblogged": { + "description": "Denotes whether the logged in user has boosted this status", + "field_type": "bool", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "0.1.0", + "added" + ] + ] + }, + "favourited": { + "description": "Denotes whether the logged in user has favourited this status", + "field_type": "bool", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "0.1.0", + "added" + ] + ] + }, + "sensitive": { + "description": "Denotes whether media attachments to the status are marked sensitive", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.9.9", + "added" + ] + ], + "enum": null + }, + "spoiler_text": { + "description": "Warning text that should be displayed before the status content", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.0.0", + "added" + ] + ], + "enum": null + }, + "visibility": { + "description": "Toot visibility", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "VisibilityEnum", + "version_history": [ + [ + "0.9.9", + "added" + ] + ], + "enum": { + "public": "Publicly visible and discoverable in public timelines", + "unlisted": "Publicly visible, but not shown on public timelines and other discovery tools", + "private": "Visible only to followers", + "direct": "Visible only to people mentioned in the status", + "list": "Visible only to people on a manually curated list (pleroma-specific)", + "local": "Visible only to local followers (pleroma-specific)" + } + }, + "mentions": { + "description": "A list Mentions this status includes", + "field_type": "EntityList", + "field_subtype": "Account", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ] + }, + "media_attachments": { + "description": "List files attached to this status", + "field_type": "EntityList", + "field_subtype": "MediaAttachment", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ], + "enum": null + }, + "emojis": { + "description": "A list of CustomEmoji used in the status", + "field_type": "EntityList", + "field_subtype": "CustomEmoji", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.0.0", + "added" + ] + ] + }, + "tags": { + "description": "A list of Tags used in the status", + "field_type": "EntityList", + "field_subtype": "Tag", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ] + }, + "bookmarked": { + "description": "True if the status is bookmarked by the logged in user, False if not.", + "field_type": "bool", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "3.1.0", + "added" + ] + ] + }, + "application": { + "description": "Application for the client used to post the status (Does not federate and is therefore always None for remote statuses, can also be None for local statuses for some legacy applications registered before this field was introduced).", + "field_type": "Application", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "0.9.9", + "added" + ] + ], + "enum": null + }, + "language": { + "description": "The language of the status, if specified by the server, as ISO 639-1 (two-letter) language code.", + "field_type": "str", + "field_subtype": null, + "field_structuretype": "TwoLetterLanguageCodeEnum", + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "1.4.0", + "added" + ] + ] + }, + "muted": { + "description": "Boolean denoting whether the user has muted this status by way of conversation muting", + "field_type": "bool", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "1.4.0", + "added" + ] + ] + }, + "pinned": { + "description": "Boolean denoting whether or not the status is currently pinned for the associated account.", + "field_type": "bool", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "1.6.0", + "added" + ] + ] + }, + "replies_count": { + "description": "The number of replies to this status.", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.5.0", + "added" + ] + ] + }, + "card": { + "description": "A preview card for links from the status, if present at time of delivery.", + "field_type": "PreviewCard", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.6.0", + "added" + ] + ] + }, + "poll": { + "description": "A poll object if a poll is attached to this status.", + "field_type": "Poll", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.8.0", + "added" + ] + ] + }, + "edited_at": { + "description": "Time the status was last edited", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "3.5.0", + "added" + ] + ] + }, + "filtered": { + "description": "If present, a list of filter application results that indicate which of the users filters matched and what actions should be taken.", + "field_type": "EntityList", + "field_subtype": "FilterResult", + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + } + } + }, + { + "name": "Status edit", + "python_name": "StatusEdit", + "func_call": "mastodon.status_history()[0]", + "func_call_real": "mastodon.status_history(110446223051565765)[-1]", + "func_call_additional": "mastodon.status_history(110446183735368325)[-1]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/StatusEdit/", + "func_alternate_acc": false, + "manual_update": false, + "description": "An object representing a past version of an edited status", + "fields": { + "content": { + "description": "Content for this version of the status", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "spoiler_text": { + "description": "CW / Spoiler text for this version of the status", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "sensitive": { + "description": "Whether media in this version of the status is marked as sensitive", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "created_at": { + "description": "Time at which this version of the status was posted", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "account": { + "description": "Account object of the user that posted the status", + "field_type": "Account", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "media_attachments": { + "description": "List of MediaAttachment objects with the attached media for this version of the status", + "field_type": "EntityList", + "field_subtype": "MediaAttachment", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ] + }, + "emojis": { + "description": "List of custom emoji used in this version of the status.", + "field_type": "EntityList", + "field_subtype": "CustomEmoji", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ] + }, + "poll": { + "description": "The current state of the poll options at this revision. Note that edits changing the poll options will be collapsed together into one edit, since this action resets the poll.", + "field_type": "Poll", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Status filter action", + "python_name": "FilterResult", + "func_call": "mastodon.status().filtered[0]", + "func_call_real": "mastodon.status(110447998920481458).filtered[0]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/FilterResult/", + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "A filter action that should be taken on a status.", + "fields": { + "filter": { + "description": "The filter that was matched.", + "field_type": "Union[Filter, FilterV2]", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "keyword_matches": { + "description": "The keyword within the filter that was matched.", + "field_type": "EntityList", + "field_subtype": "str", + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "status_matches": { + "description": "The status ID within the filter that was matched.", + "field_type": "EntityList", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Mention", + "python_name": "StatusMention", + "func_call": "mastodon.toot(\"@admin he doing it sideways\").mentions[0]", + "func_call_real": "mastodon.status(110446223051565765).mentions[0]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Mention/", + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "A mention of a user within a status", + "fields": { + "url": { + "description": "Mentioned user's profile URL (potentially remote)", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "0.6.0", + "added" + ] + ], + "enum": null + }, + "username": { + "description": "Mentioned user's user name (not including domain)", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ], + "enum": null + }, + "acct": { + "description": "Mentioned user's account name (including domain)", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ], + "enum": null + }, + "id": { + "description": "Mentioned user's (local) account ID", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Scheduled status / toot", + "python_name": "ScheduledStatus", + "func_call": "mastodon.status_post(\"futureposting\", scheduled_at=the_future)", + "func_call_real": "mastodon.status_post(\"posting in the far future\", scheduled_at=datetime(2100,12,12))", + "masto_doc_link": "https://docs.joinmastodon.org/entities/ScheduledStatus/", + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "A scheduled status / toot to be eventually posted.", + "fields": { + "id": { + "description": "Scheduled status ID (note: Not the id of the status once it gets posted!)", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.7.0", + "added" + ] + ], + "enum": null + }, + "scheduled_at": { + "description": "datetime object describing when the status is to be posted", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.7.0", + "added" + ] + ], + "enum": null + }, + "params": { + "description": "Parameters for the scheduled status, specifically", + "field_type": "ScheduledStatusParams", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.7.0", + "added" + ] + ], + "enum": null + }, + "media_attachments": { + "description": "Array of MediaAttachment objects for the attachments to the scheduled status", + "field_type": "EntityList", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.7.0", + "added" + ] + ] + } + } + }, + { + "name": "Scheduled status / toot params", + "python_name": "ScheduledStatusParams", + "func_call": "mastodon.status_post(\"futureposting... 2\", scheduled_at=the_future).params", + "func_call_real": "mastodon.status_post(\"posting in the far future\", scheduled_at=datetime(2100,12,12)).params", + "masto_doc_link": "https://docs.joinmastodon.org/entities/ScheduledStatus/", + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Parameters for a status / toot to be posted in the future.", + "fields": { + "text": { + "description": "Toot text", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.7.0", + "added" + ] + ], + "enum": null + }, + "in_reply_to_id": { + "description": "ID of the status this one is a reply to", + "field_type": "MaybeSnowflakeIdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.7.0", + "added" + ] + ], + "enum": null + }, + "media_ids": { + "description": "IDs of media attached to this status", + "field_type": "EntityList", + "field_subtype": "str", + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.7.0", + "added" + ] + ], + "enum": null + }, + "sensitive": { + "description": "Whether this status is sensitive or not", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.7.0", + "added" + ] + ], + "enum": null + }, + "visibility": { + "description": "Visibility of the status", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.7.0", + "added" + ] + ], + "enum": null + }, + "idempotency": { + "description": "Idempotency key for the scheduled status", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.7.0", + "added" + ] + ], + "enum": null + }, + "scheduled_at": { + "description": "Present, but generally \"None\". Unsure what this is for - the actual scheduled_at is in the ScheduledStatus object, not here. If you know, let me know.", + "help_wanted": true, + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.7.0", + "added" + ] + ], + "enum": null + }, + "spoiler_text": { + "description": "CW text for this status", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.7.0", + "added" + ] + ], + "enum": null + }, + "application_id": { + "description": "ID of the application that scheduled the status", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.7.0", + "added" + ] + ], + "enum": null + }, + "poll": { + "description": "Poll parameters", + "field_type": "Poll", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "enum": null + }, + "language": { + "description": "The language that will be used for the status.", + "field_type": "str", + "field_subtype": null, + "field_structuretype": "TwoLetterLanguageCodeEnum", + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.7.0", + "added" + ] + ], + "enum": null + }, + "allowed_mentions": { + "description": "Undocumented. If you know what this does, please let me know.", + "help_wanted": true, + "field_type": "EntityList", + "field_subtype": "str", + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.7.0", + "added" + ] + ] + }, + "with_rate_limit": { + "description": "Whether the status should be rate limited. It is unclear to me what this does. If you know, please let met know", + "help_wanted": true, + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.7.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Poll", + "python_name": "Poll", + "func_call": "mastodon.poll()", + "func_call_real": "mastodon.status(110446383900387196).poll", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Poll/", + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "A poll attached to a status", + "fields": { + "id": { + "description": "The polls ID", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "enum": null + }, + "expires_at": { + "description": "The time at which the poll is set to expire", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "enum": null + }, + "expired": { + "description": "Boolean denoting whether users can still vote in this poll", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "enum": null + }, + "multiple": { + "description": "Boolean indicating whether it is allowed to vote for more than one option", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "enum": null + }, + "votes_count": { + "description": "Total number of votes cast in this poll", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "enum": null + }, + "voted": { + "description": "Boolean indicating whether the logged-in user has already voted in this poll", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "enum": null + }, + "options": { + "description": "The poll options", + "field_type": "EntityList", + "field_subtype": "PollOption", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "enum": null + }, + "emojis": { + "description": "List of CustomEmoji used in answer strings,", + "field_type": "EntityList", + "field_subtype": "CustomEmoji", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "enum": null + }, + "own_votes": { + "description": "The logged-in users votes, as a list of indices to the options.", + "field_type": "EntityList", + "field_subtype": "int", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "enum": null + }, + "voters_count": { + "description": "How many unique accounts have voted on a multiple-choice poll.", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Poll option", + "python_name": "PollOption", + "func_call": "mastodon.poll().options[0]", + "func_call_real": "mastodon.status(110446383900387196).poll.options[0]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Poll/", + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "A poll option within a poll", + "fields": { + "title": { + "description": "Text of the option", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "enum": null + }, + "votes_count": { + "description": "Count of votes for the option. Can be None if the poll creator has chosen to hide vote totals until the poll expires and it hasn't yet.", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Conversation", + "python_name": "Conversation", + "func_call": "mastodon.conversations()[0]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Conversation/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "A conversation (using direct / mentions-only visibility) between two or more users", + "fields": { + "id": { + "description": "The ID of this conversation object", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.6.0", + "added" + ] + ], + "enum": null + }, + "unread": { + "description": "Boolean indicating whether this conversation has yet to be read by the user", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.6.0", + "added" + ] + ], + "enum": null + }, + "accounts": { + "description": "List of accounts (other than the logged-in account) that are part of this conversation", + "field_type": "EntityList", + "field_subtype": "Account", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.6.0", + "added" + ] + ], + "enum": null + }, + "last_status": { + "description": "The newest status in this conversation", + "field_type": "Status", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.6.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Hashtag", + "python_name": "Tag", + "func_call": "mastodon.trending_tags()[0]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Tag/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "A hashtag, as part of a status or on its own (e.g. trending)", + "fields": { + "name": { + "description": "Hashtag name (not including the #)", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.9.0", + "added" + ] + ], + "enum": null + }, + "url": { + "description": "Hashtag URL (can be remote)", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "0.9.0", + "added" + ] + ], + "enum": null + }, + "history": { + "description": "List of TagHistory for up to 7 days. Not present in statuses.", + "field_type": "EntityList", + "field_subtype": "TagHistory", + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "2.4.1", + "added" + ] + ], + "enum": null + }, + "following": { + "description": "Boolean indicating whether the logged-in user is following this tag.", + "field_type": "bool", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + } + } + }, + { + "name": "Hashtag usage history", + "python_name": "TagHistory", + "func_call": "mastodon.trending_tags()[0].history[0]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Tag/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Usage history for a hashtag", + "fields": { + "day": { + "description": "Date of the day this TagHistory is for", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "datetime", + "version_history": [ + [ + "2.4.1", + "added" + ] + ], + "enum": null + }, + "uses": { + "description": "Number of statuses using this hashtag on that day", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.1", + "added" + ] + ], + "enum": null + }, + "accounts": { + "description": "Number of accounts using this hashtag in at least one status on that day", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.1", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Emoji", + "python_name": "CustomEmoji", + "func_call": "mastodon.toot(\":sidekiqin:\").emojis[0]", + "func_call_real": "mastodon.status(110446223051565765).emojis[0]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/CustomEmoji/", + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "A custom emoji", + "fields": { + "shortcode": { + "description": "Emoji shortcode, without surrounding colons", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.0.0", + "added" + ] + ], + "enum": null + }, + "url": { + "description": "URL for the emoji image, can be animated", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "2.0.0", + "added" + ] + ], + "enum": null + }, + "static_url": { + "description": "URL for the emoji image, never animated", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "2.0.0", + "added" + ] + ], + "enum": null + }, + "visible_in_picker": { + "description": "True if the emoji is enabled, False if not.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.0.0", + "added" + ] + ], + "enum": null + }, + "category": { + "description": "The category to display the emoji under (not present if none is set)", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Application", + "python_name": "Application", + "func_call": "mastodon.app_verify_credentials()", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Application/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Information about an app (in terms of the API)", + "fields": { + "name": { + "description": "The applications name", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.9.9", + "added" + ] + ], + "enum": null + }, + "website": { + "description": "The applications website", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "0.9.9", + "added" + ], + [ + "3.5.1", + "this property is now nullable" + ] + ], + "enum": null + }, + "vapid_key": { + "description": "A vapid key that can be used in web applications", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Relationship", + "python_name": "Relationship", + "func_call": "mastodon.account_relationships()[0]", + "func_call_real": "mastodon.account_relationships(23972)[0]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Relationship/", + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Information about the relationship between two users", + "fields": { + "id": { + "description": "ID of the relationship object", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ], + "enum": null + }, + "following": { + "description": "Boolean denoting whether the logged-in user follows the specified user", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ], + "enum": null + }, + "followed_by": { + "description": "Boolean denoting whether the specified user follows the logged-in user", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ], + "enum": null + }, + "blocking": { + "description": "Boolean denoting whether the logged-in user has blocked the specified user", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ], + "enum": null + }, + "blocked_by": { + "description": "Boolean denoting whether the logged-in user has been blocked by the specified user, if information is available", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "enum": null + }, + "muting": { + "description": "Boolean denoting whether the logged-in user has muted the specified user", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.1.0", + "added" + ] + ], + "enum": null + }, + "muting_notifications": { + "description": "Boolean denoting wheter the logged-in user has muted notifications related to the specified user", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.1.0", + "added" + ] + ], + "enum": null + }, + "requested": { + "description": "Boolean denoting whether the logged-in user has sent the specified user a follow request", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.9.9", + "added" + ] + ], + "enum": null + }, + "domain_blocking": { + "description": "Boolean denoting whether the logged-in user has blocked the specified users domain", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.4.0", + "added" + ] + ], + "enum": null + }, + "showing_reblogs": { + "description": "Boolean denoting whether the specified users reblogs show up on the logged-in users Timeline", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.1.0", + "added" + ] + ], + "enum": null + }, + "endorsed": { + "description": "Boolean denoting wheter the specified user is being endorsed / featured by the logged-in user", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.5.0", + "added" + ] + ], + "enum": null + }, + "note": { + "description": "A free text note the logged in user has created for this account (not publicly visible)", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.2.0", + "added" + ] + ], + "enum": null + }, + "notifying": { + "description": "Boolean indicating whether the logged-in user has enabled notifications for this users posts", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.3.0", + "added" + ] + ], + "enum": null + }, + "languages": { + "description": "List of languages that the logged in user is following this user for (if any)", + "field_type": "EntityList", + "field_subtype": "str", + "field_structuretype": "TwoLetterLanguageCodeEnum", + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "requested_by": { + "description": "Boolean indicating whether the specified user has sent the logged-in user a follow request", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.9.9", + "added" + ] + ] + } + } + }, + { + "name": "Filter (v1)", + "python_name": "Filter", + "func_call": "mastodon.filters()[0]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/V1_Filter/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "is_deprecated": true, + "has_versions": [ + "v1", + "v2" + ], + "description": "Information about a keyword / status filter", + "fields": { + "id": { + "description": "Id of the filter", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.3", + "added" + ] + ], + "enum": null + }, + "phrase": { + "description": "Filtered keyword or phrase", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "api_version": "v1", + "version_history": [ + [ + "2.4.3", + "added" + ] + ], + "enum": null + }, + "context": { + "description": "List of places where the filters are applied.", + "field_type": "EntityList", + "field_subtype": "str", + "is_optional": false, + "is_nullable": false, + "field_structuretype": "FilterContextEnum", + "version_history": [ + [ + "2.4.3", + "added" + ], + [ + "3.1.0", + "added `account`" + ] + ], + "enum": { + "home": "Home timeline and lists", + "notifications": "Notifications timeline", + "public": "Puclic timelines", + "thread": "Expanded view of a status with replies", + "account": "Posts displayed when viewing a profile" + } + }, + "expires_at": { + "description": "Expiry date for the filter", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.4.3", + "added" + ] + ], + "enum": null + }, + "irreversible": { + "description": "Boolean denoting if this filter is executed server-side or if it should be ran client-side.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "api_version": "v1", + "version_history": [ + [ + "2.4.3", + "added" + ] + ], + "enum": null + }, + "whole_word": { + "description": "Boolean denoting whether this filter can match partial words", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "api_version": "v1", + "version_history": [ + [ + "2.4.3", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Filter (v2)", + "python_name": "FilterV2", + "func_call": "mastodon.filters()[0]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Filter/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "has_versions": [ + "v1", + "v2" + ], + "description": "Information about a keyword / status filter", + "fields": { + "id": { + "description": "Id of the filter", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "context": { + "description": "List of places where the filters are applied.", + "field_type": "EntityList", + "field_subtype": "str", + "is_optional": false, + "is_nullable": false, + "field_structuretype": "FilterContextEnum", + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": { + "home": "Home timeline and lists", + "notifications": "Notifications timeline", + "public": "Puclic timelines", + "thread": "Expanded view of a status with replies", + "account": "Posts displayed when viewing a profile" + } + }, + "expires_at": { + "description": "Expiry date for the filter", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "title": { + "description": "Name the user has chosen for this filter", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "api_version": "v2", + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "filter_action": { + "description": "The action to be taken when a status matches this filter.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "FilterActionEnum", + "api_version": "v2", + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": { + "warn": "Display a note to the user that the status has been filtered, showing the title of the filter. The mastodon documentation suggests that absent any other information or if unknown values are encountered, this should be the default action to take.", + "hide": "Hide the status from the user completely, as if it did not exist" + } + }, + "keywords": { + "description": "A list of keywords that will trigger this filter.", + "field_type": "EntityList", + "field_subtype": "FilterKeyword", + "is_optional": false, + "is_nullable": false, + "api_version": "v2", + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "statuses": { + "description": "A list of statuses that will trigger this filter.", + "field_type": "EntityList", + "field_subtype": "FilterStatus", + "is_optional": false, + "is_nullable": false, + "api_version": "v2", + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Notification", + "python_name": "Notification", + "func_call": "mastodon.notifications()[0]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Notification/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "A notification about some event, like a new reply or follower.", + "fields": { + "id": { + "description": "id of the notification", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.9.9", + "added" + ] + ], + "enum": null + }, + "type": { + "description": "\"mention\", \"reblog\", \"favourite\", \"follow\", \"poll\" or \"follow_request\"", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "NotificationTypeEnum", + "version_history": [ + [ + "0.9.9", + "added" + ], + [ + "2.8.0", + "added `poll`" + ], + [ + "3.1.0", + "added `follow_request`" + ], + [ + "3.3.0", + "added `status`" + ], + [ + "3.5.0", + "added `update` and `admin.sign_up`" + ], + [ + "4.0.0", + "added `admin.report`" + ] + ], + "enum": null + }, + "created_at": { + "description": "The time the notification was created", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.9.9", + "added" + ] + ], + "enum": null + }, + "account": { + "description": "Account of the user from whom the notification originates", + "field_type": "Account", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.9.9", + "added" + ] + ], + "enum": null + }, + "status": { + "description": "In case of \"mention\", the mentioning status In case of reblog / favourite, the reblogged / favourited status", + "field_type": "Status", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.9.9", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Context", + "python_name": "Context", + "func_call": "mastodon.status_context()", + "func_call_real": "mastodon.status_context(110446983926957470)", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Context/", + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "The conversation context for a given status, i.e. its predecessors (that it replies to) and successors (that reply to it).", + "fields": { + "ancestors": { + "description": "A list of Statuses that the Status with this Context is a reply to", + "field_type": "EntityList", + "field_subtype": "Status", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ], + "enum": null + }, + "descendants": { + "description": "A list of Statuses that are replies to the Status with this Context", + "field_type": "EntityList", + "field_subtype": "Status", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "User List", + "python_name": "UserList", + "func_call": "mastodon.lists()[0]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/List/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "A list of users", + "fields": { + "id": { + "description": "id of the list", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.1.0", + "added" + ] + ], + "enum": null + }, + "title": { + "description": "title of the list", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.1.0", + "added" + ] + ], + "enum": null + }, + "replies_policy": { + "description": "Which replies should be shown in the list.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "RepliesPolicyEnum", + "version_history": [ + [ + "3.3.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Media attachment", + "python_name": "MediaAttachment", + "func_call": "mastodon.media_post(\"image.jpg\", \"image/jpeg\")[\"meta\"]", + "func_call_real": "mastodon.status(110447012773105565).media_attachments[0]", + "func_call_additional": "mastodon.status(110447003454258227).media_attachments[0]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/MediaAttachment/", + "func_alternate_acc": false, + "manual_update": false, + "description": "A piece of media (like an image, video, or audio file) that can be or has been attached to a status.", + "fields": { + "id": { + "description": "The ID of the attachment.", + "field_type": "MaybeSnowflakeIdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ], + "enum": null + }, + "type": { + "description": "Media type: 'image', 'video', 'gifv', 'audio' or 'unknown'.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ], + [ + "2.9.1", + "added `audio`" + ] + ], + "enum": { + "unknown": "unsupported or unrecognized file type", + "image": "Static image", + "gifv": "Looping, soundless animation", + "video": "Video clip", + "audio": "Audio track" + } + }, + "url": { + "description": "The URL for the image in the local cache", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "0.6.0", + "added" + ] + ], + "enum": null + }, + "remote_url": { + "description": "The remote URL for the media (if the image is from a remote instance)", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "field_structuretype": "URL", + "version_history": [ + [ + "0.6.0", + "added" + ] + ], + "enum": null + }, + "preview_url": { + "description": "The URL for the media preview", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "0.6.0", + "added" + ] + ], + "enum": null + }, + "text_url": { + "description": "Deprecated. The display text for the media (what shows up in text). May not be present in mastodon versions after 3.5.0", + "is_deprecated": true, + "field_type": "str", + "field_subtype": null, + "field_structuretype": "URL", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ], + [ + "3.5.0", + "removed" + ] + ] + }, + "meta": { + "description": "MediaAttachmentMetadataContainer that contains metadata for 'original' and 'small' (preview) versions of the MediaAttachment. Either may be empty. May additionally contain an \"fps\" field giving a videos frames per second (possibly rounded), and a \"length\" field giving a videos length in a human-readable format. Note that a video may have an image as preview. May also contain a 'focus' object and a media 'colors' object.", + "field_type": "MediaAttachmentMetadataContainer", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.5.0", + "added" + ], + [ + "2.3.0", + "added focus" + ], + [ + "4.0.0", + "added colors" + ] + ], + "enum": null + }, + "blurhash": { + "description": "The blurhash for the image, used for preview / placeholder generation", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "Blurhash", + "version_history": [ + [ + "2.8.1", + "added" + ] + ], + "enum": null + }, + "description": { + "description": "If set, the user-provided description for this media.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.0.0", + "added" + ] + ], + "enum": null + }, + "preview_remote_url": { + "description": "If set, the remote URL for the thumbnail of this media attachment on the or originating instance.", + "field_type": "str", + "field_subtype": null, + "field_structuretype": "URL", + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "0.6.0", + "added" + ] + ] + } + } + }, + { + "name": "Media metadata container", + "func_call_real": "mastodon.status(110447012773105565).media_attachments[0].meta", + "func_call_additional": "mastodon.status(110447003454258227).media_attachments[0].meta", + "python_name": "MediaAttachmentMetadataContainer", + "func_call": "mastodon.media_post(\"audio.mp3\").meta", + "masto_doc_link": "https://docs.joinmastodon.org/entities/MediaAttachment/", + "func_alternate_acc": false, + "manual_update": false, + "description": "An object holding metadata about a media attachment and its thumbnail.", + "fields": { + "original": { + "description": "Metadata for the original media attachment", + "field_type": "Union[MediaAttachmentImageMetadata, MediaAttachmentVideoMetadata, MediaAttachmentAudioMetadata]", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ] + }, + "small": { + "description": "Metadata for the thumbnail of this media attachment.", + "field_type": "MediaAttachmentImageMetadata", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ] + }, + "colors": { + "description": "Information about accent colors for the media.", + "field_type": "MediaAttachmentColors", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + }, + "focus": { + "description": "Information about the focus point for the media.", + "field_type": "MediaAttachmentFocusPoint", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.3.0", + "added" + ] + ] + } + } + }, + { + "name": "Media image metadata", + "python_name": "MediaAttachmentImageMetadata", + "func_call": "mastodon.media_post(\"image.jpg\").meta.original", + "func_call_real": "mastodon.status(110447003454258227).media_attachments[0].meta.original", + "masto_doc_link": "https://docs.joinmastodon.org/entities/MediaAttachment/", + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Metadata for an image media attachment.", + "fields": { + "width": { + "description": "Width of the image in pixels", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ] + }, + "height": { + "description": "Height of the image in pixels", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ] + }, + "aspect": { + "description": "Aspect ratio of the image as a floating point number", + "field_type": "float", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ] + }, + "size": { + "description": "Textual representation of the image size in pixels, e.g. '800x600'", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ] + } + } + }, + { + "name": "Media video and gifv metadata", + "python_name": "MediaAttachmentVideoMetadata", + "func_call": "mastodon.media_post(\"video.mp4\").meta.original", + "func_call_real": "mastodon.status(110447001287656894).media_attachments[0].meta.original", + "func_call_additional": "mastodon.status(110447018236380496).media_attachments[0].meta.original", + "masto_doc_link": "https://docs.joinmastodon.org/entities/MediaAttachment/", + "func_alternate_acc": false, + "manual_update": false, + "description": "Metadata for a video or gifv media attachment.", + "fields": { + "width": { + "description": "Width of the video in pixels", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ] + }, + "height": { + "description": "Height of the video in pixels", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ] + }, + "frame_rate": { + "description": "Exact frame rate of the video in frames per second. Can be an integer fraction (i.e. \"20/7\")", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ] + }, + "duration": { + "description": "Duration of the video in seconds", + "field_type": "float", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ] + }, + "bitrate": { + "description": "Average bit-rate of the video in bytes per second", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ] + } + } + }, + { + "name": "Media audio metadata", + "python_name": "MediaAttachmentAudioMetadata", + "func_call": "mastodon.media_post(\"audio.mp3\").meta.original", + "func_call_real": "mastodon.status(110447012773105565).media_attachments[0].meta.original", + "masto_doc_link": "https://docs.joinmastodon.org/entities/MediaAttachment/", + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Metadata for an audio media attachment.", + "fields": { + "duration": { + "description": "Duration of the audio file in seconds", + "field_type": "float", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ] + }, + "bitrate": { + "description": "Average bit-rate of the audio file in bytes per second", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "0.6.0", + "added" + ] + ] + } + } + }, + { + "name": "Media focus point", + "python_name": "MediaAttachmentFocusPoint", + "func_call": "mastodon.media_post(\"image.jpg\").meta.focus", + "func_call_real": "mastodon.status(110447003454258227).media_attachments[0].meta.focus", + "masto_doc_link": "https://docs.joinmastodon.org/entities/MediaAttachment/", + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "The focus point for a media attachment, for cropping purposes.", + "fields": { + "x": { + "description": "Focus point x coordinate (between -1 and 1), with 0 being the center and -1 and 1 being the left and right edges respectively.", + "field_type": "float", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.3.0", + "added" + ] + ] + }, + "y": { + "description": "Focus point x coordinate (between -1 and 1), with 0 being the center and -1 and 1 being the upper and lower edges respectively.", + "field_type": "float", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.3.0", + "added" + ] + ] + } + } + }, + { + "name": "Media colors", + "python_name": "MediaAttachmentColors", + "func_call": "mastodon.media_post(\"image.jpg\").meta.colors", + "func_call_real": "mastodon.status(110447012773105565).media_attachments[0].meta.colors", + "masto_doc_link": "https://docs.joinmastodon.org/entities/MediaAttachment/", + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Object describing the accent colors for a media attachment.", + "fields": { + "foreground": { + "description": "Estimated foreground colour for the attachment thumbnail, as a html format hex color (#rrggbb)", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + }, + "background": { + "description": "Estimated background colour for the attachment thumbnail, as a html format hex color (#rrggbb)", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + }, + "accent": { + "description": "Estimated accent colour for the attachment thumbnail", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + } + } + }, + { + "name": "Card", + "func_call": "mastodon.status_card()", + "func_call_real": "mastodon.status_card(110447098625216345)", + "python_name": "PreviewCard", + "masto_doc_link": "https://docs.joinmastodon.org/entities/PreviewCard/", + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "A preview card attached to a status, e.g. for an embedded video or link.", + "fields": { + "url": { + "description": "The URL of the card.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "1.0.0", + "added" + ] + ], + "enum": null + }, + "title": { + "description": "The title of the card.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.0.0", + "added" + ] + ], + "enum": null + }, + "description": { + "description": "Description of the embedded content", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.0.0", + "added" + ] + ], + "enum": null + }, + "type": { + "description": "Embed type: 'link', 'photo', 'video', or 'rich'", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.3.0", + "added" + ] + ], + "enum": { + "link": "Link OEmbed", + "photo": "Photo OEmbed", + "video": "Video OEmbed", + "rich": "iframe OEmbed. Not currently accepted, so won't show up in practice." + } + }, + "image": { + "description": "(optional) The image associated with the card.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "field_structuretype": "URL", + "version_history": [ + [ + "1.0.0", + "added" + ] + ], + "enum": null + }, + "author_name": { + "description": "Name of the embedded contents author", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.3.0", + "added" + ] + ], + "enum": null + }, + "author_url": { + "description": "URL pointing to the embedded contents author", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "1.3.0", + "added" + ] + ], + "enum": null + }, + "width": { + "description": "Width of the embedded object", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.3.0", + "added" + ] + ], + "enum": null + }, + "height": { + "description": "Height of the embedded object", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.3.0", + "added" + ] + ], + "enum": null + }, + "html": { + "description": "HTML string representing the embed", + "field_type": "str", + "field_subtype": null, + "field_structuretype": "HTML", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.3.0", + "added" + ] + ], + "enum": null + }, + "provider_name": { + "description": "Name of the provider from which the embed originates", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.3.0", + "added" + ] + ], + "enum": null + }, + "provider_url": { + "description": "URL pointing to the embeds provider", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "1.3.0", + "added" + ] + ], + "enum": null + }, + "blurhash": { + "description": "Blurhash of the preview image", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "field_structuretype": "Blurhash", + "version_history": [ + [ + "3.2.0", + "added" + ] + ], + "enum": null + }, + "language": { + "description": "Language of the embedded content", + "field_type": "str", + "field_subtype": null, + "field_structuretype": "TwoLetterLanguageCodeEnum", + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "1.3.0", + "added" + ] + ] + }, + "embed_url": { + "description": "Used for photo embeds, instead of custom `html`.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "2.1.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Search result (v1)", + "python_name": "Search", + "func_call": "mastodon.search(\"\")", + "func_call_real": "mastodon.search(\"halcy\")", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Search/", + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "A search result, with accounts, hashtags and statuses.", + "has_versions": [ + "v1", + "v2" + ], + "is_deprecated": true, + "fields": { + "accounts": { + "description": "List of Accounts resulting from the query", + "field_type": "EntityList", + "field_subtype": "Account", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.1.0", + "added" + ] + ], + "enum": null + }, + "hashtags": { + "description": "List of Tags resulting from the query", + "field_type": "EntityList", + "field_subtype": "str", + "is_optional": false, + "is_nullable": false, + "is_deprecated": true, + "version_history": [ + [ + "1.1.0", + "added" + ], + [ + "2.4.1", + "v1 search deprecated because it returns a list of strings. v2 search added which returns a list of tags." + ], + [ + "3.0.0", + "v1 removed" + ] + ], + "enum": null + }, + "statuses": { + "description": "List of Statuses resulting from the query", + "field_type": "EntityList", + "field_subtype": "Status", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.1.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Search result (v2)", + "python_name": "SearchV2", + "func_call": "mastodon.search(\"\")", + "func_call_real": "mastodon.search(\"halcy\")", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Search/", + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "A search result, with accounts, hashtags and statuses.", + "has_versions": [ + "v1", + "v2" + ], + "fields": { + "accounts": { + "description": "List of Accounts resulting from the query", + "field_type": "EntityList", + "field_subtype": "Account", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.1.0", + "added" + ] + ], + "enum": null + }, + "hashtags": { + "description": "List of Tags resulting from the query", + "field_type": "EntityList", + "field_subtype": "Tag", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.1", + "added" + ] + ], + "enum": null + }, + "statuses": { + "description": "List of Statuses resulting from the query", + "field_type": "EntityList", + "field_subtype": "Status", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.1.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Instance (v1)", + "python_name": "Instance", + "func_call": "mastodon.instance_v1()", + "masto_doc_link": "https://docs.joinmastodon.org/entities/V1_Instance/", + "masto_doc_link_additional": "https://docs.joinmastodon.org/entities/Instance/", + "func_call_real": null, + "func_alternate_acc": false, + "manual_update": false, + "has_versions": [ + "v1", + "v2" + ], + "description": "Information about an instance. V1 API version.", + "fields": { + "uri": { + "description": "The instance's domain name. Moved to 'domain' for the v2 API, though Mastodon.py will mirror it here for backwards compatibility.", + "field_type": "str", + "moved_path": "domain", + "field_structuretype": "DomainName", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.1.0", + "added" + ] + ], + "enum": null + }, + "title": { + "description": "The instance's title", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.1.0", + "added" + ] + ], + "enum": null + }, + "short_description": { + "description": "An very brief text only instance description. Moved to 'description' for the v2 API.", + "moved_path": "description", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.2", + "added" + ] + ], + "enum": null + }, + "description": { + "description": "A brief instance description set by the admin. The V1 variant could contain html, but this is now deprecated. Likely to be empty on many instances.", + "field_type": "str", + "field_subtype": null, + "field_structuretype": "HTML", + "is_optional": false, + "is_nullable": false, + "is_deprecated": true, + "version_history": [ + [ + "1.1.0", + "added" + ], + [ + "4.0.0", + "deprecated - likely to be empty." + ] + ], + "enum": null + }, + "email": { + "description": "The admin contact email. Moved to InstanceContacts for the v2 API, though Mastodon.py will mirror it here for backwards compatibility.", + "moved_path": "contact.email", + "field_type": "str", + "field_subtype": null, + "field_structuretype": "Email", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.1.0", + "added" + ] + ], + "enum": null + }, + "version": { + "description": "The instance's Mastodon version. For a more robust parsed major/minor/patch version see TODO IMPLEMENT FUNCTION TO RETURN VERSIONS", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.3.0", + "added" + ] + ], + "enum": null + }, + "urls": { + "description": "Additional InstanceURLs, in the v1 api version likely to be just 'streaming_api' with the stream server websocket address.", + "field_type": "InstanceURLs", + "moved_path": "configuration.urls", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.4.2", + "added" + ] + ], + "enum": null + }, + "stats": { + "description": "InstanceStatistics containing three stats, user_count (number of local users), status_count (number of local statuses) and domain_count (number of known instance domains other than this one). This information is not present in the v2 API variant in this form - there is a 'usage' field instead.", + "field_type": "InstanceStatistics", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "1.6.0", + "added" + ] + ] + }, + "thumbnail": { + "description": "Information about thumbnails to represent the instance. In the v1 API variant, simply an URL pointing to a banner image representing the instance. The v2 API provides a more complex structure with a list of thumbnails of different sizes in this field.", + "field_type": "str", + "field_subtype": null, + "field_structuretype": "URL", + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "1.6.1", + "added" + ] + ] + }, + "languages": { + "description": "Array of ISO 639-1 (two-letter) language codes the instance has chosen to advertise.", + "field_type": "EntityList", + "field_subtype": "str", + "field_structuretype": "TwoLetterLanguageCodeEnum", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.3.0", + "added" + ] + ] + }, + "registrations": { + "description": "A boolean indication whether registrations on this instance are open (True) or not (False). The v2 API variant instead provides a dict with more information about possible registration requirements here.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.6.0", + "added" + ] + ] + }, + "approval_required": { + "description": "True if account approval is required when registering, False if not. Moved to InstanceRegistrations object for the v2 API.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.2", + "added" + ] + ] + }, + "invites_enabled": { + "description": "Boolean indicating whether invites are enabled on this instance. Changed in 4.0.0 from being true when the instance setting to enable invites is true to be true when the default user role has invites enabled (i.e. everyone can invite people). The v2 API does not contain this field, and it is not clear whether it will stay around.", + "is_deprecated": true, + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.4", + "added" + ], + [ + "4.0.0", + "changed specifics of when field is true, deprecated" + ] + ] + }, + "configuration": { + "description": "Various instance configuration settings - especially various limits (character counts, media upload sizes, ...)", + "field_type": "InstanceConfiguration", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.4", + "added" + ] + ] + }, + "contact_account": { + "description": "Account of the primary contact for the instance. Moved to InstanceContacts for the v2 API.", + "moved_path": "contact.account", + "field_type": "Account", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.1.0", + "added" + ] + ] + }, + "rules": { + "description": "List of Rules with `id` and `text` fields, one for each server rule set by the admin", + "field_type": "EntityList", + "field_subtype": "Rule", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.0", + "added" + ] + ] + } + } + }, + { + "name": "Instance configuration (v1)", + "python_name": "InstanceConfiguration", + "func_call": "mastodon.instance_v1().configuration", + "masto_doc_link": "https://docs.joinmastodon.org/methods/instance/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "has_versions": [ + "v1", + "v2" + ], + "description": "Configuration values for this instance, especially limits and enabled features.", + "fields": { + "accounts": { + "description": "Account-related instance configuration fields", + "field_type": "InstanceAccountConfiguration", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.2", + "added" + ] + ] + }, + "statuses": { + "description": "Status-related instance configuration fields", + "field_type": "InstanceStatusConfiguration", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.2", + "added" + ] + ] + }, + "media_attachments": { + "description": "Media-related instance configuration fields", + "field_type": "InstanceMediaConfiguration", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.2", + "added" + ] + ] + }, + "polls": { + "description": "Poll-related instance configuration fields", + "field_type": "InstancePollConfiguration", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.2", + "added" + ] + ] + } + } + }, + { + "name": "Instance urls (v1)", + "python_name": "InstanceURLs", + "func_call": "mastodon.instance_v1().urls", + "func_call_additional": "mastodon.instance_v1().urls", + "masto_doc_link": "https://docs.joinmastodon.org/entities/V1_Instance/", + "func_call_real": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "A list of URLs related to an instance.", + "has_versions": [ + "v1", + "v2" + ], + "fields": { + "streaming_api": { + "description": "The Websockets URL for connecting to the streaming API. Renamed to 'streaming' for the v2 API.", + "field_type": "str", + "moved_path": "streaming", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "3.4.2", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Instance (v2)", + "python_name": "InstanceV2", + "func_call": "mastodon.instance_v2()", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Instance/", + "func_call_real": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Information about an instance", + "has_versions": [ + "v1", + "v2" + ], + "fields": { + "domain": { + "description": "The instances domain name", + "field_type": "str", + "is_optional": false, + "is_nullable": false, + "field_structuretype": "DomainName", + "field_subtype": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + }, + "title": { + "description": "The instance's title", + "field_type": "str", + "is_optional": false, + "is_nullable": false, + "field_subtype": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + }, + "version": { + "description": "The instance's Mastodon version. For a more robust parsed major/minor/patch version see TODO IMPLEMENT FUNCTION TO RETURN VERSIONS", + "field_type": "str", + "is_optional": false, + "is_nullable": false, + "field_subtype": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + }, + "source_url": { + "description": "URL pointing to a copy of the source code that is used to run this instance. For Mastodon instances, the AGPL requires that this code be available.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + }, + "description": { + "description": "A brief instance description set by the admin. Contains what in the v1 version was the short description.", + "field_type": "str", + "is_optional": false, + "is_nullable": false, + "field_structuretype": "HTML", + "field_subtype": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + }, + "usage": { + "description": "Information about recent activity on this instance.", + "field_type": "InstanceUsage", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + }, + "thumbnail": { + "description": "Information about thumbnails to represent the instance.", + "field_type": "InstanceThumbnail", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + }, + "languages": { + "description": "Array of ISO 639-1 (two-letter) language codes the instance has chosen to advertise.", + "field_type": "EntityList", + "field_subtype": "str", + "field_structuretype": "TwoLetterLanguageCodeEnum", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + }, + "configuration": { + "description": "Various instance configuration settings - especially various limits (character counts, media upload sizes, ...)", + "field_type": "InstanceConfiguration", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.4", + "added" + ] + ] + }, + "registrations": { + "description": "InstanceRegistrations object with information about how users can sign up on this instance.", + "field_type": "InstanceRegistrations", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + }, + "contact": { + "description": "Contact information for this instance.", + "field_type": "InstanceContact", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "rules": { + "description": "List of Rules with `id` and `text` fields, one for each server rule set by the admin", + "field_type": "EntityList", + "field_subtype": "Rule", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + } + } + }, + { + "name": "Instance configuration (v2)", + "python_name": "InstanceConfigurationV2", + "func_call": "mastodon.instance_v2().configuration", + "masto_doc_link": "https://docs.joinmastodon.org/methods/instance/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "has_versions": [ + "v1", + "v2" + ], + "description": "Configuration values for this instance, especially limits and enabled features.", + "fields": { + "accounts": { + "description": "Account-related instance configuration fields", + "field_type": "InstanceAccountConfiguration", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.2", + "added" + ] + ] + }, + "statuses": { + "description": "Status-related instance configuration fields", + "field_type": "InstanceStatusConfiguration", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.2", + "added" + ] + ] + }, + "media_attachments": { + "description": "Media-related instance configuration fields", + "field_type": "InstanceMediaConfiguration", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.2", + "added" + ] + ] + }, + "polls": { + "description": "Poll-related instance configuration fields", + "field_type": "InstancePollConfiguration", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.2", + "added" + ] + ] + }, + "translation": { + "description": "Translation-related instance configuration fields. Only present for the v2 API variant of the instance API.", + "field_type": "InstanceTranslationConfiguration", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "api_version": "v2", + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + }, + "urls": { + "description": "Instance related URLs. Only present for the v2 API variant of the instance API.", + "field_type": "InstanceURLsV2", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "api_version": "v2", + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + } + } + }, + { + "name": "Instance urls (v2)", + "python_name": "InstanceURLsV2", + "func_call": "mastodon.instance_v2().configuration.urls", + "func_call_additional": "mastodon.instance_v1().urls", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Instance/", + "func_call_real": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "A list of URLs related to an instance.", + "has_versions": [ + "v1", + "v2" + ], + "fields": { + "streaming": { + "description": "The Websockets URL for connecting to the streaming API.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "status": { + "description": "If present, a URL where the status and possibly current issues with the instance can be checked.", + "field_type": "str", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + } + } + }, + { + "name": "Instance thumbnail", + "python_name": "InstanceThumbnail", + "func_call": "mastodon.instance().thumbnail", + "masto_doc_link": "https://docs.joinmastodon.org/entities/V1_Instance/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Extended information about an instances thumbnail.", + "fields": { + "url": { + "description": "The URL for an image representing the instance.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "blurhash": { + "description": "The blurhash for the image representing the instance.", + "field_type": "str", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "field_structuretype": "Blurhash", + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "versions": { + "description": "Different resolution versions of the image representing the instance.", + "field_type": "InstanceThumbnailVersions", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Instance thumbnail versions", + "python_name": "InstanceThumbnailVersions", + "func_call": "mastodon.instance().thumbnail.versions", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Instance/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Different resolution versions of the image representing the instance.", + "fields": { + "@1x": { + "description": "The URL for an image representing the instance, for devices with 1x resolution / 96 dpi", + "python_name": "at1x", + "field_type": "str", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "@2x": { + "description": "The URL for the image representing the instance, for devices with 2x resolution / 192 dpi", + "field_type": "str", + "python_name": "at2x", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Instance statistics", + "python_name": "InstanceStatistics", + "func_call": "mastodon.instance_v1().stats", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Instance/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Usage statistics for an instance.", + "fields": { + "user_count": { + "description": "The total number of accounts that have been created on this instance.", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.6.0", + "added" + ] + ] + }, + "status_count": { + "description": "The total number of local posts that have been made on this instance.", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.6.0", + "added" + ] + ] + }, + "domain_count": { + "description": "The total number of other instances that this instance is aware of.", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "1.6.0", + "added" + ] + ] + } + } + }, + { + "name": "Instance usage", + "python_name": "InstanceUsage", + "func_call": "mastodon.instance().usage", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Instance/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Usage / recent activity information for this instance.", + "fields": { + "users": { + "description": "Information about user counts on this instance.", + "field_type": "InstanceUsageUsers", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ] + } + } + }, + { + "name": "Instance usage user information", + "python_name": "InstanceUsageUsers", + "func_call": "mastodon.instance().usage.users", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Instance/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Recent active user information about this instance.", + "fields": { + "active_month": { + "description": "This instances most recent monthly active user count.", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ] + } + } + }, + { + "name": "Instance rule", + "python_name": "Rule", + "func_call": "mastodon.instance().rules[0]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Rule/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "A rule that instance staff has specified users must follow on this instance.", + "fields": { + "id": { + "description": "An identifier for the rule.", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.0", + "added" + ] + ], + "enum": null + }, + "text": { + "description": "The rule to be followed.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Instance registration information", + "python_name": "InstanceRegistrations", + "func_call": "mastodon.instance().registrations", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Instance/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Registration information for this instance, like whether registrations are open and whether they require approval.", + "fields": { + "approval_required": { + "description": "Boolean indicating whether registrations on the instance require approval.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + }, + "enabled": { + "description": "Boolean indicating whether registrations are enabled on this instance.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + }, + "message": { + "description": "A message to be shown instead of the sign-up form when registrations are closed.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "field_structuretype": "HTML", + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + }, + "url": { + "description": "Presumably, a registration related URL. It is unclear what this is for.", + "field_type": "str", + "help_wanted": true, + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "field_structuretype": "URL", + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + } + } + }, + { + "name": "Instance contact information", + "python_name": "InstanceContact", + "func_call": "mastodon.instance().contact", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Instance/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Contact information for this instances' staff.", + "fields": { + "account": { + "description": "Account that has been designated as the instances contact account.", + "field_type": "Account", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + }, + "email": { + "description": "E-mail address that can be used to contact the instance staff.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "Email", + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + } + } + }, + { + "name": "Instance account configuration", + "python_name": "InstanceAccountConfiguration", + "func_call": "mastodon.instance().configuration.accounts", + "masto_doc_link": "https://docs.joinmastodon.org/methods/instance/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Configuration values relating to accounts.", + "fields": { + "max_featured_tags": { + "description": "The maximum number of featured tags that can be displayed on a profile.", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + } + } + }, + { + "name": "Instance status configuration", + "python_name": "InstanceStatusConfiguration", + "func_call": "mastodon.instance().configuration.statuses", + "masto_doc_link": "https://docs.joinmastodon.org/methods/instance/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Configuration values relating to statuses.", + "fields": { + "max_characters": { + "description": "Maximum number of characters in a status this instance allows local users to use.", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.2", + "added" + ] + ] + }, + "max_media_attachments": { + "description": "Maximum number of media attachments per status this instance allows local users to use.", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.2", + "added" + ] + ] + }, + "characters_reserved_per_url": { + "description": "Number of characters that this instance counts a URL as when counting charaters.", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.2", + "added" + ] + ] + } + } + }, + { + "name": "Instance translation configuration", + "python_name": "InstanceTranslationConfiguration", + "func_call": "mastodon.instance().configuration.translation", + "masto_doc_link": "https://docs.joinmastodon.org/methods/instance/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Configuration values relating to translation.", + "fields": { + "enabled": { + "description": "Boolean indicating whether the translation API is enabled on this instance.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ] + } + } + }, + { + "name": "Instance media attachment configuration", + "python_name": "InstanceMediaConfiguration", + "func_call": "mastodon.instance().configuration.media_attachments", + "masto_doc_link": "https://docs.joinmastodon.org/methods/instance/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Configuration values relating to media attachments.", + "fields": { + "supported_mime_types": { + "description": "Mime types the instance accepts for media attachment uploads.", + "field_type": "EntityList", + "field_subtype": "str", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.2", + "added" + ] + ] + }, + "image_size_limit": { + "description": "Maximum size (in bytes) the instance will accept for image uploads.", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.2", + "added" + ] + ] + }, + "image_matrix_limit": { + "description": "Maximum total number of pixels (i.e. width * height) the instance will accept for image uploads.", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.2", + "added" + ] + ] + }, + "video_size_limit": { + "description": "Maximum size (in bytes) the instance will accept for video uploads", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.2", + "added" + ] + ] + }, + "video_frame_rate_limit": { + "description": "Maximum frame rate the instance will accept for video uploads", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.2", + "added" + ] + ] + }, + "video_matrix_limit": { + "description": "Maximum total number of pixels (i.e. width * height) the instance will accept for video uploads", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.2", + "added" + ] + ] + } + } + }, + { + "name": "Instance poll configuration", + "python_name": "InstancePollConfiguration", + "func_call": "mastodon.instance().configuration.polls", + "masto_doc_link": "https://docs.joinmastodon.org/methods/instance/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Configuration values relating to polls.", + "fields": { + "max_options": { + "description": "How many poll options this instance allows local users to use per poll", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.2", + "added" + ] + ] + }, + "max_characters_per_option": { + "description": "Maximum number of characters this instance allows local users to use per poll option", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.2", + "added" + ] + ] + }, + "min_expiration": { + "description": "The shortest allowed duration for a poll on this instance, in seconds", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.2", + "added" + ] + ] + }, + "max_expiration": { + "description": "The longest allowed duration for a poll on this instance, in seconds", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.4.2", + "added" + ] + ] + } + } + }, + { + "name": "Nodeinfo", + "python_name": "Nodeinfo", + "func_call": "mastodon.instance_nodeinfo()", + "masto_doc_link": "https://github.com/jhass/nodeinfo", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "The instances standardized NodeInfo data.", + "fields": { + "version": { + "description": "Version of the nodeinfo schema spec that was used for this response.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ] + }, + "software": { + "description": "Information about the server software being used on this instance.", + "field_type": "NodeinfoSoftware", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ] + }, + "protocols": { + "description": "A list of strings specifying the federation protocols this instance supports. Typically, just \"activitypub\".", + "field_type": "EntityList", + "field_subtype": "str", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ] + }, + "services": { + "description": "Services that this instance can retrieve messages from or send messages to.", + "field_type": "NodeinfoServices", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ] + }, + "usage": { + "description": "Information about recent activity on this instance.", + "field_type": "NodeinfoUsage", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ] + }, + "openRegistrations": { + "description": "Bool indicating whether the instance is open for registrations.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ] + }, + "metadata": { + "description": "Additional node metadata. On Mastodon, typically an empty object with no fields.", + "field_type": "NodeinfoMetadata", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ] + } + } + }, + { + "name": "Nodeinfo software", + "python_name": "NodeinfoSoftware", + "func_call": "mastodon.instance_nodeinfo().software", + "masto_doc_link": "https://github.com/jhass/nodeinfo", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "NodeInfo software-related information.", + "fields": { + "name": { + "description": "Name of the software used by this instance.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ] + }, + "version": { + "description": "String indicating the version of the software used by this instance.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ] + } + } + }, + { + "name": "Nodeinfo services", + "python_name": "NodeinfoServices", + "func_call": "mastodon.instance_nodeinfo().services", + "masto_doc_link": "https://github.com/jhass/nodeinfo", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Nodeinfo services-related information.", + "fields": { + "outbound": { + "description": "List of services that this instance can send messages to. On Mastodon, typically an empty list.", + "field_type": "EntityList", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ] + }, + "inbound": { + "description": "List of services that this instance can retrieve messages from. On Mastodon, typically an empty list.", + "field_type": "EntityList", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ] + } + } + }, + { + "name": "Nodeinfo usage", + "python_name": "NodeinfoUsage", + "func_call": "mastodon.instance_nodeinfo().usage", + "masto_doc_link": "https://github.com/jhass/nodeinfo", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Nodeinfo usage-related information.", + "fields": { + "users": { + "description": "Information about user counts on this instance.", + "field_type": "NodeinfoUsageUsers", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ] + }, + "localPosts": { + "description": "The total number of local posts that have been made on this instance.", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ] + } + } + }, + { + "name": "Nodeinfo usage user count", + "python_name": "NodeinfoUsageUsers", + "func_call": "mastodon.instance_nodeinfo().usage.users", + "masto_doc_link": "https://github.com/jhass/nodeinfo", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Nodeinfo user count statistics.", + "fields": { + "total": { + "description": "The total number of accounts that have been created on this instance.", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ] + }, + "activeMonth": { + "description": "Number of users that have been active, by some definition (Mastodon: Have logged in at least once) in the last month.", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ] + }, + "activeHalfyear": { + "description": "Number of users that have been active, by some definition (Mastodon: Have logged in at least once) in the last half year.", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ] + } + } + }, + { + "name": "Nodeinfo metadata", + "python_name": "NodeinfoMetadata", + "masto_doc_link": "https://github.com/jhass/nodeinfo", + "func_call": "mastodon.instance_nodeinfo().metadata", + "description": "Nodeinfo extra metadata.", + "fields": {} + }, + { + "name": "Activity", + "python_name": "Activity", + "func_call": "mastodon.instance_activity()[0]", + "masto_doc_link": "https://docs.joinmastodon.org/methods/instance/#activity", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Information about recent activity on an instance.", + "fields": { + "week": { + "description": "Date of the first day of the week the stats were collected for", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.1.2", + "added" + ] + ] + }, + "logins": { + "description": "Number of users that logged in that week", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.1.2", + "added" + ] + ] + }, + "registrations": { + "description": "Number of new users that week", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.1.2", + "added" + ] + ] + }, + "statuses": { + "description": "Number of statuses posted that week", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.1.2", + "added" + ] + ] + } + } + }, + { + "name": "Report", + "python_name": "Report", + "func_call": "mastodon.report()[0]", + "func_alternate_acc": true, + "func_call_real": null, + "func_call_additional": null, + "masto_doc_link": "https://docs.joinmastodon.org/entities/Report/", + "manual_update": false, + "description": "Information about a report that has been filed against a user. Currently largely pointless, as updated reports cannot be fetched.", + "fields": { + "id": { + "description": "Id of the report", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "action_taken": { + "description": "True if a moderator or admin has processed the report, False otherwise.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "comment": { + "description": "Text comment submitted with the report", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "created_at": { + "description": "Time at which this report was created, as a datetime object", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "target_account": { + "description": "Account that has been reported with this report", + "field_type": "Account", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "status_ids": { + "description": "List of status IDs attached to the report", + "field_type": "EntityList", + "field_subtype": "IdType", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "action_taken_at": { + "description": "When an action was taken, if this report is currently resolved.", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "category": { + "description": "The category under which the report is classified.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "ReportReasonEnum", + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "forwarded": { + "description": "Whether a report was forwarded to a remote instance.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "rules_ids": { + "description": "IDs of the rules selected for this report.", + "field_type": "EntityList", + "field_subtype": "IdType", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Admin report", + "python_name": "AdminReport", + "func_call": "mastodon.admin_reports()[0]", + "func_alternate_acc": true, + "func_call_real": "mastodon.admin_reports()[-1]", + "func_call_additional": "mastodon.admin_reports(resolved=True)[-1]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Admin_Report/", + "masto_doc_link_additional": "https://docs.joinmastodon.org/entities/Report/", + "manual_update": false, + "description": "Information about a report that has been filed against a user.", + "fields": { + "id": { + "description": "Id of the report", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "action_taken": { + "description": "True if a moderator or admin has processed the report, False otherwise.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "comment": { + "description": "Text comment submitted with the report", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "created_at": { + "description": "Time at which this report was created, as a datetime object", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "updated_at": { + "description": "Last time this report has been updated, as a datetime object", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "account": { + "description": "Account of the user that filed this report", + "field_type": "Account", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "target_account": { + "description": "Account that has been reported with this report", + "field_type": "Account", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "assigned_account": { + "description": "If the report as been assigned to an account, that Account (None if not)", + "field_type": "AdminAccount", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "action_taken_by_account": { + "description": "Account that processed this report", + "field_type": "AdminAccount", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "statuses": { + "description": "List of Statuses attached to the report", + "field_type": "EntityList", + "field_subtype": "Status", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "action_taken_at": { + "description": "When an action was taken, if this report is currently resolved.", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "category": { + "description": "The category under which the report is classified.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "ReportReasonEnum", + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "forwarded": { + "description": "Whether a report was forwarded to a remote instance.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "rules": { + "description": "Rules attached to the report, for context.", + "field_type": "EntityList", + "field_subtype": "Rule", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Push subscription", + "python_name": "WebPushSubscription", + "func_call": "mastodon.push_subscription()", + "func_call_real": "mastodon.push_subscription_set(\"http://halcy.de/\",mastodon.push_subscription_generate_keys()[1],follow_events=True)", + "masto_doc_link": "https://docs.joinmastodon.org/entities/WebPushSubscription/", + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Information about the logged-in users web push subscription for the authenticated application.", + "fields": { + "id": { + "description": "Id of the push subscription", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ] + ], + "enum": null + }, + "endpoint": { + "description": "Endpoint URL for the subscription", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "2.4.0", + "added" + ] + ], + "enum": null + }, + "server_key": { + "description": "Server pubkey used for signature verification", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ] + ], + "enum": null + }, + "alerts": { + "description": "Subscribed events - object that may contain various keys, with value True if webpushes have been requested for those events.", + "field_type": "WebPushSubscriptionAlerts", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ], + [ + "2.8.0", + "added poll`" + ], + [ + "3.1.0", + "added follow_request`" + ], + [ + "3.3.0", + "added status" + ], + [ + "3.5.0", + "added update and admin.sign_up" + ], + [ + "4.0.0", + "added admin.report" + ] + ], + "enum": null + }, + "policy": { + "description": "Which sources should generate webpushes.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "enum": { + "all": "All sources generate pushes.", + "none": "Don't actually send pushes.", + "follower": "Pushes should be generated for events originating from accounts that follow the logged in user.", + "followed": "Pushes should be generated for events originating from accounts the logged in user follows." + }, + "version_history": [ + [ + "2.4.0", + "added" + ] + ] + } + } + }, + { + "name": "Push subscription alert", + "python_name": "WebPushSubscriptionAlerts", + "func_call": "mastodon.push_subscription().alerts", + "func_call_real": "mastodon_soc.push_subscription_set(\"http://halcy.de/\",mastodon_soc.push_subscription_generate_keys()[1],follow_events=True).alerts", + "masto_doc_link": "https://docs.joinmastodon.org/entities/WebPushSubscription/", + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "Information about alerts as part of a push subscription.", + "fields": { + "follow": { + "description": "True if push subscriptions for follow events have been requested, false or not present otherwise.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ] + ], + "enum": null + }, + "favourite": { + "description": "True if push subscriptions for favourite events have been requested, false or not present otherwise.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ] + ], + "enum": null + }, + "reblog": { + "description": "True if push subscriptions for reblog events have been requested, false or not present otherwise.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ] + ], + "enum": null + }, + "mention": { + "description": "True if push subscriptions for mention events have been requested, false or not present otherwise.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ] + ], + "enum": null + }, + "poll": { + "description": "True if push subscriptions for poll events have been requested, false or not present otherwise.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "enum": null + }, + "follow_request": { + "description": "True if push subscriptions for follow request events have been requested, false or not present otherwise.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ] + ], + "enum": null + }, + "status": { + "description": "True if push subscriptions for status creation (watched users only) events have been requested, false or not present otherwise.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + }, + "update": { + "description": "True if push subscriptions for status update (edit) events have been requested, false or not present otherwise.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.3.0", + "added" + ] + ], + "enum": null + }, + "admin_sign_up": { + "description": "True if push subscriptions for sign up events have been requested, false or not present otherwise. Admins only.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "admin_report": { + "description": "True if push subscriptions for report creation events have been requested, false or not present otherwise. Admins only.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Push notification", + "python_name": "PushNotification", + "func_call": "mastodon.push_subscription_decrypt_push(...)", + "manual_update": true, + "masto_doc_link": "https://docs.joinmastodon.org/entities/WebPushSubscription/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "description": "A single Mastodon push notification received via WebPush, after decryption.", + "fields": { + "access_token": { + "description": "Access token that can be used to access the API as the notified user", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ] + ] + }, + "body": { + "description": "Text body of the notification", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ] + ] + }, + "icon": { + "description": "URL to an icon for the notification", + "field_type": "str", + "field_subtype": null, + "field_structuretype": "URL", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ] + ] + }, + "notification_id": { + "description": "ID that can be passed to notification() to get the full notification object,", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ] + ] + }, + "notification_type": { + "description": "String indicating the type of notification.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ] + ], + "enum": { + "follow": "A user followed the logged in user.", + "favourite": "A user favourited one of the logged in user's statuses.", + "reblog": "A user reblogged one of the logged in user's statuses.", + "mention": "A user mentioned the logged in user in a status.", + "poll": "A poll created or participated in by the logged in user has updated or ended", + "follow_request": "A user has requested to follow the logged in user.", + "status": " A watched user has posted a new status.", + "update": "A status the logged in user has reblogged has been edited.", + "admin_sign_up": "A new user has signed up on the instance.", + "admin_report": "A user has been reported to the instance's administrators." + } + }, + "preferred_locale": { + "description": "The user's preferred locale", + "field_type": "str", + "field_subtype": null, + "field_structuretype": "TwoLetterLanguageCodeEnum", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ] + ] + }, + "title": { + "description": "Title for the notification", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.4.0", + "added" + ] + ] + } + } + }, + { + "name": "Preference", + "python_name": "Preferences", + "func_call": "mastodon.preferences()", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Preferences/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "The logged in users preferences.", + "fields": { + "posting:default:visibility": { + "python_name": "posting_default_visibility", + "description": "Default visibility for new posts. Also found in CredentialAccountSource as `privacy`.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "enum": { + "public": "Public post", + "unlisted": "Unlisted post", + "private": "Followers-only post", + "direct": "Direct post" + } + }, + "posting:default:sensitive": { + "python_name": "posting_default_sensitive", + "description": "Default sensitivity flag for new posts. Also found in CredentialAccountSource as `sensitive`.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "enum": null + }, + "posting:default:language": { + "python_name": "posting_default_language", + "description": "Default language for new posts. Also found in CredentialAccountSource as `language`.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "field_structuretype": "TwoLetterLanguageCodeEnum", + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "enum": null + }, + "reading:expand:media": { + "python_name": "reading_expand_media", + "description": "String indicating whether media attachments should be automatically displayed or blurred/hidden.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "enum": { + "default": "Hide media marked as sensitive", + "show_all": "Always show all media by default, regardless of sensitivity", + "hide_all": "Always hide all media by default, regardless of sensitivity" + } + }, + "reading:expand:spoilers": { + "python_name": "reading_expand_spoilers", + "description": "Boolean indicating whether CWs should be expanded by default.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "enum": null + }, + "reading:autoplay:gifs": { + "python_name": "reading_autoplay_gifs", + "description": "Boolean indicating whether gifs should be autoplayed (True) or not (False)", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.8.0", + "added" + ] + ] + } + } + }, + { + "name": "Featured tag", + "python_name": "FeaturedTag", + "func_call": "mastodon.featured_tags()[0]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/FeaturedTag/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "A tag featured on a users profile.", + "fields": { + "id": { + "description": "The featured tags id", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ], + "enum": null + }, + "name": { + "description": "The featured tags name (without leading #)", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ], + "enum": null + }, + "statuses_count": { + "description": "Number of publicly visible statuses posted with this hashtag that this instance knows about", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ], + "enum": null + }, + "last_status_at": { + "description": "The last time a public status containing this hashtag was added to this instance's database (can be None if there are none)", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ], + "enum": null + }, + "url": { + "description": "A link to all statuses by a user that contain this hashtag.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "3.3.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Read marker", + "python_name": "Marker", + "func_call": "mastodon.markers_get()[\"home\"]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/Marker/", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": false, + "manual_update": false, + "description": "A read marker indicating where the logged in user has left off reading a given timeline.", + "fields": { + "last_read_id": { + "description": "ID of the last read object in the timeline", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ], + "enum": null + }, + "version": { + "description": "A counter that is incremented whenever the marker is set to a new status", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ], + "enum": null + }, + "updated_at": { + "description": "The time the marker was last set, as a datetime object", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.0.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Announcement", + "python_name": "Announcement", + "func_call": "mastodon.announcements()[0]", + "func_alternate_acc": true, + "masto_doc_link": "https://docs.joinmastodon.org/entities/Announcement/", + "func_call_real": null, + "func_call_additional": null, + "manual_update": false, + "description": "An announcement sent by the instances staff.", + "fields": { + "id": { + "description": "The annoucements id", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + }, + "content": { + "description": "The contents of the annoucement, as an html string", + "field_type": "str", + "field_subtype": null, + "field_structuretype": "HTML", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + }, + "starts_at": { + "description": "The annoucements start time, as a datetime object. Can be None", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + }, + "ends_at": { + "description": "The annoucements end time, as a datetime object. Can be None", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + }, + "all_day": { + "description": "Boolean indicating whether the annoucement represents an \"all day\" event", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + }, + "published_at": { + "description": "The annoucements publish time, as a datetime object", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + }, + "updated_at": { + "description": "The annoucements last updated time, as a datetime object", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + }, + "read": { + "description": "A boolean indicating whether the logged in user has dismissed the annoucement", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + }, + "mentions": { + "description": "Users mentioned in the annoucement", + "field_type": "EntityList", + "field_subtype": "StatusMention", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + }, + "tags": { + "description": "Hashtags mentioned in the announcement", + "field_type": "EntityList", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + }, + "emojis": { + "description": "Custom emoji used in the annoucement", + "field_type": "EntityList", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + }, + "reactions": { + "description": "Reactions to the annoucement", + "field_type": "EntityList", + "field_subtype": "Reaction", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + }, + "statuses": { + "description": "Statuses linked in the announcement text.", + "field_type": "EntityList", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Announcement reaction", + "python_name": "Reaction", + "func_call": "mastodon.announcements()[0].reactions[0]", + "func_alternate_acc": true, + "masto_doc_link": "https://docs.joinmastodon.org/entities/Reaction/", + "func_call_real": null, + "func_call_additional": null, + "manual_update": false, + "description": "A reaction to an announcement.", + "fields": { + "name": { + "description": "Name of the custom emoji or unicode emoji of the reaction", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + }, + "count": { + "description": "Reaction counter (i.e. number of users who have added this reaction)", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + }, + "me": { + "description": "True if the logged-in user has reacted with this emoji, false otherwise", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + }, + "url": { + "description": "URL for the custom emoji image", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + }, + "static_url": { + "description": "URL for a never-animated version of the custom emoji image", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "URL", + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Announcement reaction (streaming edition)", + "python_name": "StreamReaction", + "func_call": "mastodon.announcements()[0].reactions[0]", + "func_alternate_acc": true, + "masto_doc_link": "https://docs.joinmastodon.org/methods/streaming/", + "func_call_real": null, + "func_call_additional": null, + "manual_update": false, + "description": "A reaction to an announcement.", + "fields": { + "name": { + "description": "Name of the custom emoji or unicode emoji of the reaction", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + }, + "count": { + "description": "Reaction counter (i.e. number of users who have added this reaction)", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + }, + "announcement_id": { + "description": "If of the announcement this reaction was for", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.1.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Familiar follower", + "python_name": "FamiliarFollowers", + "func_alternate_acc": true, + "func_call": "mastodon.account_familiar_followers()[0]", + "func_call_real": "mastodon.account_familiar_followers(2)[0]", + "masto_doc_link": "https://docs.joinmastodon.org/entities/FamiliarFollowers/", + "func_call_additional": null, + "manual_update": false, + "description": "A follower of a given account that is also followed by the logged-in user.", + "fields": { + "id": { + "description": "ID of the account for which the familiar followers are being returned", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "accounts": { + "description": "List of Accounts of the familiar followers", + "field_type": "EntityList", + "field_subtype": "Account", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Admin account", + "python_name": "AdminAccount", + "func_call": "mastodon.admin_account()", + "func_call_real": "mastodon.admin_account(1)", + "func_alternate_acc": true, + "masto_doc_link": "https://docs.joinmastodon.org/entities/Admin_Account/", + "func_call_additional": null, + "manual_update": false, + "description": "Admin variant of the Account entity, with some additional information.", + "fields": { + "id": { + "description": "The users id,", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "username": { + "description": "The users username, no leading @", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "domain": { + "description": "The users domain", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "created_at": { + "description": "The time of account creation", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "email": { + "description": "For local users, the user's email", + "field_type": "str", + "field_subtype": null, + "field_structuretype": "Email", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "ip": { + "description": "For local users, the user's last known IP address", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.9.1", + "added" + ], + [ + "3.5.0", + "return type changed from String to [AdminIp]({{< relref \"entities/Admin_Ip\" >}}) due to a bug" + ], + [ + "4.0.0", + "bug fixed, return type is now a String again" + ] + ], + "enum": null + }, + "role": { + "description": "The users role", + "field_type": "Role", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added, returns a String (enumerable, oneOf `user` `moderator` `admin`)" + ], + [ + "4.0.0", + "now uses Role entity" + ] + ], + "enum": null + }, + "confirmed": { + "description": "For local users, False if the user has not confirmed their email, True otherwise", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "suspended": { + "description": "Boolean indicating whether the user has been suspended", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "silenced": { + "description": "Boolean indicating whether the user has been silenced", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "disabled": { + "description": "For local users, boolean indicating whether the user has had their login disabled", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "approved": { + "description": "For local users, False if the user is pending, True otherwise", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "locale": { + "description": "For local users, the locale the user has set,", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "TwoLetterLanguageCodeEnum", + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "invite_request": { + "description": "If the user requested an invite, the invite request comment of that user.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "account": { + "description": "The user's Account", + "field_type": "Account", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "sensitized": { + "description": "Undocumented. If you know what this means, please let me know.", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "help_wanted": true, + "version_history": [ + [ + "2.9.1", + "added" + ] + ] + }, + "ips": { + "description": "All known IP addresses associated with this account.", + "field_type": "EntityList", + "field_subtype": "AdminIp", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "created_by_application_id": { + "description": "Present if the user was created by an application and set to the application id.", + "field_type": "IdType", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + }, + "invited_by_account_id ": { + "description": "Present if the user was created via invite and set to the inviting users id.", + "field_type": "IdType", + "field_subtype": null, + "is_optional": true, + "is_nullable": false, + "version_history": [ + [ + "2.9.1", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Admin account IP", + "python_name": "AdminIp", + "func_call": "mastodon.admin_account().ips[0]", + "func_call_real": "mastodon.admin_account(1).ips[0]", + "func_alternate_acc": true, + "masto_doc_link": "https://docs.joinmastodon.org/entities/Admin_Ip/", + "func_call_additional": null, + "manual_update": false, + "description": "An IP address used by some user or other instance, visible as part of some admin APIs.", + "fields": { + "ip": { + "description": "The IP address.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "used_at": { + "description": "The timestamp of when the IP address was last used for this account.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Admin measure", + "python_name": "AdminMeasure", + "func_call": "mastodon.admin_measures(datetime.now() - timedelta(hours=24*5), datetime.now(), interactions=True)[0]", + "func_alternate_acc": true, + "masto_doc_link": "https://docs.joinmastodon.org/entities/Admin_Measure/", + "func_call_real": null, + "func_call_additional": null, + "manual_update": false, + "description": "A measurement, such as the number of active users, as returned by the admin reporting API.", + "fields": { + "key": { + "description": "Name of the measure returned", + "field_type": "str", + "field_subtype": null, + "field_structuretype": "AdminMeasureTypeEnum", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": { + "active_users": "Total active users on your instance within the time period", + "new_users": "Users who joined your instance within the time period", + "interactions": "Total interactions (favourites, boosts, replies) on local statuses within the time period", + "opened_reports": "Total reports filed within the time period", + "resolved_reports": "Total reports resolved within the time period", + "tag_accounts": "Total accounts who used a tag in at least one status within the time period", + "tag_uses": "Total statuses which used a tag within the time period", + "tag_servers": "Total remote origin servers for statuses which used a tag within the time period", + "instance_accounts": "Total accounts originating from a remote domain within the time period", + "instance_media_attachments": "Total space used by media attachments from a remote domain within the time period", + "instance_reports": "Total reports filed against accounts from a remote domain within the time period", + "instance_statuses": "Total statuses originating from a remote domain within the time period", + "instance_follows": "Total accounts from a remote domain followed by a local user within the time period", + "instance_followers": "Total local accounts followed by accounts from a remote domain within the time period" + } + }, + "unit": { + "description": "Unit for the measure, if available", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "total": { + "description": "Value of the measure returned", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "human_value": { + "description": "Human readable variant of the measure returned", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "previous_total": { + "description": "Previous measurement period value of the measure returned, if available", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "data": { + "description": "A list of AdminMeasureData with the measure broken down by date", + "field_type": "EntityList", + "field_subtype": "AdminMeasureData", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Admin measure data", + "python_name": "AdminMeasureData", + "func_call": "mastodon.admin_measures(datetime.now() - timedelta(hours=24*5), datetime.now(), active_users=True)[0].data[0]", + "func_alternate_acc": true, + "masto_doc_link": "https://docs.joinmastodon.org/entities/Admin_Measure/", + "func_call_real": null, + "func_call_additional": null, + "manual_update": false, + "description": "A single row of data for an admin reporting api measurement.", + "fields": { + "date": { + "description": "Date for this row", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "value": { + "description": "Value of the measure for this row", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Admin dimension", + "python_name": "AdminDimension", + "func_call": "mastodon.admin_dimensions(datetime.now() - timedelta(hours=24*5), datetime.now(), languages=True)[0]", + "func_alternate_acc": true, + "masto_doc_link": "https://docs.joinmastodon.org/entities/Admin_Dimension/", + "func_call_real": null, + "func_call_additional": null, + "manual_update": false, + "description": "A qualitative measurement about the server, as returned by the admin reporting api.", + "fields": { + "key": { + "description": "Name of the dimension returned", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "data": { + "description": "A list of data AdminDimensionData objects", + "field_type": "EntityList", + "field_subtype": "AdminDimensionData", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Admin dimension data", + "python_name": "AdminDimensionData", + "func_call": "mastodon.admin_dimensions(datetime.now() - timedelta(hours=24*5), datetime.now(), languages=True)[0].data[0]", + "func_alternate_acc": true, + "masto_doc_link": "https://docs.joinmastodon.org/entities/Admin_Dimension/", + "func_call_real": null, + "func_call_additional": null, + "manual_update": false, + "description": "A single row of data for qualitative measurements about the server, as returned by the admin reporting api.", + "fields": { + "key": { + "description": "category for this row", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "human_key": { + "description": "Human readable name for the category for this row, when available", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + }, + "value": { + "description": "Numeric value for the category", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Admin retention", + "python_name": "AdminRetention", + "func_call": "mastodon.admin_retention(datetime.now() - timedelta(hours=24*5), datetime.now())[0]", + "func_alternate_acc": true, + "masto_doc_link": "https://docs.joinmastodon.org/entities/Admin_Cohort/", + "func_call_real": null, + "func_call_additional": null, + "manual_update": false, + "description": "User retention data for a given cohort, as returned by the admin reporting api.", + "fields": { + "period": { + "description": "Starting time of the period that the data is being returned for", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ] + }, + "frequency": { + "description": "Time resolution (day or month) for the returned data", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ] + }, + "data": { + "description": "List of AdminCohort objects", + "field_type": "EntityList", + "field_subtype": "AdminCohort", + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ] + } + } + }, + { + "name": "Admin retention data", + "python_name": "AdminCohort", + "func_call": "mastodon.admin_retention(datetime.now() - timedelta(hours=24*5), datetime.now())[0].data[0]", + "func_alternate_acc": true, + "masto_doc_link": "https://docs.joinmastodon.org/entities/Admin_Cohort/", + "func_call_real": null, + "func_call_additional": null, + "manual_update": false, + "description": "A single data point regarding user retention for a given cohort, as returned by the admin reporting api.", + "fields": { + "date": { + "description": "Date for this entry", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ] + }, + "rate": { + "description": "Fraction of users retained", + "field_type": "float", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ] + }, + "value": { + "description": "Absolute number of users retained", + "field_type": "int", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "3.5.0", + "added" + ] + ] + } + } + }, + { + "name": "Admin domain block", + "python_name": "AdminDomainBlock", + "func_call": "mastodon_ico_admin.admin_domain_blocks()[0]", + "func_alternate_acc": true, + "masto_doc_link": "https://docs.joinmastodon.org/entities/Admin_DomainBlock/", + "func_call_real": null, + "func_call_additional": null, + "manual_update": false, + "description": "A domain block, as returned by the admin API.", + "fields": { + "id": { + "description": "The ID of the DomainBlock in the database.", + "field_type": "IdType", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "domain": { + "description": "The domain that is not allowed to federate.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "created_at": { + "description": "When the domain was blocked from federating.", + "field_type": "datetime", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "severity": { + "description": "The policy to be applied by this domain block.", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "field_structuretype": "AdminDomainLimitEnum", + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": { + "silence": "Users from this domain will be hidden from timelines, threads, and notifications, except for followed users.", + "suspend": "Incoming messages from this domain will be rejected and dropped entirely.", + "noop": "Do nothing to statuses. May be used to only media-reject or report-reject." + } + }, + "reject_media": { + "description": "Whether to reject media attachments from this domain", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "reject_reports": { + "description": "Whether to reject reports from this domain", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "private_comment": { + "description": "A private comment (visible only to other moderators) for the domain block", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "public_comment": { + "description": "A public comment (visible to either all users, or the whole world) for the domain block", + "field_type": "str", + "field_subtype": null, + "is_optional": false, + "is_nullable": true, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + }, + "obfuscate": { + "description": "Whether to obfuscate public displays of this domain block", + "field_type": "bool", + "field_subtype": null, + "is_optional": false, + "is_nullable": false, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "enum": null + } + } + }, + { + "name": "Admin email block", + "python_name": "AdminCanonicalEmailBlock", + "func_call": "TODO_TO_BE_IMPLEMENTED", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": null, + "manual_update": false, + "masto_doc_link": "https://docs.joinmastodon.org/entities/Admin_CanonicalEmailBlock", + "description": "An e-mail block that has been set up to prevent certain e-mails to be used when signing up, via hash matching.", + "fields": { + "id": { + "description": "The ID of the email block in the database.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "IdType", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "canonical_email_hash": { + "description": "The SHA256 hash of the canonical email address.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + } + } + }, + { + "name": "Admin domain allow", + "python_name": "AdminDomainAllow", + "func_call": "TODO_TO_BE_IMPLEMENTED", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": null, + "manual_update": false, + "masto_doc_link": "https://docs.joinmastodon.org/entities/Admin_DomainAllow", + "description": "The opposite of a domain block, specifically allowing a domain to federate when the instance is in allowlist mode.", + "fields": { + "id": { + "description": "The ID of the DomainAllow in the database.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "IdType", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "domain": { + "description": "The domain that is allowed to federate.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "created_at": { + "description": "When the domain was allowed to federate.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "datetime", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + } + } + }, + { + "name": "Admin email domain block", + "python_name": "AdminEmailDomainBlock", + "func_call": "TODO_TO_BE_IMPLEMENTED", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": null, + "manual_update": false, + "masto_doc_link": "https://docs.joinmastodon.org/entities/Admin_EmailDomainBlock", + "description": "A block that has been set up to prevent e-mails from certain domains to be used when signing up.", + "fields": { + "id": { + "description": "The ID of the EmailDomainBlock in the database.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "IdType", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "domain": { + "description": "The email domain that is not allowed to be used for signups.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "created_at": { + "description": "When the email domain was disallowed from signups.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "datetime", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "history": { + "description": "Usage statistics for given days (typically the past week).", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "EntityList", + "field_subtype": "AdminEmailDomainBlockHistory", + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + } + } + }, + { + "name": "Admin email signup attempt history", + "python_name": "AdminEmailDomainBlockHistory", + "func_call": "TODO_TO_BE_IMPLEMENTED", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": null, + "manual_update": false, + "masto_doc_link": "https://docs.joinmastodon.org/entities/Admin_EmailDomainBlock", + "description": "Historic data about attempted signups using e-mails from a given domain.", + "fields": { + "day": { + "description": "The time (in day increments) for which this row of historical data is valid.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "datetime", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "accounts": { + "description": "The number of different account creation attempts that have been made.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "int", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "uses": { + "description": "The number of different ips used in account creation attempts.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "int", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + } + } + }, + { + "name": "Admin IP block", + "python_name": "AdminIpBlock", + "func_call": "TODO_TO_BE_IMPLEMENTED", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": null, + "manual_update": false, + "masto_doc_link": "https://docs.joinmastodon.org/entities/Admin_IpBlock", + "description": "An admin IP block, to prevent certain IP addresses or address ranges from accessing the instance.", + "fields": { + "id": { + "description": "The ID of the DomainBlock in the database.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "IdType", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "ip": { + "description": "The IP address range that is not allowed to federate.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "severity": { + "description": "The associated policy with this IP block.", + "enum": { + "sign_up_requires_approval": "Any signup from this IP range will create a pending account", + "sign_up_block": "Any signup from this IP range will be rejected", + "no_access": "Any activity from this IP range will be rejected entirely" + }, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "comment": { + "description": "The recorded reason for this IP block.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "created_at": { + "description": "When the IP block was created.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "datetime", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "expires_at": { + "description": "When the IP block will expire.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "datetime", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": true + } + } + }, + { + "name": "Domain block", + "python_name": "DomainBlock", + "func_call": "TODO_TO_BE_IMPLEMENTED", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": null, + "manual_update": false, + "masto_doc_link": "https://docs.joinmastodon.org/entities/DomainBlock", + "description": "A domain block that has been implemented by instance staff, limiting the way posts from the blocked instance are handled.", + "fields": { + "domain": { + "description": "The domain which is blocked. This may be obfuscated or partially censored.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "digest": { + "description": "The SHA256 hash digest of the domain string.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "severity": { + "description": "The level to which the domain is blocked.", + "enum": { + "silence": "Users from this domain will be hidden from timelines, threads, and notifications, except for followed users.", + "suspend": "Incoming messages from this domain will be rejected and dropped entirely." + }, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": "DomainLimitEnum", + "is_optional": false, + "is_nullable": false + }, + "comment": { + "description": "An optional reason for the domain block.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + } + } + }, + { + "name": "Extended instance description", + "python_name": "ExtendedDescription", + "func_call": "TODO_TO_BE_IMPLEMENTED", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": null, + "manual_update": false, + "masto_doc_link": "https://docs.joinmastodon.org/entities/ExtendedDescription", + "description": "An extended instance description that can contain HTML.", + "fields": { + "updated_at": { + "description": "A timestamp of when the extended description was last updated.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "datetime", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "content": { + "description": "The rendered HTML content of the extended description.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": "HTML", + "is_optional": false, + "is_nullable": false + } + } + }, + { + "name": "Filter keyword", + "python_name": "FilterKeyword", + "func_call": "TODO_TO_BE_IMPLEMENTED", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": null, + "manual_update": false, + "masto_doc_link": "https://docs.joinmastodon.org/entities/FilterKeyword", + "description": "A keyword that is being matched as part of a filter.", + "fields": { + "id": { + "description": "The ID of the FilterKeyword in the database.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "IdType", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "keyword": { + "description": "The phrase to be matched against.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "whole_word": { + "description": "Should the filter consider word boundaries? See implementation guidelines for filters().", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "bool", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + } + } + }, + { + "name": "Filter status", + "python_name": "FilterStatus", + "func_call": "TODO_TO_BE_IMPLEMENTED", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": null, + "manual_update": false, + "masto_doc_link": "https://docs.joinmastodon.org/entities/FilterStatus", + "description": "A single status that is being matched as part of a filter.", + "fields": { + "id": { + "description": "The ID of the FilterStatus in the database.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "IdType", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "status_id": { + "description": "The ID of the Status that will be filtered.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "MaybeSnowflakeIdType", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + } + } + }, + { + "name": "Identity proof", + "python_name": "IdentityProof", + "func_call": "TODO_TO_BE_IMPLEMENTED", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": null, + "manual_update": false, + "masto_doc_link": "https://docs.joinmastodon.org/entities/IdentityProof", + "description": "A cryptographic proof-of-identity.", + "fields": { + "provider": { + "description": "The name of the identity provider.", + "enum": null, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "provider_username": { + "description": "The account owner's username on the identity provider's service.", + "enum": null, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "updated_at": { + "description": "When the identity proof was last updated.", + "enum": null, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "field_type": "datetime", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "proof_url": { + "description": "A link to a statement of identity proof, hosted by the identity provider.", + "enum": null, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "profile_url": { + "description": "The account owner's profile URL on the identity provider.", + "enum": null, + "version_history": [ + [ + "2.8.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + } + } + }, + { + "name": "Status source", + "python_name": "StatusSource", + "func_call": "TODO_TO_BE_IMPLEMENTED", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": null, + "manual_update": false, + "masto_doc_link": "https://docs.joinmastodon.org/entities/StatusSource", + "description": "The source data of a status, useful when editing a status.", + "fields": { + "id": { + "description": "ID of the status in the database.", + "enum": null, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "field_type": "IdType", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "text": { + "description": "The plain text used to compose the status.", + "enum": null, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "spoiler_text": { + "description": "The plain text used to compose the status's subject or content warning.", + "enum": null, + "version_history": [ + [ + "3.5.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + } + } + }, + { + "name": "Suggestion", + "python_name": "Suggestion", + "func_call": "TODO_TO_BE_IMPLEMENTED", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": null, + "manual_update": false, + "masto_doc_link": "https://docs.joinmastodon.org/entities/Suggestion", + "description": "A follow suggestion.", + "fields": { + "source": { + "description": "The reason this account is being suggested.", + "enum": null, + "version_history": [ + [ + "3.4.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "account": { + "description": "The account being recommended to follow.", + "enum": null, + "version_history": [ + [ + "3.4.0", + "added" + ] + ], + "field_type": "Account", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + } + } + }, + { + "name": "Translation", + "python_name": "Translation", + "func_call": "TODO_TO_BE_IMPLEMENTED", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": null, + "manual_update": false, + "masto_doc_link": "https://docs.joinmastodon.org/entities/Translation", + "description": "A translation of a status.", + "fields": { + "content": { + "description": "The translated text of the status.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "detected_source_language": { + "description": "The language of the source text, as auto-detected by the machine translation provider.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "provider": { + "description": "The service that provided the machine translation.", + "enum": null, + "version_history": [ + [ + "4.0.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + } + } + }, + { + "name": "Account creation error", + "python_name": "AccountCreationError", + "func_call": "mastodon.create_account('halcy', 'secret', 'invalid email lol', True)", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": null, + "manual_update": false, + "masto_doc_link": "https://docs.joinmastodon.org/methods/accounts/#create", + "description": "An error response returned when creating an account fails.", + "fields": { + "error": { + "description": "The error as a localized string.", + "enum": null, + "version_history": [ + [ + "2.7.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + }, + "details": { + "description": "A dictionary giving more details about what fields caused errors and in which ways.", + "enum": null, + "version_history": [ + [ + "3.4.0", + "added" + ] + ], + "field_type": "AccountCreationErrorDetails", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + } + } + }, + { + "name": "Account creation error details", + "python_name": "AccountCreationErrorDetails", + "func_call": "mastodon.create_account('halcy', 'secret', 'invalid email lol', False).details", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": null, + "manual_update": false, + "masto_doc_link": "https://docs.joinmastodon.org/methods/accounts/#create", + "description": "An object containing detailed errors for different fields in the account creation attempt.", + "fields": { + "username": { + "description": "An object giving more details about an error caused by the username.", + "enum": null, + "version_history": [ + [ + "3.4.0", + "added" + ] + ], + "field_type": "AccountCreationErrorDetailsField", + "field_subtype": null, + "field_structuretype": null, + "is_optional": true, + "is_nullable": false + }, + "password": { + "description": "An object giving more details about an error caused by the password.", + "enum": null, + "version_history": [ + [ + "3.4.0", + "added" + ] + ], + "field_type": "AccountCreationErrorDetailsField", + "field_subtype": null, + "field_structuretype": null, + "is_optional": true, + "is_nullable": false + }, + "email": { + "description": "An object giving more details about an error caused by the e-mail.", + "enum": null, + "version_history": [ + [ + "3.4.0", + "added" + ] + ], + "field_type": "AccountCreationErrorDetailsField", + "field_subtype": null, + "field_structuretype": null, + "is_optional": true, + "is_nullable": false + }, + "agreement": { + "description": "An object giving more details about an error caused by the usage policy agreement.", + "enum": null, + "version_history": [ + [ + "3.4.0", + "added" + ] + ], + "field_type": "AccountCreationErrorDetailsField", + "field_subtype": null, + "field_structuretype": null, + "is_optional": true, + "is_nullable": false + }, + "locale": { + "description": "An object giving more details about an error caused by the locale.", + "enum": null, + "version_history": [ + [ + "3.4.0", + "added" + ] + ], + "field_type": "AccountCreationErrorDetailsField", + "field_subtype": null, + "field_structuretype": null, + "is_optional": true, + "is_nullable": false + }, + "reason": { + "description": "An object giving more details about an error caused by the registration reason.", + "enum": null, + "version_history": [ + [ + "3.4.0", + "added" + ] + ], + "field_type": "AccountCreationErrorDetailsField", + "field_subtype": null, + "field_structuretype": null, + "is_optional": true, + "is_nullable": false + } + } + }, + { + "name": "Account creation error details field", + "python_name": "AccountCreationErrorDetailsField", + "func_call": "mastodon.create_account('halcy', 'secret', 'invalid email lol', True).details.email", + "func_call_real": null, + "func_call_additional": null, + "func_alternate_acc": null, + "manual_update": false, + "masto_doc_link": "https://docs.joinmastodon.org/methods/accounts/#create", + "description": "An object giving details about what specifically is wrong with a given field in an account registration attempt.", + "fields": { + "error": { + "description": "A machine readable string giving an error category.", + "version_history": [ + [ + "3.4.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false, + "enum": { + "ERR_BLOCKED": "e-mail provider is not allowed", + "ERR_UNREACHABLE": "e-mail address does not resolve to any IP via DNS (MX, A, AAAA)", + "ERR_TAKEN": "username or e-mail are already taken", + "ERR_RESERVED": "username is reserved, e.g. 'webmaster' or 'admin'", + "ERR_ACCEPTED": "agreement has not been accepted", + "ERR_BLANK": "a required attribute is blank", + "ERR_INVALID": "an attribute is malformed, e.g. wrong characters or invalid e-mail address", + "ERR_TOO_LONG": "an attribute is over the character limit", + "ERR_TOO_SHORT": "an attribute is under the character requirement", + "ERR_INCLUSION": "an attribute is not one of the allowed values, e.g. unsupported locale" + } + }, + "description": { + "description": "A description of the issue as a localized string.", + "enum": null, + "version_history": [ + [ + "3.4.0", + "added" + ] + ], + "field_type": "str", + "field_subtype": null, + "field_structuretype": null, + "is_optional": false, + "is_nullable": false + } + } + } +] diff --git a/tests/test_account.py b/tests/test_account.py index 5cfad98..86b92ab 100644 --- a/tests/test_account.py +++ b/tests/test_account.py @@ -61,7 +61,6 @@ def test_account_follow_unfollow(api, api2): relationship = api.account_follow(api2_id) try: assert relationship - print(relationship) assert relationship['following'] finally: relationship = api.account_unfollow(api2_id) @@ -125,6 +124,7 @@ def test_account_update_credentials(api): ) assert account + assert account.id assert account["display_name"] == 'John Lennon' assert re.sub("<.*?>", " ", account["note"]).strip() == 'I walk funny' assert account["fields"][0].name == "bread" @@ -222,6 +222,7 @@ def test_preferences(api): @pytest.mark.vcr() def test_suggested_tags(api): + status = None try: status = api.status_post("cool free #ringtones") time.sleep(2) @@ -234,6 +235,8 @@ def test_suggested_tags(api): @pytest.mark.vcr() def test_featured_tags(api): + featured_tag = None + featured_tag_2 = None try: featured_tag = api.featured_tag_create("ringtones") assert featured_tag @@ -253,7 +256,8 @@ def test_featured_tags(api): finally: if featured_tag is not None: api.featured_tag_delete(featured_tag) - api.featured_tag_delete(featured_tag_2) + if featured_tag_2 is not None: + api.featured_tag_delete(featured_tag_2) @pytest.mark.vcr() def test_account_notes(api, api2): @@ -264,6 +268,8 @@ def test_account_notes(api, api2): @pytest.mark.vcr() def test_follow_with_notify_reblog(api, api2, api3): api2_id = api2.account_verify_credentials() + status1 = None + status2 = None try: api.account_follow(api2_id, notify = True, reblogs = False) status1 = api3.toot("rootin tooting and shootin") diff --git a/tests/test_instance.py b/tests/test_instance.py index afd883d..aeab305 100644 --- a/tests/test_instance.py +++ b/tests/test_instance.py @@ -7,14 +7,24 @@ import os import pickle @pytest.mark.vcr() -def test_instance(api): - instance = api.instance() +def test_instance_v1(api): + instance = api.instance_v1() - assert isinstance(instance, dict) # hehe, instance is instance + assert isinstance(instance, dict) expected_keys = set(('description', 'email', 'title', 'uri', 'version', 'urls')) assert set(instance.keys()) >= expected_keys +@pytest.mark.vcr() +def test_instance(api): + instance = api.instance() + + assert isinstance(instance, dict) + + expected_keys = set(('description')) # TODO add some more maybe + assert set(instance.keys()) >= expected_keys + + @pytest.mark.vcr() def test_instance_activity(api): activity = api.instance_activity()