aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/conf.py32
-rw-r--r--docs/index.rst301
2 files changed, 166 insertions, 167 deletions
diff --git a/docs/conf.py b/docs/conf.py
index 14a3902..ac8858f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -29,7 +29,7 @@
29import os 29import os
30import sys 30import sys
31sys.path.insert(0, os.path.abspath('../')) 31sys.path.insert(0, os.path.abspath('../'))
32autodoc_member_order = 'by_source' 32autodoc_member_order = 'bysource'
33# print(sys.path) 33# print(sys.path)
34 34
35# Add any Sphinx extension module names here, as strings. They can be 35# Add any Sphinx extension module names here, as strings. They can be
@@ -58,7 +58,7 @@ master_doc = 'index'
58 58
59# General information about the project. 59# General information about the project.
60project = u'Mastodon.py' 60project = u'Mastodon.py'
61copyright = u'2016-2020, Lorenz Diener' 61copyright = u'2016-2022, Lorenz Diener'
62author = u'Lorenz Diener' 62author = u'Lorenz Diener'
63 63
64# The version info for the project you're documenting, acts as replacement for 64# The version info for the project you're documenting, acts as replacement for
@@ -68,14 +68,14 @@ author = u'Lorenz Diener'
68# The short X.Y version. 68# The short X.Y version.
69version = u'1.5' 69version = u'1.5'
70# The full version, including alpha/beta/rc tags. 70# The full version, including alpha/beta/rc tags.
71release = u'1.5.1' 71release = u'1.5.2'
72 72
73# The language for content autogenerated by Sphinx. Refer to documentation 73# The language for content autogenerated by Sphinx. Refer to documentation
74# for a list of supported languages. 74# for a list of supported languages.
75# 75#
76# This is also used if you do content translation via gettext catalogs. 76# This is also used if you do content translation via gettext catalogs.
77# Usually you set "language" from the command line for these cases. 77# Usually you set "language" from the command line for these cases.
78language = None 78# language = None
79 79
80# There are two options for replacing |today|: either, you set today to some 80# There are two options for replacing |today|: either, you set today to some
81# non-false value, then it is used: 81# non-false value, then it is used:
@@ -247,21 +247,21 @@ htmlhelp_basename = 'Mastodonpydoc'
247# -- Options for LaTeX output --------------------------------------------- 247# -- Options for LaTeX output ---------------------------------------------
248 248
249latex_elements = { 249latex_elements = {
250 # The paper size ('letterpaper' or 'a4paper'). 250 # The paper size ('letterpaper' or 'a4paper').
251 # 251 #
252 # 'papersize': 'letterpaper', 252 # 'papersize': 'letterpaper',
253 253
254 # The font size ('10pt', '11pt' or '12pt'). 254 # The font size ('10pt', '11pt' or '12pt').
255 # 255 #
256 # 'pointsize': '10pt', 256 # 'pointsize': '10pt',
257 257
258 # Additional stuff for the LaTeX preamble. 258 # Additional stuff for the LaTeX preamble.
259 # 259 #
260 # 'preamble': '', 260 # 'preamble': '',
261 261
262 # Latex figure (float) alignment 262 # Latex figure (float) alignment
263 # 263 #
264 # 'figure_align': 'htbp', 264 # 'figure_align': 'htbp',
265} 265}
266 266
267# Grouping the document tree into LaTeX files. List of tuples 267# Grouping the document tree into LaTeX files. List of tuples
diff --git a/docs/index.rst b/docs/index.rst
index 1e90bc2..025896d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -2,7 +2,7 @@ Mastodon.py
2=========== 2===========
3.. py:module:: mastodon 3.. py:module:: mastodon
4.. py:class: Mastodon 4.. py:class: Mastodon
5 5
6Register your app! This only needs to be done once. Uncomment the code and substitute in your information: 6Register your app! This only needs to be done once. Uncomment the code and substitute in your information:
7 7
8.. code-block:: python 8.. code-block:: python
@@ -22,7 +22,7 @@ Then login. This can be done every time, or you can use the persisted informatio
22.. code-block:: python 22.. code-block:: python
23 23
24 from mastodon import Mastodon 24 from mastodon import Mastodon
25 25
26 mastodon = Mastodon( 26 mastodon = Mastodon(
27 client_id = 'pytooter_clientcred.secret', 27 client_id = 'pytooter_clientcred.secret',
28 api_base_url = 'https://mastodon.social' 28 api_base_url = 'https://mastodon.social'
@@ -38,38 +38,38 @@ To post, create an actual API instance:
38.. code-block:: python 38.. code-block:: python
39 39
40 from mastodon import Mastodon 40 from mastodon import Mastodon
41 41
42 mastodon = Mastodon( 42 mastodon = Mastodon(
43 access_token = 'pytooter_usercred.secret', 43 access_token = 'pytooter_usercred.secret',
44 api_base_url = 'https://mastodon.social' 44 api_base_url = 'https://mastodon.social'
45 ) 45 )
46 mastodon.toot('Tooting from python using #mastodonpy !') 46 mastodon.toot('Tooting from Python using #mastodonpy !')
47 47
48`Mastodon`_ is an ActivityPub and OStatus based twitter-like federated social 48`Mastodon`_ is an ActivityPub-based Twitter-like federated social
49network node. It has an API that allows you to interact with its 49network node. It has an API that allows you to interact with its
50every aspect. This is a simple python wrapper for that api, provided 50every aspect. This is a simple Python wrapper for that API, provided
51as a single python module. By default, it talks to the 51as a single Python module. By default, it talks to the
52`Mastodon flagship instance`_, but it can be set to talk to any 52`Mastodon flagship instance`_, but it can be set to talk to any
53node running Mastodon by setting `api_base_url` when creating the 53node running Mastodon by setting `api_base_url` when creating the
54api object (or creating an app). 54API object (or creating an app).
55 55
56Mastodon.py aims to implement the complete public Mastodon API. As 56Mastodon.py aims to implement the complete public Mastodon API. As
57of this time, it is feature complete for Mastodon version 3.0.1. Pleromas 57of this time, it is feature complete for Mastodon version 3.0.1. Pleroma's
58Mastodon API layer, while not an official target, should also be basically 58Mastodon API layer, while not an official target, should also be basically
59compatible, and Mastodon.py does make some allowances for behaviour that isn't 59compatible, and Mastodon.py does make some allowances for behaviour that isn't
60strictly like Mastodons. 60strictly like that of Mastodon.
61 61
62A note about rate limits 62A note about rate limits
63------------------------ 63------------------------
64Mastodons API rate limits per user account. By default, the limit is 300 requests 64Mastodon's API rate limits per user account. By default, the limit is 300 requests
65per 5 minute time slot. This can differ from instance to instance and is subject to change. 65per 5 minute time slot. This can differ from instance to instance and is subject to change.
66Mastodon.py has three modes for dealing with rate limiting that you can pass to 66Mastodon.py has three modes for dealing with rate limiting that you can pass to
67the constructor, "throw", "wait" and "pace", "wait" being the default. 67the constructor, "throw", "wait" and "pace", "wait" being the default.
68 68
69In "throw" mode, Mastodon.py makes no attempt to stick to rate limits. When 69In "throw" mode, Mastodon.py makes no attempt to stick to rate limits. When
70a request hits the rate limit, it simply throws a `MastodonRateLimitError`. This is 70a request hits the rate limit, it simply throws a `MastodonRateLimitError`. This is
71for applications that need to handle all rate limiting themselves (i.e. interactive apps), 71for applications that need to handle all rate limiting themselves (i.e. interactive apps),
72or applications wanting to use Mastodon.py in a multi-threaded context ("wait" and "pace" 72or applications wanting to use Mastodon.py in a multi-threaded context ("wait" and "pace"
73modes are not thread safe). 73modes are not thread safe).
74 74
75.. note:: 75.. note::
@@ -95,10 +95,10 @@ modes are not thread safe).
95In "wait" mode, once a request hits the rate limit, Mastodon.py will wait until 95In "wait" mode, once a request hits the rate limit, Mastodon.py will wait until
96the rate limit resets and then try again, until the request succeeds or an error 96the rate limit resets and then try again, until the request succeeds or an error
97is encountered. This mode is for applications that would rather just not worry about rate limits 97is encountered. This mode is for applications that would rather just not worry about rate limits
98much, don't poll the api all that often, and are okay with a call sometimes just taking 98much, don't poll the API all that often, and are okay with a call sometimes just taking
99a while. 99a while.
100 100
101In "pace" mode, Mastodon.py will delay each new request after the first one such that, 101In "pace" mode, Mastodon.py will delay each new request after the first one such that,
102if requests were to continue at the same rate, only a certain fraction (set in the 102if requests were to continue at the same rate, only a certain fraction (set in the
103constructor as `ratelimit_pacefactor`) of the rate limit will be used up. The fraction can 103constructor as `ratelimit_pacefactor`) of the rate limit will be used up. The fraction can
104be (and by default, is) greater than one. If the rate limit is hit, "pace" behaves like 104be (and by default, is) greater than one. If the rate limit is hit, "pace" behaves like
@@ -107,7 +107,7 @@ a loop without ever sleeping at all yourself. It is for applications that would
107just pretend there is no such thing as a rate limit and are fine with sometimes not 107just pretend there is no such thing as a rate limit and are fine with sometimes not
108being very interactive. 108being very interactive.
109 109
110In addition to the per-user limit, there is a per-IP limit of 7500 requests per 5 110In addition to the per-user limit, there is a per-IP limit of 7500 requests per 5
111minute time slot, and tighter limits on logins. Mastodon.py does not make any effort 111minute time slot, and tighter limits on logins. Mastodon.py does not make any effort
112to respect these. 112to respect these.
113 113
@@ -117,36 +117,36 @@ in, do consider using Mastodon.py without authenticating to get the full per-IP
117 117
118A note about pagination 118A note about pagination
119----------------------- 119-----------------------
120Many of Mastodons API endpoints are paginated. What this means is that if you request 120Many of Mastodon's API endpoints are paginated. What this means is that if you request
121data from them, you might not get all the data at once - instead, you might only get the 121data from them, you might not get all the data at once - instead, you might only get the
122first few results. 122first few results.
123 123
124All endpoints that are paginated have four parameters: `since_id`, `max_id`, `min_id` and 124All endpoints that are paginated have four parameters: `since_id`, `max_id`, `min_id` and
125`limit`. `since_id` allows you to specify the smallest id you want in the returned data, but 125`limit`. `since_id` allows you to specify the smallest id you want in the returned data, but
126you will still always get the newest data, so if there are too many statuses between 126you will still always get the newest data, so if there are too many statuses between
127the newest one and `since_id`, some will not be returned. `min_id`, on the other hand, gives 127the newest one and `since_id`, some will not be returned. `min_id`, on the other hand, gives
128you statuses with that minimum id and newer, starting at the given id. `max_id`, similarly, 128you statuses with that minimum id and newer, starting at the given id. `max_id`, similarly,
129allows you to specify the largest id you want. By specifying either min_id or `max_id` 129allows you to specify the largest id you want. By specifying either min_id or `max_id`
130(generally, only one, not both, though specifying both is supported starting with Mastodon 130(generally, only one, not both, though specifying both is supported starting with Mastodon
131version 3.3.0) of them you can go through pages forwards and backwards. 131version 3.3.0) of them you can go through pages forwards and backwards.
132 132
133On Mastodon mainline, you can, pass datetime objects as IDs when fetching posts, 133On Mastodon mainline, you can, pass datetime objects as IDs when fetching posts,
134since the IDs used are Snowflake IDs and dates can be approximately converted to those. 134since the IDs used are Snowflake IDs and dates can be approximately converted to those.
135This is guaranteed to work on mainline Mastodon servers and very likely to work on all 135This is guaranteed to work on mainline Mastodon servers and very likely to work on all
136forks, but will **not** work on other servers implementing the API, like Pleroma, Misskey 136forks, but will **not** work on other servers implementing the API, like Pleroma, Misskey
137or Gotosocial. You should not use this if you want your application to be universally 137or Gotosocial. You should not use this if you want your application to be universally
138compatible. 138compatible.
139 139
140`limit` allows you to specify how many results you would like returned. Note that an 140`limit` allows you to specify how many results you would like returned. Note that an
141instance may choose to return less results than you requested - by default, Mastodon 141instance may choose to return less results than you requested - by default, Mastodon
142will return no more than 40 statues and no more than 80 accounts no matter how high 142will return no more than 40 statuses and no more than 80 accounts no matter how high
143you set the limit. 143you set the limit.
144 144
145The responses returned by paginated endpoints contain a "link" header that specifies 145The responses returned by paginated endpoints contain a "link" header that specifies
146which parameters to use to get the next and previous pages. Mastodon.py parses these 146which parameters to use to get the next and previous pages. Mastodon.py parses these
147and stores them (if present) in the first (for the previous page) and last (for the 147and stores them (if present) in the first (for the previous page) and last (for the
148next page) item of the returned list as _pagination_prev and _pagination_next. They 148next page) item of the returned list as _pagination_prev and _pagination_next. They
149are accessible only via attribute-style access. Note that this means that if you 149are accessible only via attribute-style access. Note that this means that if you
150want to persist pagination info with your data, you'll have to take care of that 150want to persist pagination info with your data, you'll have to take care of that
151manually (or persist objects, not just dicts). 151manually (or persist objects, not just dicts).
152 152
@@ -155,9 +155,9 @@ a paginated request as well as for fetching all pages starting from a first page
155 155
156Two notes about IDs 156Two notes about IDs
157------------------- 157-------------------
158Mastodons API uses IDs in several places: User IDs, Toot IDs, ... 158Mastodon's API uses IDs in several places: User IDs, Toot IDs, ...
159 159
160While debugging, it might be tempting to copy-paste in IDs from the 160While debugging, it might be tempting to copy-paste IDs from the
161web interface into your code. This will not work, as the IDs on the web 161web interface into your code. This will not work, as the IDs on the web
162interface and in the URLs are not the same as the IDs used internally 162interface and in the URLs are not the same as the IDs used internally
163in the API, so don't do that. 163in the API, so don't do that.
@@ -165,30 +165,30 @@ in the API, so don't do that.
165ID unpacking 165ID unpacking
166~~~~~~~~~~~~ 166~~~~~~~~~~~~
167Wherever Mastodon.py expects an ID as a parameter, you can also pass a 167Wherever Mastodon.py expects an ID as a parameter, you can also pass a
168dict that contains an id - this means that, for example, instead of writing 168dict that contains an id - this means that, for example, instead of writing
169 169
170.. code-block:: python 170.. code-block:: python
171 171
172 mastodon.status_post("@somebody wow!", in_reply_to_id = toot["id"]) 172 mastodon.status_post("@somebody wow!", in_reply_to_id = toot["id"])
173 173
174you can also just write 174you can also just write
175 175
176.. code-block:: python 176.. code-block:: python
177 177
178 mastodon.status_post("@somebody wow!", in_reply_to_id = toot) 178 mastodon.status_post("@somebody wow!", in_reply_to_id = toot)
179 179
180and everything will work as intended. 180and everything will work as intended.
181 181
182Error handling 182Error handling
183-------------- 183--------------
184When Mastodon.py encounters an error, it will raise an exception, generally with 184When Mastodon.py encounters an error, it will raise an exception, generally with
185some text included to tell you what went wrong. 185some text included to tell you what went wrong.
186 186
187The base class that all mastodon exceptions inherit from is `MastodonError`. 187The base class that all Mastodon exceptions inherit from is `MastodonError`.
188If you are only interested in the fact an error was raised somewhere in 188If you are only interested in the fact an error was raised somewhere in
189Mastodon.py, and not the details, this is the exception you can catch. 189Mastodon.py, and not the details, this is the exception you can catch.
190 190
191`MastodonIllegalArgumentError` is generally a programming problem - you asked the 191`MastodonIllegalArgumentError` is generally a programming problem - you asked the
192API to do something obviously invalid (i.e. specify a privacy option that does 192API to do something obviously invalid (i.e. specify a privacy option that does
193not exist). 193not exist).
194 194
@@ -199,16 +199,16 @@ of `MastodonNetworkError`, `MastodonReadTimeout`, which is thrown when a streami
199API stream times out during reading. 199API stream times out during reading.
200 200
201`MastodonAPIError` is an error returned from the Mastodon instance - the server 201`MastodonAPIError` is an error returned from the Mastodon instance - the server
202has decided it can't fullfill your request (i.e. you requested info on a user that 202has decided it can't fulfil your request (i.e. you requested info on a user that
203does not exist). It is further split into `MastodonNotFoundError` (API returned 404) 203does not exist). It is further split into `MastodonNotFoundError` (API returned 404)
204and `MastodonUnauthorizedError` (API returned 401). Different error codes might exist, 204and `MastodonUnauthorizedError` (API returned 401). Different error codes might exist,
205but are not currently handled separately. 205but are not currently handled separately.
206 206
207`MastodonMalformedEventError` is raised when a streaming API listener receives an 207`MastodonMalformedEventError` is raised when a streaming API listener receives an
208invalid event. There have been reports that this can sometimes happen after prolonged 208invalid event. There have been reports that this can sometimes happen after prolonged
209operation due to an upstream problem in the requests/urllib libraries. 209operation due to an upstream problem in the requests/urllib libraries.
210 210
211`MastodonRatelimitError` is raised when you hit an API rate limit. You should try 211`MastodonRatelimitError` is raised when you hit an API rate limit. You should try
212again after a while (see the rate limiting section above). 212again after a while (see the rate limiting section above).
213 213
214`MastodonServerError` is raised when the server throws an internal error, likely due 214`MastodonServerError` is raised when the server throws an internal error, likely due
@@ -224,9 +224,9 @@ While you take the extra step of removing the code, please take a moment to cons
224 224
225Return values 225Return values
226------------- 226-------------
227Unless otherwise specified, all data is returned as python dictionaries, matching 227Unless otherwise specified, all data is returned as Python dictionaries, matching
228the JSON format used by the API. Dates returned by the API are in ISO 8601 format 228the JSON format used by the API. Dates returned by the API are in ISO 8601 format
229and are parsed into python datetime objects. 229and are parsed into Python datetime objects.
230 230
231To make access easier, the dictionaries returned are wrapped by a class that adds 231To make access easier, the dictionaries returned are wrapped by a class that adds
232read-only attributes for all dict values - this means that, for example, instead of 232read-only attributes for all dict values - this means that, for example, instead of
@@ -235,13 +235,13 @@ writing
235.. code-block:: python 235.. code-block:: python
236 236
237 description = mastodon.account_verify_credentials()["source"]["note"] 237 description = mastodon.account_verify_credentials()["source"]["note"]
238 238
239you can also just write 239you can also just write
240 240
241.. code-block:: python 241.. code-block:: python
242 242
243 description = mastodon.account_verify_credentials().source.note 243 description = mastodon.account_verify_credentials().source.note
244 244
245and everything will work as intended. The class used for this is exposed as 245and everything will work as intended. The class used for this is exposed as
246`AttribAccessDict`. 246`AttribAccessDict`.
247 247
@@ -268,12 +268,12 @@ User / account dicts
268 'followers_count': # How many followers they have 268 'followers_count': # How many followers they have
269 'statuses_count': # How many statuses they have 269 'statuses_count': # How many statuses they have
270 'note': # Their bio 270 'note': # Their bio
271 'url': # Their URL; usually 'https://mastodon.social/users/<acct>' 271 'url': # Their URL; for example 'https://mastodon.social/users/<acct>'
272 'avatar': # URL for their avatar, can be animated 272 'avatar': # URL for their avatar, can be animated
273 'header': # URL for their header image, can be animated 273 'header': # URL for their header image, can be animated
274 'avatar_static': # URL for their avatar, never animated 274 'avatar_static': # URL for their avatar, never animated
275 'header_static': # URL for their header image, never animated 275 'header_static': # URL for their header image, never animated
276 'source': # Additional information - only present for user dict returned 276 'source': # Additional information - only present for user dict returned
277 # from account_verify_credentials() 277 # from account_verify_credentials()
278 'moved_to_account': # If set, a user dict of the account this user has 278 'moved_to_account': # If set, a user dict of the account this user has
279 # set up as their moved-to address. 279 # set up as their moved-to address.
@@ -288,11 +288,11 @@ User / account dicts
288 mastodon.account_verify_credentials()["source"] 288 mastodon.account_verify_credentials()["source"]
289 # Returns the following dictionary: 289 # Returns the following dictionary:
290 { 290 {
291 'privacy': # The users default visibility setting ("private", "unlisted" or "public") 291 'privacy': # The user's default visibility setting ("private", "unlisted" or "public")
292 'sensitive': # Denotes whether user media should be marked sensitive by default 292 'sensitive': # Denotes whether user media should be marked sensitive by default
293 'note': # Plain text version of the users bio 293 'note': # Plain text version of the user's bio
294 } 294 }
295 295
296Toot dicts 296Toot dicts
297~~~~~~~~~~ 297~~~~~~~~~~
298.. _toot dict: 298.. _toot dict:
@@ -327,9 +327,9 @@ Toot dicts
327 'application': # Application dict for the client used to post the toot (Does not federate 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 328 # and is therefore always None for remote toots, can also be None for
329 # local toots for some legacy applications). 329 # local toots for some legacy applications).
330 'language': # The language of the toot, if specified by the server, 330 'language': # The language of the toot, if specified by the server,
331 # as ISO 639-1 (two-letter) language code. 331 # as ISO 639-1 (two-letter) language code.
332 'muted': # Boolean denoting whether the user has muted this status by 332 'muted': # Boolean denoting whether the user has muted this status by
333 # way of conversation muting 333 # way of conversation muting
334 'pinned': # Boolean denoting whether or not the status is currently pinned for the 334 'pinned': # Boolean denoting whether or not the status is currently pinned for the
335 # associated account. 335 # associated account.
@@ -346,12 +346,12 @@ Mention dicts
346.. code-block:: python 346.. code-block:: python
347 347
348 { 348 {
349 'url': # Mentioned users profile URL (potentially remote) 349 'url': # Mentioned user's profile URL (potentially remote)
350 'username': # Mentioned users user name (not including domain) 350 'username': # Mentioned user's user name (not including domain)
351 'acct': # Mentioned users account name (including domain) 351 'acct': # Mentioned user's account name (including domain)
352 'id': # Mentioned users (local) account ID 352 'id': # Mentioned user's (local) account ID
353 } 353 }
354 354
355Scheduled toot dicts 355Scheduled toot dicts
356~~~~~~~~~~~~~~~~~~~~ 356~~~~~~~~~~~~~~~~~~~~
357.. _scheduled toot dict: 357.. _scheduled toot dict:
@@ -400,25 +400,25 @@ Poll dicts
400 'emojis': # List of emoji dicts for all emoji used in answer strings, 400 'emojis': # List of emoji dicts for all emoji used in answer strings,
401 'own_votes': # The logged-in users votes, as a list of indices to the options. 401 'own_votes': # The logged-in users votes, as a list of indices to the options.
402 } 402 }
403 403
404 404
405Conversation dicts 405Conversation dicts
406~~~~~~~~~~~~~~~~~~ 406~~~~~~~~~~~~~~~~~~
407.. _conversation dict: 407.. _conversation dict:
408 408
409.. code-block:: python 409.. code-block:: python
410 410
411 mastodon.conversations()[0] 411 mastodon.conversations()[0]
412 # Returns the following dictionary: 412 # Returns the following dictionary:
413 { 413 {
414 'id': # The ID of this conversation object 414 'id': # The ID of this conversation object
415 'unread': # Boolean indicating whether this conversation has yet to be 415 'unread': # Boolean indicating whether this conversation has yet to be
416 # read by the user 416 # read by the user
417 'accounts': # List of accounts (other than the logged-in account) that 417 'accounts': # List of accounts (other than the logged-in account) that
418 # are part of this conversation 418 # are part of this conversation
419 'last_status': # The newest status in this conversation 419 'last_status': # The newest status in this conversation
420 } 420 }
421 421
422Hashtag dicts 422Hashtag dicts
423~~~~~~~~~~~~~ 423~~~~~~~~~~~~~
424.. _hashtag dict: 424.. _hashtag dict:
@@ -442,7 +442,7 @@ Hashtag usage history dicts
442 'uses': # Number of statuses using this hashtag on that day 442 'uses': # Number of statuses using this hashtag on that day
443 'accounts': # Number of accounts using this hashtag in at least one status on that day 443 'accounts': # Number of accounts using this hashtag in at least one status on that day
444 } 444 }
445 445
446Emoji dicts 446Emoji dicts
447~~~~~~~~~~~ 447~~~~~~~~~~~
448.. _emoji dict: 448.. _emoji dict:
@@ -451,16 +451,16 @@ Emoji dicts
451 451
452 { 452 {
453 'shortcode': # Emoji shortcode, without surrounding colons 453 'shortcode': # Emoji shortcode, without surrounding colons
454 'url': # URL for the emoji image, can be animated 454 'url': # URL for the emoji image, can be animated
455 'static_url': # URL for the emoji image, never animated 455 'static_url': # URL for the emoji image, never animated
456 'visible_in_picker': # True if the emoji is enabled, False if not. 456 'visible_in_picker': # True if the emoji is enabled, False if not.
457 'category': # The category to display the emoji under (not present if none is set) 457 'category': # The category to display the emoji under (not present if none is set)
458 } 458 }
459 459
460Application dicts 460Application dicts
461~~~~~~~~~~~~~~~~~ 461~~~~~~~~~~~~~~~~~
462 .. _application dict: 462 .. _application dict:
463 463
464.. code-block:: python 464.. code-block:: python
465 465
466 { 466 {
@@ -468,8 +468,8 @@ Application dicts
468 'website': # The applications website 468 'website': # The applications website
469 'vapid_key': # A vapid key that can be used in web applications 469 'vapid_key': # A vapid key that can be used in web applications
470 } 470 }
471 471
472 472
473Relationship dicts 473Relationship dicts
474~~~~~~~~~~~~~~~~~~ 474~~~~~~~~~~~~~~~~~~
475.. _relationship dict: 475.. _relationship dict:
@@ -485,11 +485,11 @@ Relationship dicts
485 'blocking': # Boolean denoting whether the logged-in user has blocked the specified user 485 'blocking': # Boolean denoting whether the logged-in user has blocked the specified user
486 'blocked_by': # Boolean denoting whether the logged-in user has been blocked by the specified user, if information is available 486 'blocked_by': # Boolean denoting whether the logged-in user has been blocked by the specified user, if information is available
487 'muting': # Boolean denoting whether the logged-in user has muted the specified user 487 'muting': # Boolean denoting whether the logged-in user has muted the specified user
488 'muting_notifications': # Boolean denoting wheter the logged-in user has muted notifications 488 'muting_notifications': # Boolean denoting wheter the logged-in user has muted notifications
489 # related to the specified user 489 # related to the specified user
490 'requested': # Boolean denoting whether the logged-in user has sent the specified 490 'requested': # Boolean denoting whether the logged-in user has sent the specified
491 # user a follow request 491 # user a follow request
492 'domain_blocking': # Boolean denoting whether the logged-in user has blocked the 492 'domain_blocking': # Boolean denoting whether the logged-in user has blocked the
493 # specified users domain 493 # specified users domain
494 'showing_reblogs': # Boolean denoting whether the specified users reblogs show up on the 494 'showing_reblogs': # Boolean denoting whether the specified users reblogs show up on the
495 # logged-in users Timeline 495 # logged-in users Timeline
@@ -502,7 +502,7 @@ Relationship dicts
502Filter dicts 502Filter dicts
503~~~~~~~~~~~~ 503~~~~~~~~~~~~
504.. _filter dict: 504.. _filter dict:
505 505
506.. code-block:: python 506.. code-block:: python
507 507
508 mastodon.filter(<numerical id>) 508 mastodon.filter(<numerical id>)
@@ -516,7 +516,7 @@ Filter dicts
516 # or if it should be ran client-side. 516 # or if it should be ran client-side.
517 'whole_word': # Boolean denoting whether this filter can match partial words 517 'whole_word': # Boolean denoting whether this filter can match partial words
518 } 518 }
519 519
520Notification dicts 520Notification dicts
521~~~~~~~~~~~~~~~~~~ 521~~~~~~~~~~~~~~~~~~
522.. _notification dict: 522.. _notification dict:
@@ -552,14 +552,14 @@ List dicts
552.. _list dict: 552.. _list dict:
553 553
554.. code-block:: python 554.. code-block:: python
555 555
556 mastodon.list(<numerical id>) 556 mastodon.list(<numerical id>)
557 # Returns the following dictionary: 557 # Returns the following dictionary:
558 { 558 {
559 'id': # id of the list 559 'id': # id of the list
560 'title': # title of the list 560 'title': # title of the list
561 } 561 }
562 562
563Media dicts 563Media dicts
564~~~~~~~~~~~ 564~~~~~~~~~~~
565.. _media dict: 565.. _media dict:
@@ -575,7 +575,7 @@ Media dicts
575 'remote_url': # The remote URL for the media (if the image is from a remote instance) 575 'remote_url': # The remote URL for the media (if the image is from a remote instance)
576 'preview_url': # The URL for the media preview 576 'preview_url': # The URL for the media preview
577 'text_url': # The display text for the media (what shows up in toots) 577 'text_url': # The display text for the media (what shows up in toots)
578 'meta': # Dictionary of two metadata dicts (see below), 578 'meta': # Dictionary of two metadata dicts (see below),
579 # 'original' and 'small' (preview). Either may be empty. 579 # 'original' and 'small' (preview). Either may be empty.
580 # May additionally contain an "fps" field giving a videos frames per second (possibly 580 # May additionally contain an "fps" field giving a videos frames per second (possibly
581 # rounded), and a "length" field giving a videos length in a human-readable format. 581 # rounded), and a "length" field giving a videos length in a human-readable format.
@@ -584,7 +584,7 @@ Media dicts
584 'blurhash': # The blurhash for the image, used for preview / placeholder generation 584 'blurhash': # The blurhash for the image, used for preview / placeholder generation
585 'description': # If set, the user-provided description for this media. 585 'description': # If set, the user-provided description for this media.
586 } 586 }
587 587
588 # Metadata dicts (image) - all fields are optional: 588 # Metadata dicts (image) - all fields are optional:
589 { 589 {
590 'width': # Width of the image in pixels 590 'width': # Width of the image in pixels
@@ -592,7 +592,7 @@ Media dicts
592 'aspect': # Aspect ratio of the image as a floating point number 592 'aspect': # Aspect ratio of the image as a floating point number
593 'size': # Textual representation of the image size in pixels, e.g. '800x600' 593 'size': # Textual representation of the image size in pixels, e.g. '800x600'
594 } 594 }
595 595
596 # Metadata dicts (video, gifv) - all fields are optional: 596 # Metadata dicts (video, gifv) - all fields are optional:
597 { 597 {
598 'width': # Width of the video in pixels 598 'width': # Width of the video in pixels
@@ -607,14 +607,14 @@ Media dicts
607 { 607 {
608 'duration': # Duration of the audio file in seconds 608 'duration': # Duration of the audio file in seconds
609 'bitrate': # Average bit-rate of the audio file in bytes per second 609 'bitrate': # Average bit-rate of the audio file in bytes per second
610 } 610 }
611 611
612 # Focus Metadata dict: 612 # Focus Metadata dict:
613 { 613 {
614 'x': Focus point x coordinate (between -1 and 1) 614 'x': Focus point x coordinate (between -1 and 1)
615 'y': Focus point x coordinate (between -1 and 1) 615 'y': Focus point x coordinate (between -1 and 1)
616 } 616 }
617 617
618 # Media colors dict: 618 # Media colors dict:
619 { 619 {
620 'foreground': # Estimated foreground colour for the attachment thumbnail 620 'foreground': # Estimated foreground colour for the attachment thumbnail
@@ -635,7 +635,7 @@ Card dicts
635 'description': # The description of the card. 635 'description': # The description of the card.
636 'type': # Embed type: 'link', 'photo', 'video', or 'rich' 636 'type': # Embed type: 'link', 'photo', 'video', or 'rich'
637 'image': # (optional) The image associated with the card. 637 'image': # (optional) The image associated with the card.
638 638
639 # OEmbed data (all optional): 639 # OEmbed data (all optional):
640 'author_name': # Name of the embedded contents author 640 'author_name': # Name of the embedded contents author
641 'author_url': # URL pointing to the embedded contents author 641 'author_url': # URL pointing to the embedded contents author
@@ -660,8 +660,8 @@ Search result dicts
660 'accounts': # List of user dicts resulting from the query 660 'accounts': # List of user dicts resulting from the query
661 'hashtags': # List of hashtag dicts resulting from the query 661 'hashtags': # List of hashtag dicts resulting from the query
662 'statuses': # List of toot dicts resulting from the query 662 'statuses': # List of toot dicts resulting from the query
663 } 663 }
664 664
665Instance dicts 665Instance dicts
666~~~~~~~~~~~~~~ 666~~~~~~~~~~~~~~
667.. _instance dict: 667.. _instance dict:
@@ -673,17 +673,17 @@ Instance dicts
673 { 673 {
674 'description': # A brief instance description set by the admin 674 'description': # A brief instance description set by the admin
675 'short_description': # An even briefer instance description 675 'short_description': # An even briefer instance description
676 'email': # The admin contact e-mail 676 'email': # The admin contact email
677 'title': # The instances title 677 'title': # The instance's title
678 'uri': # The instances URL 678 'uri': # The instance's URL
679 'version': # The instances mastodon version 679 'version': # The instance's Mastodon version
680 'urls': # Additional URLs dict, presently only 'streaming_api' with the 680 'urls': # Additional URLs dict, presently only 'streaming_api' with the
681 # stream websocket address. 681 # stream websocket address.
682 'stats: # A dictionary containing three stats, user_count (number of local users), 682 'stats: # A dictionary containing three stats, user_count (number of local users),
683 # status_count (number of local statuses) and domain_count (number of known 683 # status_count (number of local statuses) and domain_count (number of known
684 # instance domains other than this one). 684 # instance domains other than this one).
685 'contact_account': # User dict of the primary contact for the instance 685 'contact_account': # User dict of the primary contact for the instance
686 'languages': # Array of ISO 639-1 (two-letter) language codes the instance 686 'languages': # Array of ISO 639-1 (two-letter) language codes the instance
687 # has chosen to advertise. 687 # has chosen to advertise.
688 'registrations': # Boolean indication whether registrations on this instance are open 688 'registrations': # Boolean indication whether registrations on this instance are open
689 # (True) or not (False) 689 # (True) or not (False)
@@ -703,8 +703,8 @@ Activity dicts
703 'logins': # Number of users that logged in that week 703 'logins': # Number of users that logged in that week
704 'registrations': # Number of new users that week 704 'registrations': # Number of new users that week
705 'statuses': # Number of statuses posted that week 705 'statuses': # Number of statuses posted that week
706 } 706 }
707 707
708Report dicts 708Report dicts
709~~~~~~~~~~~~ 709~~~~~~~~~~~~
710.. _report dict: 710.. _report dict:
@@ -717,19 +717,19 @@ Report dicts
717 'id': # Numerical id of the report 717 'id': # Numerical id of the report
718 'action_taken': # True if a moderator or admin has processed the 718 'action_taken': # True if a moderator or admin has processed the
719 # report, False otherwise. 719 # report, False otherwise.
720 720
721 # The following fields are only present in the report dicts returned by moderation API: 721 # The following fields are only present in the report dicts returned by moderation API:
722 'comment': # Text comment submitted with the report 722 'comment': # Text comment submitted with the report
723 'created_at': # Time at which this report was created, as a datetime object 723 'created_at': # Time at which this report was created, as a datetime object
724 'updated_at': # Last time this report has been updated, as a datetime object 724 'updated_at': # Last time this report has been updated, as a datetime object
725 'account': # User dict of the user that filed this report 725 'account': # User dict of the user that filed this report
726 'target_account': # Account that has been reported with this report 726 'target_account': # Account that has been reported with this report
727 'assigned_account': # If the report as been assigned to an account, 727 'assigned_account': # If the report as been assigned to an account,
728 # User dict of that account (None if not) 728 # User dict of that account (None if not)
729 'action_taken_by_account': # User dict of the account that processed this report 729 'action_taken_by_account': # User dict of the account that processed this report
730 'statuses': # List of statuses attached to the report, as toot dicts 730 'statuses': # List of statuses attached to the report, as toot dicts
731 } 731 }
732 732
733Push subscription dicts 733Push subscription dicts
734~~~~~~~~~~~~~~~~~~~~~~~ 734~~~~~~~~~~~~~~~~~~~~~~~
735.. _push subscription dict: 735.. _push subscription dict:
@@ -746,7 +746,7 @@ Push subscription dicts
746 # 'favourite', 'reblog' and 'mention', with value True 746 # 'favourite', 'reblog' and 'mention', with value True
747 # if webpushes have been requested for those events. 747 # if webpushes have been requested for those events.
748 } 748 }
749 749
750Push notification dicts 750Push notification dicts
751~~~~~~~~~~~~~~~~~~~~~~~ 751~~~~~~~~~~~~~~~~~~~~~~~
752.. _push notification dict: 752.. _push notification dict:
@@ -756,37 +756,37 @@ Push notification dicts
756 mastodon.push_subscription_decrypt_push(...) 756 mastodon.push_subscription_decrypt_push(...)
757 # Returns the following dictionary 757 # Returns the following dictionary
758 { 758 {
759 'access_token': # Access token that can be used to access the API as the 759 'access_token': # Access token that can be used to access the API as the
760 # notified user 760 # notified user
761 'body': # Text body of the notification 761 'body': # Text body of the notification
762 'icon': # URL to an icon for the notification 762 'icon': # URL to an icon for the notification
763 'notification_id': # ID that can be passed to notification() to get the full 763 'notification_id': # ID that can be passed to notification() to get the full
764 # notification object, 764 # notification object,
765 'notification_type': # 'mention', 'reblog', 'follow' or 'favourite' 765 'notification_type': # 'mention', 'reblog', 'follow' or 'favourite'
766 'preferred_locale': # The users preferred locale 766 'preferred_locale': # The user's preferred locale
767 'title': # Title for the notification 767 'title': # Title for the notification
768 } 768 }
769 769
770Preference dicts 770Preference dicts
771~~~~~~~~~~~~~~~~ 771~~~~~~~~~~~~~~~~
772.. _preference dict: 772.. _preference dict:
773 773
774.. code-block:: python 774.. code-block:: python
775 775
776 mastodon.preferences() 776 mastodon.preferences()
777 # Returns the following dictionary 777 # Returns the following dictionary
778 { 778 {
779 'posting:default:visibility': # The default visibility setting for the users posts, 779 'posting:default:visibility': # The default visibility setting for the user's posts,
780 # as a string 780 # as a string
781 'posting:default:sensitive': # Boolean indicating whether the users uploads should 781 'posting:default:sensitive': # Boolean indicating whether the user's uploads should
782 # be marked sensitive by default 782 # be marked sensitive by default
783 'posting:default:language': # The users default post language, if set (None if not) 783 'posting:default:language': # The user's default post language, if set (None if not)
784 'reading:expand:media': # How the user wishes to be shown sensitive media. Can be 784 'reading:expand:media': # How the user wishes to be shown sensitive media. Can be
785 # 'default' (hide if sensitive), 'hide_all' or 'show_all' 785 # 'default' (hide if sensitive), 'hide_all' or 'show_all'
786 'reading:expand:spoilers': # Boolean indicating whether the user wishes to expand 786 'reading:expand:spoilers': # Boolean indicating whether the user wishes to expand
787 # content warnings by default 787 # content warnings by default
788 } 788 }
789 789
790Featured tag dicts 790Featured tag dicts
791~~~~~~~~~~~~~~~~~~ 791~~~~~~~~~~~~~~~~~~
792.. _featured tag dict: 792.. _featured tag dict:
@@ -799,10 +799,10 @@ Featured tag dicts
799 'id': # The featured tags id 799 'id': # The featured tags id
800 'name': # The featured tags name (without leading #) 800 'name': # The featured tags name (without leading #)
801 'statuses_count': # Number of publicly visible statuses posted with this hashtag that this instance knows about 801 'statuses_count': # Number of publicly visible statuses posted with this hashtag that this instance knows about
802 'last_status_at': # The last time a public status containing this hashtag was added to this instances database 802 'last_status_at': # The last time a public status containing this hashtag was added to this instance's database
803 # (can be None if there are none) 803 # (can be None if there are none)
804 } 804 }
805 805
806Read marker dicts 806Read marker dicts
807~~~~~~~~~~~~~~~~~ 807~~~~~~~~~~~~~~~~~
808.. _read marker dict: 808.. _read marker dict:
@@ -815,7 +815,7 @@ Read marker dicts
815 'last_read_id': # ID of the last read object in the timeline 815 'last_read_id': # ID of the last read object in the timeline
816 'version': # A counter that is incremented whenever the marker is set to a new status 816 'version': # A counter that is incremented whenever the marker is set to a new status
817 'updated_at': # The time the marker was last set, as a datetime object 817 'updated_at': # The time the marker was last set, as a datetime object
818 } 818 }
819 819
820Announcement dicts 820Announcement dicts
821~~~~~~~~~~~~~~~~~~ 821~~~~~~~~~~~~~~~~~~
@@ -824,7 +824,7 @@ Announcement dicts
824.. code-block:: python 824.. code-block:: python
825 825
826 mastodon.annoucements()[0] 826 mastodon.annoucements()[0]
827 # Returns the following dictionary: 827 # Returns the following dictionary:
828 { 828 {
829 'id': # The annoucements id 829 'id': # The annoucements id
830 'content': # The contents of the annoucement, as an html string 830 'content': # The contents of the annoucement, as an html string
@@ -852,7 +852,7 @@ Admin account dicts
852.. _admin account dict: 852.. _admin account dict:
853 853
854.. code-block:: python 854.. code-block:: python
855 855
856 mastodon.admin_account(id) 856 mastodon.admin_account(id)
857 # Returns the following dictionary 857 # Returns the following dictionary
858 { 858 {
@@ -860,10 +860,10 @@ Admin account dicts
860 'username': # The users username, no leading @ 860 'username': # The users username, no leading @
861 'domain': # The users domain 861 'domain': # The users domain
862 'created_at': # The time of account creation 862 'created_at': # The time of account creation
863 'email': # For local users, the users e-mail 863 'email': # For local users, the user's email
864 'ip': # For local users, the users last known IP address 864 'ip': # For local users, the user's last known IP address
865 'role': # 'admin', 'moderator' or None 865 'role': # 'admin', 'moderator' or None
866 'confirmed': # For local users, False if the user has not confirmed their e-mail, True otherwise 866 'confirmed': # For local users, False if the user has not confirmed their email, True otherwise
867 'suspended': # Boolean indicating whether the user has been suspended 867 'suspended': # Boolean indicating whether the user has been suspended
868 'silenced': # Boolean indicating whether the user has been suspended 868 'silenced': # Boolean indicating whether the user has been suspended
869 'disabled': # For local users, boolean indicating whether the user has had their login disabled 869 'disabled': # For local users, boolean indicating whether the user has had their login disabled
@@ -871,29 +871,29 @@ Admin account dicts
871 'locale': # For local users, the locale the user has set, 871 'locale': # For local users, the locale the user has set,
872 'invite_request': # If the user requested an invite, the invite request comment of that user. (TODO permanent?) 872 'invite_request': # If the user requested an invite, the invite request comment of that user. (TODO permanent?)
873 'invited_by_account_id': # Present if the user was invited by another user and set to the inviting users id. 873 'invited_by_account_id': # Present if the user was invited by another user and set to the inviting users id.
874 'account': # The users account, as a standard user dict 874 'account': # The user's account, as a standard user dict
875 } 875 }
876 876
877App registration and user authentication 877App registration and user authentication
878---------------------------------------- 878----------------------------------------
879Before you can use the mastodon API, you have to register your 879Before you can use the Mastodon API, you have to register your
880application (which gets you a client key and client secret) 880application (which gets you a client key and client secret)
881and then log in (which gets you an access token). These functions 881and then log in (which gets you an access token). These functions
882allow you to do those things. Additionally, it is also possible 882allow you to do those things. Additionally, it is also possible
883to programmatically register a new user. 883to programmatically register a new user.
884 884
885For convenience, once you have a client id, secret and access token, 885For convenience, once you have a client id, secret and access token,
886you can simply pass them to the constructor of the class, too! 886you can simply pass them to the constructor of the class, too!
887 887
888Note that while it is perfectly reasonable to log back in whenever 888Note that while it is perfectly reasonable to log back in whenever
889your app starts, registering a new application on every 889your app starts, registering a new application on every
890startup is not, so don't do that - instead, register an application 890startup is not, so don't do that - instead, register an application
891once, and then persist your client id and secret. A convenient method 891once, and then persist your client id and secret. A convenient method
892for this is provided by the functions dealing with registering the app, 892for this is provided by the functions dealing with registering the app,
893logging in and the Mastodon classes constructor. 893logging in and the Mastodon classes constructor.
894 894
895To talk to an instance different from the flagship instance, specify 895To talk to an instance different from the flagship instance, specify
896the api_base_url (usually, just the URL of the instance, i.e. 896the api_base_url (usually, just the URL of the instance, i.e.
897https://mastodon.social/ for the flagship instance). If no protocol 897https://mastodon.social/ for the flagship instance). If no protocol
898is specified, Mastodon.py defaults to https. 898is specified, Mastodon.py defaults to https.
899 899
@@ -909,17 +909,17 @@ Versioning
909---------- 909----------
910Mastodon.py will check if a certain endpoint is available before doing API 910Mastodon.py will check if a certain endpoint is available before doing API
911calls. By default, it checks against the version of Mastodon retrieved on 911calls. By default, it checks against the version of Mastodon retrieved on
912init(), or the version you specified. Mastodon.py can be set (in the 912init(), or the version you specified. Mastodon.py can be set (in the
913constructor) to either check if an endpoint is available at all (this is the 913constructor) to either check if an endpoint is available at all (this is the
914default) or to check if the endpoint is available and behaves as in the newest 914default) or to check if the endpoint is available and behaves as in the newest
915Mastodon version (with regards to parameters as well as return values). 915Mastodon version (with regards to parameters as well as return values).
916Version checking can also be disabled altogether. If a version check fails, 916Version checking can also be disabled altogether. If a version check fails,
917Mastodon.py throws a `MastodonVersionError`. 917Mastodon.py throws a `MastodonVersionError`.
918 918
919With the following functions, you can make Mastodon.py re-check the server 919With the following functions, you can make Mastodon.py re-check the server
920version or explicitly determine if a specific minimum Version is available. 920version or explicitly determine if a specific minimum Version is available.
921Long-running applications that aim to support multiple Mastodon versions 921Long-running applications that aim to support multiple Mastodon versions
922should do this from time to time in case a server they are running against 922should do this from time to time in case a server they are running against
923updated. 923updated.
924 924
925.. automethod:: Mastodon.retrieve_mastodon_version 925.. automethod:: Mastodon.retrieve_mastodon_version
@@ -979,7 +979,7 @@ This function allows you to get and refresh information about polls.
979 979
980Reading data: Notifications 980Reading data: Notifications
981--------------------------- 981---------------------------
982This function allows you to get information about a users notifications. 982This function allows you to get information about a user's notifications.
983 983
984.. automethod:: Mastodon.notifications 984.. automethod:: Mastodon.notifications
985 985
@@ -1020,7 +1020,7 @@ Reading data: Follow suggestions
1020Reading data: Profile directory 1020Reading data: Profile directory
1021~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1021~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1022 1022
1023.. authomethod:: Mastodon.directory 1023.. automethod:: Mastodon.directory
1024 1024
1025Reading data: Lists 1025Reading data: Lists
1026------------------- 1026-------------------
@@ -1033,7 +1033,7 @@ These functions allow you to view information about lists.
1033Reading data: Follows 1033Reading data: Follows
1034--------------------- 1034---------------------
1035 1035
1036.. automethod:: Mastodon.followshttps://docs.joinmastodon.org/api/rest 1036.. automethod:: Mastodon.follows
1037 1037
1038Reading data: Favourites 1038Reading data: Favourites
1039------------------------ 1039------------------------
@@ -1078,7 +1078,7 @@ of reports filed by the logged in user. It has since been removed.
1078 1078
1079 1079
1080Writing data: Last-read markers 1080Writing data: Last-read markers
1081-------------------------- 1081--------------------------------
1082This function allows you to set get last read position for timelines. 1082This function allows you to set get last read position for timelines.
1083 1083
1084.. automethod:: Mastodon.markers_get 1084.. automethod:: Mastodon.markers_get
@@ -1139,8 +1139,8 @@ interact with already posted statuses.
1139 1139
1140Writing data: Scheduled statuses 1140Writing data: Scheduled statuses
1141~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1141~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1142Mastodon allows you to schedule statuses (using `status_post()`_. 1142Mastodon allows you to schedule statuses (using `status_post()`_).
1143The functions in this section allow you to update or delete thusly 1143The functions in this section allow you to update or delete
1144scheduled statuses. 1144scheduled statuses.
1145 1145
1146.. automethod:: Mastodon.scheduled_status_update 1146.. automethod:: Mastodon.scheduled_status_update
@@ -1171,7 +1171,6 @@ These functions allow you to interact with other accounts: To (un)follow and
1171(un)block. 1171(un)block.
1172 1172
1173.. automethod:: Mastodon.account_follow 1173.. automethod:: Mastodon.account_follow
1174.. automethod:: Mastodon.follows
1175.. automethod:: Mastodon.account_unfollow 1174.. automethod:: Mastodon.account_unfollow
1176.. automethod:: Mastodon.account_block 1175.. automethod:: Mastodon.account_block
1177.. automethod:: Mastodon.account_unblock 1176.. automethod:: Mastodon.account_unblock
@@ -1185,7 +1184,7 @@ These functions allow you to interact with other accounts: To (un)follow and
1185 1184
1186Writing data: Featured tags 1185Writing data: Featured tags
1187~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1186~~~~~~~~~~~~~~~~~~~~~~~~~~~
1188These functions allow setting which tags are featured on a users profile. 1187These functions allow setting which tags are featured on a user's profile.
1189 1188
1190.. automethod:: Mastodon.featured_tag_create 1189.. automethod:: Mastodon.featured_tag_create
1191.. automethod:: Mastodon.featured_tag_delete 1190.. automethod:: Mastodon.featured_tag_delete
@@ -1240,7 +1239,7 @@ Writing data: Reports
1240.. automethod:: Mastodon.report 1239.. automethod:: Mastodon.report
1241 1240
1242Writing data: Last-read markers 1241Writing data: Last-read markers
1243-------------------------- 1242-------------------------------
1244This function allows you to set the last read position for timelines to 1243This function allows you to set the last read position for timelines to
1245allow for persisting where the user was reading a timeline between sessions 1244allow for persisting where the user was reading a timeline between sessions
1246and clients / devices. 1245and clients / devices.
@@ -1296,12 +1295,12 @@ using the `on_abort` handler to fill in events since the last received one and t
1296Both `run_async` and `reconnect_async` default to false, and you'll have to set each to true 1295Both `run_async` and `reconnect_async` default to false, and you'll have to set each to true
1297separately to get the behaviour described above. 1296separately to get the behaviour described above.
1298 1297
1299The connection may be closed at any time by calling the handles close() method. The 1298The connection may be closed at any time by calling the handles close() method. The
1300current status of the handler thread can be checked with the handles is_alive() function, 1299current status of the handler thread can be checked with the handles is_alive() function,
1301and the streaming status can be checked by calling is_receiving(). 1300and the streaming status can be checked by calling is_receiving().
1302 1301
1303The streaming functions take instances of `StreamListener` as the `listener` parameter. 1302The streaming functions take instances of `StreamListener` as the `listener` parameter.
1304A `CallbackStreamListener` class that allows you to specify function callbacks 1303A `CallbackStreamListener` class that allows you to specify function callbacks
1305directly is included for convenience. 1304directly is included for convenience.
1306 1305
1307For new well-known events implement the streaming function in `StreamListener` or `CallbackStreamListener`. 1306For new well-known events implement the streaming function in `StreamListener` or `CallbackStreamListener`.
@@ -1335,7 +1334,7 @@ StreamListener
1335.. automethod:: StreamListener.on_notification 1334.. automethod:: StreamListener.on_notification
1336.. automethod:: StreamListener.on_delete 1335.. automethod:: StreamListener.on_delete
1337.. automethod:: StreamListener.on_conversation 1336.. automethod:: StreamListener.on_conversation
1338.. automethod:: StreamListener.on_status_update 1337.. automethod:: StreamListener.on_status_update
1339.. automethod:: StreamListener.on_unknown_event 1338.. automethod:: StreamListener.on_unknown_event
1340.. automethod:: StreamListener.on_abort 1339.. automethod:: StreamListener.on_abort
1341.. automethod:: StreamListener.handle_heartbeat 1340.. automethod:: StreamListener.handle_heartbeat
@@ -1348,14 +1347,14 @@ CallbackStreamListener
1348Push subscriptions 1347Push subscriptions
1349------------------ 1348------------------
1350These functions allow you to manage webpush subscriptions and to decrypt received 1349These functions allow you to manage webpush subscriptions and to decrypt received
1351pushes. Note that the intended setup is not mastodon pushing directly to a users client - 1350pushes. Note that the intended setup is not Mastodon pushing directly to a user's client -
1352the push endpoint should usually be a relay server that then takes care of delivering the 1351the push endpoint should usually be a relay server that then takes care of delivering the
1353(encrypted) push to the end user via some mechanism, where it can then be decrypted and 1352(encrypted) push to the end user via some mechanism, where it can then be decrypted and
1354displayed. 1353displayed.
1355 1354
1356Mastodon allows an application to have one webpush subscription per user at a time. 1355Mastodon allows an application to have one webpush subscription per user at a time.
1357 1356
1358All crypto utilities require Mastodon.pys optional "webpush" feature dependencies 1357All crypto utilities require Mastodon.py's optional "webpush" feature dependencies
1359(specifically, the "cryptography" and "http_ece" packages). 1358(specifically, the "cryptography" and "http_ece" packages).
1360 1359
1361.. automethod:: Mastodon.push_subscription 1360.. automethod:: Mastodon.push_subscription
@@ -1372,8 +1371,8 @@ Moderation API
1372-------------- 1371--------------
1373These functions allow you to perform moderation actions on users and generally 1372These functions allow you to perform moderation actions on users and generally
1374process reports using the API. To do this, you need access to the "admin:read" and/or 1373process reports using the API. To do this, you need access to the "admin:read" and/or
1375"admin:write" scopes or their more granular variants (both for the application and the 1374"admin:write" scopes or their more granular variants (both for the application and the
1376access token), as well as at least moderator access. Mastodon.py will not request these 1375access token), as well as at least moderator access. Mastodon.py will not request these
1377by default, as that would be very dangerous. 1376by default, as that would be very dangerous.
1378 1377
1379BIG WARNING: TREAT ANY ACCESS TOKENS THAT HAVE ADMIN CREDENTIALS AS EXTREMELY, MASSIVELY 1378BIG WARNING: TREAT ANY ACCESS TOKENS THAT HAVE ADMIN CREDENTIALS AS EXTREMELY, MASSIVELY
@@ -1403,10 +1402,10 @@ have admin: scopes attached with a lot of care, but be extra careful with those
1403 1402
1404Acknowledgements 1403Acknowledgements
1405---------------- 1404----------------
1406Mastodon.py contains work by a large amount of contributors, many of which have 1405Mastodon.py contains work by a large number of contributors, many of which have
1407put significant work into making it a better library. You can find some information 1406put significant work into making it a better library. You can find some information
1408about who helped with which particular feature or fix in the changelog. 1407about who helped with which particular feature or fix in the changelog.
1409 1408
1410.. _Mastodon: https://github.com/mastodon/mastodon 1409.. _Mastodon: https://github.com/mastodon/mastodon
1411.. _Mastodon flagship instance: http://mastodon.social/ 1410.. _Mastodon flagship instance: https://mastodon.social/
1412.. _Official Mastodon api docs: https://docs.joinmastodon.org/api/rest 1411.. _Official Mastodon API docs: https://docs.joinmastodon.org/client/intro/
Powered by cgit v1.2.3 (git 2.41.0)