aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLorenz Diener <[email protected]>2017-12-13 18:40:17 +0100
committerLorenz Diener <[email protected]>2017-12-13 18:40:17 +0100
commit7d2f2441269fda71b72322825b5813a2aec4c7bd (patch)
tree9784c20d119b623051edec0d78251de08c9bfa18 /mastodon
parentd7d8f153a31b76493daf68a44e01d4c4e11b180d (diff)
downloadmastodon.py-7d2f2441269fda71b72322825b5813a2aec4c7bd.tar.gz
Add internal links in docs
Diffstat (limited to 'mastodon')
-rw-r--r--mastodon/Mastodon.py209
1 files changed, 104 insertions, 105 deletions
diff --git a/mastodon/Mastodon.py b/mastodon/Mastodon.py
index 2e3935c..af450ec 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,7 @@ 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 Returns an `instance dict`_.
310 """ 310 """
311 return self.__instance() 311 return self.__instance()
312 312
@@ -322,13 +322,13 @@ class Mastodon:
322 @api_version("1.0.0") 322 @api_version("1.0.0")
323 def timeline(self, timeline="home", max_id=None, since_id=None, limit=None): 323 def timeline(self, timeline="home", max_id=None, since_id=None, limit=None):
324 """ 324 """
325 Fetch statuses, most recent ones first. Timeline can be 'home', 'local', 'public', 325 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. 326 or 'tag/hashtag'. See the following functions documentation for what those do.
327 Local hashtag timelines are supported via the timeline_hashtag() function. 327 Local hashtag timelines are supported via the `timeline_hashtag()`_ function.
328 328
329 The default timeline is the "home" timeline. 329 The default timeline is the "home" timeline.
330 330
331 Returns a list of toot dicts. 331 Returns a list of `toot dicts`_.
332 """ 332 """
333 if max_id != None: 333 if max_id != None:
334 max_id = self.__unpack_id(max_id) 334 max_id = self.__unpack_id(max_id)
@@ -349,9 +349,9 @@ class Mastodon:
349 @api_version("1.0.0") 349 @api_version("1.0.0")
350 def timeline_home(self, max_id=None, since_id=None, limit=None): 350 def timeline_home(self, max_id=None, since_id=None, limit=None):
351 """ 351 """
352 Fetch the authenticated users home timeline (i.e. followed users and self). 352 Fetch the logged-in users home timeline (i.e. followed users and self).
353 353
354 Returns a list of toot dicts. 354 Returns a list of `toot dicts`_.
355 """ 355 """
356 return self.timeline('home', max_id=max_id, since_id=since_id, 356 return self.timeline('home', max_id=max_id, since_id=since_id,
357 limit=limit) 357 limit=limit)
@@ -361,7 +361,7 @@ class Mastodon:
361 """ 361 """
362 Fetches the local / instance-wide timeline, not including replies. 362 Fetches the local / instance-wide timeline, not including replies.
363 363
364 Returns a list of toot dicts. 364 Returns a list of `toot dicts`_.
365 """ 365 """
366 return self.timeline('local', max_id=max_id, since_id=since_id, 366 return self.timeline('local', max_id=max_id, since_id=since_id,
367 limit=limit) 367 limit=limit)
@@ -371,7 +371,7 @@ class Mastodon:
371 """ 371 """
372 Fetches the public / visible-network timeline, not including replies. 372 Fetches the public / visible-network timeline, not including replies.
373 373
374 Returns a list of toot dicts. 374 Returns a list of `toot dicts`_.
375 """ 375 """
376 return self.timeline('public', max_id=max_id, since_id=since_id, 376 return self.timeline('public', max_id=max_id, since_id=since_id,
377 limit=limit) 377 limit=limit)
@@ -382,9 +382,9 @@ class Mastodon:
382 Fetch a timeline of toots with a given hashtag. The hashtag parameter 382 Fetch a timeline of toots with a given hashtag. The hashtag parameter
383 should not contain the leading #. 383 should not contain the leading #.
384 384
385 Set "local" to True to retrieve only instance-local tagged posts. 385 Set `local` to True to retrieve only instance-local tagged posts.
386 386
387 Returns a list of toot dicts. 387 Returns a list of `toot dicts`_.
388 """ 388 """
389 if hashtag.startswith("#"): 389 if hashtag.startswith("#"):
390 raise MastodonIllegalArgumentError("Hashtag parameter should omit leading #") 390 raise MastodonIllegalArgumentError("Hashtag parameter should omit leading #")
@@ -413,7 +413,7 @@ class Mastodon:
413 """ 413 """
414 Fetch information about a single toot. 414 Fetch information about a single toot.
415 415
416 Returns a toot dict. 416 Returns a `toot dict`_.
417 """ 417 """
418 id = self.__unpack_id(id) 418 id = self.__unpack_id(id)
419 url = '/api/v1/statuses/{0}'.format(str(id)) 419 url = '/api/v1/statuses/{0}'.format(str(id))
@@ -425,7 +425,7 @@ class Mastodon:
425 Fetch a card associated with a status. A card describes an object (such as an 425 Fetch a card associated with a status. A card describes an object (such as an
426 external video or link) embedded into a status. 426 external video or link) embedded into a status.
427 427
428 Returns a card dict. 428 Returns a `card dict`_.
429 """ 429 """
430 id = self.__unpack_id(id) 430 id = self.__unpack_id(id)
431 url = '/api/v1/statuses/{0}/card'.format(str(id)) 431 url = '/api/v1/statuses/{0}/card'.format(str(id))
@@ -436,7 +436,7 @@ class Mastodon:
436 """ 436 """
437 Fetch information about ancestors and descendants of a toot. 437 Fetch information about ancestors and descendants of a toot.
438 438
439 Returns a context dict. 439 Returns a `context dict`_.
440 """ 440 """
441 id = self.__unpack_id(id) 441 id = self.__unpack_id(id)
442 url = '/api/v1/statuses/{0}/context'.format(str(id)) 442 url = '/api/v1/statuses/{0}/context'.format(str(id))
@@ -447,7 +447,7 @@ class Mastodon:
447 """ 447 """
448 Fetch a list of users that have reblogged a status. 448 Fetch a list of users that have reblogged a status.
449 449
450 Returns a list of user dicts. 450 Returns a list of `user dicts`_.
451 """ 451 """
452 id = self.__unpack_id(id) 452 id = self.__unpack_id(id)
453 url = '/api/v1/statuses/{0}/reblogged_by'.format(str(id)) 453 url = '/api/v1/statuses/{0}/reblogged_by'.format(str(id))
@@ -458,7 +458,7 @@ class Mastodon:
458 """ 458 """
459 Fetch a list of users that have favourited a status. 459 Fetch a list of users that have favourited a status.
460 460
461 Returns a list of user dicts. 461 Returns a list of `user dicts`_.
462 """ 462 """
463 id = self.__unpack_id(id) 463 id = self.__unpack_id(id)
464 url = '/api/v1/statuses/{0}/favourited_by'.format(str(id)) 464 url = '/api/v1/statuses/{0}/favourited_by'.format(str(id))
@@ -470,12 +470,12 @@ class Mastodon:
470 @api_version("1.0.0") 470 @api_version("1.0.0")
471 def notifications(self, id=None, max_id=None, since_id=None, limit=None): 471 def notifications(self, id=None, max_id=None, since_id=None, limit=None):
472 """ 472 """
473 Fetch notifications (mentions, favourites, reblogs, follows) for the authenticated 473 Fetch notifications (mentions, favourites, reblogs, follows) for the logged-in
474 user. 474 user.
475 475
476 Can be passed an id to fetch a single notification. 476 Can be passed an `id` to fetch a single notification.
477 477
478 Returns a list of notification dicts. 478 Returns a list of `notification dicts`_.
479 """ 479 """
480 if max_id != None: 480 if max_id != None:
481 max_id = self.__unpack_id(max_id) 481 max_id = self.__unpack_id(max_id)
@@ -497,9 +497,9 @@ class Mastodon:
497 @api_version("1.0.0") 497 @api_version("1.0.0")
498 def account(self, id): 498 def account(self, id):
499 """ 499 """
500 Fetch account information by user id. 500 Fetch account information by user `id`.
501 501
502 Returns a user dict. 502 Returns a `user dict`_.
503 """ 503 """
504 id = self.__unpack_id(id) 504 id = self.__unpack_id(id)
505 url = '/api/v1/accounts/{0}'.format(str(id)) 505 url = '/api/v1/accounts/{0}'.format(str(id))
@@ -508,18 +508,21 @@ class Mastodon:
508 @api_version("1.0.0") 508 @api_version("1.0.0")
509 def account_verify_credentials(self): 509 def account_verify_credentials(self):
510 """ 510 """
511 Fetch authenticated user's account information. 511 Fetch logged-in user's account information.
512 512
513 Returns a user dict (Starting from 2.1.0, with an additional "source" field). 513 Returns a `user dict`_ (Starting from 2.1.0, with an additional "source" field).
514 """ 514 """
515 return self.__api_request('GET', '/api/v1/accounts/verify_credentials') 515 return self.__api_request('GET', '/api/v1/accounts/verify_credentials')
516 516
517 @api_version("1.0.0") 517 @api_version("1.0.0")
518 def account_statuses(self, id, max_id=None, since_id=None, limit=None): 518 def account_statuses(self, id, max_id=None, since_id=None, limit=None):
519 """ 519 """
520 Fetch statuses by user id. Same options as timeline are permitted. 520 Fetch statuses by user `id`. Same options as `timeline()`_ are permitted.
521 Returned toots are from the perspective of the logged-in user, i.e.
522 all statuses visible to the logged-in user (including DMs) are
523 included.
521 524
522 Returns a list of toot dicts. 525 Returns a list of `toot dicts`_.
523 """ 526 """
524 id = self.__unpack_id(id) 527 id = self.__unpack_id(id)
525 if max_id != None: 528 if max_id != None:
@@ -537,7 +540,7 @@ class Mastodon:
537 """ 540 """
538 Fetch users the given user is following. 541 Fetch users the given user is following.
539 542
540 Returns a list of user dicts. 543 Returns a list of `user dicts`_.
541 """ 544 """
542 id = self.__unpack_id(id) 545 id = self.__unpack_id(id)
543 if max_id != None: 546 if max_id != None:
@@ -555,7 +558,7 @@ class Mastodon:
555 """ 558 """
556 Fetch users the given user is followed by. 559 Fetch users the given user is followed by.
557 560
558 Returns a list of user dicts. 561 Returns a list of `user dicts`_.
559 """ 562 """
560 id = self.__unpack_id(id) 563 id = self.__unpack_id(id)
561 if max_id != None: 564 if max_id != None:
@@ -572,9 +575,9 @@ class Mastodon:
572 def account_relationships(self, id): 575 def account_relationships(self, id):
573 """ 576 """
574 Fetch relationship (following, followed_by, blocking, follow requested) of 577 Fetch relationship (following, followed_by, blocking, follow requested) of
575 the logged in user to a given account. id can be a list. 578 the logged in user to a given account. `id` can be a list.
576 579
577 Returns a list of relationship dicts. 580 Returns a list of `relationship dicts`_.
578 """ 581 """
579 id = self.__unpack_id(id) 582 id = self.__unpack_id(id)
580 params = self.__generate_params(locals()) 583 params = self.__generate_params(locals())
@@ -587,7 +590,7 @@ class Mastodon:
587 Fetch matching accounts. Will lookup an account remotely if the search term is 590 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. 591 in the username@domain format and not yet in the database.
589 592
590 Returns a list of user dicts. 593 Returns a list of `user dicts`_.
591 """ 594 """
592 params = self.__generate_params(locals()) 595 params = self.__generate_params(locals())
593 return self.__api_request('GET', '/api/v1/accounts/search', params) 596 return self.__api_request('GET', '/api/v1/accounts/search', params)
@@ -601,7 +604,7 @@ class Mastodon:
601 Fetch matching hashtags, accounts and statuses. Will search federated 604 Fetch matching hashtags, accounts and statuses. Will search federated
602 instances if resolve is True. 605 instances if resolve is True.
603 606
604 Returns a search result dict. 607 Returns a `search result dict`_.
605 """ 608 """
606 params = self.__generate_params(locals()) 609 params = self.__generate_params(locals())
607 return self.__api_request('GET', '/api/v1/search', params) 610 return self.__api_request('GET', '/api/v1/search', params)
@@ -614,7 +617,7 @@ class Mastodon:
614 """ 617 """
615 Fetch a list of all the Lists by the logged-in user. 618 Fetch a list of all the Lists by the logged-in user.
616 619
617 Returns a list of list dicts. 620 Returns a list of `list dicts`_.
618 """ 621 """
619 return self.__api_request('GET', '/api/v1/lists') 622 return self.__api_request('GET', '/api/v1/lists')
620 623
@@ -624,9 +627,9 @@ class Mastodon:
624 @api_version("1.1.0") 627 @api_version("1.1.0")
625 def mutes(self, max_id=None, since_id=None, limit=None): 628 def mutes(self, max_id=None, since_id=None, limit=None):
626 """ 629 """
627 Fetch a list of users muted by the authenticated user. 630 Fetch a list of users muted by the logged-in user.
628 631
629 Returns a list of user dicts. 632 Returns a list of `user dicts`_.
630 """ 633 """
631 if max_id != None: 634 if max_id != None:
632 max_id = self.__unpack_id(max_id) 635 max_id = self.__unpack_id(max_id)
@@ -640,9 +643,9 @@ class Mastodon:
640 @api_version("1.0.0") 643 @api_version("1.0.0")
641 def blocks(self, max_id=None, since_id=None, limit=None): 644 def blocks(self, max_id=None, since_id=None, limit=None):
642 """ 645 """
643 Fetch a list of users blocked by the authenticated user. 646 Fetch a list of users blocked by the logged-in user.
644 647
645 Returns a list of user dicts. 648 Returns a list of `user dicts`_.
646 """ 649 """
647 if max_id != None: 650 if max_id != None:
648 max_id = self.__unpack_id(max_id) 651 max_id = self.__unpack_id(max_id)
@@ -659,12 +662,12 @@ class Mastodon:
659 @api_version("1.1.0") 662 @api_version("1.1.0")
660 def reports(self): 663 def reports(self):
661 """ 664 """
662 Fetch a list of reports made by the authenticated user. 665 Fetch a list of reports made by the logged-in user.
663 666
664 Returns a list of report dicts. 667 Returns a list of `report dicts`_.
665 668
666 Warning: According to the official API documentation, this 669 Warning: According to the official API documentation, this
667 method is to be treated as not finalized as of Mastodon 2.0.0. 670 method is to be treated as not finalized as of Mastodon 2.1.0.
668 """ 671 """
669 return self.__api_request('GET', '/api/v1/reports') 672 return self.__api_request('GET', '/api/v1/reports')
670 673
@@ -674,9 +677,9 @@ class Mastodon:
674 @api_version("1.0.0") 677 @api_version("1.0.0")
675 def favourites(self, max_id=None, since_id=None, limit=None): 678 def favourites(self, max_id=None, since_id=None, limit=None):
676 """ 679 """
677 Fetch the authenticated user's favourited statuses. 680 Fetch the logged-in user's favourited statuses.
678 681
679 Returns a list of toot dicts. 682 Returns a list of `toot dicts`_.
680 """ 683 """
681 if max_id != None: 684 if max_id != None:
682 max_id = self.__unpack_id(max_id) 685 max_id = self.__unpack_id(max_id)
@@ -693,9 +696,9 @@ class Mastodon:
693 @api_version("1.0.0") 696 @api_version("1.0.0")
694 def follow_requests(self, max_id=None, since_id=None, limit=None): 697 def follow_requests(self, max_id=None, since_id=None, limit=None):
695 """ 698 """
696 Fetch the authenticated user's incoming follow requests. 699 Fetch the logged-in user's incoming follow requests.
697 700
698 Returns a list of user dicts. 701 Returns a list of `user dicts`_.
699 """ 702 """
700 if max_id != None: 703 if max_id != None:
701 max_id = self.__unpack_id(max_id) 704 max_id = self.__unpack_id(max_id)
@@ -712,7 +715,7 @@ class Mastodon:
712 @api_version("1.4.0") 715 @api_version("1.4.0")
713 def domain_blocks(self, max_id=None, since_id=None, limit=None): 716 def domain_blocks(self, max_id=None, since_id=None, limit=None):
714 """ 717 """
715 Fetch the authenticated user's blocked domains. 718 Fetch the logged-in user's blocked domains.
716 719
717 Returns a list of blocked domain URLs (as strings, without protocol specifier). 720 Returns a list of blocked domain URLs (as strings, without protocol specifier).
718 """ 721 """
@@ -733,7 +736,7 @@ class Mastodon:
733 """ 736 """
734 Fetch the list of custom emoji the instance has installed. 737 Fetch the list of custom emoji the instance has installed.
735 738
736 Returns a list of emoji dicts. 739 Returns a list of `emoji dicts`_.
737 740
738 """ 741 """
739 return self.__api_request('GET', '/api/v1/custom_emojis') 742 return self.__api_request('GET', '/api/v1/custom_emojis')
@@ -746,11 +749,11 @@ class Mastodon:
746 sensitive=False, visibility='', spoiler_text=None): 749 sensitive=False, visibility='', spoiler_text=None):
747 """ 750 """
748 Post a status. Can optionally be in reply to another status and contain 751 Post a status. Can optionally be in reply to another status and contain
749 up to four pieces of media (Uploaded via media_post()). media_ids can 752 up to four pieces of media (Uploaded via `media_post()`_). media_ids can
750 also be the media dicts returned by media_post - they are unpacked 753 also be the `media dicts`_ returned by `media_post()`_ - they are unpacked
751 automatically. 754 automatically.
752 755
753 The 'sensitive' boolean decides whether or not media attached to the post 756 The `sensitive` boolean decides whether or not media attached to the post
754 should be marked as sensitive, which hides it by default on the Mastodon 757 should be marked as sensitive, which hides it by default on the Mastodon
755 web front-end. 758 web front-end.
756 759
@@ -766,11 +769,11 @@ class Mastodon:
766 locked setting - private if the account is locked, public otherwise 769 locked setting - private if the account is locked, public otherwise
767 (for Mastodon versions lower than 1.6). 770 (for Mastodon versions lower than 1.6).
768 771
769 The spoiler_text parameter is a string to be shown as a warning before 772 The `spoiler_text` parameter is a string to be shown as a warning before
770 the text of the status. If no text is passed in, no warning will be 773 the text of the status. If no text is passed in, no warning will be
771 displayed. 774 displayed.
772 775
773 Returns a toot dict with the new status. 776 Returns a `toot dict`_ with the new status.
774 """ 777 """
775 if in_reply_to_id != None: 778 if in_reply_to_id != None:
776 in_reply_to_id = self.__unpack_id(in_reply_to_id) 779 in_reply_to_id = self.__unpack_id(in_reply_to_id)
@@ -806,11 +809,11 @@ class Mastodon:
806 @api_version("1.0.0") 809 @api_version("1.0.0")
807 def toot(self, status): 810 def toot(self, status):
808 """ 811 """
809 Synonym for status_post that only takes the status text as input. 812 Synonym for `status_post()`_ that only takes the status text as input.
810 813
811 Usage in production code is not recommended. 814 Usage in production code is not recommended.
812 815
813 Returns a toot dict with the new status. 816 Returns a `toot dict`_ with the new status.
814 """ 817 """
815 return self.status_post(status) 818 return self.status_post(status)
816 819
@@ -818,19 +821,17 @@ class Mastodon:
818 def status_delete(self, id): 821 def status_delete(self, id):
819 """ 822 """
820 Delete a status 823 Delete a status
821
822 Returns an empty dict for good measure.
823 """ 824 """
824 id = self.__unpack_id(id) 825 id = self.__unpack_id(id)
825 url = '/api/v1/statuses/{0}'.format(str(id)) 826 url = '/api/v1/statuses/{0}'.format(str(id))
826 return self.__api_request('DELETE', url) 827 self.__api_request('DELETE', url)
827 828
828 @api_version("1.0.0") 829 @api_version("1.0.0")
829 def status_reblog(self, id): 830 def status_reblog(self, id):
830 """ 831 """
831 Reblog a status. 832 Reblog a status.
832 833
833 Returns a toot dict with a new status that wraps around the reblogged one. 834 Returns a `toot dict`_ with a new status that wraps around the reblogged one.
834 """ 835 """
835 id = self.__unpack_id(id) 836 id = self.__unpack_id(id)
836 url = '/api/v1/statuses/{0}/reblog'.format(str(id)) 837 url = '/api/v1/statuses/{0}/reblog'.format(str(id))
@@ -841,7 +842,7 @@ class Mastodon:
841 """ 842 """
842 Un-reblog a status. 843 Un-reblog a status.
843 844
844 Returns a toot dict with the status that used to be reblogged. 845 Returns a `toot dict`_ with the status that used to be reblogged.
845 """ 846 """
846 id = self.__unpack_id(id) 847 id = self.__unpack_id(id)
847 url = '/api/v1/statuses/{0}/unreblog'.format(str(id)) 848 url = '/api/v1/statuses/{0}/unreblog'.format(str(id))
@@ -852,7 +853,7 @@ class Mastodon:
852 """ 853 """
853 Favourite a status. 854 Favourite a status.
854 855
855 Returns a toot dict with the favourited status. 856 Returns a `toot dict`_ with the favourited status.
856 """ 857 """
857 id = self.__unpack_id(id) 858 id = self.__unpack_id(id)
858 url = '/api/v1/statuses/{0}/favourite'.format(str(id)) 859 url = '/api/v1/statuses/{0}/favourite'.format(str(id))
@@ -863,7 +864,7 @@ class Mastodon:
863 """ 864 """
864 Un-favourite a status. 865 Un-favourite a status.
865 866
866 Returns a toot dict with the un-favourited status. 867 Returns a `toot dict`_ with the un-favourited status.
867 """ 868 """
868 id = self.__unpack_id(id) 869 id = self.__unpack_id(id)
869 url = '/api/v1/statuses/{0}/unfavourite'.format(str(id)) 870 url = '/api/v1/statuses/{0}/unfavourite'.format(str(id))
@@ -874,7 +875,7 @@ class Mastodon:
874 """ 875 """
875 Mute notifications for a status. 876 Mute notifications for a status.
876 877
877 Returns a toot dict with the now muted status 878 Returns a `toot dict`_ with the now muted status
878 """ 879 """
879 id = self.__unpack_id(id) 880 id = self.__unpack_id(id)
880 url = '/api/v1/statuses/{0}/mute'.format(str(id)) 881 url = '/api/v1/statuses/{0}/mute'.format(str(id))
@@ -885,7 +886,7 @@ class Mastodon:
885 """ 886 """
886 Unmute notifications for a status. 887 Unmute notifications for a status.
887 888
888 Returns a toot dict with the status that used to be muted. 889 Returns a `toot dict`_ with the status that used to be muted.
889 """ 890 """
890 id = self.__unpack_id(id) 891 id = self.__unpack_id(id)
891 url = '/api/v1/statuses/{0}/unmute'.format(str(id)) 892 url = '/api/v1/statuses/{0}/unmute'.format(str(id))
@@ -899,7 +900,7 @@ class Mastodon:
899 """ 900 """
900 Clear out a users notifications 901 Clear out a users notifications
901 """ 902 """
902 return self.__api_request('POST', '/api/v1/notifications/clear') 903 self.__api_request('POST', '/api/v1/notifications/clear')
903 904
904 905
905 @api_version("1.3.0") 906 @api_version("1.3.0")
@@ -909,7 +910,7 @@ class Mastodon:
909 """ 910 """
910 id = self.__unpack_id(id) 911 id = self.__unpack_id(id)
911 params = self.__generate_params(locals()) 912 params = self.__generate_params(locals())
912 return self.__api_request('POST', '/api/v1/notifications/dismiss', params) 913 self.__api_request('POST', '/api/v1/notifications/dismiss', params)
913 914
914 ### 915 ###
915 # Writing data: Accounts 916 # Writing data: Accounts
@@ -919,7 +920,7 @@ class Mastodon:
919 """ 920 """
920 Follow a user. 921 Follow a user.
921 922
922 Returns a relationship dict containing the updated relationship to the user. 923 Returns a `relationship dict`_ containing the updated relationship to the user.
923 """ 924 """
924 id = self.__unpack_id(id) 925 id = self.__unpack_id(id)
925 url = '/api/v1/accounts/{0}/follow'.format(str(id)) 926 url = '/api/v1/accounts/{0}/follow'.format(str(id))
@@ -930,7 +931,7 @@ class Mastodon:
930 """ 931 """
931 Follow a remote user by uri (username@domain). 932 Follow a remote user by uri (username@domain).
932 933
933 Returns a user dict. 934 Returns a `user dict`_.
934 """ 935 """
935 params = self.__generate_params(locals()) 936 params = self.__generate_params(locals())
936 return self.__api_request('POST', '/api/v1/follows', params) 937 return self.__api_request('POST', '/api/v1/follows', params)
@@ -940,7 +941,7 @@ class Mastodon:
940 """ 941 """
941 Unfollow a user. 942 Unfollow a user.
942 943
943 Returns a relationship dict containing the updated relationship to the user. 944 Returns a `relationship dict`_ containing the updated relationship to the user.
944 """ 945 """
945 id = self.__unpack_id(id) 946 id = self.__unpack_id(id)
946 url = '/api/v1/accounts/{0}/unfollow'.format(str(id)) 947 url = '/api/v1/accounts/{0}/unfollow'.format(str(id))
@@ -951,7 +952,7 @@ class Mastodon:
951 """ 952 """
952 Block a user. 953 Block a user.
953 954
954 Returns a relationship dict containing the updated relationship to the user. 955 Returns a `relationship dict`_ containing the updated relationship to the user.
955 """ 956 """
956 id = self.__unpack_id(id) 957 id = self.__unpack_id(id)
957 url = '/api/v1/accounts/{0}/block'.format(str(id)) 958 url = '/api/v1/accounts/{0}/block'.format(str(id))
@@ -962,7 +963,7 @@ class Mastodon:
962 """ 963 """
963 Unblock a user. 964 Unblock a user.
964 965
965 Returns a relationship dict containing the updated relationship to the user. 966 Returns a `relationship dict`_ containing the updated relationship to the user.
966 """ 967 """
967 id = self.__unpack_id(id) 968 id = self.__unpack_id(id)
968 url = '/api/v1/accounts/{0}/unblock'.format(str(id)) 969 url = '/api/v1/accounts/{0}/unblock'.format(str(id))
@@ -973,7 +974,7 @@ class Mastodon:
973 """ 974 """
974 Mute a user. 975 Mute a user.
975 976
976 Returns a relationship dict containing the updated relationship to the user. 977 Returns a `relationship dict`_ containing the updated relationship to the user.
977 """ 978 """
978 id = self.__unpack_id(id) 979 id = self.__unpack_id(id)
979 url = '/api/v1/accounts/{0}/mute'.format(str(id)) 980 url = '/api/v1/accounts/{0}/mute'.format(str(id))
@@ -984,7 +985,7 @@ class Mastodon:
984 """ 985 """
985 Unmute a user. 986 Unmute a user.
986 987
987 Returns a relationship dict containing the updated relationship to the user. 988 Returns a `relationship dict`_ containing the updated relationship to the user.
988 """ 989 """
989 id = self.__unpack_id(id) 990 id = self.__unpack_id(id)
990 url = '/api/v1/accounts/{0}/unmute'.format(str(id)) 991 url = '/api/v1/accounts/{0}/unmute'.format(str(id))
@@ -994,12 +995,14 @@ class Mastodon:
994 def account_update_credentials(self, display_name=None, note=None, 995 def account_update_credentials(self, display_name=None, note=None,
995 avatar=None, header=None): 996 avatar=None, header=None):
996 """ 997 """
997 Update the profile for the currently authenticated user. 998 Update the profile for the currently logged-in user.
998 999
999 'note' is the user's bio. 1000 'note' is the user's bio.
1000 1001
1001 'avatar' and 'header' are images encoded in base64, prepended by a content-type 1002 'avatar' and 'header' are images encoded in base64, prepended by a content-type
1002 (for example: 'data:image/png;base64,iVBORw0KGgoAAAA[...]') 1003 (for example: 'data:image/png;base64,iVBORw0KGgoAAAA[...]')
1004
1005 Returns the updated `user dict` of the logged-in user.
1003 """ 1006 """
1004 params = self.__generate_params(locals()) 1007 params = self.__generate_params(locals())
1005 return self.__api_request('PATCH', '/api/v1/accounts/update_credentials', params) 1008 return self.__api_request('PATCH', '/api/v1/accounts/update_credentials', params)
@@ -1014,7 +1017,7 @@ class Mastodon:
1014 1017
1015 Accepts a list of toot IDs associated with the report, and a comment. 1018 Accepts a list of toot IDs associated with the report, and a comment.
1016 1019
1017 Returns a report dict. 1020 Returns a `report dict`_.
1018 """ 1021 """
1019 account_id = self.__unpack_id(account_id) 1022 account_id = self.__unpack_id(account_id)
1020 status_ids = map(lambda x: self.__unpack_id(x), status_ids) 1023 status_ids = map(lambda x: self.__unpack_id(x), status_ids)
@@ -1028,23 +1031,19 @@ class Mastodon:
1028 def follow_request_authorize(self, id): 1031 def follow_request_authorize(self, id):
1029 """ 1032 """
1030 Accept an incoming follow request. 1033 Accept an incoming follow request.
1031
1032 Returns an empty dict.
1033 """ 1034 """
1034 id = self.__unpack_id(id) 1035 id = self.__unpack_id(id)
1035 url = '/api/v1/follow_requests/{0}/authorize'.format(str(id)) 1036 url = '/api/v1/follow_requests/{0}/authorize'.format(str(id))
1036 return self.__api_request('POST', url) 1037 self.__api_request('POST', url)
1037 1038
1038 @api_version("1.0.0") 1039 @api_version("1.0.0")
1039 def follow_request_reject(self, id): 1040 def follow_request_reject(self, id):
1040 """ 1041 """
1041 Reject an incoming follow request. 1042 Reject an incoming follow request.
1042
1043 Returns an empty dict.
1044 """ 1043 """
1045 id = self.__unpack_id(id) 1044 id = self.__unpack_id(id)
1046 url = '/api/v1/follow_requests/{0}/reject'.format(str(id)) 1045 url = '/api/v1/follow_requests/{0}/reject'.format(str(id))
1047 return self.__api_request('POST', url) 1046 self.__api_request('POST', url)
1048 1047
1049 ### 1048 ###
1050 # Writing data: Media 1049 # Writing data: Media
@@ -1052,15 +1051,15 @@ class Mastodon:
1052 @api_version("1.0.0") 1051 @api_version("1.0.0")
1053 def media_post(self, media_file, mime_type=None, description=None): 1052 def media_post(self, media_file, mime_type=None, description=None):
1054 """ 1053 """
1055 Post an image. media_file can either be image data or 1054 Post an image. `media_file` can either be image data or
1056 a file name. If image data is passed directly, the mime 1055 a file name. If image data is passed directly, the mime
1057 type has to be specified manually, otherwise, it is 1056 type has to be specified manually, otherwise, it is
1058 determined from the file name. 1057 determined from the file name.
1059 1058
1060 Throws a MastodonIllegalArgumentError if the mime type of the 1059 Throws a `MastodonIllegalArgumentError` if the mime type of the
1061 passed data or file can not be determined properly. 1060 passed data or file can not be determined properly.
1062 1061
1063 Returns a media dict. This contains the id that can be used in 1062 Returns a `media dict`_. This contains the id that can be used in
1064 status_post to attach the media file to a toot. 1063 status_post to attach the media file to a toot.
1065 """ 1064 """
1066 if mime_type is None and os.path.isfile(media_file): 1065 if mime_type is None and os.path.isfile(media_file):
@@ -1090,7 +1089,7 @@ class Mastodon:
1090 Add a block for all statuses originating from the specified domain for the logged-in user. 1089 Add a block for all statuses originating from the specified domain for the logged-in user.
1091 """ 1090 """
1092 params = self.__generate_params(locals()) 1091 params = self.__generate_params(locals())
1093 return self.__api_request('POST', '/api/v1/domain_blocks', params) 1092 self.__api_request('POST', '/api/v1/domain_blocks', params)
1094 1093
1095 @api_version("1.4.0") 1094 @api_version("1.4.0")
1096 def domain_unblock(self, domain=None): 1095 def domain_unblock(self, domain=None):
@@ -1098,7 +1097,7 @@ class Mastodon:
1098 Remove a domain block for the logged-in user. 1097 Remove a domain block for the logged-in user.
1099 """ 1098 """
1100 params = self.__generate_params(locals()) 1099 params = self.__generate_params(locals())
1101 return self.__api_request('DELETE', '/api/v1/domain_blocks', params) 1100 self.__api_request('DELETE', '/api/v1/domain_blocks', params)
1102 1101
1103 ### 1102 ###
1104 # Pagination 1103 # Pagination
Powered by cgit v1.2.3 (git 2.41.0)