aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/index.rst111
-rw-r--r--mastodon/.Mastodon.py.kate-swpbin0 -> 106 bytes
-rw-r--r--mastodon/Mastodon.py386
3 files changed, 374 insertions, 123 deletions
diff --git a/docs/index.rst b/docs/index.rst
index dfd91ab..4dd6403 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -134,7 +134,7 @@ If you are only interested in the fact an error was raised somewhere in
134Mastodon.py, and not the details, this is the exception you can catch. 134Mastodon.py, and not the details, this is the exception you can catch.
135 135
136`MastodonIllegalArgumentError` is generally a programming problem - you asked the 136`MastodonIllegalArgumentError` is generally a programming problem - you asked the
137API to do something obviously invalid (i.e. specify a privacy scope that does 137API to do something obviously invalid (i.e. specify a privacy option that does
138not exist). 138not exist).
139 139
140`MastodonFileNotFoundError` and `MastodonNetworkError` are IO errors - could be you 140`MastodonFileNotFoundError` and `MastodonNetworkError` are IO errors - could be you
@@ -156,6 +156,8 @@ and are parsed into python datetime objects.
156 156
157User dicts 157User dicts
158~~~~~~~~~~ 158~~~~~~~~~~
159.. _user dict:
160
159.. code-block:: python 161.. code-block:: python
160 162
161 mastodon.account(<numerical id>) 163 mastodon.account(<numerical id>)
@@ -176,10 +178,21 @@ User dicts
176 'header': # URL for their header image, can be animated 178 'header': # URL for their header image, can be animated
177 'avatar_static': # URL for their avatar, never animated 179 'avatar_static': # URL for their avatar, never animated
178 'header_static': # URL for their header image, never animated 180 'header_static': # URL for their header image, never animated
181 'source': # Additional information - only present for user dict returned from account_verify_credentials()
179 } 182 }
180 183
184 mastodon.account_verify_credentials()["source"]
185 # Returns the following dictionary:
186 {
187 'privacy': # The users default visibility setting ("private", "unlisted" or "public")
188 'sensitive': # Denotes whether user media should be marked sensitive by default
189 'note': # Plain text version of the users bio
190 }
191
181Toot dicts 192Toot dicts
182~~~~~~~~~~ 193~~~~~~~~~~
194.. _toot dict:
195
183.. code-block:: python 196.. code-block:: python
184 197
185 mastodon.toot("Hello from Python") 198 mastodon.toot("Hello from Python")
@@ -213,6 +226,8 @@ Toot dicts
213 226
214Mention dicts 227Mention dicts
215~~~~~~~~~~~~~ 228~~~~~~~~~~~~~
229.. _mention dict:
230
216.. code-block:: python 231.. code-block:: python
217 232
218 { 233 {
@@ -224,6 +239,8 @@ Mention dicts
224 239
225Hashtag dicts 240Hashtag dicts
226~~~~~~~~~~~~~ 241~~~~~~~~~~~~~
242.. _hashtag dict:
243
227.. code-block:: python 244.. code-block:: python
228 245
229 { 246 {
@@ -233,6 +250,8 @@ Hashtag dicts
233 250
234Emoji dicts 251Emoji dicts
235~~~~~~~~~~~ 252~~~~~~~~~~~
253.. _emoji dict:
254
236.. code-block:: python 255.. code-block:: python
237 256
238 { 257 {
@@ -243,6 +262,8 @@ Emoji dicts
243 262
244Relationship dicts 263Relationship dicts
245~~~~~~~~~~~~~~~~~~ 264~~~~~~~~~~~~~~~~~~
265.. _relationship dict:
266
246.. code-block:: python 267.. code-block:: python
247 268
248 mastodon.account_follow(<numerical id>) 269 mastodon.account_follow(<numerical id>)
@@ -259,21 +280,25 @@ Relationship dicts
259 280
260Notification dicts 281Notification dicts
261~~~~~~~~~~~~~~~~~~ 282~~~~~~~~~~~~~~~~~~
283.. _notification dict:
284
262.. code-block:: python 285.. code-block:: python
263 286
264 mastodon.notifications()[0] 287 mastodon.notifications()[0]
265 # Returns the following dictionary: 288 # Returns the following dictionary:
266 { 289 {
267 'id': # id of the notification. 290 'id': # id of the notification
268 'type': # "mention", "reblog", "favourite" or "follow". 291 'type': # "mention", "reblog", "favourite" or "follow"
269 'created_at': # The time the notification was created. 292 'created_at': # The time the notification was created
270 'account': # User dict of the user from whom the notification originates. 293 'account': # User dict of the user from whom the notification originates
271 'status': # In case of "mention", the mentioning status. 294 'status': # In case of "mention", the mentioning status
272 # In case of reblog / favourite, the reblogged / favourited status. 295 # In case of reblog / favourite, the reblogged / favourited status
273 } 296 }
274 297
275Context dicts 298Context dicts
276~~~~~~~~~~~~~ 299~~~~~~~~~~~~~
300.. _context dict:
301
277.. code-block:: python 302.. code-block:: python
278 303
279 mastodon.status_context(<numerical id>) 304 mastodon.status_context(<numerical id>)
@@ -283,8 +308,23 @@ Context dicts
283 'descendants': # A list of toot dicts 308 'descendants': # A list of toot dicts
284 } 309 }
285 310
311List dicts
312~~~~~~~~~~
313.. _list dict:
314
315.. code-block:: python
316
317 mastodon.list(<numerical id>)
318 # Returns the following dictionary:
319 {
320 'id': # id of the list
321 'title': # title of the list
322 }
323
286Media dicts 324Media dicts
287~~~~~~~~~~~ 325~~~~~~~~~~~
326.. _media dict:
327
288.. code-block:: python 328.. code-block:: python
289 329
290 mastodon.media_post("image.jpg", "image/jpeg") 330 mastodon.media_post("image.jpg", "image/jpeg")
@@ -309,6 +349,8 @@ Media dicts
309 349
310Card dicts 350Card dicts
311~~~~~~~~~~ 351~~~~~~~~~~
352.. _card dict:
353
312.. code-block:: python 354.. code-block:: python
313 355
314 mastodon.status_card(<numerical id>): 356 mastodon.status_card(<numerical id>):
@@ -331,8 +373,24 @@ Card dicts
331 'provider_url': # URL pointing to the embeds provider 373 'provider_url': # URL pointing to the embeds provider
332 } 374 }
333 375
376Search result dicts
377~~~~~~~~~~~~~~~~~~~
378.. _search result dict:
379
380.. code-block:: python
381
382 mastodon.search("<query>")
383 # Returns the folowing dictionary
384 {
385 'accounts': # List of account dicts resulting from the query
386 'hashtags': # List of hashtag dicts resulting from the query
387 'statuses': # List of toot dicts resulting from the query
388 }
389
334Instance dicts 390Instance dicts
335~~~~~~~~~~~~~~ 391~~~~~~~~~~~~~~
392.. _instance dict:
393
336.. code-block:: python 394.. code-block:: python
337 395
338 mastodon.instance() 396 mastodon.instance()
@@ -348,6 +406,8 @@ Instance dicts
348 406
349Report dicts 407Report dicts
350~~~~~~~~~~~~ 408~~~~~~~~~~~~
409.. _report dict:
410
351.. code-block:: python 411.. code-block:: python
352 412
353 mastodon.reports()[0] 413 mastodon.reports()[0]
@@ -383,6 +443,7 @@ is specified, Mastodon.py defaults to https.
383 443
384.. automethod:: Mastodon.create_app 444.. automethod:: Mastodon.create_app
385.. automethod:: Mastodon.__init__ 445.. automethod:: Mastodon.__init__
446.. _log_in():
386.. automethod:: Mastodon.log_in 447.. automethod:: Mastodon.log_in
387.. automethod:: Mastodon.auth_request_url 448.. automethod:: Mastodon.auth_request_url
388 449
@@ -413,11 +474,14 @@ Reading data: Timelines
413This function allows you to access the timelines a logged in 474This function allows you to access the timelines a logged in
414user could see, as well as hashtag timelines and the public timeline. 475user could see, as well as hashtag timelines and the public timeline.
415 476
477.. _timeline():
416.. automethod:: Mastodon.timeline 478.. automethod:: Mastodon.timeline
417.. automethod:: Mastodon.timeline_home 479.. automethod:: Mastodon.timeline_home
418.. automethod:: Mastodon.timeline_local 480.. automethod:: Mastodon.timeline_local
419.. automethod:: Mastodon.timeline_public 481.. automethod:: Mastodon.timeline_public
482.. _timeline_hashtag():
420.. automethod:: Mastodon.timeline_hashtag 483.. automethod:: Mastodon.timeline_hashtag
484.. automethod:: Mastodon.timeline_list
421 485
422Reading data: Statuses 486Reading data: Statuses
423---------------------- 487----------------------
@@ -448,6 +512,14 @@ their relationships.
448.. automethod:: Mastodon.account_relationships 512.. automethod:: Mastodon.account_relationships
449.. automethod:: Mastodon.account_search 513.. automethod:: Mastodon.account_search
450 514
515Reading data: Lists
516-------------------
517These functions allow you to view information about lists.
518
519.. automethod:: Mastodon.lists
520.. automethod:: Mastodon.list
521.. automethod:: Mastodon.list_accounts
522
451Reading data: Follows 523Reading data: Follows
452--------------------- 524---------------------
453 525
@@ -468,7 +540,6 @@ Reading data: Searching
468 540
469.. automethod:: Mastodon.search 541.. automethod:: Mastodon.search
470 542
471
472Reading data: Mutes and blocks 543Reading data: Mutes and blocks
473------------------------------ 544------------------------------
474These functions allow you to get information about accounts that are 545These functions allow you to get information about accounts that are
@@ -487,11 +558,17 @@ Reading data: Domain blocks
487 558
488.. automethod:: Mastodon.domain_blocks 559.. automethod:: Mastodon.domain_blocks
489 560
561Reading data: Emoji
562-------------------
563
564.. automethod:: Mastodon.custom_emojis
565
490Writing data: Statuses 566Writing data: Statuses
491---------------------- 567----------------------
492These functions allow you to post statuses to Mastodon and to 568These functions allow you to post statuses to Mastodon and to
493interact with already posted statuses. 569interact with already posted statuses.
494 570
571.. _status_post():
495.. automethod:: Mastodon.status_post 572.. automethod:: Mastodon.status_post
496.. automethod:: Mastodon.toot 573.. automethod:: Mastodon.toot
497.. automethod:: Mastodon.status_reblog 574.. automethod:: Mastodon.status_reblog
@@ -523,6 +600,19 @@ These functions allow you to interact with other accounts: To (un)follow and
523.. automethod:: Mastodon.account_unmute 600.. automethod:: Mastodon.account_unmute
524.. automethod:: Mastodon.account_update_credentials 601.. automethod:: Mastodon.account_update_credentials
525 602
603Writing data: Lists
604-------------------
605These functions allow you to create, maintain and delete lists.
606
607When creating lists, note that (As of Mastodon 2.1.0), a user can only
608have a maximum of 50 lists.
609
610.. automethod:: Mastodon.list_create
611.. automethod:: Mastodon.list_update
612.. automethod:: Mastodon.list_delete
613.. automethod:: Mastodon.list_accounts_add
614.. automethod:: Mastodon.list_accounts_delete
615
526Writing data: Follow requests 616Writing data: Follow requests
527----------------------------- 617-----------------------------
528These functions allow you to accept or reject incoming follow requests. 618These functions allow you to accept or reject incoming follow requests.
@@ -536,6 +626,8 @@ This function allows you to upload media to Mastodon. The returned
536media IDs (Up to 4 at the same time) can then be used with post_status 626media IDs (Up to 4 at the same time) can then be used with post_status
537to attach media to statuses. 627to attach media to statuses.
538 628
629.. _media_post():
630
539.. automethod:: Mastodon.media_post 631.. automethod:: Mastodon.media_post
540 632
541Writing data: Reports 633Writing data: Reports
@@ -571,7 +663,7 @@ will return a handle corresponding to the open connection. The
571connection may be closed at any time by calling the handles close() method, and the 663connection may be closed at any time by calling the handles close() method, and the
572status of the connection can be verified calling is_alive() on the handle. 664status of the connection can be verified calling is_alive() on the handle.
573 665
574The streaming functions take instances of `StreamListener` as a parameter. 666The streaming functions take instances of `StreamListener` as the `listener` parameter.
575A `CallbackStreamListener` class that allows you to specify function callbacks 667A `CallbackStreamListener` class that allows you to specify function callbacks
576directly is included for convenience. 668directly is included for convenience.
577 669
@@ -579,6 +671,7 @@ directly is included for convenience.
579.. automethod:: Mastodon.stream_public 671.. automethod:: Mastodon.stream_public
580.. automethod:: Mastodon.stream_local 672.. automethod:: Mastodon.stream_local
581.. automethod:: Mastodon.stream_hashtag 673.. automethod:: Mastodon.stream_hashtag
674.. automethod:: Mastodon.stream_list
582 675
583StreamListener 676StreamListener
584~~~~~~~~~~~~~~ 677~~~~~~~~~~~~~~
diff --git a/mastodon/.Mastodon.py.kate-swp b/mastodon/.Mastodon.py.kate-swp
new file mode 100644
index 0000000..60f8d57
--- /dev/null
+++ b/mastodon/.Mastodon.py.kate-swp
Binary files differ
diff --git a/mastodon/Mastodon.py b/mastodon/Mastodon.py
index 641b742..f15ee23 100644
--- a/mastodon/Mastodon.py
+++ b/mastodon/Mastodon.py
@@ -72,16 +72,16 @@ class Mastodon:
72 def create_app(client_name, scopes=['read', 'write', 'follow'], redirect_uris=None, website=None, to_file=None, 72 def create_app(client_name, scopes=['read', 'write', 'follow'], redirect_uris=None, website=None, to_file=None,
73 api_base_url=__DEFAULT_BASE_URL, request_timeout=__DEFAULT_TIMEOUT): 73 api_base_url=__DEFAULT_BASE_URL, request_timeout=__DEFAULT_TIMEOUT):
74 """ 74 """
75 Create a new app with given client_name and scopes (read, write, follow) 75 Create a new app with given `client_name` and `scopes` (read, write, follow)
76 76
77 Specify redirect_uris if you want users to be redirected to a certain page after authenticating. 77 Specify `redirect_uris` if you want users to be redirected to a certain page after authenticating.
78 Specify to_file to persist your apps info to a file so you can use them in the constructor. 78 Specify `to_file` to persist your apps info to a file so you can use them in the constructor.
79 Specify api_base_url if you want to register an app on an instance different from the flagship one. 79 Specify `api_base_url` if you want to register an app on an instance different from the flagship one.
80 80
81 Presently, app registration is open by default, but this is not guaranteed to be the case for all 81 Presently, app registration is open by default, but this is not guaranteed to be the case for all
82 future mastodon instances or even the flagship instance in the future. 82 future mastodon instances or even the flagship instance in the future.
83 83
84 Returns client_id and client_secret. 84 Returns `client_id` and `client_secret`, both as strings.
85 """ 85 """
86 api_base_url = Mastodon.__protocolize(api_base_url) 86 api_base_url = Mastodon.__protocolize(api_base_url)
87 87
@@ -118,13 +118,13 @@ class Mastodon:
118 ratelimit_method="wait", ratelimit_pacefactor=1.1, 118 ratelimit_method="wait", ratelimit_pacefactor=1.1,
119 request_timeout=__DEFAULT_TIMEOUT, mastodon_version=None): 119 request_timeout=__DEFAULT_TIMEOUT, mastodon_version=None):
120 """ 120 """
121 Create a new API wrapper instance based on the given client_secret and client_id. If you 121 Create a new API wrapper instance based on the given `client_secret` and `client_id`. If you
122 give a client_id and it is not a file, you must also give a secret. 122 give a `client_id` and it is not a file, you must also give a secret.
123 123
124 You can also specify an access_token, directly or as a file (as written by log_in). 124 You can also specify an `access_token`, directly or as a file (as written by `log_in()`_).
125 125
126 Mastodon.py can try to respect rate limits in several ways, controlled by ratelimit_method. 126 Mastodon.py can try to respect rate limits in several ways, controlled by `ratelimit_method`.
127 "throw" makes functions throw a MastodonRatelimitError when the rate 127 "throw" makes functions throw a `MastodonRatelimitError` when the rate
128 limit is hit. "wait" mode will, once the limit is hit, wait and retry the request as soon 128 limit is hit. "wait" mode will, once the limit is hit, wait and retry the request as soon
129 as the rate limit resets, until it succeeds. "pace" works like throw, but tries to wait in 129 as the rate limit resets, until it succeeds. "pace" works like throw, but tries to wait in
130 between calls so that the limit is generally not hit (How hard it tries to not hit the rate 130 between calls so that the limit is generally not hit (How hard it tries to not hit the rate
@@ -132,15 +132,15 @@ class Mastodon:
132 even in "wait" and "pace" mode, requests can still fail due to network or other problems! Also 132 even in "wait" and "pace" mode, requests can still fail due to network or other problems! Also
133 note that "pace" and "wait" are NOT thread safe. 133 note that "pace" and "wait" are NOT thread safe.
134 134
135 Specify api_base_url if you wish to talk to an instance other than the flagship one. 135 Specify `api_base_url` if you wish to talk to an instance other than the flagship one.
136 If a file is given as client_id, read client ID and secret from that file. 136 If a file is given as `client_id`, client ID and secret are read from that file.
137 137
138 By default, a timeout of 300 seconds is used for all requests. If you wish to change this, 138 By default, a timeout of 300 seconds is used for all requests. If you wish to change this,
139 pass the desired timeout (in seconds) as request_timeout. 139 pass the desired timeout (in seconds) as `request_timeout`.
140 140
141 The mastodon_version parameter can be used to specify the version of Mastodon that Mastodon.py will 141 The `mastodon_version` parameter can be used to specify the version of Mastodon that Mastodon.py will
142 expect to be installed on the server. The function will throw an error if an unparseable 142 expect to be installed on the server. The function will throw an error if an unparseable
143 Version is specified. If no version is specified, Mastodon.py will set mastodon_version to the 143 Version is specified. If no version is specified, Mastodon.py will set `mastodon_version` to the
144 detected version. 144 detected version.
145 """ 145 """
146 self.api_base_url = Mastodon.__protocolize(api_base_url) 146 self.api_base_url = Mastodon.__protocolize(api_base_url)
@@ -240,21 +240,21 @@ class Mastodon:
240 code=None, redirect_uri="urn:ietf:wg:oauth:2.0:oob", refresh_token=None, 240 code=None, redirect_uri="urn:ietf:wg:oauth:2.0:oob", refresh_token=None,
241 scopes=['read', 'write', 'follow'], to_file=None): 241 scopes=['read', 'write', 'follow'], to_file=None):
242 """ 242 """
243 Your username is the e-mail you use to log in into mastodon. 243 Get the access token for a user.
244 244
245 Can persist access token to file, to be used in the constructor. 245 The username is the e-mail used to log in into mastodon.
246
247 Supports refresh_token but Mastodon.social doesn't implement it at the moment.
248 246
249 Handles password, authorization_code, and refresh_token authentication. 247 Can persist access token to file `to_file`, to be used in the constructor.
250 248
251 Will throw a MastodonIllegalArgumentError if username / password 249 Handles password and OAuth-based authorization.
250
251 Will throw a `MastodonIllegalArgumentError` if username / password
252 are wrong, scopes are not valid or granted scopes differ from requested. 252 are wrong, scopes are not valid or granted scopes differ from requested.
253 253
254 For OAuth2 documentation, compare 254 For OAuth2 documentation, compare
255 https://github.com/doorkeeper-gem/doorkeeper/wiki/Interacting-as-an-OAuth-client-with-Doorkeeper 255 https://github.com/doorkeeper-gem/doorkeeper/wiki/Interacting-as-an-OAuth-client-with-Doorkeeper
256 256
257 Returns the access token. 257 Returns the access token as a string.
258 """ 258 """
259 if username is not None and password is not None: 259 if username is not None and password is not None:
260 params = self.__generate_params(locals(), ['scopes', 'to_file', 'code', 'refresh_token']) 260 params = self.__generate_params(locals(), ['scopes', 'to_file', 'code', 'refresh_token'])
@@ -306,7 +306,9 @@ class Mastodon:
306 """ 306 """
307 Retrieve basic information about the instance, including the URI and administrative contact email. 307 Retrieve basic information about the instance, including the URI and administrative contact email.
308 308
309 Returns an instance dict. 309 Does not require authentication.
310
311 Returns an `instance dict`_.
310 """ 312 """
311 return self.__instance() 313 return self.__instance()
312 314
@@ -322,13 +324,13 @@ class Mastodon:
322 @api_version("1.0.0") 324 @api_version("1.0.0")
323 def timeline(self, timeline="home", max_id=None, since_id=None, limit=None): 325 def timeline(self, timeline="home", max_id=None, since_id=None, limit=None):
324 """ 326 """
325 Fetch statuses, most recent ones first. Timeline can be 'home', 'local', 'public', 327 Fetch statuses, most recent ones first. `timeline` can be 'home', 'local', 'public',
326 or 'tag/hashtag'. See the following functions documentation for what those do. 328 'tag/hashtag' or 'list/id'. See the following functions documentation for what those do.
327 Local hashtag timelines are supported via the timeline_hashtag() function. 329 Local hashtag timelines are supported via the `timeline_hashtag()`_ function.
328 330
329 The default timeline is the "home" timeline. 331 The default timeline is the "home" timeline.
330 332
331 Returns a list of toot dicts. 333 Returns a list of `toot dicts`_.
332 """ 334 """
333 if max_id != None: 335 if max_id != None:
334 max_id = self.__unpack_id(max_id) 336 max_id = self.__unpack_id(max_id)
@@ -349,9 +351,9 @@ class Mastodon:
349 @api_version("1.0.0") 351 @api_version("1.0.0")
350 def timeline_home(self, max_id=None, since_id=None, limit=None): 352 def timeline_home(self, max_id=None, since_id=None, limit=None):
351 """ 353 """
352 Fetch the authenticated users home timeline (i.e. followed users and self). 354 Fetch the logged-in users home timeline (i.e. followed users and self).
353 355
354 Returns a list of toot dicts. 356 Returns a list of `toot dicts`_.
355 """ 357 """
356 return self.timeline('home', max_id=max_id, since_id=since_id, 358 return self.timeline('home', max_id=max_id, since_id=since_id,
357 limit=limit) 359 limit=limit)
@@ -361,7 +363,7 @@ class Mastodon:
361 """ 363 """
362 Fetches the local / instance-wide timeline, not including replies. 364 Fetches the local / instance-wide timeline, not including replies.
363 365
364 Returns a list of toot dicts. 366 Returns a list of `toot dicts`_.
365 """ 367 """
366 return self.timeline('local', max_id=max_id, since_id=since_id, 368 return self.timeline('local', max_id=max_id, since_id=since_id,
367 limit=limit) 369 limit=limit)
@@ -371,7 +373,7 @@ class Mastodon:
371 """ 373 """
372 Fetches the public / visible-network timeline, not including replies. 374 Fetches the public / visible-network timeline, not including replies.
373 375
374 Returns a list of toot dicts. 376 Returns a list of `toot dicts`_.
375 """ 377 """
376 return self.timeline('public', max_id=max_id, since_id=since_id, 378 return self.timeline('public', max_id=max_id, since_id=since_id,
377 limit=limit) 379 limit=limit)
@@ -382,9 +384,9 @@ class Mastodon:
382 Fetch a timeline of toots with a given hashtag. The hashtag parameter 384 Fetch a timeline of toots with a given hashtag. The hashtag parameter
383 should not contain the leading #. 385 should not contain the leading #.
384 386
385 Set "local" to True to retrieve only instance-local tagged posts. 387 Set `local` to True to retrieve only instance-local tagged posts.
386 388
387 Returns a list of toot dicts. 389 Returns a list of `toot dicts`_.
388 """ 390 """
389 if hashtag.startswith("#"): 391 if hashtag.startswith("#"):
390 raise MastodonIllegalArgumentError("Hashtag parameter should omit leading #") 392 raise MastodonIllegalArgumentError("Hashtag parameter should omit leading #")
@@ -405,6 +407,17 @@ class Mastodon:
405 407
406 return self.__api_request('GET', url, params) 408 return self.__api_request('GET', url, params)
407 409
410 @api_version("2.1.0")
411 def timeline_list(self, id, max_id=None, since_id=None, limit=None):
412 """
413 Fetches a timeline containing all the toots by users in a given list.
414
415 Returns a list of `toot dicts`_.
416 """
417 id = self.__unpack_id(id)
418 return self.timeline('list/{0}'.format(id), max_id=max_id,
419 since_id=since_id, limit=limit)
420
408 ### 421 ###
409 # Reading data: Statuses 422 # Reading data: Statuses
410 ### 423 ###
@@ -413,7 +426,9 @@ class Mastodon:
413 """ 426 """
414 Fetch information about a single toot. 427 Fetch information about a single toot.
415 428
416 Returns a toot dict. 429 Does not require authentication for publicly visible statuses.
430
431 Returns a `toot dict`_.
417 """ 432 """
418 id = self.__unpack_id(id) 433 id = self.__unpack_id(id)
419 url = '/api/v1/statuses/{0}'.format(str(id)) 434 url = '/api/v1/statuses/{0}'.format(str(id))
@@ -425,7 +440,9 @@ class Mastodon:
425 Fetch a card associated with a status. A card describes an object (such as an 440 Fetch a card associated with a status. A card describes an object (such as an
426 external video or link) embedded into a status. 441 external video or link) embedded into a status.
427 442
428 Returns a card dict. 443 Does not require authentication for publicly visible statuses.
444
445 Returns a `card dict`_.
429 """ 446 """
430 id = self.__unpack_id(id) 447 id = self.__unpack_id(id)
431 url = '/api/v1/statuses/{0}/card'.format(str(id)) 448 url = '/api/v1/statuses/{0}/card'.format(str(id))
@@ -436,7 +453,9 @@ class Mastodon:
436 """ 453 """
437 Fetch information about ancestors and descendants of a toot. 454 Fetch information about ancestors and descendants of a toot.
438 455
439 Returns a context dict. 456 Does not require authentication for publicly visible statuses.
457
458 Returns a `context dict`_.
440 """ 459 """
441 id = self.__unpack_id(id) 460 id = self.__unpack_id(id)
442 url = '/api/v1/statuses/{0}/context'.format(str(id)) 461 url = '/api/v1/statuses/{0}/context'.format(str(id))
@@ -447,7 +466,9 @@ class Mastodon:
447 """ 466 """
448 Fetch a list of users that have reblogged a status. 467 Fetch a list of users that have reblogged a status.
449 468
450 Returns a list of user dicts. 469 Does not require authentication for publicly visible statuses.
470
471 Returns a list of `user dicts`_.
451 """ 472 """
452 id = self.__unpack_id(id) 473 id = self.__unpack_id(id)
453 url = '/api/v1/statuses/{0}/reblogged_by'.format(str(id)) 474 url = '/api/v1/statuses/{0}/reblogged_by'.format(str(id))
@@ -458,7 +479,9 @@ class Mastodon:
458 """ 479 """
459 Fetch a list of users that have favourited a status. 480 Fetch a list of users that have favourited a status.
460 481
461 Returns a list of user dicts. 482 Does not require authentication for publicly visible statuses.
483
484 Returns a list of `user dicts`_.
462 """ 485 """
463 id = self.__unpack_id(id) 486 id = self.__unpack_id(id)
464 url = '/api/v1/statuses/{0}/favourited_by'.format(str(id)) 487 url = '/api/v1/statuses/{0}/favourited_by'.format(str(id))
@@ -470,12 +493,12 @@ class Mastodon:
470 @api_version("1.0.0") 493 @api_version("1.0.0")
471 def notifications(self, id=None, max_id=None, since_id=None, limit=None): 494 def notifications(self, id=None, max_id=None, since_id=None, limit=None):
472 """ 495 """
473 Fetch notifications (mentions, favourites, reblogs, follows) for the authenticated 496 Fetch notifications (mentions, favourites, reblogs, follows) for the logged-in
474 user. 497 user.
475 498
476 Can be passed an id to fetch a single notification. 499 Can be passed an `id` to fetch a single notification.
477 500
478 Returns a list of notification dicts. 501 Returns a list of `notification dicts`_.
479 """ 502 """
480 if max_id != None: 503 if max_id != None:
481 max_id = self.__unpack_id(max_id) 504 max_id = self.__unpack_id(max_id)
@@ -497,9 +520,9 @@ class Mastodon:
497 @api_version("1.0.0") 520 @api_version("1.0.0")
498 def account(self, id): 521 def account(self, id):
499 """ 522 """
500 Fetch account information by user id. 523 Fetch account information by user `id`.
501 524
502 Returns a user dict. 525 Returns a `user dict`_.
503 """ 526 """
504 id = self.__unpack_id(id) 527 id = self.__unpack_id(id)
505 url = '/api/v1/accounts/{0}'.format(str(id)) 528 url = '/api/v1/accounts/{0}'.format(str(id))
@@ -508,18 +531,21 @@ class Mastodon:
508 @api_version("1.0.0") 531 @api_version("1.0.0")
509 def account_verify_credentials(self): 532 def account_verify_credentials(self):
510 """ 533 """
511 Fetch authenticated user's account information. 534 Fetch logged-in user's account information.
512 535
513 Returns a user dict. 536 Returns a `user dict`_ (Starting from 2.1.0, with an additional "source" field).
514 """ 537 """
515 return self.__api_request('GET', '/api/v1/accounts/verify_credentials') 538 return self.__api_request('GET', '/api/v1/accounts/verify_credentials')
516 539
517 @api_version("1.0.0") 540 @api_version("1.0.0")
518 def account_statuses(self, id, max_id=None, since_id=None, limit=None): 541 def account_statuses(self, id, max_id=None, since_id=None, limit=None):
519 """ 542 """
520 Fetch statuses by user id. Same options as timeline are permitted. 543 Fetch statuses by user `id`. Same options as `timeline()`_ are permitted.
544 Returned toots are from the perspective of the logged-in user, i.e.
545 all statuses visible to the logged-in user (including DMs) are
546 included.
521 547
522 Returns a list of toot dicts. 548 Returns a list of `toot dicts`_.
523 """ 549 """
524 id = self.__unpack_id(id) 550 id = self.__unpack_id(id)
525 if max_id != None: 551 if max_id != None:
@@ -537,7 +563,7 @@ class Mastodon:
537 """ 563 """
538 Fetch users the given user is following. 564 Fetch users the given user is following.
539 565
540 Returns a list of user dicts. 566 Returns a list of `user dicts`_.
541 """ 567 """
542 id = self.__unpack_id(id) 568 id = self.__unpack_id(id)
543 if max_id != None: 569 if max_id != None:
@@ -555,7 +581,7 @@ class Mastodon:
555 """ 581 """
556 Fetch users the given user is followed by. 582 Fetch users the given user is followed by.
557 583
558 Returns a list of user dicts. 584 Returns a list of `user dicts`_.
559 """ 585 """
560 id = self.__unpack_id(id) 586 id = self.__unpack_id(id)
561 if max_id != None: 587 if max_id != None:
@@ -572,9 +598,9 @@ class Mastodon:
572 def account_relationships(self, id): 598 def account_relationships(self, id):
573 """ 599 """
574 Fetch relationship (following, followed_by, blocking, follow requested) of 600 Fetch relationship (following, followed_by, blocking, follow requested) of
575 the logged in user to a given account. id can be a list. 601 the logged in user to a given account. `id` can be a list.
576 602
577 Returns a list of relationship dicts. 603 Returns a list of `relationship dicts`_.
578 """ 604 """
579 id = self.__unpack_id(id) 605 id = self.__unpack_id(id)
580 params = self.__generate_params(locals()) 606 params = self.__generate_params(locals())
@@ -587,11 +613,23 @@ class Mastodon:
587 Fetch matching accounts. Will lookup an account remotely if the search term is 613 Fetch matching accounts. Will lookup an account remotely if the search term is
588 in the username@domain format and not yet in the database. 614 in the username@domain format and not yet in the database.
589 615
590 Returns a list of user dicts. 616 Returns a list of `user dicts`_.
591 """ 617 """
592 params = self.__generate_params(locals()) 618 params = self.__generate_params(locals())
593 return self.__api_request('GET', '/api/v1/accounts/search', params) 619 return self.__api_request('GET', '/api/v1/accounts/search', params)
594 620
621 @api_version("2.1.0")
622 def account_lists(self, id):
623 """
624 Get all of the logged in users lists which the specified user is
625 a member of.
626
627 Returns a list of `list dicts`_.
628 """
629 params = self.__generate_params(locals(), ['id'])
630 url = '/api/v1/accounts/{0}/lists'.format(str(id))
631 return self.__api_request('GET', url, params)
632
595 ### 633 ###
596 # Reading data: Searching 634 # Reading data: Searching
597 ### 635 ###
@@ -601,20 +639,61 @@ class Mastodon:
601 Fetch matching hashtags, accounts and statuses. Will search federated 639 Fetch matching hashtags, accounts and statuses. Will search federated
602 instances if resolve is True. 640 instances if resolve is True.
603 641
604 Returns a dict of lists. 642 Returns a `search result dict`_.
605 """ 643 """
606 params = self.__generate_params(locals()) 644 params = self.__generate_params(locals())
607 return self.__api_request('GET', '/api/v1/search', params) 645 return self.__api_request('GET', '/api/v1/search', params)
608 646
609 ### 647 ###
648 # Reading data: Lists
649 ###
650 @api_version("2.1.0")
651 def lists(self):
652 """
653 Fetch a list of all the Lists by the logged-in user.
654
655 Returns a list of `list dicts`_.
656 """
657 return self.__api_request('GET', '/api/v1/lists')
658
659 @api_version("2.1.0")
660 def list(self, id):
661 """
662 Fetch info about a specific list.
663
664 Returns a `list dict`_.
665 """
666 id = self.__unpack_id(id)
667 return self.__api_request('GET', '/api/v1/lists/{0}'.format(id))
668
669 @api_version("2.1.0")
670 def list_accounts(self, id, max_id=None, since_id=None, limit=None):
671 """
672 Get the accounts that are on the given list. A `limit` of 0 can
673 be specified to get all accounts without pagination.
674
675 Returns a list of `user dicts`_.
676 """
677 id = self.__unpack_id(id)
678
679 if max_id != None:
680 max_id = self.__unpack_id(max_id)
681
682 if since_id != None:
683 since_id = self.__unpack_id(since_id)
684
685 params = self.__generate_params(locals(), ['id'])
686 return self.__api_request('GET', '/api/v1/lists/{0}/accounts'.format(id))
687
688 ###
610 # Reading data: Mutes and Blocks 689 # Reading data: Mutes and Blocks
611 ### 690 ###
612 @api_version("1.1.0") 691 @api_version("1.1.0")
613 def mutes(self, max_id=None, since_id=None, limit=None): 692 def mutes(self, max_id=None, since_id=None, limit=None):
614 """ 693 """
615 Fetch a list of users muted by the authenticated user. 694 Fetch a list of users muted by the logged-in user.
616 695
617 Returns a list of user dicts. 696 Returns a list of `user dicts`_.
618 """ 697 """
619 if max_id != None: 698 if max_id != None:
620 max_id = self.__unpack_id(max_id) 699 max_id = self.__unpack_id(max_id)
@@ -628,9 +707,9 @@ class Mastodon:
628 @api_version("1.0.0") 707 @api_version("1.0.0")
629 def blocks(self, max_id=None, since_id=None, limit=None): 708 def blocks(self, max_id=None, since_id=None, limit=None):
630 """ 709 """
631 Fetch a list of users blocked by the authenticated user. 710 Fetch a list of users blocked by the logged-in user.
632 711
633 Returns a list of user dicts. 712 Returns a list of `user dicts`_.
634 """ 713 """
635 if max_id != None: 714 if max_id != None:
636 max_id = self.__unpack_id(max_id) 715 max_id = self.__unpack_id(max_id)
@@ -647,12 +726,12 @@ class Mastodon:
647 @api_version("1.1.0") 726 @api_version("1.1.0")
648 def reports(self): 727 def reports(self):
649 """ 728 """
650 Fetch a list of reports made by the authenticated user. 729 Fetch a list of reports made by the logged-in user.
651 730
652 Returns a list of report dicts. 731 Returns a list of `report dicts`_.
653 732
654 Warning: According to the official API documentation, this 733 Warning: According to the official API documentation, this
655 method is to be treated as not finalized as of Mastodon 2.0.0. 734 method is to be treated as not finalized as of Mastodon 2.1.0.
656 """ 735 """
657 return self.__api_request('GET', '/api/v1/reports') 736 return self.__api_request('GET', '/api/v1/reports')
658 737
@@ -662,9 +741,9 @@ class Mastodon:
662 @api_version("1.0.0") 741 @api_version("1.0.0")
663 def favourites(self, max_id=None, since_id=None, limit=None): 742 def favourites(self, max_id=None, since_id=None, limit=None):
664 """ 743 """
665 Fetch the authenticated user's favourited statuses. 744 Fetch the logged-in user's favourited statuses.
666 745
667 Returns a list of toot dicts. 746 Returns a list of `toot dicts`_.
668 """ 747 """
669 if max_id != None: 748 if max_id != None:
670 max_id = self.__unpack_id(max_id) 749 max_id = self.__unpack_id(max_id)
@@ -681,9 +760,9 @@ class Mastodon:
681 @api_version("1.0.0") 760 @api_version("1.0.0")
682 def follow_requests(self, max_id=None, since_id=None, limit=None): 761 def follow_requests(self, max_id=None, since_id=None, limit=None):
683 """ 762 """
684 Fetch the authenticated user's incoming follow requests. 763 Fetch the logged-in user's incoming follow requests.
685 764
686 Returns a list of user dicts. 765 Returns a list of `user dicts`_.
687 """ 766 """
688 if max_id != None: 767 if max_id != None:
689 max_id = self.__unpack_id(max_id) 768 max_id = self.__unpack_id(max_id)
@@ -700,7 +779,7 @@ class Mastodon:
700 @api_version("1.4.0") 779 @api_version("1.4.0")
701 def domain_blocks(self, max_id=None, since_id=None, limit=None): 780 def domain_blocks(self, max_id=None, since_id=None, limit=None):
702 """ 781 """
703 Fetch the authenticated user's blocked domains. 782 Fetch the logged-in user's blocked domains.
704 783
705 Returns a list of blocked domain URLs (as strings, without protocol specifier). 784 Returns a list of blocked domain URLs (as strings, without protocol specifier).
706 """ 785 """
@@ -714,6 +793,21 @@ class Mastodon:
714 return self.__api_request('GET', '/api/v1/domain_blocks', params) 793 return self.__api_request('GET', '/api/v1/domain_blocks', params)
715 794
716 ### 795 ###
796 # Reading data: Emoji
797 ###
798 @api_version("2.1.0")
799 def custom_emojis(self):
800 """
801 Fetch the list of custom emoji the instance has installed.
802
803 Does not require authentication.
804
805 Returns a list of `emoji dicts`_.
806
807 """
808 return self.__api_request('GET', '/api/v1/custom_emojis')
809
810 ###
717 # Writing data: Statuses 811 # Writing data: Statuses
718 ### 812 ###
719 @api_version("1.0.0") 813 @api_version("1.0.0")
@@ -721,11 +815,11 @@ class Mastodon:
721 sensitive=False, visibility='', spoiler_text=None): 815 sensitive=False, visibility='', spoiler_text=None):
722 """ 816 """
723 Post a status. Can optionally be in reply to another status and contain 817 Post a status. Can optionally be in reply to another status and contain
724 up to four pieces of media (Uploaded via media_post()). media_ids can 818 up to four pieces of media (Uploaded via `media_post()`_). media_ids can
725 also be the media dicts returned by media_post - they are unpacked 819 also be the `media dicts`_ returned by `media_post()`_ - they are unpacked
726 automatically. 820 automatically.
727 821
728 The 'sensitive' boolean decides whether or not media attached to the post 822 The `sensitive` boolean decides whether or not media attached to the post
729 should be marked as sensitive, which hides it by default on the Mastodon 823 should be marked as sensitive, which hides it by default on the Mastodon
730 web front-end. 824 web front-end.
731 825
@@ -741,11 +835,11 @@ class Mastodon:
741 locked setting - private if the account is locked, public otherwise 835 locked setting - private if the account is locked, public otherwise
742 (for Mastodon versions lower than 1.6). 836 (for Mastodon versions lower than 1.6).
743 837
744 The spoiler_text parameter is a string to be shown as a warning before 838 The `spoiler_text` parameter is a string to be shown as a warning before
745 the text of the status. If no text is passed in, no warning will be 839 the text of the status. If no text is passed in, no warning will be
746 displayed. 840 displayed.
747 841
748 Returns a toot dict with the new status. 842 Returns a `toot dict`_ with the new status.
749 """ 843 """
750 if in_reply_to_id != None: 844 if in_reply_to_id != None:
751 in_reply_to_id = self.__unpack_id(in_reply_to_id) 845 in_reply_to_id = self.__unpack_id(in_reply_to_id)
@@ -781,11 +875,11 @@ class Mastodon:
781 @api_version("1.0.0") 875 @api_version("1.0.0")
782 def toot(self, status): 876 def toot(self, status):
783 """ 877 """
784 Synonym for status_post that only takes the status text as input. 878 Synonym for `status_post()`_ that only takes the status text as input.
785 879
786 Usage in production code is not recommended. 880 Usage in production code is not recommended.
787 881
788 Returns a toot dict with the new status. 882 Returns a `toot dict`_ with the new status.
789 """ 883 """
790 return self.status_post(status) 884 return self.status_post(status)
791 885
@@ -793,19 +887,17 @@ class Mastodon:
793 def status_delete(self, id): 887 def status_delete(self, id):
794 """ 888 """
795 Delete a status 889 Delete a status
796
797 Returns an empty dict for good measure.
798 """ 890 """
799 id = self.__unpack_id(id) 891 id = self.__unpack_id(id)
800 url = '/api/v1/statuses/{0}'.format(str(id)) 892 url = '/api/v1/statuses/{0}'.format(str(id))
801 return self.__api_request('DELETE', url) 893 self.__api_request('DELETE', url)
802 894
803 @api_version("1.0.0") 895 @api_version("1.0.0")
804 def status_reblog(self, id): 896 def status_reblog(self, id):
805 """ 897 """
806 Reblog a status. 898 Reblog a status.
807 899
808 Returns a toot dict with a new status that wraps around the reblogged one. 900 Returns a `toot dict`_ with a new status that wraps around the reblogged one.
809 """ 901 """
810 id = self.__unpack_id(id) 902 id = self.__unpack_id(id)
811 url = '/api/v1/statuses/{0}/reblog'.format(str(id)) 903 url = '/api/v1/statuses/{0}/reblog'.format(str(id))
@@ -816,7 +908,7 @@ class Mastodon:
816 """ 908 """
817 Un-reblog a status. 909 Un-reblog a status.
818 910
819 Returns a toot dict with the status that used to be reblogged. 911 Returns a `toot dict`_ with the status that used to be reblogged.
820 """ 912 """
821 id = self.__unpack_id(id) 913 id = self.__unpack_id(id)
822 url = '/api/v1/statuses/{0}/unreblog'.format(str(id)) 914 url = '/api/v1/statuses/{0}/unreblog'.format(str(id))
@@ -827,7 +919,7 @@ class Mastodon:
827 """ 919 """
828 Favourite a status. 920 Favourite a status.
829 921
830 Returns a toot dict with the favourited status. 922 Returns a `toot dict`_ with the favourited status.
831 """ 923 """
832 id = self.__unpack_id(id) 924 id = self.__unpack_id(id)
833 url = '/api/v1/statuses/{0}/favourite'.format(str(id)) 925 url = '/api/v1/statuses/{0}/favourite'.format(str(id))
@@ -838,7 +930,7 @@ class Mastodon:
838 """ 930 """
839 Un-favourite a status. 931 Un-favourite a status.
840 932
841 Returns a toot dict with the un-favourited status. 933 Returns a `toot dict`_ with the un-favourited status.
842 """ 934 """
843 id = self.__unpack_id(id) 935 id = self.__unpack_id(id)
844 url = '/api/v1/statuses/{0}/unfavourite'.format(str(id)) 936 url = '/api/v1/statuses/{0}/unfavourite'.format(str(id))
@@ -849,7 +941,7 @@ class Mastodon:
849 """ 941 """
850 Mute notifications for a status. 942 Mute notifications for a status.
851 943
852 Returns a toot dict with the now muted status 944 Returns a `toot dict`_ with the now muted status
853 """ 945 """
854 id = self.__unpack_id(id) 946 id = self.__unpack_id(id)
855 url = '/api/v1/statuses/{0}/mute'.format(str(id)) 947 url = '/api/v1/statuses/{0}/mute'.format(str(id))
@@ -860,7 +952,7 @@ class Mastodon:
860 """ 952 """
861 Unmute notifications for a status. 953 Unmute notifications for a status.
862 954
863 Returns a toot dict with the status that used to be muted. 955 Returns a `toot dict`_ with the status that used to be muted.
864 """ 956 """
865 id = self.__unpack_id(id) 957 id = self.__unpack_id(id)
866 url = '/api/v1/statuses/{0}/unmute'.format(str(id)) 958 url = '/api/v1/statuses/{0}/unmute'.format(str(id))
@@ -874,7 +966,7 @@ class Mastodon:
874 """ 966 """
875 Clear out a users notifications 967 Clear out a users notifications
876 """ 968 """
877 return self.__api_request('POST', '/api/v1/notifications/clear') 969 self.__api_request('POST', '/api/v1/notifications/clear')
878 970
879 971
880 @api_version("1.3.0") 972 @api_version("1.3.0")
@@ -884,7 +976,7 @@ class Mastodon:
884 """ 976 """
885 id = self.__unpack_id(id) 977 id = self.__unpack_id(id)
886 params = self.__generate_params(locals()) 978 params = self.__generate_params(locals())
887 return self.__api_request('POST', '/api/v1/notifications/dismiss', params) 979 self.__api_request('POST', '/api/v1/notifications/dismiss', params)
888 980
889 ### 981 ###
890 # Writing data: Accounts 982 # Writing data: Accounts
@@ -894,7 +986,7 @@ class Mastodon:
894 """ 986 """
895 Follow a user. 987 Follow a user.
896 988
897 Returns a relationship dict containing the updated relationship to the user. 989 Returns a `relationship dict`_ containing the updated relationship to the user.
898 """ 990 """
899 id = self.__unpack_id(id) 991 id = self.__unpack_id(id)
900 url = '/api/v1/accounts/{0}/follow'.format(str(id)) 992 url = '/api/v1/accounts/{0}/follow'.format(str(id))
@@ -905,7 +997,7 @@ class Mastodon:
905 """ 997 """
906 Follow a remote user by uri (username@domain). 998 Follow a remote user by uri (username@domain).
907 999
908 Returns a user dict. 1000 Returns a `user dict`_.
909 """ 1001 """
910 params = self.__generate_params(locals()) 1002 params = self.__generate_params(locals())
911 return self.__api_request('POST', '/api/v1/follows', params) 1003 return self.__api_request('POST', '/api/v1/follows', params)
@@ -915,7 +1007,7 @@ class Mastodon:
915 """ 1007 """
916 Unfollow a user. 1008 Unfollow a user.
917 1009
918 Returns a relationship dict containing the updated relationship to the user. 1010 Returns a `relationship dict`_ containing the updated relationship to the user.
919 """ 1011 """
920 id = self.__unpack_id(id) 1012 id = self.__unpack_id(id)
921 url = '/api/v1/accounts/{0}/unfollow'.format(str(id)) 1013 url = '/api/v1/accounts/{0}/unfollow'.format(str(id))
@@ -926,7 +1018,7 @@ class Mastodon:
926 """ 1018 """
927 Block a user. 1019 Block a user.
928 1020
929 Returns a relationship dict containing the updated relationship to the user. 1021 Returns a `relationship dict`_ containing the updated relationship to the user.
930 """ 1022 """
931 id = self.__unpack_id(id) 1023 id = self.__unpack_id(id)
932 url = '/api/v1/accounts/{0}/block'.format(str(id)) 1024 url = '/api/v1/accounts/{0}/block'.format(str(id))
@@ -937,7 +1029,7 @@ class Mastodon:
937 """ 1029 """
938 Unblock a user. 1030 Unblock a user.
939 1031
940 Returns a relationship dict containing the updated relationship to the user. 1032 Returns a `relationship dict`_ containing the updated relationship to the user.
941 """ 1033 """
942 id = self.__unpack_id(id) 1034 id = self.__unpack_id(id)
943 url = '/api/v1/accounts/{0}/unblock'.format(str(id)) 1035 url = '/api/v1/accounts/{0}/unblock'.format(str(id))
@@ -948,7 +1040,7 @@ class Mastodon:
948 """ 1040 """
949 Mute a user. 1041 Mute a user.
950 1042
951 Returns a relationship dict containing the updated relationship to the user. 1043 Returns a `relationship dict`_ containing the updated relationship to the user.
952 """ 1044 """
953 id = self.__unpack_id(id) 1045 id = self.__unpack_id(id)
954 url = '/api/v1/accounts/{0}/mute'.format(str(id)) 1046 url = '/api/v1/accounts/{0}/mute'.format(str(id))
@@ -959,7 +1051,7 @@ class Mastodon:
959 """ 1051 """
960 Unmute a user. 1052 Unmute a user.
961 1053
962 Returns a relationship dict containing the updated relationship to the user. 1054 Returns a `relationship dict`_ containing the updated relationship to the user.
963 """ 1055 """
964 id = self.__unpack_id(id) 1056 id = self.__unpack_id(id)
965 url = '/api/v1/accounts/{0}/unmute'.format(str(id)) 1057 url = '/api/v1/accounts/{0}/unmute'.format(str(id))
@@ -969,17 +1061,79 @@ class Mastodon:
969 def account_update_credentials(self, display_name=None, note=None, 1061 def account_update_credentials(self, display_name=None, note=None,
970 avatar=None, header=None): 1062 avatar=None, header=None):
971 """ 1063 """
972 Update the profile for the currently authenticated user. 1064 Update the profile for the currently logged-in user.
973 1065
974 'note' is the user's bio. 1066 'note' is the user's bio.
975 1067
976 'avatar' and 'header' are images encoded in base64, prepended by a content-type 1068 'avatar' and 'header' are images encoded in base64, prepended by a content-type
977 (for example: 'data:image/png;base64,iVBORw0KGgoAAAA[...]') 1069 (for example: 'data:image/png;base64,iVBORw0KGgoAAAA[...]')
1070
1071 Returns the updated `user dict` of the logged-in user.
978 """ 1072 """
979 params = self.__generate_params(locals()) 1073 params = self.__generate_params(locals())
980 return self.__api_request('PATCH', '/api/v1/accounts/update_credentials', params) 1074 return self.__api_request('PATCH', '/api/v1/accounts/update_credentials', params)
981 1075
982 ### 1076 ###
1077 # Writing data: Lists
1078 ###
1079 @api_version("2.1.0")
1080 def list_create(self, title):
1081 """
1082 Create a new list with the given `title`.
1083
1084 Returns the `list dict`_ of the created list.
1085 """
1086 params = self.__generate_params(locals())
1087 return self.__api_request('POST', '/api/v1/lists', params)
1088
1089 @api_version("2.1.0")
1090 def list_update(self, id, title):
1091 """
1092 Update info about a list, where "info" is really the lists `title`.
1093
1094 Returns the `list dict`_ of the modified list.
1095 """
1096 id = self.__unpack_id(id)
1097 params = self.__generate_params(locals(), ['id'])
1098 return self.__api_request('PUT', '/api/v1/lists/{0}'.format(id), params)
1099
1100 @api_version("2.1.0")
1101 def list_delete(self, id):
1102 """
1103 Delete a list.
1104 """
1105 id = self.__unpack_id(id)
1106 self.__api_request('DELETE', '/api/v1/lists/{0}'.format(id))
1107
1108 @api_version("2.1.0")
1109 def list_accounts_add(self, id, account_ids):
1110 """
1111 Add the account(s) given in `account_ids` to the list.
1112 """
1113 id = self.__unpack_id(id)
1114
1115 if not isinstance(account_ids, list):
1116 account_ids = [account_ids]
1117 account_ids = list(map(lambda x: self.__unpack_id(x), account_ids))
1118
1119 params = self.__generate_params(locals(), ['id'])
1120 self.__api_request('POST', '/api/v1/lists/{0}/accounts'.format(id), params)
1121
1122 @api_version("2.1.0")
1123 def list_accounts_delete(self, id, account_ids):
1124 """
1125 Remove the account(s) given in `account_ids` from the list.
1126 """
1127 id = self.__unpack_id(id)
1128
1129 if not isinstance(account_ids, list):
1130 account_ids = [account_ids]
1131 account_ids = list(map(lambda x: self.__unpack_id(x), account_ids))
1132
1133 params = self.__generate_params(locals(), ['id'])
1134 self.__api_request('DELETE', '/api/v1/lists/{0}/accounts'.format(id), params)
1135
1136 ###
983 # Writing data: Reports 1137 # Writing data: Reports
984 ### 1138 ###
985 @api_version("1.1.0") 1139 @api_version("1.1.0")
@@ -989,10 +1143,14 @@ class Mastodon:
989 1143
990 Accepts a list of toot IDs associated with the report, and a comment. 1144 Accepts a list of toot IDs associated with the report, and a comment.
991 1145
992 Returns a report dict. 1146 Returns a `report dict`_.
993 """ 1147 """
994 account_id = self.__unpack_id(account_id) 1148 account_id = self.__unpack_id(account_id)
995 status_ids = map(lambda x: self.__unpack_id(x), status_ids) 1149
1150 if not isinstance(status_ids, list):
1151 status_ids = [status_ids]
1152 status_ids = list(map(lambda x: self.__unpack_id(x), status_ids))
1153
996 params = self.__generate_params(locals()) 1154 params = self.__generate_params(locals())
997 return self.__api_request('POST', '/api/v1/reports/', params) 1155 return self.__api_request('POST', '/api/v1/reports/', params)
998 1156
@@ -1003,23 +1161,19 @@ class Mastodon:
1003 def follow_request_authorize(self, id): 1161 def follow_request_authorize(self, id):
1004 """ 1162 """
1005 Accept an incoming follow request. 1163 Accept an incoming follow request.
1006
1007 Returns an empty dict.
1008 """ 1164 """
1009 id = self.__unpack_id(id) 1165 id = self.__unpack_id(id)
1010 url = '/api/v1/follow_requests/{0}/authorize'.format(str(id)) 1166 url = '/api/v1/follow_requests/{0}/authorize'.format(str(id))
1011 return self.__api_request('POST', url) 1167 self.__api_request('POST', url)
1012 1168
1013 @api_version("1.0.0") 1169 @api_version("1.0.0")
1014 def follow_request_reject(self, id): 1170 def follow_request_reject(self, id):
1015 """ 1171 """
1016 Reject an incoming follow request. 1172 Reject an incoming follow request.
1017
1018 Returns an empty dict.
1019 """ 1173 """
1020 id = self.__unpack_id(id) 1174 id = self.__unpack_id(id)
1021 url = '/api/v1/follow_requests/{0}/reject'.format(str(id)) 1175 url = '/api/v1/follow_requests/{0}/reject'.format(str(id))
1022 return self.__api_request('POST', url) 1176 self.__api_request('POST', url)
1023 1177
1024 ### 1178 ###
1025 # Writing data: Media 1179 # Writing data: Media
@@ -1027,15 +1181,15 @@ class Mastodon:
1027 @api_version("1.0.0") 1181 @api_version("1.0.0")
1028 def media_post(self, media_file, mime_type=None, description=None): 1182 def media_post(self, media_file, mime_type=None, description=None):
1029 """ 1183 """
1030 Post an image. media_file can either be image data or 1184 Post an image. `media_file` can either be image data or
1031 a file name. If image data is passed directly, the mime 1185 a file name. If image data is passed directly, the mime
1032 type has to be specified manually, otherwise, it is 1186 type has to be specified manually, otherwise, it is
1033 determined from the file name. 1187 determined from the file name.
1034 1188
1035 Throws a MastodonIllegalArgumentError if the mime type of the 1189 Throws a `MastodonIllegalArgumentError` if the mime type of the
1036 passed data or file can not be determined properly. 1190 passed data or file can not be determined properly.
1037 1191
1038 Returns a media dict. This contains the id that can be used in 1192 Returns a `media dict`_. This contains the id that can be used in
1039 status_post to attach the media file to a toot. 1193 status_post to attach the media file to a toot.
1040 """ 1194 """
1041 if mime_type is None and os.path.isfile(media_file): 1195 if mime_type is None and os.path.isfile(media_file):
@@ -1065,7 +1219,7 @@ class Mastodon:
1065 Add a block for all statuses originating from the specified domain for the logged-in user. 1219 Add a block for all statuses originating from the specified domain for the logged-in user.
1066 """ 1220 """
1067 params = self.__generate_params(locals()) 1221 params = self.__generate_params(locals())
1068 return self.__api_request('POST', '/api/v1/domain_blocks', params) 1222 self.__api_request('POST', '/api/v1/domain_blocks', params)
1069 1223
1070 @api_version("1.4.0") 1224 @api_version("1.4.0")
1071 def domain_unblock(self, domain=None): 1225 def domain_unblock(self, domain=None):
@@ -1073,7 +1227,7 @@ class Mastodon:
1073 Remove a domain block for the logged-in user. 1227 Remove a domain block for the logged-in user.
1074 """ 1228 """
1075 params = self.__generate_params(locals()) 1229 params = self.__generate_params(locals())
1076 return self.__api_request('DELETE', '/api/v1/domain_blocks', params) 1230 self.__api_request('DELETE', '/api/v1/domain_blocks', params)
1077 1231
1078 ### 1232 ###
1079 # Pagination 1233 # Pagination
@@ -1152,25 +1306,21 @@ class Mastodon:
1152 def stream_user(self, listener, async=False): 1306 def stream_user(self, listener, async=False):
1153 """ 1307 """
1154 Streams events that are relevant to the authorized user, i.e. home 1308 Streams events that are relevant to the authorized user, i.e. home
1155 timeline and notifications. 'listener' should be a subclass of 1309 timeline and notifications.
1156 StreamListener which will receive callbacks for incoming events.
1157 """ 1310 """
1158 return self.__stream('/api/v1/streaming/user', listener, async=async) 1311 return self.__stream('/api/v1/streaming/user', listener, async=async)
1159 1312
1160 @api_version("1.1.0") 1313 @api_version("1.1.0")
1161 def stream_public(self, listener, async=False): 1314 def stream_public(self, listener, async=False):
1162 """ 1315 """
1163 Streams public events. 'listener' should be a subclass of StreamListener 1316 Streams public events.
1164 which will receive callbacks for incoming events.
1165 """ 1317 """
1166 return self.__stream('/api/v1/streaming/public', listener, async=async) 1318 return self.__stream('/api/v1/streaming/public', listener, async=async)
1167 1319
1168 @api_version("1.1.0") 1320 @api_version("1.1.0")
1169 def stream_local(self, listener, async=False): 1321 def stream_local(self, listener, async=False):
1170 """ 1322 """
1171 Streams local events. 'listener' should be a subclass of StreamListener 1323 Streams local public events.
1172 which will receive callbacks for incoming events.
1173
1174 """ 1324 """
1175 return self.__stream('/api/v1/streaming/public/local', listener, async=async) 1325 return self.__stream('/api/v1/streaming/public/local', listener, async=async)
1176 1326
@@ -1178,13 +1328,21 @@ class Mastodon:
1178 def stream_hashtag(self, tag, listener, async=False): 1328 def stream_hashtag(self, tag, listener, async=False):
1179 """ 1329 """
1180 Stream for all public statuses for the hashtag 'tag' seen by the connected 1330 Stream for all public statuses for the hashtag 'tag' seen by the connected
1181 instance. 'listener' should be a subclass of StreamListener which will receive 1331 instance.
1182 callbacks for incoming events.
1183 """ 1332 """
1184 if tag.startswith("#"): 1333 if tag.startswith("#"):
1185 raise MastodonIllegalArgumentError("Tag parameter should omit leading #") 1334 raise MastodonIllegalArgumentError("Tag parameter should omit leading #")
1186 return self.__stream("/api/v1/streaming/hashtag?tag={}".format(tag), listener) 1335 return self.__stream("/api/v1/streaming/hashtag?tag={}".format(tag), listener)
1187 1336
1337 @api_version("2.1.0")
1338 def stream_list(self, id, listener, async=False):
1339 """
1340 Stream events for the current user, restricted to accounts on the given
1341 list.
1342 """
1343 id = self.__unpack_id(id)
1344 return self.__stream("/api/v1/streaming/list?list={}".format(id), listener)
1345
1188 ### 1346 ###
1189 # Internal helpers, dragons probably 1347 # Internal helpers, dragons probably
1190 ### 1348 ###
Powered by cgit v1.2.3 (git 2.41.0)