aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorhalcy <halcy@ARARAGI-KUN>2022-11-28 01:31:04 +0200
committerhalcy <halcy@ARARAGI-KUN>2022-11-28 01:31:04 +0200
commitc49364fcc4981eee500dcde34f2e494fdd15ff96 (patch)
tree18debe40c3bd42044f5f98a8bbab28be1e6aa60b
parent13d6ff69e97452a014e40f8d511bbee6b39a392e (diff)
downloadmastodon.py-c49364fcc4981eee500dcde34f2e494fdd15ff96.tar.gz
Some more doc split tests
Diffstat
-rw-r--r--docs/01_general.rst31
-rw-r--r--docs/02_return_values.rst743
-rw-r--r--docs/03_errors.rst36
-rw-r--r--docs/04_auth.rst36
-rw-r--r--docs/index.rst11
5 files changed, 855 insertions, 2 deletions
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 @@
1General information
2===================
3
1Rate limiting 4Rate limiting
2------------- 5-------------
3Mastodon's API rate limits per user account. By default, the limit is 300 requests 6Mastodon's API rate limits per user account. By default, the limit is 300 requests
@@ -117,6 +120,34 @@ you can also just write
117 120
118and everything will work as intended. 121and everything will work as intended.
119 122
123Versioning
124----------
125Mastodon.py will check if a certain endpoint is available before doing API
126calls. By default, it checks against the version of Mastodon retrieved on
127init(), or the version you specified. Mastodon.py can be set (in the
128constructor) to either check if an endpoint is available at all (this is the
129default) or to check if the endpoint is available and behaves as in the newest
130Mastodon version (with regards to parameters as well as return values).
131Version checking can also be disabled altogether. If a version check fails,
132Mastodon.py throws a `MastodonVersionError`.
133
134Some functions need to check what version of Mastodon they are talking to.
135These will generally use a cached version to avoid sending a lot of pointless
136requests.
137
138Many non-mainline forks have various different formats for their versions and
139they have different, incompatible ideas about how to report version. Mastodon.py
140tries its best to figure out what is going on, but success is not guaranteed.
141
142With the following functions, you can make Mastodon.py re-check the server
143version or explicitly determine if a specific minimum Version is available.
144Long-running applications that aim to support multiple Mastodon versions
145should do this from time to time in case a server they are running against
146updated.
147
148.. automethod:: Mastodon.retrieve_mastodon_version
149.. automethod:: Mastodon.verify_minimum_version
150
120A brief note on block lists 151A brief note on block lists
121--------------------------- 152---------------------------
122Mastodon.py used to block three instances because these were particularly notorious for 153Mastodon.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 @@
1Return values
2=============
3
4Unless otherwise specified, all data is returned as Python dictionaries, matching
5the JSON format used by the API. Dates returned by the API are in ISO 8601 format
6and are parsed into Python datetime objects.
7
8To make access easier, the dictionaries returned are wrapped by a class that adds
9read-only attributes for all dict values - this means that, for example, instead of
10writing
11
12.. code-block:: python
13
14 description = mastodon.account_verify_credentials()["source"]["note"]
15
16you can also just write
17
18.. code-block:: python
19
20 description = mastodon.account_verify_credentials().source.note
21
22and everything will work as intended. The class used for this is exposed as
23`AttribAccessDict`.
24
25User / account dicts
26--------------------
27.. _user dict:
28.. _user dicts:
29.. _account dict:
30.. _account dicts:
31
32.. code-block:: python
33
34 mastodon.account(<numerical id>)
35 # Returns the following dictionary:
36 {
37 'id': # Same as <numerical id>
38 'username': # The username (what you @ them with)
39 'acct': # The user's account name as username@domain (@domain omitted for local users)
40 'display_name': # The user's display name
41 'discoverable': # True if the user is listed in the user directory, false if not. None
42 # for remote users.
43 'group': # A boolean indicating whether the account represents a group rather than an
44 # individual.
45 'locked': # Denotes whether the account can be followed without a follow request
46 'created_at': # Account creation time
47 'following_count': # How many people they follow
48 'followers_count': # How many followers they have
49 'statuses_count': # How many statuses they have
50 'note': # Their bio
51 'url': # Their URL; for example 'https://mastodon.social/users/<acct>'
52 'avatar': # URL for their avatar, can be animated
53 'header': # URL for their header image, can be animated
54 'avatar_static': # URL for their avatar, never animated
55 'header_static': # URL for their header image, never animated
56 'source': # Additional information - only present for user dict returned
57 # from account_verify_credentials()
58 'moved_to_account': # If set, a user dict of the account this user has
59 # set up as their moved-to address.
60 'bot': # Boolean indicating whether this account is automated.
61 'fields': # List of up to four dicts with free-form 'name' and 'value' profile info.
62 # For fields with "this is me" type verification, verified_at is set to the
63 # last verification date (It is None otherwise)
64 'emojis': # List of custom emoji used in name, bio or fields
65 'discoverable': # Indicates whether or not a user is visible on the discovery page
66 }
67
68 mastodon.account_verify_credentials()["source"]
69 # Returns the following dictionary:
70 {
71 'privacy': # The user's default visibility setting ("private", "unlisted" or "public")
72 'sensitive': # Denotes whether user media should be marked sensitive by default
73 'note': # Plain text version of the user's bio
74 }
75
76Toot / Status dicts
77----------
78.. _toot dict:
79.. _toot dicts:
80.. _status dict:
81.. _status dicts:
82
83.. code-block:: python
84
85 mastodon.toot("Hello from Python")
86 # Returns the following dictionary:
87 {
88 'id': # Numerical id of this toot
89 'uri': # Descriptor for the toot
90 # EG 'tag:mastodon.social,2016-11-25:objectId=<id>:objectType=Status'
91 'url': # URL of the toot
92 'account': # User dict for the account which posted the status
93 'in_reply_to_id': # Numerical id of the toot this toot is in response to
94 'in_reply_to_account_id': # Numerical id of the account this toot is in response to
95 'reblog': # Denotes whether the toot is a reblog. If so, set to the original toot dict.
96 'content': # Content of the toot, as HTML: '<p>Hello from Python</p>'
97 'created_at': # Creation time
98 'reblogs_count': # Number of reblogs
99 'favourites_count': # Number of favourites
100 'reblogged': # Denotes whether the logged in user has boosted this toot
101 'favourited': # Denotes whether the logged in user has favourited this toot
102 'sensitive': # Denotes whether media attachments to the toot are marked sensitive
103 'spoiler_text': # Warning text that should be displayed before the toot content
104 'visibility': # Toot visibility ('public', 'unlisted', 'private', or 'direct')
105 'mentions': # A list of users dicts mentioned in the toot, as Mention dicts
106 'media_attachments': # A list of media dicts of attached files
107 'emojis': # A list of custom emojis used in the toot, as Emoji dicts
108 'tags': # A list of hashtag used in the toot, as Hashtag dicts
109 'bookmarked': # True if the status is bookmarked by the logged in user, False if not.
110 'application': # Application dict for the client used to post the toot (Does not federate
111 # and is therefore always None for remote toots, can also be None for
112 # local toots for some legacy applications).
113 'language': # The language of the toot, if specified by the server,
114 # as ISO 639-1 (two-letter) language code.
115 'muted': # Boolean denoting whether the user has muted this status by
116 # way of conversation muting
117 'pinned': # Boolean denoting whether or not the status is currently pinned for the
118 # associated account.
119 'replies_count': # The number of replies to this status.
120 'card': # A preview card for links from the status, if present at time of delivery,
121 # as card dict.
122 'poll': # A poll dict if a poll is attached to this status.
123 }
124
125Status edit dicts
126-----------------
127.. _status edit dict:
128
129.. code-block:: python
130
131 mastodonstatus_history(id)[0]
132 # Returns the following dictionary
133 {
134 TODO
135 }
136
137Mention dicts
138-------------
139.. _mention dict:
140
141.. code-block:: python
142
143 {
144 'url': # Mentioned user's profile URL (potentially remote)
145 'username': # Mentioned user's user name (not including domain)
146 'acct': # Mentioned user's account name (including domain)
147 'id': # Mentioned user's (local) account ID
148 }
149
150Scheduled status / toot dicts
151-----------------------------
152.. _scheduled status dict:
153.. _scheduled status dicts:
154.. _scheduled toot dict:
155.. _scheduled toot dicts:
156
157.. code-block:: python
158
159 mastodon.status_post("text", scheduled_at=the_future)
160 # Returns the following dictionary:
161 {
162 'id': # Scheduled toot ID (note: Not the id of the toot once it gets posted!)
163 'scheduled_at': # datetime object describing when the toot is to be posted
164 'params': # Parameters for the scheduled toot, specifically
165 {
166 'text': # Toot text
167 'in_reply_to_id': # ID of the toot this one is a reply to
168 'media_ids': # IDs of media attached to this toot
169 'sensitive': # Whether this toot is sensitive or not
170 'visibility': # Visibility of the toot
171 'idempotency': # Idempotency key for the scheduled toot
172 'scheduled_at': # Present, but generally "None"
173 'spoiler_text': # CW text for this toot
174 'application_id': # ID of the application that scheduled the toot
175 'poll': # Poll parameters, as a poll dict
176 },
177 'media_attachments': # Array of media dicts for the attachments to the scheduled toot
178 }
179
180Poll dicts
181----------
182.. _poll dict:
183
184.. code-block:: python
185
186 # Returns the following dictionary:
187 mastodon.poll(id)
188 {
189 'id': # The polls ID
190 'expires_at': # The time at which the poll is set to expire
191 'expired': # Boolean denoting whether you can still vote in this poll
192 'multiple': # Boolean indicating whether it is allowed to vote for more than one option
193 'votes_count': # Total number of votes cast in this poll
194 'voted': # Boolean indicating whether the logged-in user has already voted in this poll
195 'options': # The poll options as a list of dicts, each option with a title and a
196 # votes_count field. votes_count can be None if the poll creator has
197 # chosen to hide vote totals until the poll expires and it hasn't yet.
198 'emojis': # List of emoji dicts for all emoji used in answer strings,
199 'own_votes': # The logged-in users votes, as a list of indices to the options.
200 }
201
202
203Conversation dicts
204------------------
205.. _conversation dict:
206
207.. code-block:: python
208
209 mastodon.conversations()[0]
210 # Returns the following dictionary:
211 {
212 'id': # The ID of this conversation object
213 'unread': # Boolean indicating whether this conversation has yet to be
214 # read by the user
215 'accounts': # List of accounts (other than the logged-in account) that
216 # are part of this conversation
217 'last_status': # The newest status in this conversation
218 }
219
220Hashtag dicts
221-------------
222.. _hashtag dict:
223
224.. code-block:: python
225
226 {
227 'name': # Hashtag name (not including the #)
228 'url': # Hashtag URL (can be remote)
229 'history': # List of usage history dicts for up to 7 days. Not present in statuses.
230 }
231
232Hashtag usage history dicts
233---------------------------
234.. _hashtag usage history dict:
235
236.. code-block:: python
237
238 {
239 'day': # Date of the day this history dict is for
240 'uses': # Number of statuses using this hashtag on that day
241 'accounts': # Number of accounts using this hashtag in at least one status on that day
242 }
243
244Emoji dicts
245-----------
246.. _emoji dict:
247
248.. code-block:: python
249
250 {
251 'shortcode': # Emoji shortcode, without surrounding colons
252 'url': # URL for the emoji image, can be animated
253 'static_url': # URL for the emoji image, never animated
254 'visible_in_picker': # True if the emoji is enabled, False if not.
255 'category': # The category to display the emoji under (not present if none is set)
256 }
257
258Application dicts
259-----------------
260 .. _application dict:
261
262.. code-block:: python
263
264 {
265 'name': # The applications name
266 'website': # The applications website
267 'vapid_key': # A vapid key that can be used in web applications
268 }
269
270
271Relationship dicts
272------------------
273.. _relationship dict:
274
275.. code-block:: python
276
277 mastodon.account_follow(<numerical id>)
278 # Returns the following dictionary:
279 {
280 'id': # Numerical id (same one as <numerical id>)
281 'following': # Boolean denoting whether the logged-in user follows the specified user
282 'followed_by': # Boolean denoting whether the specified user follows the logged-in user
283 'blocking': # Boolean denoting whether the logged-in user has blocked the specified user
284 'blocked_by': # Boolean denoting whether the logged-in user has been blocked by the specified user, if information is available
285 'muting': # Boolean denoting whether the logged-in user has muted the specified user
286 'muting_notifications': # Boolean denoting wheter the logged-in user has muted notifications
287 # related to the specified user
288 'requested': # Boolean denoting whether the logged-in user has sent the specified
289 # user a follow request
290 'domain_blocking': # Boolean denoting whether the logged-in user has blocked the
291 # specified users domain
292 'showing_reblogs': # Boolean denoting whether the specified users reblogs show up on the
293 # logged-in users Timeline
294 'endorsed': # Boolean denoting wheter the specified user is being endorsed / featured by the
295 # logged-in user
296 'note': # A free text note the logged in user has created for this account (not publicly visible)
297 'notifying' # Boolean denoting whether the logged-in user has requested to get notified every time the followed user posts
298 }
299
300Filter dicts
301------------
302.. _filter dict:
303
304.. code-block:: python
305
306 mastodon.filter(<numerical id>)
307 # Returns the following dictionary:
308 {
309 'id': # Numerical id of the filter
310 'phrase': # Filtered keyword or phrase
311 'context': # List of places where the filters are applied ('home', 'notifications', 'public', 'thread')
312 'expires_at': # Expiry date for the filter
313 'irreversible': # Boolean denoting if this filter is executed server-side
314 # or if it should be ran client-side.
315 'whole_word': # Boolean denoting whether this filter can match partial words
316 }
317
318Notification dicts
319------------------
320.. _notification dict:
321
322.. code-block:: python
323
324 mastodon.notifications()[0]
325 # Returns the following dictionary:
326 {
327 'id': # id of the notification
328 'type': # "mention", "reblog", "favourite", "follow", "poll" or "follow_request"
329 'created_at': # The time the notification was created
330 'account': # User dict of the user from whom the notification originates
331 'status': # In case of "mention", the mentioning status
332 # In case of reblog / favourite, the reblogged / favourited status
333 }
334
335Context dicts
336-------------
337.. _context dict:
338
339.. code-block:: python
340
341 mastodon.status_context(<numerical id>)
342 # Returns the following dictionary:
343 {
344 'ancestors': # A list of toot dicts
345 'descendants': # A list of toot dicts
346 }
347
348List dicts
349----------
350.. _list dict:
351
352.. code-block:: python
353
354 mastodon.list(<numerical id>)
355 # Returns the following dictionary:
356 {
357 'id': # id of the list
358 'title': # title of the list
359 }
360
361Media dicts
362-----------
363.. _media dict:
364
365.. code-block:: python
366
367 mastodon.media_post("image.jpg", "image/jpeg")
368 # Returns the following dictionary:
369 {
370 'id': # The ID of the attachment.
371 'type': # Media type: 'image', 'video', 'gifv', 'audio' or 'unknown'.
372 'url': # The URL for the image in the local cache
373 'remote_url': # The remote URL for the media (if the image is from a remote instance)
374 'preview_url': # The URL for the media preview
375 'text_url': # The display text for the media (what shows up in toots)
376 'meta': # Dictionary of two metadata dicts (see below),
377 # 'original' and 'small' (preview). Either may be empty.
378 # May additionally contain an "fps" field giving a videos frames per second (possibly
379 # rounded), and a "length" field giving a videos length in a human-readable format.
380 # Note that a video may have an image as preview.
381 # May also contain a 'focus' dict and a media 'colors' dict.
382 'blurhash': # The blurhash for the image, used for preview / placeholder generation
383 'description': # If set, the user-provided description for this media.
384 }
385
386 # Metadata dicts (image) - all fields are optional:
387 {
388 'width': # Width of the image in pixels
389 'height': # Height of the image in pixels
390 'aspect': # Aspect ratio of the image as a floating point number
391 'size': # Textual representation of the image size in pixels, e.g. '800x600'
392 }
393
394 # Metadata dicts (video, gifv) - all fields are optional:
395 {
396 'width': # Width of the video in pixels
397 'heigh': # Height of the video in pixels
398 'frame_rate': # Exact frame rate of the video in frames per second.
399 # Can be an integer fraction (i.e. "20/7")
400 'duration': # Duration of the video in seconds
401 'bitrate': # Average bit-rate of the video in bytes per second
402 }
403
404 # Metadata dicts (audio) - all fields are optional:
405 {
406 'duration': # Duration of the audio file in seconds
407 'bitrate': # Average bit-rate of the audio file in bytes per second
408 }
409
410 # Focus Metadata dict:
411 {
412 'x': # Focus point x coordinate (between -1 and 1)
413 'y': # Focus point x coordinate (between -1 and 1)
414 }
415
416 # Media colors dict:
417 {
418 'foreground': # Estimated foreground colour for the attachment thumbnail
419 'background': # Estimated background colour for the attachment thumbnail
420 'accent': # Estimated accent colour for the attachment thumbnail
421
422Card dicts
423----------
424.. _card dict:
425
426.. code-block:: python
427
428 mastodon.status_card(<numerical id>):
429 # Returns the following dictionary
430 {
431 'url': # The URL of the card.
432 'title': # The title of the card.
433 'description': # The description of the card.
434 'type': # Embed type: 'link', 'photo', 'video', or 'rich'
435 'image': # (optional) The image associated with the card.
436
437 # OEmbed data (all optional):
438 'author_name': # Name of the embedded contents author
439 'author_url': # URL pointing to the embedded contents author
440 'description': # Description of the embedded content
441 'width': # Width of the embedded object
442 'height': # Height of the embedded object
443 'html': # HTML string of the embed
444 'provider_name': # Name of the provider from which the embed originates
445 'provider_url': # URL pointing to the embeds provider
446 'blurhash': # (optional) Blurhash of the preview image
447 }
448
449Search result dicts
450-------------------
451.. _search result dict:
452
453.. code-block:: python
454
455 mastodon.search("<query>")
456 # Returns the following dictionary
457 {
458 'accounts': # List of user dicts resulting from the query
459 'hashtags': # List of hashtag dicts resulting from the query
460 'statuses': # List of toot dicts resulting from the query
461 }
462
463Instance dicts
464--------------
465.. _instance dict:
466
467.. code-block:: python
468
469 mastodon.instance()
470 # Returns the following dictionary
471 {
472 'domain': # The instances domain name
473 'description': # A brief instance description set by the admin
474 'short_description': # An even briefer instance description
475 'email': # The admin contact email
476 'title': # The instance's title
477 'uri': # The instance's URL
478 'version': # The instance's Mastodon version
479 'urls': # Additional URLs dict, presently only 'streaming_api' with the
480 # stream websocket address.
481 'stats': # A dictionary containing three stats, user_count (number of local users),
482 # status_count (number of local statuses) and domain_count (number of known
483 # instance domains other than this one).
484 'contact_account': # User dict of the primary contact for the instance
485 'languages': # Array of ISO 639-1 (two-letter) language codes the instance
486 # has chosen to advertise.
487 'registrations': # Boolean indication whether registrations on this instance are open
488 # (True) or not (False)
489 'approval_required': # True if account approval is required when registering,
490 'rules': # List of dicts with `id` and `text` fields, one for each server rule set by the admin
491 }
492
493Activity dicts
494--------------
495.. _activity dict:
496
497.. code-block:: python
498
499 mastodon.instance_activity()[0]
500 # Returns the following dictionary
501 {
502 'week': # Date of the first day of the week the stats were collected for
503 'logins': # Number of users that logged in that week
504 'registrations': # Number of new users that week
505 'statuses': # Number of statuses posted that week
506 }
507
508Report dicts
509------------
510.. _report dict:
511
512.. code-block:: python
513
514 mastodon.admin_reports()[0]
515 # Returns the following dictionary
516 {
517 'id': # Numerical id of the report
518 'action_taken': # True if a moderator or admin has processed the
519 # report, False otherwise.
520
521 # The following fields are only present in the report dicts returned by moderation API:
522 'comment': # Text comment submitted with the report
523 'created_at': # Time at which this report was created, as a datetime object
524 'updated_at': # Last time this report has been updated, as a datetime object
525 'account': # User dict of the user that filed this report
526 'target_account': # Account that has been reported with this report
527 'assigned_account': # If the report as been assigned to an account,
528 # User dict of that account (None if not)
529 'action_taken_by_account': # User dict of the account that processed this report
530 'statuses': # List of statuses attached to the report, as toot dicts
531 }
532
533Push subscription dicts
534-----------------------
535.. _push subscription dict:
536
537.. code-block:: python
538
539 mastodon.push_subscription()
540 # Returns the following dictionary
541 {
542 'id': # Numerical id of the push subscription
543 'endpoint': # Endpoint URL for the subscription
544 'server_key': # Server pubkey used for signature verification
545 'alerts': # Subscribed events - dict that may contain keys 'follow',
546 # 'favourite', 'reblog' and 'mention', with value True
547 # if webpushes have been requested for those events.
548 }
549
550Push notification dicts
551-----------------------
552.. _push notification dict:
553
554.. code-block:: python
555
556 mastodon.push_subscription_decrypt_push(...)
557 # Returns the following dictionary
558 {
559 'access_token': # Access token that can be used to access the API as the
560 # notified user
561 'body': # Text body of the notification
562 'icon': # URL to an icon for the notification
563 'notification_id': # ID that can be passed to notification() to get the full
564 # notification object,
565 'notification_type': # 'mention', 'reblog', 'follow' or 'favourite'
566 'preferred_locale': # The user's preferred locale
567 'title': # Title for the notification
568 }
569
570Preference dicts
571----------------
572.. _preference dict:
573
574.. code-block:: python
575
576 mastodon.preferences()
577 # Returns the following dictionary
578 {
579 'posting:default:visibility': # The default visibility setting for the user's posts,
580 # as a string
581 'posting:default:sensitive': # Boolean indicating whether the user's uploads should
582 # be marked sensitive by default
583 'posting:default:language': # The user's default post language, if set (None if not)
584 'reading:expand:media': # How the user wishes to be shown sensitive media. Can be
585 # 'default' (hide if sensitive), 'hide_all' or 'show_all'
586 'reading:expand:spoilers': # Boolean indicating whether the user wishes to expand
587 # content warnings by default
588 }
589
590Featured tag dicts
591------------------
592.. _featured tag dict:
593
594.. code-block:: python
595
596 mastodon.featured_tags()[0]
597 # Returns the following dictionary:
598 {
599 'id': # The featured tags id
600 'name': # The featured tags name (without leading #)
601 'statuses_count': # Number of publicly visible statuses posted with this hashtag that this instance knows about
602 'last_status_at': # The last time a public status containing this hashtag was added to this instance's database
603 # (can be None if there are none)
604 }
605
606Read marker dicts
607-----------------
608.. _read marker dict:
609
610.. code-block:: python
611
612 mastodon.markers_get()["home"]
613 # Returns the following dictionary:
614 {
615 'last_read_id': # ID of the last read object in the timeline
616 'version': # A counter that is incremented whenever the marker is set to a new status
617 'updated_at': # The time the marker was last set, as a datetime object
618 }
619
620Announcement dicts
621------------------
622.. _announcement dict:
623
624.. code-block:: python
625
626 mastodon.annoucements()[0]
627 # Returns the following dictionary:
628 {
629 'id': # The annoucements id
630 'content': # The contents of the annoucement, as an html string
631 'starts_at': # The annoucements start time, as a datetime object. Can be None
632 'ends_at': # The annoucements end time, as a datetime object. Can be None
633 'all_day': # Boolean indicating whether the annoucement represents an "all day" event
634 'published_at': # The annoucements publish time, as a datetime object
635 'updated_at': # The annoucements last updated time, as a datetime object
636 'read': # A boolean indicating whether the logged in user has dismissed the annoucement
637 'mentions': # Users mentioned in the annoucement, as a list of mention dicts
638 'tags': # Hashtags mentioned in the announcement, as a list of hashtag dicts
639 'emojis': # Custom emoji used in the annoucement, as a list of emoji dicts
640 'reactions': # Reactions to the annoucement, as a list of reaction dicts (documented inline here):
641 [ {
642 'name': # Name of the custom emoji or unicode emoji of the reaction
643 'count': # Reaction counter (i.e. number of users who have added this reaction)
644 'me': # True if the logged-in user has reacted with this emoji, false otherwise
645 'url': # URL for the custom emoji image
646 'static_url': # URL for a never-animated version of the custom emoji image
647 } ],
648 }
649
650Familiar follower dicts
651-----------------------
652.. _familiar follower dict:
653
654.. code-block:: python
655
656 mastodon.account_familiar_followers(1)[0]
657 # Returns the following dictionary:
658 {
659
660 }
661
662Admin account dicts
663-------------------
664.. _admin account dict:
665
666.. code-block:: python
667
668 mastodon.admin_account(id)
669 # Returns the following dictionary
670 {
671 'id': # The users id,
672 'username': # The users username, no leading @
673 'domain': # The users domain
674 'created_at': # The time of account creation
675 'email': # For local users, the user's email
676 'ip': # For local users, the user's last known IP address
677 'role': # 'admin', 'moderator' or None
678 'confirmed': # For local users, False if the user has not confirmed their email, True otherwise
679 'suspended': # Boolean indicating whether the user has been suspended
680 'silenced': # Boolean indicating whether the user has been suspended
681 'disabled': # For local users, boolean indicating whether the user has had their login disabled
682 'approved': # For local users, False if the user is pending, True otherwise
683 'locale': # For local users, the locale the user has set,
684 'invite_request': # If the user requested an invite, the invite request comment of that user. (TODO permanent?)
685 'invited_by_account_id': # Present if the user was invited by another user and set to the inviting users id.
686 'account': # The user's account, as a standard user dict
687 }
688
689Admin domain block dicts
690------------------------
691.. _admin domain block dict:
692
693.. code-block::python
694
695 mastodon.domain_blocks(id=1)
696 #Returns the following dictionary:
697 {
698 'id': #Str. The database id of a domain block,
699 'domain': #Str. The root domain of a block, ie: "example.com",
700 'created_at': #Datetime of the block creation.
701 'severity': #Str. Severity of the domain block, ie: "suspend".
702 'reject_media': #Boolean. True if media is not downloaded from this domain.
703 'reject_reports': #Boolean. True if reports are automatically ignored from this domain.
704 'private_comment': #Str. Private admin comment for a block. None if not set.
705 'public_comment': #Str. Publicly viewable (depending on settings) comment about this domain. None if not set.
706 'obfuscate': #Boolean. True if domain name is obfuscated when listing.
707 }
708
709Admin measure dicts
710-------------------
711.. _admin measure dict:
712
713.. code-block:: python
714
715 api.admin_measures(datetime.now() - timedelta(hours=24*5), datetime.now(), active_users=True)
716 # Returns the following dictionary
717 {
718 TODO
719 }
720
721Admin dimension dicts
722---------------------
723.. _admin dimension dict:
724
725.. code-block:: python
726
727 api.admin_dimensions(datetime.now() - timedelta(hours=24*5), datetime.now(), languages=True)
728 # Returns the following dictionary
729 {
730 TODO
731 }
732
733Admin retention dicts
734---------------------
735.. _admin retention dict:
736
737.. code-block:: python
738
739 api.admin_retention(datetime.now() - timedelta(hours=24*5), datetime.now())
740 # Returns the following dictionary
741 {
742 TODO
743 }
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 @@
1Error handling
2==============
3When Mastodon.py encounters an error, it will raise an exception, generally with
4some text included to tell you what went wrong.
5
6The base class that all Mastodon exceptions inherit from is `MastodonError`.
7If you are only interested in the fact an error was raised somewhere in
8Mastodon.py, and not the details, this is the exception you can catch.
9
10`MastodonIllegalArgumentError` is generally a programming problem - you asked the
11API to do something obviously invalid (i.e. specify a privacy option that does
12not exist).
13
14`MastodonFileNotFoundError` and `MastodonNetworkError` are IO errors - could be you
15specified a wrong URL, could be the internet is down or your hard drive is
16dying. They inherit from `MastodonIOError`, for easy catching. There is a sub-error
17of `MastodonNetworkError`, `MastodonReadTimeout`, which is thrown when a streaming
18API stream times out during reading.
19
20`MastodonAPIError` is an error returned from the Mastodon instance - the server
21has decided it can't fulfil your request (i.e. you requested info on a user that
22does not exist). It is further split into `MastodonNotFoundError` (API returned 404)
23and `MastodonUnauthorizedError` (API returned 401). Different error codes might exist,
24but are not currently handled separately.
25
26`MastodonMalformedEventError` is raised when a streaming API listener receives an
27invalid event. There have been reports that this can sometimes happen after prolonged
28operation due to an upstream problem in the requests/urllib libraries.
29
30`MastodonRatelimitError` is raised when you hit an API rate limit. You should try
31again after a while (see the rate limiting section above).
32
33`MastodonServerError` is raised when the server throws an internal error, likely due
34to server misconfiguration.
35
36`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 @@
1App registration and user authentication
2========================================
3
4Before you can use the Mastodon API, you have to register your
5application (which gets you a client key and client secret)
6and then log in (which gets you an access token) and out (revoking
7the access token you are logged in with). These functions
8allow you to do those things. Additionally, it is also possible
9to programmatically register a new user.
10
11For convenience, once you have a client id, secret and access token,
12you can simply pass them to the constructor of the class, too!
13
14Note that while it is perfectly reasonable to log back in whenever
15your app starts, registering a new application on every
16startup is not, so don't do that - instead, register an application
17once, and then persist your client id and secret. A convenient method
18for this is provided by the functions dealing with registering the app,
19logging in and the Mastodon classes constructor.
20
21To talk to an instance different from the flagship instance, specify
22the api_base_url (usually, just the URL of the instance, i.e.
23https://mastodon.social/ for the flagship instance). If no protocol
24is specified, Mastodon.py defaults to https.
25
26.. automethod:: Mastodon.create_app
27.. automethod:: Mastodon.__init__
28.. _log_in():
29.. automethod:: Mastodon.log_in
30.. _auth_request_url():
31.. automethod:: Mastodon.auth_request_url
32.. _set_language():
33.. automethod:: Mastodon.set_language
34.. automethod:: Mastodon.revoke_access_token
35.. automethod:: Mastodon.create_account
36.. 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.
58.. _Official Mastodon API docs: https://docs.joinmastodon.org/client/intro/ 58.. _Official Mastodon API docs: https://docs.joinmastodon.org/client/intro/
59 59
60.. toctree:: 60.. toctree::
61 :caption: Introduction
62 Mastodon.py <self>
63 01_general
64 02_return_values
65 03_errors
61 66
62 Mastodon.py <self> 67.. toctree::
63 01_general 68 :caption: API methods
69 Mastodon.py <self>
70 04_auth
Powered by cgit v1.2.3 (git 2.41.0)