From c49364fcc4981eee500dcde34f2e494fdd15ff96 Mon Sep 17 00:00:00 2001 From: halcy Date: Mon, 28 Nov 2022 01:31:04 +0200 Subject: Some more doc split tests --- docs/01_general.rst | 31 ++ docs/02_return_values.rst | 743 ++++++++++++++++++++++++++++++++++++++++++++++ docs/03_errors.rst | 36 +++ docs/04_auth.rst | 36 +++ docs/index.rst | 11 +- 5 files changed, 855 insertions(+), 2 deletions(-) create mode 100644 docs/02_return_values.rst create mode 100644 docs/03_errors.rst create mode 100644 docs/04_auth.rst diff --git a/docs/01_general.rst b/docs/01_general.rst index 0ea3ac4..70c7e6e 100644 --- a/docs/01_general.rst +++ b/docs/01_general.rst @@ -1,3 +1,6 @@ +General information +=================== + Rate limiting ------------- Mastodon's API rate limits per user account. By default, the limit is 300 requests @@ -117,6 +120,34 @@ you can also just write and everything will work as intended. +Versioning +---------- +Mastodon.py will check if a certain endpoint is available before doing API +calls. By default, it checks against the version of Mastodon retrieved on +init(), or the version you specified. Mastodon.py can be set (in the +constructor) to either check if an endpoint is available at all (this is the +default) or to check if the endpoint is available and behaves as in the newest +Mastodon version (with regards to parameters as well as return values). +Version checking can also be disabled altogether. If a version check fails, +Mastodon.py throws a `MastodonVersionError`. + +Some functions need to check what version of Mastodon they are talking to. +These will generally use a cached version to avoid sending a lot of pointless +requests. + +Many non-mainline forks have various different formats for their versions and +they have different, incompatible ideas about how to report version. Mastodon.py +tries its best to figure out what is going on, but success is not guaranteed. + +With the following functions, you can make Mastodon.py re-check the server +version or explicitly determine if a specific minimum Version is available. +Long-running applications that aim to support multiple Mastodon versions +should do this from time to time in case a server they are running against +updated. + +.. automethod:: Mastodon.retrieve_mastodon_version +.. automethod:: Mastodon.verify_minimum_version + A brief note on block lists --------------------------- Mastodon.py used to block three instances because these were particularly notorious for diff --git a/docs/02_return_values.rst b/docs/02_return_values.rst new file mode 100644 index 0000000..52947e9 --- /dev/null +++ b/docs/02_return_values.rst @@ -0,0 +1,743 @@ +Return values +============= + +Unless otherwise specified, all data is returned as Python dictionaries, matching +the JSON format used by the API. Dates returned by the API are in ISO 8601 format +and are parsed into Python datetime objects. + +To make access easier, the dictionaries returned are wrapped by a class that adds +read-only attributes for all dict values - this means that, for example, instead of +writing + +.. code-block:: python + + description = mastodon.account_verify_credentials()["source"]["note"] + +you can also just write + +.. code-block:: python + + description = mastodon.account_verify_credentials().source.note + +and everything will work as intended. The class used for this is exposed as +`AttribAccessDict`. + +User / account dicts +-------------------- +.. _user dict: +.. _user dicts: +.. _account dict: +.. _account dicts: + +.. code-block:: python + + mastodon.account() + # Returns the following dictionary: + { + 'id': # Same as + 'username': # The username (what you @ them with) + 'acct': # The user's account name as username@domain (@domain omitted for local users) + 'display_name': # The user's display name + 'discoverable': # True if the user is listed in the user directory, false if not. None + # for remote users. + 'group': # A boolean indicating whether the account represents a group rather than an + # individual. + 'locked': # Denotes whether the account can be followed without a follow request + 'created_at': # Account creation time + 'following_count': # How many people they follow + 'followers_count': # How many followers they have + 'statuses_count': # How many statuses they have + 'note': # Their bio + 'url': # Their URL; for example 'https://mastodon.social/users/' + 'avatar': # URL for their avatar, can be animated + 'header': # URL for their header image, can be animated + 'avatar_static': # URL for their avatar, never animated + 'header_static': # URL for their header image, never animated + 'source': # Additional information - only present for user dict returned + # from account_verify_credentials() + 'moved_to_account': # If set, a user dict of the account this user has + # set up as their moved-to address. + 'bot': # Boolean indicating whether this account is automated. + 'fields': # List of up to four dicts with free-form 'name' and 'value' profile info. + # For fields with "this is me" type verification, verified_at is set to the + # last verification date (It is None otherwise) + 'emojis': # List of custom emoji used in name, bio or fields + 'discoverable': # Indicates whether or not a user is visible on the discovery page + } + + mastodon.account_verify_credentials()["source"] + # Returns the following dictionary: + { + 'privacy': # The user's default visibility setting ("private", "unlisted" or "public") + 'sensitive': # Denotes whether user media should be marked sensitive by default + 'note': # Plain text version of the user's bio + } + +Toot / Status dicts +---------- +.. _toot dict: +.. _toot dicts: +.. _status dict: +.. _status dicts: + +.. code-block:: python + + mastodon.toot("Hello from Python") + # Returns the following dictionary: + { + 'id': # Numerical id of this toot + 'uri': # Descriptor for the toot + # EG 'tag:mastodon.social,2016-11-25:objectId=:objectType=Status' + 'url': # URL of the toot + 'account': # User dict for the account which posted the status + 'in_reply_to_id': # Numerical id of the toot this toot is in response to + 'in_reply_to_account_id': # Numerical id of the account this toot is in response to + 'reblog': # Denotes whether the toot is a reblog. If so, set to the original toot dict. + 'content': # Content of the toot, as HTML: '

