aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorhalcy <halcy@ARARAGI-KUN>2022-11-28 01:17:08 +0200
committerhalcy <halcy@ARARAGI-KUN>2022-11-28 01:17:08 +0200
commit2045183deeefee83341f5b69598a89cbc458b9d9 (patch)
tree5b460820e284c07672d9a00af502a4290013090b
parentdbceccb210d401887002abf0ea3c746260423f1f (diff)
downloadmastodon.py-2045183deeefee83341f5b69598a89cbc458b9d9.tar.gz
First attempt at making docs a bit more neat
Diffstat
-rw-r--r--docs/01_general.rst130
-rw-r--r--docs/index.rst1491
2 files changed, 133 insertions, 1488 deletions
diff --git a/docs/01_general.rst b/docs/01_general.rst
new file mode 100644
index 0000000..0ea3ac4
--- /dev/null
+++ b/docs/01_general.rst
@@ -0,0 +1,130 @@
1Rate limiting
2-------------
3Mastodon's API rate limits per user account. By default, the limit is 300 requests
4per 5 minute time slot. This can differ from instance to instance and is subject to change.
5Mastodon.py has three modes for dealing with rate limiting that you can pass to
6the constructor, "throw", "wait" and "pace", "wait" being the default.
7
8In "throw" mode, Mastodon.py makes no attempt to stick to rate limits. When
9a request hits the rate limit, it simply throws a `MastodonRateLimitError`. This is
10for applications that need to handle all rate limiting themselves (i.e. interactive apps),
11or applications wanting to use Mastodon.py in a multi-threaded context ("wait" and "pace"
12modes are not thread safe).
13
14.. note::
15 Rate limit information is available on the `Mastodon` object for applications that
16 implement their own rate limit handling.
17
18 .. attribute:: Mastodon.ratelimit_remaining
19
20 Number of requests allowed until the next reset.
21
22 .. attribute:: Mastodon.ratelimit_reset
23
24 Time at which the rate limit will next be reset, as a POSIX timestamp.
25
26 .. attribute:: Mastodon.ratelimit_limit
27
28 Total number of requests allowed between resets. Typically 300.
29
30 .. attribute:: Mastodon.ratelimit_lastcall
31
32 Time at which these values have last been seen and updated, as a POSIX timestamp.
33
34In "wait" mode, once a request hits the rate limit, Mastodon.py will wait until
35the rate limit resets and then try again, until the request succeeds or an error
36is encountered. This mode is for applications that would rather just not worry about rate limits
37much, don't poll the API all that often, and are okay with a call sometimes just taking
38a while.
39
40In "pace" mode, Mastodon.py will delay each new request after the first one such that,
41if requests were to continue at the same rate, only a certain fraction (set in the
42constructor as `ratelimit_pacefactor`) of the rate limit will be used up. The fraction can
43be (and by default, is) greater than one. If the rate limit is hit, "pace" behaves like
44"wait". This mode is probably the most advanced one and allows you to just poll in
45a loop without ever sleeping at all yourself. It is for applications that would rather
46just pretend there is no such thing as a rate limit and are fine with sometimes not
47being very interactive.
48
49In addition to the per-user limit, there is a per-IP limit of 7500 requests per 5
50minute time slot, and tighter limits on logins. Mastodon.py does not make any effort
51to respect these.
52
53If your application requires many hits to endpoints that are available without logging
54in, do consider using Mastodon.py without authenticating to get the full per-IP limit.
55
56Pagination
57----------
58Many of Mastodon's API endpoints are paginated. What this means is that if you request
59data from them, you might not get all the data at once - instead, you might only get the
60first few results.
61
62All endpoints that are paginated have four parameters: `since_id`, `max_id`, `min_id` and
63`limit`. `since_id` allows you to specify the smallest id you want in the returned data, but
64you will still always get the newest data, so if there are too many statuses between
65the newest one and `since_id`, some will not be returned. `min_id`, on the other hand, gives
66you statuses with that minimum id and newer, starting at the given id. `max_id`, similarly,
67allows you to specify the largest id you want. By specifying either min_id or `max_id`
68(generally, only one, not both, though specifying both is supported starting with Mastodon
69version 3.3.0) of them you can go through pages forwards and backwards.
70
71On Mastodon mainline, you can, pass datetime objects as IDs when fetching posts,
72since the IDs used are Snowflake IDs and dates can be approximately converted to those.
73This is guaranteed to work on mainline Mastodon servers and very likely to work on all
74forks, but will **not** work on other servers implementing the API, like Pleroma, Misskey
75or Gotosocial. You should not use this if you want your application to be universally
76compatible. It's also relatively coarse-grained.
77
78`limit` allows you to specify how many results you would like returned. Note that an
79instance may choose to return less results than you requested - by default, Mastodon
80will return no more than 40 statuses and no more than 80 accounts no matter how high
81you set the limit.
82
83The responses returned by paginated endpoints contain a "link" header that specifies
84which parameters to use to get the next and previous pages. Mastodon.py parses these
85and stores them (if present) in the first (for the previous page) and last (for the
86next page) item of the returned list as _pagination_prev and _pagination_next. They
87are accessible only via attribute-style access. Note that this means that if you
88want to persist pagination info with your data, you'll have to take care of that
89manually (or persist objects, not just dicts).
90
91There are convenience functions available for fetching the previous and next page of
92a paginated request as well as for fetching all pages starting from a first page.
93
94IDs and unpacking
95-----------------
96Mastodon's API uses IDs in several places: User IDs, Toot IDs, ...
97
98While debugging, it might be tempting to copy-paste IDs from the
99web interface into your code. This will not work, as the IDs on the web
100interface and in the URLs are not the same as the IDs used internally
101in the API, so don't do that.
102
103ID unpacking
104~~~~~~~~~~~~
105Wherever Mastodon.py expects an ID as a parameter, you can also pass a
106dict that contains an id - this means that, for example, instead of writing
107
108.. code-block:: python
109
110 mastodon.status_post("@somebody wow!", in_reply_to_id = toot["id"])
111
112you can also just write
113
114.. code-block:: python
115
116 mastodon.status_post("@somebody wow!", in_reply_to_id = toot)
117
118and everything will work as intended.
119
120A brief note on block lists
121---------------------------
122Mastodon.py used to block three instances because these were particularly notorious for
123harassing trans people and I don't feel like I have an obligation to let software I
124distribute help people who want my friends to die. I don't want to be associated with
125that, at all.
126
127Those instances are now all gone, any point that could have been has been made, and
128there is no list anymore.
129
130Trans rights are human rights.
diff --git a/docs/index.rst b/docs/index.rst
index 5103b0b..6802626 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -47,1494 +47,6 @@ as forks, while not an official target, should also be basically
47compatible, and Mastodon.py does make some allowances for behaviour that isn't 47compatible, and Mastodon.py does make some allowances for behaviour that isn't
48strictly like that of Mastodon, and attempts to support extensions to the API. 48strictly like that of Mastodon, and attempts to support extensions to the API.
49 49
50A note about rate limits
51------------------------
52Mastodon's API rate limits per user account. By default, the limit is 300 requests
53per 5 minute time slot. This can differ from instance to instance and is subject to change.
54Mastodon.py has three modes for dealing with rate limiting that you can pass to
55the constructor, "throw", "wait" and "pace", "wait" being the default.
56
57In "throw" mode, Mastodon.py makes no attempt to stick to rate limits. When
58a request hits the rate limit, it simply throws a `MastodonRateLimitError`. This is
59for applications that need to handle all rate limiting themselves (i.e. interactive apps),
60or applications wanting to use Mastodon.py in a multi-threaded context ("wait" and "pace"
61modes are not thread safe).
62
63.. note::
64 Rate limit information is available on the `Mastodon` object for applications that
65 implement their own rate limit handling.
66
67 .. attribute:: Mastodon.ratelimit_remaining
68
69 Number of requests allowed until the next reset.
70
71 .. attribute:: Mastodon.ratelimit_reset
72
73 Time at which the rate limit will next be reset, as a POSIX timestamp.
74
75 .. attribute:: Mastodon.ratelimit_limit
76
77 Total number of requests allowed between resets. Typically 300.
78
79 .. attribute:: Mastodon.ratelimit_lastcall
80
81 Time at which these values have last been seen and updated, as a POSIX timestamp.
82
83In "wait" mode, once a request hits the rate limit, Mastodon.py will wait until
84the rate limit resets and then try again, until the request succeeds or an error
85is encountered. This mode is for applications that would rather just not worry about rate limits
86much, don't poll the API all that often, and are okay with a call sometimes just taking
87a while.
88
89In "pace" mode, Mastodon.py will delay each new request after the first one such that,
90if requests were to continue at the same rate, only a certain fraction (set in the
91constructor as `ratelimit_pacefactor`) of the rate limit will be used up. The fraction can
92be (and by default, is) greater than one. If the rate limit is hit, "pace" behaves like
93"wait". This mode is probably the most advanced one and allows you to just poll in
94a loop without ever sleeping at all yourself. It is for applications that would rather
95just pretend there is no such thing as a rate limit and are fine with sometimes not
96being very interactive.
97
98In addition to the per-user limit, there is a per-IP limit of 7500 requests per 5
99minute time slot, and tighter limits on logins. Mastodon.py does not make any effort
100to respect these.
101
102If your application requires many hits to endpoints that are available without logging
103in, do consider using Mastodon.py without authenticating to get the full per-IP limit.
104
105
106A note about pagination
107-----------------------
108Many of Mastodon's API endpoints are paginated. What this means is that if you request
109data from them, you might not get all the data at once - instead, you might only get the
110first few results.
111
112All endpoints that are paginated have four parameters: `since_id`, `max_id`, `min_id` and
113`limit`. `since_id` allows you to specify the smallest id you want in the returned data, but
114you will still always get the newest data, so if there are too many statuses between
115the newest one and `since_id`, some will not be returned. `min_id`, on the other hand, gives
116you statuses with that minimum id and newer, starting at the given id. `max_id`, similarly,
117allows you to specify the largest id you want. By specifying either min_id or `max_id`
118(generally, only one, not both, though specifying both is supported starting with Mastodon
119version 3.3.0) of them you can go through pages forwards and backwards.
120
121On Mastodon mainline, you can, pass datetime objects as IDs when fetching posts,
122since the IDs used are Snowflake IDs and dates can be approximately converted to those.
123This is guaranteed to work on mainline Mastodon servers and very likely to work on all
124forks, but will **not** work on other servers implementing the API, like Pleroma, Misskey
125or Gotosocial. You should not use this if you want your application to be universally
126compatible. It's also relatively coarse-grained.
127
128`limit` allows you to specify how many results you would like returned. Note that an
129instance may choose to return less results than you requested - by default, Mastodon
130will return no more than 40 statuses and no more than 80 accounts no matter how high
131you set the limit.
132
133The responses returned by paginated endpoints contain a "link" header that specifies
134which parameters to use to get the next and previous pages. Mastodon.py parses these
135and stores them (if present) in the first (for the previous page) and last (for the
136next page) item of the returned list as _pagination_prev and _pagination_next. They
137are accessible only via attribute-style access. Note that this means that if you
138want to persist pagination info with your data, you'll have to take care of that
139manually (or persist objects, not just dicts).
140
141There are convenience functions available for fetching the previous and next page of
142a paginated request as well as for fetching all pages starting from a first page.
143
144Two notes about IDs
145-------------------
146Mastodon's API uses IDs in several places: User IDs, Toot IDs, ...
147
148While debugging, it might be tempting to copy-paste IDs from the
149web interface into your code. This will not work, as the IDs on the web
150interface and in the URLs are not the same as the IDs used internally
151in the API, so don't do that.
152
153ID unpacking
154~~~~~~~~~~~~
155Wherever Mastodon.py expects an ID as a parameter, you can also pass a
156dict that contains an id - this means that, for example, instead of writing
157
158.. code-block:: python
159
160 mastodon.status_post("@somebody wow!", in_reply_to_id = toot["id"])
161
162you can also just write
163
164.. code-block:: python
165
166 mastodon.status_post("@somebody wow!", in_reply_to_id = toot)
167
168and everything will work as intended.
169
170Error handling
171--------------
172When Mastodon.py encounters an error, it will raise an exception, generally with
173some text included to tell you what went wrong.
174
175The base class that all Mastodon exceptions inherit from is `MastodonError`.
176If you are only interested in the fact an error was raised somewhere in
177Mastodon.py, and not the details, this is the exception you can catch.
178
179`MastodonIllegalArgumentError` is generally a programming problem - you asked the
180API to do something obviously invalid (i.e. specify a privacy option that does
181not exist).
182
183`MastodonFileNotFoundError` and `MastodonNetworkError` are IO errors - could be you
184specified a wrong URL, could be the internet is down or your hard drive is
185dying. They inherit from `MastodonIOError`, for easy catching. There is a sub-error
186of `MastodonNetworkError`, `MastodonReadTimeout`, which is thrown when a streaming
187API stream times out during reading.
188
189`MastodonAPIError` is an error returned from the Mastodon instance - the server
190has decided it can't fulfil your request (i.e. you requested info on a user that
191does not exist). It is further split into `MastodonNotFoundError` (API returned 404)
192and `MastodonUnauthorizedError` (API returned 401). Different error codes might exist,
193but are not currently handled separately.
194
195`MastodonMalformedEventError` is raised when a streaming API listener receives an
196invalid event. There have been reports that this can sometimes happen after prolonged
197operation due to an upstream problem in the requests/urllib libraries.
198
199`MastodonRatelimitError` is raised when you hit an API rate limit. You should try
200again after a while (see the rate limiting section above).
201
202`MastodonServerError` is raised when the server throws an internal error, likely due
203to server misconfiguration.
204
205`MastodonVersionError` is raised when a version check for an API call fails.
206
207A brief note on block lists
208---------------------------
209Mastodon.py used to block three instances because these were particularly notorious for
210harassing trans people and I don't feel like I have an obligation to let software I
211distribute help people who want my friends to die. I don't want to be associated with
212that, at all.
213
214Those instances are now all gone, any point that could have been has been made, and
215there is no list anymore.
216
217Trans rights are human rights.
218
219Return values
220-------------
221Unless otherwise specified, all data is returned as Python dictionaries, matching
222the JSON format used by the API. Dates returned by the API are in ISO 8601 format
223and are parsed into Python datetime objects.
224
225To make access easier, the dictionaries returned are wrapped by a class that adds
226read-only attributes for all dict values - this means that, for example, instead of
227writing
228
229.. code-block:: python
230
231 description = mastodon.account_verify_credentials()["source"]["note"]
232
233you can also just write
234
235.. code-block:: python
236
237 description = mastodon.account_verify_credentials().source.note
238
239and everything will work as intended. The class used for this is exposed as
240`AttribAccessDict`.
241
242User / account dicts
243~~~~~~~~~~~~~~~~~~~~
244.. _user dict:
245.. _user dicts:
246.. _account dict:
247.. _account dicts:
248
249.. code-block:: python
250
251 mastodon.account(<numerical id>)
252 # Returns the following dictionary:
253 {
254 'id': # Same as <numerical id>
255 'username': # The username (what you @ them with)
256 'acct': # The user's account name as username@domain (@domain omitted for local users)
257 'display_name': # The user's display name
258 'discoverable': # True if the user is listed in the user directory, false if not. None
259 # for remote users.
260 'group': # A boolean indicating whether the account represents a group rather than an
261 # individual.
262 'locked': # Denotes whether the account can be followed without a follow request
263 'created_at': # Account creation time
264 'following_count': # How many people they follow
265 'followers_count': # How many followers they have
266 'statuses_count': # How many statuses they have
267 'note': # Their bio
268 'url': # Their URL; for example 'https://mastodon.social/users/<acct>'
269 'avatar': # URL for their avatar, can be animated
270 'header': # URL for their header image, can be animated
271 'avatar_static': # URL for their avatar, never animated
272 'header_static': # URL for their header image, never animated
273 'source': # Additional information - only present for user dict returned
274 # from account_verify_credentials()
275 'moved_to_account': # If set, a user dict of the account this user has
276 # set up as their moved-to address.
277 'bot': # Boolean indicating whether this account is automated.
278 'fields': # List of up to four dicts with free-form 'name' and 'value' profile info.
279 # For fields with "this is me" type verification, verified_at is set to the
280 # last verification date (It is None otherwise)
281 'emojis': # List of custom emoji used in name, bio or fields
282 'discoverable': # Indicates whether or not a user is visible on the discovery page
283 }
284
285 mastodon.account_verify_credentials()["source"]
286 # Returns the following dictionary:
287 {
288 'privacy': # The user's default visibility setting ("private", "unlisted" or "public")
289 'sensitive': # Denotes whether user media should be marked sensitive by default
290 'note': # Plain text version of the user's bio
291 }
292
293Toot / Status dicts
294~~~~~~~~~~
295.. _toot dict:
296.. _toot dicts:
297.. _status dict:
298.. _status dicts:
299
300.. code-block:: python
301
302 mastodon.toot("Hello from Python")
303 # Returns the following dictionary:
304 {
305 'id': # Numerical id of this toot
306 'uri': # Descriptor for the toot
307 # EG 'tag:mastodon.social,2016-11-25:objectId=<id>:objectType=Status'
308 'url': # URL of the toot
309 'account': # User dict for the account which posted the status
310 'in_reply_to_id': # Numerical id of the toot this toot is in response to
311 'in_reply_to_account_id': # Numerical id of the account this toot is in response to
312 'reblog': # Denotes whether the toot is a reblog. If so, set to the original toot dict.
313 'content': # Content of the toot, as HTML: '<p>Hello from Python</p>'
314 'created_at': # Creation time
315 'reblogs_count': # Number of reblogs
316 'favourites_count': # Number of favourites
317 'reblogged': # Denotes whether the logged in user has boosted this toot
318 'favourited': # Denotes whether the logged in user has favourited this toot
319 'sensitive': # Denotes whether media attachments to the toot are marked sensitive
320 'spoiler_text': # Warning text that should be displayed before the toot content
321 'visibility': # Toot visibility ('public', 'unlisted', 'private', or 'direct')
322 'mentions': # A list of users dicts mentioned in the toot, as Mention dicts
323 'media_attachments': # A list of media dicts of attached files
324 'emojis': # A list of custom emojis used in the toot, as Emoji dicts
325 'tags': # A list of hashtag used in the toot, as Hashtag dicts
326 'bookmarked': # True if the status is bookmarked by the logged in user, False if not.
327 'application': # Application dict for the client used to post the toot (Does not federate
328 # and is therefore always None for remote toots, can also be None for
329 # local toots for some legacy applications).
330 'language': # The language of the toot, if specified by the server,
331 # as ISO 639-1 (two-letter) language code.
332 'muted': # Boolean denoting whether the user has muted this status by
333 # way of conversation muting
334 'pinned': # Boolean denoting whether or not the status is currently pinned for the
335 # associated account.
336 'replies_count': # The number of replies to this status.
337 'card': # A preview card for links from the status, if present at time of delivery,
338 # as card dict.
339 'poll': # A poll dict if a poll is attached to this status.
340 }
341
342Status edit dicts
343~~~~~~~~~~~~~~~~~
344.. _status edit dict:
345
346.. code-block:: python
347
348 mastodonstatus_history(id)[0]
349 # Returns the following dictionary
350 {
351 TODO
352 }
353
354Mention dicts
355~~~~~~~~~~~~~
356.. _mention dict:
357
358.. code-block:: python
359
360 {
361 'url': # Mentioned user's profile URL (potentially remote)
362 'username': # Mentioned user's user name (not including domain)
363 'acct': # Mentioned user's account name (including domain)
364 'id': # Mentioned user's (local) account ID
365 }
366
367Scheduled status / toot dicts
368~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
369.. _scheduled status dict:
370.. _scheduled status dicts:
371.. _scheduled toot dict:
372.. _scheduled toot dicts:
373
374.. code-block:: python
375
376 mastodon.status_post("text", scheduled_at=the_future)
377 # Returns the following dictionary:
378 {
379 'id': # Scheduled toot ID (note: Not the id of the toot once it gets posted!)
380 'scheduled_at': # datetime object describing when the toot is to be posted
381 'params': # Parameters for the scheduled toot, specifically
382 {
383 'text': # Toot text
384 'in_reply_to_id': # ID of the toot this one is a reply to
385 'media_ids': # IDs of media attached to this toot
386 'sensitive': # Whether this toot is sensitive or not
387 'visibility': # Visibility of the toot
388 'idempotency': # Idempotency key for the scheduled toot
389 'scheduled_at': # Present, but generally "None"
390 'spoiler_text': # CW text for this toot
391 'application_id': # ID of the application that scheduled the toot
392 'poll': # Poll parameters, as a poll dict
393 },
394 'media_attachments': # Array of media dicts for the attachments to the scheduled toot
395 }
396
397Poll dicts
398~~~~~~~~~~
399.. _poll dict:
400
401.. code-block:: python
402
403 # Returns the following dictionary:
404 mastodon.poll(id)
405 {
406 'id': # The polls ID
407 'expires_at': # The time at which the poll is set to expire
408 'expired': # Boolean denoting whether you can still vote in this poll
409 'multiple': # Boolean indicating whether it is allowed to vote for more than one option
410 'votes_count': # Total number of votes cast in this poll
411 'voted': # Boolean indicating whether the logged-in user has already voted in this poll
412 'options': # The poll options as a list of dicts, each option with a title and a
413 # votes_count field. votes_count can be None if the poll creator has
414 # chosen to hide vote totals until the poll expires and it hasn't yet.
415 'emojis': # List of emoji dicts for all emoji used in answer strings,
416 'own_votes': # The logged-in users votes, as a list of indices to the options.
417 }
418
419
420Conversation dicts
421~~~~~~~~~~~~~~~~~~
422.. _conversation dict:
423
424.. code-block:: python
425
426 mastodon.conversations()[0]
427 # Returns the following dictionary:
428 {
429 'id': # The ID of this conversation object
430 'unread': # Boolean indicating whether this conversation has yet to be
431 # read by the user
432 'accounts': # List of accounts (other than the logged-in account) that
433 # are part of this conversation
434 'last_status': # The newest status in this conversation
435 }
436
437Hashtag dicts
438~~~~~~~~~~~~~
439.. _hashtag dict:
440
441.. code-block:: python
442
443 {
444 'name': # Hashtag name (not including the #)
445 'url': # Hashtag URL (can be remote)
446 'history': # List of usage history dicts for up to 7 days. Not present in statuses.
447 }
448
449Hashtag usage history dicts
450~~~~~~~~~~~~~~~~~~~~~~~~~~~
451.. _hashtag usage history dict:
452
453.. code-block:: python
454
455 {
456 'day': # Date of the day this history dict is for
457 'uses': # Number of statuses using this hashtag on that day
458 'accounts': # Number of accounts using this hashtag in at least one status on that day
459 }
460
461Emoji dicts
462~~~~~~~~~~~
463.. _emoji dict:
464
465.. code-block:: python
466
467 {
468 'shortcode': # Emoji shortcode, without surrounding colons
469 'url': # URL for the emoji image, can be animated
470 'static_url': # URL for the emoji image, never animated
471 'visible_in_picker': # True if the emoji is enabled, False if not.
472 'category': # The category to display the emoji under (not present if none is set)
473 }
474
475Application dicts
476~~~~~~~~~~~~~~~~~
477 .. _application dict:
478
479.. code-block:: python
480
481 {
482 'name': # The applications name
483 'website': # The applications website
484 'vapid_key': # A vapid key that can be used in web applications
485 }
486
487
488Relationship dicts
489~~~~~~~~~~~~~~~~~~
490.. _relationship dict:
491
492.. code-block:: python
493
494 mastodon.account_follow(<numerical id>)
495 # Returns the following dictionary:
496 {
497 'id': # Numerical id (same one as <numerical id>)
498 'following': # Boolean denoting whether the logged-in user follows the specified user
499 'followed_by': # Boolean denoting whether the specified user follows the logged-in user
500 'blocking': # Boolean denoting whether the logged-in user has blocked the specified user
501 'blocked_by': # Boolean denoting whether the logged-in user has been blocked by the specified user, if information is available
502 'muting': # Boolean denoting whether the logged-in user has muted the specified user
503 'muting_notifications': # Boolean denoting wheter the logged-in user has muted notifications
504 # related to the specified user
505 'requested': # Boolean denoting whether the logged-in user has sent the specified
506 # user a follow request
507 'domain_blocking': # Boolean denoting whether the logged-in user has blocked the
508 # specified users domain
509 'showing_reblogs': # Boolean denoting whether the specified users reblogs show up on the
510 # logged-in users Timeline
511 'endorsed': # Boolean denoting wheter the specified user is being endorsed / featured by the
512 # logged-in user
513 'note': # A free text note the logged in user has created for this account (not publicly visible)
514 'notifying' # Boolean denoting whether the logged-in user has requested to get notified every time the followed user posts
515 }
516
517Filter dicts
518~~~~~~~~~~~~
519.. _filter dict:
520
521.. code-block:: python
522
523 mastodon.filter(<numerical id>)
524 # Returns the following dictionary:
525 {
526 'id': # Numerical id of the filter
527 'phrase': # Filtered keyword or phrase
528 'context': # List of places where the filters are applied ('home', 'notifications', 'public', 'thread')
529 'expires_at': # Expiry date for the filter
530 'irreversible': # Boolean denoting if this filter is executed server-side
531 # or if it should be ran client-side.
532 'whole_word': # Boolean denoting whether this filter can match partial words
533 }
534
535Notification dicts
536~~~~~~~~~~~~~~~~~~
537.. _notification dict:
538
539.. code-block:: python
540
541 mastodon.notifications()[0]
542 # Returns the following dictionary:
543 {
544 'id': # id of the notification
545 'type': # "mention", "reblog", "favourite", "follow", "poll" or "follow_request"
546 'created_at': # The time the notification was created
547 'account': # User dict of the user from whom the notification originates
548 'status': # In case of "mention", the mentioning status
549 # In case of reblog / favourite, the reblogged / favourited status
550 }
551
552Context dicts
553~~~~~~~~~~~~~
554.. _context dict:
555
556.. code-block:: python
557
558 mastodon.status_context(<numerical id>)
559 # Returns the following dictionary:
560 {
561 'ancestors': # A list of toot dicts
562 'descendants': # A list of toot dicts
563 }
564
565List dicts
566~~~~~~~~~~
567.. _list dict:
568
569.. code-block:: python
570
571 mastodon.list(<numerical id>)
572 # Returns the following dictionary:
573 {
574 'id': # id of the list
575 'title': # title of the list
576 }
577
578Media dicts
579~~~~~~~~~~~
580.. _media dict:
581
582.. code-block:: python
583
584 mastodon.media_post("image.jpg", "image/jpeg")
585 # Returns the following dictionary:
586 {
587 'id': # The ID of the attachment.
588 'type': # Media type: 'image', 'video', 'gifv', 'audio' or 'unknown'.
589 'url': # The URL for the image in the local cache
590 'remote_url': # The remote URL for the media (if the image is from a remote instance)
591 'preview_url': # The URL for the media preview
592 'text_url': # The display text for the media (what shows up in toots)
593 'meta': # Dictionary of two metadata dicts (see below),
594 # 'original' and 'small' (preview). Either may be empty.
595 # May additionally contain an "fps" field giving a videos frames per second (possibly
596 # rounded), and a "length" field giving a videos length in a human-readable format.
597 # Note that a video may have an image as preview.
598 # May also contain a 'focus' dict and a media 'colors' dict.
599 'blurhash': # The blurhash for the image, used for preview / placeholder generation
600 'description': # If set, the user-provided description for this media.
601 }
602
603 # Metadata dicts (image) - all fields are optional:
604 {
605 'width': # Width of the image in pixels
606 'height': # Height of the image in pixels
607 'aspect': # Aspect ratio of the image as a floating point number
608 'size': # Textual representation of the image size in pixels, e.g. '800x600'
609 }
610
611 # Metadata dicts (video, gifv) - all fields are optional:
612 {
613 'width': # Width of the video in pixels
614 'heigh': # Height of the video in pixels
615 'frame_rate': # Exact frame rate of the video in frames per second.
616 # Can be an integer fraction (i.e. "20/7")
617 'duration': # Duration of the video in seconds
618 'bitrate': # Average bit-rate of the video in bytes per second
619 }
620
621 # Metadata dicts (audio) - all fields are optional:
622 {
623 'duration': # Duration of the audio file in seconds
624 'bitrate': # Average bit-rate of the audio file in bytes per second
625 }
626
627 # Focus Metadata dict:
628 {
629 'x': # Focus point x coordinate (between -1 and 1)
630 'y': # Focus point x coordinate (between -1 and 1)
631 }
632
633 # Media colors dict:
634 {
635 'foreground': # Estimated foreground colour for the attachment thumbnail
636 'background': # Estimated background colour for the attachment thumbnail
637 'accent': # Estimated accent colour for the attachment thumbnail
638
639Card dicts
640~~~~~~~~~~
641.. _card dict:
642
643.. code-block:: python
644
645 mastodon.status_card(<numerical id>):
646 # Returns the following dictionary
647 {
648 'url': # The URL of the card.
649 'title': # The title of the card.
650 'description': # The description of the card.
651 'type': # Embed type: 'link', 'photo', 'video', or 'rich'
652 'image': # (optional) The image associated with the card.
653
654 # OEmbed data (all optional):
655 'author_name': # Name of the embedded contents author
656 'author_url': # URL pointing to the embedded contents author
657 'description': # Description of the embedded content
658 'width': # Width of the embedded object
659 'height': # Height of the embedded object
660 'html': # HTML string of the embed
661 'provider_name': # Name of the provider from which the embed originates
662 'provider_url': # URL pointing to the embeds provider
663 'blurhash': # (optional) Blurhash of the preview image
664 }
665
666Search result dicts
667~~~~~~~~~~~~~~~~~~~
668.. _search result dict:
669
670.. code-block:: python
671
672 mastodon.search("<query>")
673 # Returns the following dictionary
674 {
675 'accounts': # List of user dicts resulting from the query
676 'hashtags': # List of hashtag dicts resulting from the query
677 'statuses': # List of toot dicts resulting from the query
678 }
679
680Instance dicts
681~~~~~~~~~~~~~~
682.. _instance dict:
683
684.. code-block:: python
685
686 mastodon.instance()
687 # Returns the following dictionary
688 {
689 'domain': # The instances domain name
690 'description': # A brief instance description set by the admin
691 'short_description': # An even briefer instance description
692 'email': # The admin contact email
693 'title': # The instance's title
694 'uri': # The instance's URL
695 'version': # The instance's Mastodon version
696 'urls': # Additional URLs dict, presently only 'streaming_api' with the
697 # stream websocket address.
698 'stats': # A dictionary containing three stats, user_count (number of local users),
699 # status_count (number of local statuses) and domain_count (number of known
700 # instance domains other than this one).
701 'contact_account': # User dict of the primary contact for the instance
702 'languages': # Array of ISO 639-1 (two-letter) language codes the instance
703 # has chosen to advertise.
704 'registrations': # Boolean indication whether registrations on this instance are open
705 # (True) or not (False)
706 'approval_required': # True if account approval is required when registering,
707 'rules': # List of dicts with `id` and `text` fields, one for each server rule set by the admin
708 }
709
710Activity dicts
711~~~~~~~~~~~~~~
712.. _activity dict:
713
714.. code-block:: python
715
716 mastodon.instance_activity()[0]
717 # Returns the following dictionary
718 {
719 'week': # Date of the first day of the week the stats were collected for
720 'logins': # Number of users that logged in that week
721 'registrations': # Number of new users that week
722 'statuses': # Number of statuses posted that week
723 }
724
725Report dicts
726~~~~~~~~~~~~
727.. _report dict:
728
729.. code-block:: python
730
731 mastodon.admin_reports()[0]
732 # Returns the following dictionary
733 {
734 'id': # Numerical id of the report
735 'action_taken': # True if a moderator or admin has processed the
736 # report, False otherwise.
737
738 # The following fields are only present in the report dicts returned by moderation API:
739 'comment': # Text comment submitted with the report
740 'created_at': # Time at which this report was created, as a datetime object
741 'updated_at': # Last time this report has been updated, as a datetime object
742 'account': # User dict of the user that filed this report
743 'target_account': # Account that has been reported with this report
744 'assigned_account': # If the report as been assigned to an account,
745 # User dict of that account (None if not)
746 'action_taken_by_account': # User dict of the account that processed this report
747 'statuses': # List of statuses attached to the report, as toot dicts
748 }
749
750Push subscription dicts
751~~~~~~~~~~~~~~~~~~~~~~~
752.. _push subscription dict:
753
754.. code-block:: python
755
756 mastodon.push_subscription()
757 # Returns the following dictionary
758 {
759 'id': # Numerical id of the push subscription
760 'endpoint': # Endpoint URL for the subscription
761 'server_key': # Server pubkey used for signature verification
762 'alerts': # Subscribed events - dict that may contain keys 'follow',
763 # 'favourite', 'reblog' and 'mention', with value True
764 # if webpushes have been requested for those events.
765 }
766
767Push notification dicts
768~~~~~~~~~~~~~~~~~~~~~~~
769.. _push notification dict:
770
771.. code-block:: python
772
773 mastodon.push_subscription_decrypt_push(...)
774 # Returns the following dictionary
775 {
776 'access_token': # Access token that can be used to access the API as the
777 # notified user
778 'body': # Text body of the notification
779 'icon': # URL to an icon for the notification
780 'notification_id': # ID that can be passed to notification() to get the full
781 # notification object,
782 'notification_type': # 'mention', 'reblog', 'follow' or 'favourite'
783 'preferred_locale': # The user's preferred locale
784 'title': # Title for the notification
785 }
786
787Preference dicts
788~~~~~~~~~~~~~~~~
789.. _preference dict:
790
791.. code-block:: python
792
793 mastodon.preferences()
794 # Returns the following dictionary
795 {
796 'posting:default:visibility': # The default visibility setting for the user's posts,
797 # as a string
798 'posting:default:sensitive': # Boolean indicating whether the user's uploads should
799 # be marked sensitive by default
800 'posting:default:language': # The user's default post language, if set (None if not)
801 'reading:expand:media': # How the user wishes to be shown sensitive media. Can be
802 # 'default' (hide if sensitive), 'hide_all' or 'show_all'
803 'reading:expand:spoilers': # Boolean indicating whether the user wishes to expand
804 # content warnings by default
805 }
806
807Featured tag dicts
808~~~~~~~~~~~~~~~~~~
809.. _featured tag dict:
810
811.. code-block:: python
812
813 mastodon.featured_tags()[0]
814 # Returns the following dictionary:
815 {
816 'id': # The featured tags id
817 'name': # The featured tags name (without leading #)
818 'statuses_count': # Number of publicly visible statuses posted with this hashtag that this instance knows about
819 'last_status_at': # The last time a public status containing this hashtag was added to this instance's database
820 # (can be None if there are none)
821 }
822
823Read marker dicts
824~~~~~~~~~~~~~~~~~
825.. _read marker dict:
826
827.. code-block:: python
828
829 mastodon.markers_get()["home"]
830 # Returns the following dictionary:
831 {
832 'last_read_id': # ID of the last read object in the timeline
833 'version': # A counter that is incremented whenever the marker is set to a new status
834 'updated_at': # The time the marker was last set, as a datetime object
835 }
836
837Announcement dicts
838~~~~~~~~~~~~~~~~~~
839.. _announcement dict:
840
841.. code-block:: python
842
843 mastodon.annoucements()[0]
844 # Returns the following dictionary:
845 {
846 'id': # The annoucements id
847 'content': # The contents of the annoucement, as an html string
848 'starts_at': # The annoucements start time, as a datetime object. Can be None
849 'ends_at': # The annoucements end time, as a datetime object. Can be None
850 'all_day': # Boolean indicating whether the annoucement represents an "all day" event
851 'published_at': # The annoucements publish time, as a datetime object
852 'updated_at': # The annoucements last updated time, as a datetime object
853 'read': # A boolean indicating whether the logged in user has dismissed the annoucement
854 'mentions': # Users mentioned in the annoucement, as a list of mention dicts
855 'tags': # Hashtags mentioned in the announcement, as a list of hashtag dicts
856 'emojis': # Custom emoji used in the annoucement, as a list of emoji dicts
857 'reactions': # Reactions to the annoucement, as a list of reaction dicts (documented inline here):
858 [ {
859 'name': # Name of the custom emoji or unicode emoji of the reaction
860 'count': # Reaction counter (i.e. number of users who have added this reaction)
861 'me': # True if the logged-in user has reacted with this emoji, false otherwise
862 'url': # URL for the custom emoji image
863 'static_url': # URL for a never-animated version of the custom emoji image
864 } ],
865 }
866
867Familiar follower dicts
868~~~~~~~~~~~~~~~~~~~~~~~
869.. _familiar follower dict:
870
871.. code-block:: python
872
873 mastodon.account_familiar_followers(1)[0]
874 # Returns the following dictionary:
875 {
876
877 }
878
879Admin account dicts
880~~~~~~~~~~~~~~~~~~~
881.. _admin account dict:
882
883.. code-block:: python
884
885 mastodon.admin_account(id)
886 # Returns the following dictionary
887 {
888 'id': # The users id,
889 'username': # The users username, no leading @
890 'domain': # The users domain
891 'created_at': # The time of account creation
892 'email': # For local users, the user's email
893 'ip': # For local users, the user's last known IP address
894 'role': # 'admin', 'moderator' or None
895 'confirmed': # For local users, False if the user has not confirmed their email, True otherwise
896 'suspended': # Boolean indicating whether the user has been suspended
897 'silenced': # Boolean indicating whether the user has been suspended
898 'disabled': # For local users, boolean indicating whether the user has had their login disabled
899 'approved': # For local users, False if the user is pending, True otherwise
900 'locale': # For local users, the locale the user has set,
901 'invite_request': # If the user requested an invite, the invite request comment of that user. (TODO permanent?)
902 'invited_by_account_id': # Present if the user was invited by another user and set to the inviting users id.
903 'account': # The user's account, as a standard user dict
904 }
905
906Admin domain block dicts
907~~~~~~~~~~~~~~~~~~~~~~~~
908.. _admin domain block dict:
909
910.. code-block::python
911
912 mastodon.domain_blocks(id=1)
913 #Returns the following dictionary:
914 {
915 'id': #Str. The database id of a domain block,
916 'domain': #Str. The root domain of a block, ie: "example.com",
917 'created_at': #Datetime of the block creation.
918 'severity': #Str. Severity of the domain block, ie: "suspend".
919 'reject_media': #Boolean. True if media is not downloaded from this domain.
920 'reject_reports': #Boolean. True if reports are automatically ignored from this domain.
921 'private_comment': #Str. Private admin comment for a block. None if not set.
922 'public_comment': #Str. Publicly viewable (depending on settings) comment about this domain. None if not set.
923 'obfuscate': #Boolean. True if domain name is obfuscated when listing.
924 }
925
926Admin measure dicts
927~~~~~~~~~~~~~~~~~~~
928.. _admin measure dict:
929
930.. code-block:: python
931
932 api.admin_measures(datetime.now() - timedelta(hours=24*5), datetime.now(), active_users=True)
933 # Returns the following dictionary
934 {
935 TODO
936 }
937
938Admin dimension dicts
939~~~~~~~~~~~~~~~~~~~~~
940.. _admin dimension dict:
941
942.. code-block:: python
943
944 api.admin_dimensions(datetime.now() - timedelta(hours=24*5), datetime.now(), languages=True)
945 # Returns the following dictionary
946 {
947 TODO
948 }
949
950Admin retention dicts
951~~~~~~~~~~~~~~~~~~~~~
952.. _admin retention dict:
953
954.. code-block:: python
955
956 api.admin_retention(datetime.now() - timedelta(hours=24*5), datetime.now())
957 # Returns the following dictionary
958 {
959 TODO
960 }
961
962
963App registration and user authentication
964----------------------------------------
965Before you can use the Mastodon API, you have to register your
966application (which gets you a client key and client secret)
967and then log in (which gets you an access token) and out (revoking
968the access token you are logged in with). These functions
969allow you to do those things. Additionally, it is also possible
970to programmatically register a new user.
971
972For convenience, once you have a client id, secret and access token,
973you can simply pass them to the constructor of the class, too!
974
975Note that while it is perfectly reasonable to log back in whenever
976your app starts, registering a new application on every
977startup is not, so don't do that - instead, register an application
978once, and then persist your client id and secret. A convenient method
979for this is provided by the functions dealing with registering the app,
980logging in and the Mastodon classes constructor.
981
982To talk to an instance different from the flagship instance, specify
983the api_base_url (usually, just the URL of the instance, i.e.
984https://mastodon.social/ for the flagship instance). If no protocol
985is specified, Mastodon.py defaults to https.
986
987.. automethod:: Mastodon.create_app
988.. automethod:: Mastodon.__init__
989.. _log_in():
990.. automethod:: Mastodon.log_in
991.. _auth_request_url():
992.. automethod:: Mastodon.auth_request_url
993.. _set_language():
994.. automethod:: Mastodon.set_language
995.. automethod:: Mastodon.revoke_access_token
996.. automethod:: Mastodon.create_account
997.. automethod:: Mastodon.email_resend_confirmation
998
999Versioning
1000----------
1001Mastodon.py will check if a certain endpoint is available before doing API
1002calls. By default, it checks against the version of Mastodon retrieved on
1003init(), or the version you specified. Mastodon.py can be set (in the
1004constructor) to either check if an endpoint is available at all (this is the
1005default) or to check if the endpoint is available and behaves as in the newest
1006Mastodon version (with regards to parameters as well as return values).
1007Version checking can also be disabled altogether. If a version check fails,
1008Mastodon.py throws a `MastodonVersionError`.
1009
1010Some functions need to check what version of Mastodon they are talking to.
1011These will generally use a cached version to avoid sending a lot of pointless
1012requests.
1013
1014Many non-mainline forks have various different formats for their versions and
1015they have different, incompatible ideas about how to report version. Mastodon.py
1016tries its best to figure out what is going on, but success is not guaranteed.
1017
1018With the following functions, you can make Mastodon.py re-check the server
1019version or explicitly determine if a specific minimum Version is available.
1020Long-running applications that aim to support multiple Mastodon versions
1021should do this from time to time in case a server they are running against
1022updated.
1023
1024.. automethod:: Mastodon.retrieve_mastodon_version
1025.. automethod:: Mastodon.verify_minimum_version
1026
1027Reading data: Instances
1028-----------------------
1029These functions allow you to fetch information associated with the
1030current instance.
1031
1032.. _instance():
1033.. automethod:: Mastodon.instance
1034.. automethod:: Mastodon.instance_activity
1035.. automethod:: Mastodon.instance_peers
1036.. automethod:: Mastodon.instance_health
1037.. automethod:: Mastodon.instance_nodeinfo
1038.. automethod:: Mastodon.instance_rules
1039
1040Reading data: Timelines
1041-----------------------
1042This function allows you to access the timelines a logged in
1043user could see, as well as hashtag timelines and the public (federated)
1044and local timelines. For the public, local and hashtag timelines,
1045access is allowed even when not authenticated.
1046
1047.. _timeline():
1048.. automethod:: Mastodon.timeline
1049.. automethod:: Mastodon.timeline_home
1050.. automethod:: Mastodon.timeline_local
1051.. _timeline_public():
1052.. automethod:: Mastodon.timeline_public
1053.. _timeline_hashtag():
1054.. automethod:: Mastodon.timeline_hashtag
1055.. automethod:: Mastodon.timeline_list
1056.. automethod:: Mastodon.conversations
1057
1058Reading data: Statuses
1059----------------------
1060These functions allow you to get information about single statuses.
1061
1062.. automethod:: Mastodon.status
1063.. automethod:: Mastodon.status_context
1064.. automethod:: Mastodon.status_reblogged_by
1065.. automethod:: Mastodon.status_favourited_by
1066.. automethod:: Mastodon.status_card
1067.. automethod:: Mastodon.status_history
1068.. automethod:: Mastodon.status_source
1069
1070Reading data: Scheduled statuses
1071~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1072These functions allow you to get information about scheduled statuses.
1073
1074.. automethod:: Mastodon.scheduled_statuses
1075.. automethod:: Mastodon.scheduled_status
1076
1077Reading data: Polls
1078~~~~~~~~~~~~~~~~~~~
1079This function allows you to get and refresh information about polls.
1080
1081.. automethod:: Mastodon.poll
1082
1083Reading data: Notifications
1084---------------------------
1085This function allows you to get information about a user's notifications.
1086
1087.. automethod:: Mastodon.notifications
1088
1089Reading data: Accounts
1090----------------------
1091These functions allow you to get information about accounts and
1092their relationships.
1093
1094.. automethod:: Mastodon.account
1095.. automethod:: Mastodon.account_verify_credentials
1096.. automethod:: Mastodon.me
1097.. automethod:: Mastodon.account_statuses
1098.. automethod:: Mastodon.account_following
1099.. automethod:: Mastodon.account_followers
1100.. automethod:: Mastodon.account_relationships
1101.. automethod:: Mastodon.account_search
1102.. automethod:: Mastodon.account_lookup
1103.. automethod:: Mastodon.account_lists
1104.. automethod:: Mastodon.account_familiar_followers
1105.. automethod:: Mastodon.account_remove_from_followers
1106
1107Reading data: Featured tags
1108~~~~~~~~~~~~~~~~~~~~~~~~~~~
1109These functions allow retrieving info about a users featured and suggested tags.
1110
1111.. automethod:: Mastodon.featured_tags
1112.. automethod:: Mastodon.featured_tag_suggestions
1113
1114Reading data: Keyword filters
1115-----------------------------
1116These functions allow you to get information about keyword filters.
1117
1118.. automethod:: Mastodon.filters
1119.. automethod:: Mastodon.filter
1120.. automethod:: Mastodon.filters_apply
1121
1122Reading data: Follow suggestions
1123--------------------------------
1124
1125.. automethod:: Mastodon.suggestions
1126
1127Reading data: Profile directory
1128~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1129
1130.. automethod:: Mastodon.directory
1131
1132Reading data: Lists
1133-------------------
1134These functions allow you to view information about lists.
1135
1136.. automethod:: Mastodon.lists
1137.. automethod:: Mastodon.list
1138.. automethod:: Mastodon.list_accounts
1139
1140Reading data: Follows
1141---------------------
1142
1143.. automethod:: Mastodon.follows
1144
1145Reading data: Favourites
1146------------------------
1147
1148.. automethod:: Mastodon.favourites
1149
1150Reading data: Follow requests
1151-----------------------------
1152
1153.. automethod:: Mastodon.follow_requests
1154
1155Reading data: Searching
1156-----------------------
1157
1158.. automethod:: Mastodon.search
1159.. automethod:: Mastodon.search_v2
1160
1161Reading data: Trends
1162--------------------
1163
1164.. _trending_tags():
1165.. automethod:: Mastodon.trending_tags
1166.. _trending_statuses():
1167.. automethod:: Mastodon.trending_statuses
1168.. _trending_links():
1169.. automethod:: Mastodon.trending_links
1170.. automethod:: Mastodon.trends
1171
1172Reading data: Mutes and blocks
1173------------------------------
1174These functions allow you to get information about accounts that are
1175muted or blocked by the logged in user.
1176
1177.. automethod:: Mastodon.mutes
1178.. automethod:: Mastodon.blocks
1179
1180Reading data: Bookmarks
1181-----------------------
1182
1183.. automethod:: Mastodon.bookmarks
1184
1185Reading data: Reports
1186---------------------
1187In Mastodon versions before 2.5.0 this function allowed for the retrieval
1188of reports filed by the logged in user. It has since been removed.
1189
1190.. automethod:: Mastodon.reports
1191
1192
1193Writing data: Last-read markers
1194--------------------------------
1195This function allows you to set get last read position for timelines.
1196
1197.. automethod:: Mastodon.markers_get
1198
1199Reading data: Domain blocks
1200---------------------------
1201
1202.. automethod:: Mastodon.domain_blocks
1203
1204Reading data: Emoji
1205-------------------
1206
1207.. automethod:: Mastodon.custom_emojis
1208
1209Reading data: Apps
1210------------------
1211
1212.. automethod:: Mastodon.app_verify_credentials
1213
1214Reading data: Endorsements
1215--------------------------
1216
1217.. automethod:: Mastodon.endorsements
1218
1219Reading data: Preferences
1220--------------------------
1221
1222.. automethod:: Mastodon.preferences
1223
1224Reading data: Announcements
1225---------------------------
1226
1227.. automethod:: Mastodon.announcements
1228
1229
1230Writing data: Statuses
1231----------------------
1232These functions allow you to post statuses to Mastodon and to
1233interact with already posted statuses.
1234
1235.. _status_post():
1236.. automethod:: Mastodon.status_post
1237.. automethod:: Mastodon.status_reply
1238.. automethod:: Mastodon.toot
1239.. _make_poll():
1240.. automethod:: Mastodon.make_poll
1241.. automethod:: Mastodon.status_reblog
1242.. automethod:: Mastodon.status_unreblog
1243.. automethod:: Mastodon.status_favourite
1244.. automethod:: Mastodon.status_unfavourite
1245.. automethod:: Mastodon.status_mute
1246.. automethod:: Mastodon.status_unmute
1247.. automethod:: Mastodon.status_pin
1248.. automethod:: Mastodon.status_unpin
1249.. automethod:: Mastodon.status_bookmark
1250.. automethod:: Mastodon.status_unbookmark
1251.. automethod:: Mastodon.status_delete
1252.. _status_update():
1253.. automethod:: Mastodon.status_update
1254
1255
1256Writing data: Scheduled statuses
1257~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1258Mastodon allows you to schedule statuses (using `status_post()`_).
1259The functions in this section allow you to update or delete
1260scheduled statuses.
1261
1262.. automethod:: Mastodon.scheduled_status_update
1263.. automethod:: Mastodon.scheduled_status_delete
1264
1265Writing data: Polls
1266~~~~~~~~~~~~~~~~~~~
1267This function allows you to vote in polls.
1268
1269.. automethod:: Mastodon.poll_vote
1270
1271Writing data: Notifications
1272---------------------------
1273These functions allow you to clear all or some notifications.
1274
1275.. automethod:: Mastodon.notifications_clear
1276.. automethod:: Mastodon.notifications_dismiss
1277
1278Writing data: Conversations
1279---------------------------
1280This function allows you to mark conversations read.
1281
1282.. automethod:: Mastodon.conversations_read
1283
1284Writing data: Accounts
1285----------------------
1286These functions allow you to interact with other accounts: To (un)follow and
1287(un)block.
1288
1289.. _account_follow():
1290.. automethod:: Mastodon.account_follow
1291.. automethod:: Mastodon.account_unfollow
1292.. automethod:: Mastodon.account_block
1293.. automethod:: Mastodon.account_unblock
1294.. automethod:: Mastodon.account_mute
1295.. automethod:: Mastodon.account_unmute
1296.. automethod:: Mastodon.account_pin
1297.. automethod:: Mastodon.account_unpin
1298.. automethod:: Mastodon.account_update_credentials
1299.. automethod:: Mastodon.account_note_set
1300.. automethod:: Mastodon.account_featured_tags
1301
1302Writing data: Featured tags
1303~~~~~~~~~~~~~~~~~~~~~~~~~~~
1304These functions allow setting which tags are featured on a user's profile.
1305
1306.. automethod:: Mastodon.featured_tag_create
1307.. automethod:: Mastodon.featured_tag_delete
1308
1309Writing data: Keyword filters
1310-----------------------------
1311These functions allow you to manipulate keyword filters.
1312
1313.. automethod:: Mastodon.filter_create
1314.. automethod:: Mastodon.filter_update
1315.. automethod:: Mastodon.filter_delete
1316
1317Writing data: Follow suggestions
1318--------------------------------
1319
1320.. automethod:: Mastodon.suggestion_delete
1321
1322Writing data: Lists
1323-------------------
1324These functions allow you to create, maintain and delete lists.
1325
1326When creating lists, note that a user can only
1327have a maximum of 50 lists.
1328
1329.. automethod:: Mastodon.list_create
1330.. automethod:: Mastodon.list_update
1331.. automethod:: Mastodon.list_delete
1332.. automethod:: Mastodon.list_accounts_add
1333.. automethod:: Mastodon.list_accounts_delete
1334
1335Writing data: Follow requests
1336-----------------------------
1337These functions allow you to accept or reject incoming follow requests.
1338
1339.. automethod:: Mastodon.follow_request_authorize
1340.. automethod:: Mastodon.follow_request_reject
1341
1342Writing data: Media
1343-------------------
1344This function allows you to upload media to Mastodon. The returned
1345media IDs (Up to 4 at the same time) can then be used with post_status
1346to attach media to statuses.
1347
1348.. _media_post():
1349
1350.. automethod:: Mastodon.media_post
1351.. automethod:: Mastodon.media_update
1352
1353Writing data: Reports
1354---------------------
1355
1356.. automethod:: Mastodon.report
1357
1358Writing data: Last-read markers
1359-------------------------------
1360This function allows you to set the last read position for timelines to
1361allow for persisting where the user was reading a timeline between sessions
1362and clients / devices.
1363
1364.. automethod:: Mastodon.markers_set
1365
1366Writing data: Domain blocks
1367---------------------------
1368These functions allow you to block and unblock all statuses from a domain
1369for the logged-in user.
1370
1371.. automethod:: Mastodon.domain_block
1372.. automethod:: Mastodon.domain_unblock
1373
1374
1375Writing data: Announcements
1376---------------------------
1377These functions allow you to mark annoucements read and modify reactions.
1378
1379.. automethod:: Mastodon.announcement_dismiss
1380.. automethod:: Mastodon.announcement_reaction_create
1381.. automethod:: Mastodon.announcement_reaction_delete
1382
1383Pagination
1384----------
1385These functions allow for convenient retrieval of paginated data.
1386
1387.. automethod:: Mastodon.fetch_next
1388.. automethod:: Mastodon.fetch_previous
1389.. automethod:: Mastodon.fetch_remaining
1390
1391Blurhash decoding
1392-----------------
1393This function allows for easy basic decoding of blurhash strings to images.
1394This requires Mastodon.pys optional "blurhash" feature dependencies.
1395
1396.. automethod:: Mastodon.decode_blurhash
1397
1398Streaming
1399---------
1400These functions allow access to the streaming API. For the public, local and hashtag streams,
1401access is generally possible without authenticating.
1402
1403If `run_async` is False, these methods block forever (or until an error is encountered).
1404
1405If `run_async` is True, the listener will listen on another thread and these methods
1406will return a handle corresponding to the open connection. If, in addition, `reconnect_async` is True,
1407the thread will attempt to reconnect to the streaming API if any errors are encountered, waiting
1408`reconnect_async_wait_sec` seconds between reconnection attempts. Note that no effort is made
1409to "catch up" - events created while the connection is broken will not be received. If you need to make
1410sure to get absolutely all notifications / deletes / toots, you will have to do that manually, e.g.
1411using the `on_abort` handler to fill in events since the last received one and then reconnecting.
1412Both `run_async` and `reconnect_async` default to false, and you'll have to set each to true
1413separately to get the behaviour described above.
1414
1415The connection may be closed at any time by calling the handles close() method. The
1416current status of the handler thread can be checked with the handles is_alive() function,
1417and the streaming status can be checked by calling is_receiving().
1418
1419The streaming functions take instances of `StreamListener` as the `listener` parameter.
1420A `CallbackStreamListener` class that allows you to specify function callbacks
1421directly is included for convenience.
1422
1423For new well-known events implement the streaming function in `StreamListener` or `CallbackStreamListener`.
1424The function name is `on_` + the event name. If the event name contains dots, they are replaced with
1425underscored, e.g. for an event called 'status.update' the listener function should be named `on_status_update`.
1426
1427It may be that future Mastodon versions will come with completely new (unknown) event names.
1428If you want to do something when such an event is received, override the listener function `on_unknown_event`.
1429This has an additional parameter `name` which informs about the name of the event. `unknown_event` contains the
1430content of the event. Alternatively, a callback function can be passed in the `unknown_event_handler` parameter
1431in the `CallbackStreamListener` constructor.
1432
1433Note that the `unknown_event` handler is *not* guaranteed to receive events once they have been implemented.
1434Events will only go to this handler temporarily, while Mastodon.py has not been updated. Changes to what events
1435do and do not go into the handler will not be considered a breaking change. If you want to handle a new event whose
1436name you _do_ know, define an appropriate handler in your StreamListener, which will work even if it is not listed here.
1437
1438When in not-async mode or async mode without async_reconnect, the stream functions may raise
1439various exceptions: `MastodonMalformedEventError` if a received event cannot be parsed and
1440`MastodonNetworkError` if any connection problems occur.
1441
1442.. automethod:: Mastodon.stream_user
1443.. automethod:: Mastodon.stream_public
1444.. automethod:: Mastodon.stream_local
1445.. automethod:: Mastodon.stream_hashtag
1446.. automethod:: Mastodon.stream_list
1447.. automethod:: Mastodon.stream_healthy
1448
1449StreamListener
1450~~~~~~~~~~~~~~
1451
1452.. autoclass:: StreamListener
1453.. automethod:: StreamListener.on_update
1454.. automethod:: StreamListener.on_notification
1455.. automethod:: StreamListener.on_delete
1456.. automethod:: StreamListener.on_conversation
1457.. automethod:: StreamListener.on_status_update
1458.. automethod:: StreamListener.on_unknown_event
1459.. automethod:: StreamListener.on_abort
1460.. automethod:: StreamListener.handle_heartbeat
1461
1462CallbackStreamListener
1463~~~~~~~~~~~~~~~~~~~~~~
1464
1465.. autoclass:: CallbackStreamListener
1466
1467Push subscriptions
1468------------------
1469These functions allow you to manage webpush subscriptions and to decrypt received
1470pushes. Note that the intended setup is not Mastodon pushing directly to a user's client -
1471the push endpoint should usually be a relay server that then takes care of delivering the
1472(encrypted) push to the end user via some mechanism, where it can then be decrypted and
1473displayed.
1474
1475Mastodon allows an application to have one webpush subscription per user at a time.
1476
1477All crypto utilities require Mastodon.py's optional "webpush" feature dependencies
1478(specifically, the "cryptography" and "http_ece" packages).
1479
1480.. automethod:: Mastodon.push_subscription
1481.. automethod:: Mastodon.push_subscription_set
1482.. automethod:: Mastodon.push_subscription_update
1483
1484.. _push_subscription_generate_keys():
1485
1486.. automethod:: Mastodon.push_subscription_generate_keys
1487.. automethod:: Mastodon.push_subscription_decrypt_push
1488
1489
1490Moderation API
1491--------------
1492These functions allow you to perform moderation actions on users and generally
1493process reports using the API. To do this, you need access to the "admin:read" and/or
1494"admin:write" scopes or their more granular variants (both for the application and the
1495access token), as well as at least moderator access. Mastodon.py will not request these
1496by default, as that would be very dangerous.
1497
1498BIG WARNING: TREAT ANY ACCESS TOKENS THAT HAVE ADMIN CREDENTIALS AS EXTREMELY, MASSIVELY
1499SENSITIVE DATA AND MAKE EXTRA SURE TO REVOKE THEM AFTER TESTING, NOT LET THEM SIT IN FILES
1500SOMEWHERE, TRACK WHICH ARE ACTIVE, ET CETERA. ANY EXPOSURE OF SUCH ACCESS TOKENS MEANS YOU
1501EXPOSE THE PERSONAL DATA OF ALL YOUR USERS TO WHOEVER HAS THESE TOKENS. TREAT THEM WITH
1502EXTREME CARE.
1503
1504This is not to say that you should not treat access tokens from admin accounts that do not
1505have admin: scopes attached with a lot of care, but be extra careful with those that do.
1506
1507.. automethod:: Mastodon.admin_accounts_v2
1508.. automethod:: Mastodon.admin_accounts
1509.. automethod:: Mastodon.admin_accounts_v1
1510.. automethod:: Mastodon.admin_account
1511.. automethod:: Mastodon.admin_account_enable
1512.. automethod:: Mastodon.admin_account_approve
1513.. automethod:: Mastodon.admin_account_reject
1514.. automethod:: Mastodon.admin_account_unsilence
1515.. automethod:: Mastodon.admin_account_unsuspend
1516.. automethod:: Mastodon.admin_account_moderate
1517
1518.. automethod:: Mastodon.admin_reports
1519.. automethod:: Mastodon.admin_report
1520.. automethod:: Mastodon.admin_report_assign
1521.. automethod:: Mastodon.admin_report_unassign
1522.. automethod:: Mastodon.admin_report_reopen
1523.. automethod:: Mastodon.admin_report_resolve
1524
1525.. automethod:: Mastodon.admin_trending_tags
1526.. automethod:: Mastodon.admin_trending_statuses
1527.. automethod:: Mastodon.admin_trending_links
1528.. automethod:: Mastodon.admin_domain_blocks
1529.. automethod:: Mastodon.admin_create_domain_block
1530.. automethod:: Mastodon.admin_update_domain_block
1531.. automethod:: Mastodon.admin_delete_domain_block
1532
1533.. automethod:: Mastodon.admin_measures
1534.. automethod:: Mastodon.admin_dimensions
1535.. automethod:: Mastodon.admin_retention
1536
1537
1538Acknowledgements 50Acknowledgements
1539---------------- 51----------------
1540Mastodon.py contains work by a large number of contributors, many of which have 52Mastodon.py contains work by a large number of contributors, many of which have
@@ -1548,3 +60,6 @@ about who helped with which particular feature or fix in the changelog.
1548.. toctree:: 60.. toctree::
1549 :maxdepth: -1 61 :maxdepth: -1
1550 :collapse_navigation: False 62 :collapse_navigation: False
63
64 Mastodon.py <self>
65 01_general
Powered by cgit v1.2.3 (git 2.41.0)