Hello from Python

' + 'created_at': # Creation time + 'reblogs_count': # Number of reblogs + 'favourites_count': # Number of favourites + 'reblogged': # Denotes whether the logged in user has boosted this toot + 'favourited': # Denotes whether the logged in user has favourited this toot + 'sensitive': # Denotes whether media attachments to the toot are marked sensitive + 'spoiler_text': # Warning text that should be displayed before the toot content + 'visibility': # Toot visibility ('public', 'unlisted', 'private', or 'direct') + 'mentions': # A list of users dicts mentioned in the toot, as Mention dicts + 'media_attachments': # A list of media dicts of attached files + 'emojis': # A list of custom emojis used in the toot, as Emoji dicts + 'tags': # A list of hashtag used in the toot, as Hashtag dicts + 'bookmarked': # True if the status is bookmarked by the logged in user, False if not. + 'application': # Application dict for the client used to post the toot (Does not federate + # and is therefore always None for remote toots, can also be None for + # local toots for some legacy applications). + 'language': # The language of the toot, if specified by the server, + # as ISO 639-1 (two-letter) language code. + 'muted': # Boolean denoting whether the user has muted this status by + # way of conversation muting + 'pinned': # Boolean denoting whether or not the status is currently pinned for the + # associated account. + 'replies_count': # The number of replies to this status. + 'card': # A preview card for links from the status, if present at time of delivery, + # as card dict. + 'poll': # A poll dict if a poll is attached to this status. + } + +Status edit dicts +----------------- +.. _status edit dict: + +.. code-block:: python + + mastodonstatus_history(id)[0] + # Returns the following dictionary + { + TODO + } + +Mention dicts +------------- +.. _mention dict: + +.. code-block:: python + + { + 'url': # Mentioned user's profile URL (potentially remote) + 'username': # Mentioned user's user name (not including domain) + 'acct': # Mentioned user's account name (including domain) + 'id': # Mentioned user's (local) account ID + } + +Scheduled status / toot dicts +----------------------------- +.. _scheduled status dict: +.. _scheduled status dicts: +.. _scheduled toot dict: +.. _scheduled toot dicts: + +.. code-block:: python + + mastodon.status_post("text", scheduled_at=the_future) + # Returns the following dictionary: + { + 'id': # Scheduled toot ID (note: Not the id of the toot once it gets posted!) + 'scheduled_at': # datetime object describing when the toot is to be posted + 'params': # Parameters for the scheduled toot, specifically + { + 'text': # Toot text + 'in_reply_to_id': # ID of the toot this one is a reply to + 'media_ids': # IDs of media attached to this toot + 'sensitive': # Whether this toot is sensitive or not + 'visibility': # Visibility of the toot + 'idempotency': # Idempotency key for the scheduled toot + 'scheduled_at': # Present, but generally "None" + 'spoiler_text': # CW text for this toot + 'application_id': # ID of the application that scheduled the toot + 'poll': # Poll parameters, as a poll dict + }, + 'media_attachments': # Array of media dicts for the attachments to the scheduled toot + } + +Poll dicts +---------- +.. _poll dict: + +.. code-block:: python + + # Returns the following dictionary: + mastodon.poll(id) + { + 'id': # The polls ID + 'expires_at': # The time at which the poll is set to expire + 'expired': # Boolean denoting whether you can still vote in this poll + 'multiple': # Boolean indicating whether it is allowed to vote for more than one option + 'votes_count': # Total number of votes cast in this poll + 'voted': # Boolean indicating whether the logged-in user has already voted in this poll + 'options': # The poll options as a list of dicts, each option with a title and a + # votes_count field. votes_count can be None if the poll creator has + # chosen to hide vote totals until the poll expires and it hasn't yet. + 'emojis': # List of emoji dicts for all emoji used in answer strings, + 'own_votes': # The logged-in users votes, as a list of indices to the options. + } + + +Conversation dicts +------------------ +.. _conversation dict: + +.. code-block:: python + + mastodon.conversations()[0] + # Returns the following dictionary: + { + 'id': # The ID of this conversation object + 'unread': # Boolean indicating whether this conversation has yet to be + # read by the user + 'accounts': # List of accounts (other than the logged-in account) that + # are part of this conversation + 'last_status': # The newest status in this conversation + } + +Hashtag dicts +------------- +.. _hashtag dict: + +.. code-block:: python + + { + 'name': # Hashtag name (not including the #) + 'url': # Hashtag URL (can be remote) + 'history': # List of usage history dicts for up to 7 days. Not present in statuses. + } + +Hashtag usage history dicts +--------------------------- +.. _hashtag usage history dict: + +.. code-block:: python + + { + 'day': # Date of the day this history dict is for + 'uses': # Number of statuses using this hashtag on that day + 'accounts': # Number of accounts using this hashtag in at least one status on that day + } + +Emoji dicts +----------- +.. _emoji dict: + +.. code-block:: python + + { + 'shortcode': # Emoji shortcode, without surrounding colons + 'url': # URL for the emoji image, can be animated + 'static_url': # URL for the emoji image, never animated + 'visible_in_picker': # True if the emoji is enabled, False if not. + 'category': # The category to display the emoji under (not present if none is set) + } + +Application dicts +----------------- + .. _application dict: + +.. code-block:: python + + { + 'name': # The applications name + 'website': # The applications website + 'vapid_key': # A vapid key that can be used in web applications + } + + +Relationship dicts +------------------ +.. _relationship dict: + +.. code-block:: python + + mastodon.account_follow() + # Returns the following dictionary: + { + 'id': # Numerical id (same one as ) + 'following': # Boolean denoting whether the logged-in user follows the specified user + 'followed_by': # Boolean denoting whether the specified user follows the logged-in user + 'blocking': # Boolean denoting whether the logged-in user has blocked the specified user + 'blocked_by': # Boolean denoting whether the logged-in user has been blocked by the specified user, if information is available + 'muting': # Boolean denoting whether the logged-in user has muted the specified user + 'muting_notifications': # Boolean denoting wheter the logged-in user has muted notifications + # related to the specified user + 'requested': # Boolean denoting whether the logged-in user has sent the specified + # user a follow request + 'domain_blocking': # Boolean denoting whether the logged-in user has blocked the + # specified users domain + 'showing_reblogs': # Boolean denoting whether the specified users reblogs show up on the + # logged-in users Timeline + 'endorsed': # Boolean denoting wheter the specified user is being endorsed / featured by the + # logged-in user + 'note': # A free text note the logged in user has created for this account (not publicly visible) + 'notifying' # Boolean denoting whether the logged-in user has requested to get notified every time the followed user posts + } + +Filter dicts +------------ +.. _filter dict: + +.. code-block:: python + + mastodon.filter() + # Returns the following dictionary: + { + 'id': # Numerical id of the filter + 'phrase': # Filtered keyword or phrase + 'context': # List of places where the filters are applied ('home', 'notifications', 'public', 'thread') + 'expires_at': # Expiry date for the filter + 'irreversible': # Boolean denoting if this filter is executed server-side + # or if it should be ran client-side. + 'whole_word': # Boolean denoting whether this filter can match partial words + } + +Notification dicts +------------------ +.. _notification dict: + +.. code-block:: python + + mastodon.notifications()[0] + # Returns the following dictionary: + { + 'id': # id of the notification + 'type': # "mention", "reblog", "favourite", "follow", "poll" or "follow_request" + 'created_at': # The time the notification was created + 'account': # User dict of the user from whom the notification originates + 'status': # In case of "mention", the mentioning status + # In case of reblog / favourite, the reblogged / favourited status + } + +Context dicts +------------- +.. _context dict: + +.. code-block:: python + + mastodon.status_context() + # Returns the following dictionary: + { + 'ancestors': # A list of toot dicts + 'descendants': # A list of toot dicts + } + +List dicts +---------- +.. _list dict: + +.. code-block:: python + + mastodon.list() + # Returns the following dictionary: + { + 'id': # id of the list + 'title': # title of the list + } + +Media dicts +----------- +.. _media dict: + +.. code-block:: python + + mastodon.media_post("image.jpg", "image/jpeg") + # Returns the following dictionary: + { + 'id': # The ID of the attachment. + 'type': # Media type: 'image', 'video', 'gifv', 'audio' or 'unknown'. + 'url': # The URL for the image in the local cache + 'remote_url': # The remote URL for the media (if the image is from a remote instance) + 'preview_url': # The URL for the media preview + 'text_url': # The display text for the media (what shows up in toots) + 'meta': # Dictionary of two metadata dicts (see below), + # 'original' and 'small' (preview). 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' dict and a media 'colors' dict. + 'blurhash': # The blurhash for the image, used for preview / placeholder generation + 'description': # If set, the user-provided description for this media. + } + + # Metadata dicts (image) - all fields are optional: + { + 'width': # Width of the image in pixels + 'height': # Height of the image in pixels + 'aspect': # Aspect ratio of the image as a floating point number + 'size': # Textual representation of the image size in pixels, e.g. '800x600' + } + + # Metadata dicts (video, gifv) - all fields are optional: + { + 'width': # Width of the video in pixels + 'heigh': # Height of the video in pixels + 'frame_rate': # Exact frame rate of the video in frames per second. + # Can be an integer fraction (i.e. "20/7") + 'duration': # Duration of the video in seconds + 'bitrate': # Average bit-rate of the video in bytes per second + } + + # Metadata dicts (audio) - all fields are optional: + { + 'duration': # Duration of the audio file in seconds + 'bitrate': # Average bit-rate of the audio file in bytes per second + } + + # Focus Metadata dict: + { + 'x': # Focus point x coordinate (between -1 and 1) + 'y': # Focus point x coordinate (between -1 and 1) + } + + # Media colors dict: + { + 'foreground': # Estimated foreground colour for the attachment thumbnail + 'background': # Estimated background colour for the attachment thumbnail + 'accent': # Estimated accent colour for the attachment thumbnail + +Card dicts +---------- +.. _card dict: + +.. code-block:: python + + mastodon.status_card(): + # Returns the following dictionary + { + 'url': # The URL of the card. + 'title': # The title of the card. + 'description': # The description of the card. + 'type': # Embed type: 'link', 'photo', 'video', or 'rich' + 'image': # (optional) The image associated with the card. + + # OEmbed data (all optional): + 'author_name': # Name of the embedded contents author + 'author_url': # URL pointing to the embedded contents author + 'description': # Description of the embedded content + 'width': # Width of the embedded object + 'height': # Height of the embedded object + 'html': # HTML string of the embed + 'provider_name': # Name of the provider from which the embed originates + 'provider_url': # URL pointing to the embeds provider + 'blurhash': # (optional) Blurhash of the preview image + } + +Search result dicts +------------------- +.. _search result dict: + +.. code-block:: python + + mastodon.search("") + # Returns the following dictionary + { + 'accounts': # List of user dicts resulting from the query + 'hashtags': # List of hashtag dicts resulting from the query + 'statuses': # List of toot dicts resulting from the query + } + +Instance dicts +-------------- +.. _instance dict: + +.. code-block:: python + + mastodon.instance() + # Returns the following dictionary + { + 'domain': # The instances domain name + 'description': # A brief instance description set by the admin + 'short_description': # An even briefer instance description + 'email': # The admin contact email + 'title': # The instance's title + 'uri': # The instance's URL + 'version': # The instance's Mastodon version + 'urls': # Additional URLs dict, presently only 'streaming_api' with the + # stream websocket address. + 'stats': # A dictionary 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). + 'contact_account': # User dict of the primary contact for the instance + 'languages': # Array of ISO 639-1 (two-letter) language codes the instance + # has chosen to advertise. + 'registrations': # Boolean indication whether registrations on this instance are open + # (True) or not (False) + 'approval_required': # True if account approval is required when registering, + 'rules': # List of dicts with `id` and `text` fields, one for each server rule set by the admin + } + +Activity dicts +-------------- +.. _activity dict: + +.. code-block:: python + + mastodon.instance_activity()[0] + # Returns the following dictionary + { + 'week': # Date of the first day of the week the stats were collected for + 'logins': # Number of users that logged in that week + 'registrations': # Number of new users that week + 'statuses': # Number of statuses posted that week + } + +Report dicts +------------ +.. _report dict: + +.. code-block:: python + + mastodon.admin_reports()[0] + # Returns the following dictionary + { + 'id': # Numerical id of the report + 'action_taken': # True if a moderator or admin has processed the + # report, False otherwise. + + # The following fields are only present in the report dicts returned by moderation API: + 'comment': # Text comment submitted with the report + 'created_at': # Time at which this report was created, as a datetime object + 'updated_at': # Last time this report has been updated, as a datetime object + 'account': # User dict of the user that filed this report + 'target_account': # Account that has been reported with this report + 'assigned_account': # If the report as been assigned to an account, + # User dict of that account (None if not) + 'action_taken_by_account': # User dict of the account that processed this report + 'statuses': # List of statuses attached to the report, as toot dicts + } + +Push subscription dicts +----------------------- +.. _push subscription dict: + +.. code-block:: python + + mastodon.push_subscription() + # Returns the following dictionary + { + 'id': # Numerical id of the push subscription + 'endpoint': # Endpoint URL for the subscription + 'server_key': # Server pubkey used for signature verification + 'alerts': # Subscribed events - dict that may contain keys 'follow', + # 'favourite', 'reblog' and 'mention', with value True + # if webpushes have been requested for those events. + } + +Push notification dicts +----------------------- +.. _push notification dict: + +.. code-block:: python + + mastodon.push_subscription_decrypt_push(...) + # Returns the following dictionary + { + 'access_token': # Access token that can be used to access the API as the + # notified user + 'body': # Text body of the notification + 'icon': # URL to an icon for the notification + 'notification_id': # ID that can be passed to notification() to get the full + # notification object, + 'notification_type': # 'mention', 'reblog', 'follow' or 'favourite' + 'preferred_locale': # The user's preferred locale + 'title': # Title for the notification + } + +Preference dicts +---------------- +.. _preference dict: + +.. code-block:: python + + mastodon.preferences() + # Returns the following dictionary + { + 'posting:default:visibility': # The default visibility setting for the user's posts, + # as a string + 'posting:default:sensitive': # Boolean indicating whether the user's uploads should + # be marked sensitive by default + 'posting:default:language': # The user's default post language, if set (None if not) + 'reading:expand:media': # How the user wishes to be shown sensitive media. Can be + # 'default' (hide if sensitive), 'hide_all' or 'show_all' + 'reading:expand:spoilers': # Boolean indicating whether the user wishes to expand + # content warnings by default + } + +Featured tag dicts +------------------ +.. _featured tag dict: + +.. code-block:: python + + mastodon.featured_tags()[0] + # Returns the following dictionary: + { + 'id': # The featured tags id + 'name': # The featured tags name (without leading #) + 'statuses_count': # Number of publicly visible statuses posted with this hashtag that this instance knows about + 'last_status_at': # The last time a public status containing this hashtag was added to this instance's database + # (can be None if there are none) + } + +Read marker dicts +----------------- +.. _read marker dict: + +.. code-block:: python + + mastodon.markers_get()["home"] + # Returns the following dictionary: + { + 'last_read_id': # ID of the last read object in the timeline + 'version': # A counter that is incremented whenever the marker is set to a new status + 'updated_at': # The time the marker was last set, as a datetime object + } + +Announcement dicts +------------------ +.. _announcement dict: + +.. code-block:: python + + mastodon.annoucements()[0] + # Returns the following dictionary: + { + 'id': # The annoucements id + 'content': # The contents of the annoucement, as an html string + 'starts_at': # The annoucements start time, as a datetime object. Can be None + 'ends_at': # The annoucements end time, as a datetime object. Can be None + 'all_day': # Boolean indicating whether the annoucement represents an "all day" event + 'published_at': # The annoucements publish time, as a datetime object + 'updated_at': # The annoucements last updated time, as a datetime object + 'read': # A boolean indicating whether the logged in user has dismissed the annoucement + 'mentions': # Users mentioned in the annoucement, as a list of mention dicts + 'tags': # Hashtags mentioned in the announcement, as a list of hashtag dicts + 'emojis': # Custom emoji used in the annoucement, as a list of emoji dicts + 'reactions': # Reactions to the annoucement, as a list of reaction dicts (documented inline here): + [ { + 'name': # Name of the custom emoji or unicode emoji of the reaction + 'count': # Reaction counter (i.e. number of users who have added this reaction) + 'me': # True if the logged-in user has reacted with this emoji, false otherwise + 'url': # URL for the custom emoji image + 'static_url': # URL for a never-animated version of the custom emoji image + } ], + } + +Familiar follower dicts +----------------------- +.. _familiar follower dict: + +.. code-block:: python + + mastodon.account_familiar_followers(1)[0] + # Returns the following dictionary: + { + + } + +Admin account dicts +------------------- +.. _admin account dict: + +.. code-block:: python + + mastodon.admin_account(id) + # Returns the following dictionary + { + 'id': # The users id, + 'username': # The users username, no leading @ + 'domain': # The users domain + 'created_at': # The time of account creation + 'email': # For local users, the user's email + 'ip': # For local users, the user's last known IP address + 'role': # 'admin', 'moderator' or None + 'confirmed': # For local users, False if the user has not confirmed their email, True otherwise + 'suspended': # Boolean indicating whether the user has been suspended + 'silenced': # Boolean indicating whether the user has been suspended + 'disabled': # For local users, boolean indicating whether the user has had their login disabled + 'approved': # For local users, False if the user is pending, True otherwise + 'locale': # For local users, the locale the user has set, + 'invite_request': # If the user requested an invite, the invite request comment of that user. (TODO permanent?) + 'invited_by_account_id': # Present if the user was invited by another user and set to the inviting users id. + 'account': # The user's account, as a standard user dict + } + +Admin domain block dicts +------------------------ +.. _admin domain block dict: + +.. code-block::python + + mastodon.domain_blocks(id=1) + #Returns the following dictionary: + { + 'id': #Str. The database id of a domain block, + 'domain': #Str. The root domain of a block, ie: "example.com", + 'created_at': #Datetime of the block creation. + 'severity': #Str. Severity of the domain block, ie: "suspend". + 'reject_media': #Boolean. True if media is not downloaded from this domain. + 'reject_reports': #Boolean. True if reports are automatically ignored from this domain. + 'private_comment': #Str. Private admin comment for a block. None if not set. + 'public_comment': #Str. Publicly viewable (depending on settings) comment about this domain. None if not set. + 'obfuscate': #Boolean. True if domain name is obfuscated when listing. + } + +Admin measure dicts +------------------- +.. _admin measure dict: + +.. code-block:: python + + api.admin_measures(datetime.now() - timedelta(hours=24*5), datetime.now(), active_users=True) + # Returns the following dictionary + { + TODO + } + +Admin dimension dicts +--------------------- +.. _admin dimension dict: + +.. code-block:: python + + api.admin_dimensions(datetime.now() - timedelta(hours=24*5), datetime.now(), languages=True) + # Returns the following dictionary + { + TODO + } + +Admin retention dicts +--------------------- +.. _admin retention dict: + +.. code-block:: python + + api.admin_retention(datetime.now() - timedelta(hours=24*5), datetime.now()) + # Returns the following dictionary + { + TODO + } diff --git a/docs/03_errors.rst b/docs/03_errors.rst new file mode 100644 index 0000000..fce7af7 --- /dev/null +++ b/docs/03_errors.rst @@ -0,0 +1,36 @@ +Error handling +============== +When Mastodon.py encounters an error, it will raise an exception, generally with +some text included to tell you what went wrong. + +The base class that all Mastodon exceptions inherit from is `MastodonError`. +If you are only interested in the fact an error was raised somewhere in +Mastodon.py, and not the details, this is the exception you can catch. + +`MastodonIllegalArgumentError` is generally a programming problem - you asked the +API to do something obviously invalid (i.e. specify a privacy option that does +not exist). + +`MastodonFileNotFoundError` and `MastodonNetworkError` are IO errors - could be you +specified a wrong URL, could be the internet is down or your hard drive is +dying. They inherit from `MastodonIOError`, for easy catching. There is a sub-error +of `MastodonNetworkError`, `MastodonReadTimeout`, which is thrown when a streaming +API stream times out during reading. + +`MastodonAPIError` is an error returned from the Mastodon instance - the server +has decided it can't fulfil your request (i.e. you requested info on a user that +does not exist). It is further split into `MastodonNotFoundError` (API returned 404) +and `MastodonUnauthorizedError` (API returned 401). Different error codes might exist, +but are not currently handled separately. + +`MastodonMalformedEventError` is raised when a streaming API listener receives an +invalid event. There have been reports that this can sometimes happen after prolonged +operation due to an upstream problem in the requests/urllib libraries. + +`MastodonRatelimitError` is raised when you hit an API rate limit. You should try +again after a while (see the rate limiting section above). + +`MastodonServerError` is raised when the server throws an internal error, likely due +to server misconfiguration. + +`MastodonVersionError` is raised when a version check for an API call fails. diff --git a/docs/04_auth.rst b/docs/04_auth.rst new file mode 100644 index 0000000..454d6a2 --- /dev/null +++ b/docs/04_auth.rst @@ -0,0 +1,36 @@ +App registration and user authentication +======================================== + +Before you can use the Mastodon API, you have to register your +application (which gets you a client key and client secret) +and then log in (which gets you an access token) and out (revoking +the access token you are logged in with). These functions +allow you to do those things. Additionally, it is also possible +to programmatically register a new user. + +For convenience, once you have a client id, secret and access token, +you can simply pass them to the constructor of the class, too! + +Note that while it is perfectly reasonable to log back in whenever +your app starts, registering a new application on every +startup is not, so don't do that - instead, register an application +once, and then persist your client id and secret. A convenient method +for this is provided by the functions dealing with registering the app, +logging in and the Mastodon classes constructor. + +To talk to an instance different from the flagship instance, specify +the api_base_url (usually, just the URL of the instance, i.e. +https://mastodon.social/ for the flagship instance). If no protocol +is specified, Mastodon.py defaults to https. + +.. automethod:: Mastodon.create_app +.. automethod:: Mastodon.__init__ +.. _log_in(): +.. automethod:: Mastodon.log_in +.. _auth_request_url(): +.. automethod:: Mastodon.auth_request_url +.. _set_language(): +.. automethod:: Mastodon.set_language +.. automethod:: Mastodon.revoke_access_token +.. automethod:: Mastodon.create_account +.. automethod:: Mastodon.email_resend_confirmation diff --git a/docs/index.rst b/docs/index.rst index 7597bc4..69a7b3d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -58,6 +58,13 @@ about who helped with which particular feature or fix in the changelog. .. _Official Mastodon API docs: https://docs.joinmastodon.org/client/intro/ .. toctree:: + :caption: Introduction + Mastodon.py + 01_general + 02_return_values + 03_errors - Mastodon.py - 01_general +.. toctree:: + :caption: API methods + Mastodon.py + 04_auth -- cgit v1.2.3