aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/index.rst30
-rw-r--r--mastodon/Mastodon.py26
2 files changed, 38 insertions, 18 deletions
diff --git a/docs/index.rst b/docs/index.rst
index 4ef5102..9b6074d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -110,7 +110,7 @@ in the API, so don't do that.
110ID unpacking 110ID unpacking
111~~~~~~~~~~~~ 111~~~~~~~~~~~~
112Wherever Mastodon.py expects an ID as a parameter, you can also pass a 112Wherever Mastodon.py expects an ID as a parameter, you can also pass a
113dict that contains an id - this means that, for example, instead of saying 113dict that contains an id - this means that, for example, instead of writing
114 114
115.. code-block:: python 115.. code-block:: python
116 116
@@ -156,6 +156,23 @@ Unless otherwise specified, all data is returned as python dictionaries, matchin
156the JSON format used by the API. Dates returned by the API are in ISO 8601 format 156the JSON format used by the API. Dates returned by the API are in ISO 8601 format
157and are parsed into python datetime objects. 157and are parsed into python datetime objects.
158 158
159To make access easier, the dictionaries returned are wrapped by a class that adds
160read-only attributes for all dict values - this means that, for example, instead of
161writing
162
163.. code-block:: python
164
165 description = mastodon.account_verify_credentials()["source"]["note"]
166
167you can also just write
168
169.. code-block:: python
170
171 description = mastodon.account_verify_credentials().source.note
172
173and everything will work as intended.
174
175
159User dicts 176User dicts
160~~~~~~~~~~ 177~~~~~~~~~~
161.. _user dict: 178.. _user dict:
@@ -182,6 +199,8 @@ User dicts
182 'header_static': # URL for their header image, never animated 199 'header_static': # URL for their header image, never animated
183 'source': # Additional information - only present for user dict returned 200 'source': # Additional information - only present for user dict returned
184 # from account_verify_credentials() 201 # from account_verify_credentials()
202 'moved_to_account': # If set, an account dict of the account this user has
203 # set up as their moved-to address.
185 } 204 }
186 205
187 mastodon.account_verify_credentials()["source"] 206 mastodon.account_verify_credentials()["source"]
@@ -474,10 +493,11 @@ Versioning
474Mastodon.py will check if a certain endpoint is available before doing API 493Mastodon.py will check if a certain endpoint is available before doing API
475calls. By default, it checks against the version of Mastodon retrieved on 494calls. By default, it checks against the version of Mastodon retrieved on
476init(), or the version you specified. Mastodon.py can be set (in the 495init(), or the version you specified. Mastodon.py can be set (in the
477constructor) to either check if an endpoint is available at all or to check 496constructor) to either check if an endpoint is available at all (this is the
478if the endpoint is available and behaves as in the newest Mastodon version 497default) or to check if the endpoint is available and behaves as in the newest
479(this is the default). Version checking can also be disabled altogether. 498Mastodon version (with regards to parameters as well as return values).
480If a version check fails, Mastodon.py throws a `MastodonVersionError`. 499Version checking can also be disabled altogether. If a version check fails,
500Mastodon.py throws a `MastodonVersionError`.
481 501
482With the following functions, you can make Mastodon.py re-check the server 502With the following functions, you can make Mastodon.py re-check the server
483version or explicitly determine if a specific minimum Version is available. 503version or explicitly determine if a specific minimum Version is available.
diff --git a/mastodon/Mastodon.py b/mastodon/Mastodon.py
index 13c3e38..b276291 100644
--- a/mastodon/Mastodon.py
+++ b/mastodon/Mastodon.py
@@ -123,7 +123,7 @@ class Mastodon:
123 api_base_url=__DEFAULT_BASE_URL, debug_requests=False, 123 api_base_url=__DEFAULT_BASE_URL, debug_requests=False,
124 ratelimit_method="wait", ratelimit_pacefactor=1.1, 124 ratelimit_method="wait", ratelimit_pacefactor=1.1,
125 request_timeout=__DEFAULT_TIMEOUT, mastodon_version=None, 125 request_timeout=__DEFAULT_TIMEOUT, mastodon_version=None,
126 version_check_mode = "changed"): 126 version_check_mode = "created"):
127 """ 127 """
128 Create a new API wrapper instance based on the given `client_secret` and `client_id`. If you 128 Create a new API wrapper instance based on the given `client_secret` and `client_id`. If you
129 give a `client_id` and it is not a file, you must also give a secret. 129 give a `client_id` and it is not a file, you must also give a secret.
@@ -150,7 +150,7 @@ class Mastodon:
150 Version is specified. If no version is specified, Mastodon.py will set `mastodon_version` to the 150 Version is specified. If no version is specified, Mastodon.py will set `mastodon_version` to the
151 detected version. 151 detected version.
152 152
153 The version check mode can be set to "created", "changed" (the default behaviour) or "none". If set to 153 The version check mode can be set to "created" (the default behaviour), "changed" or "none". If set to
154 "created", Mastodon.py will throw an error if the version of Mastodon it is connected to is too old 154 "created", Mastodon.py will throw an error if the version of Mastodon it is connected to is too old
155 to have an endpoint. If it is set to "changed", it will throw an error if the endpoints behaviour has 155 to have an endpoint. If it is set to "changed", it will throw an error if the endpoints behaviour has
156 changed after the version of Mastodon that is connected has been released. If it is set to "none", 156 changed after the version of Mastodon that is connected has been released. If it is set to "none",
@@ -478,7 +478,7 @@ class Mastodon:
478 url = '/api/v1/statuses/{0}/context'.format(str(id)) 478 url = '/api/v1/statuses/{0}/context'.format(str(id))
479 return self.__api_request('GET', url) 479 return self.__api_request('GET', url)
480 480
481 @api_version("1.0.0", "1.0.0") 481 @api_version("1.0.0", "2.1.0")
482 def status_reblogged_by(self, id): 482 def status_reblogged_by(self, id):
483 """ 483 """
484 Fetch a list of users that have reblogged a status. 484 Fetch a list of users that have reblogged a status.
@@ -491,7 +491,7 @@ class Mastodon:
491 url = '/api/v1/statuses/{0}/reblogged_by'.format(str(id)) 491 url = '/api/v1/statuses/{0}/reblogged_by'.format(str(id))
492 return self.__api_request('GET', url) 492 return self.__api_request('GET', url)
493 493
494 @api_version("1.0.0", "1.0.0") 494 @api_version("1.0.0", "2.1.0")
495 def status_favourited_by(self, id): 495 def status_favourited_by(self, id):
496 """ 496 """
497 Fetch a list of users that have favourited a status. 497 Fetch a list of users that have favourited a status.
@@ -545,7 +545,7 @@ class Mastodon:
545 url = '/api/v1/accounts/{0}'.format(str(id)) 545 url = '/api/v1/accounts/{0}'.format(str(id))
546 return self.__api_request('GET', url) 546 return self.__api_request('GET', url)
547 547
548 @api_version("1.0.0", "1.5.0") 548 @api_version("1.0.0", "2.1.0")
549 def account_verify_credentials(self): 549 def account_verify_credentials(self):
550 """ 550 """
551 Fetch logged-in user's account information. 551 Fetch logged-in user's account information.
@@ -587,7 +587,7 @@ class Mastodon:
587 url = '/api/v1/accounts/{0}/statuses'.format(str(id)) 587 url = '/api/v1/accounts/{0}/statuses'.format(str(id))
588 return self.__api_request('GET', url, params) 588 return self.__api_request('GET', url, params)
589 589
590 @api_version("1.0.0", "1.0.0") 590 @api_version("1.0.0", "2.1.0")
591 def account_following(self, id, max_id=None, since_id=None, limit=None): 591 def account_following(self, id, max_id=None, since_id=None, limit=None):
592 """ 592 """
593 Fetch users the given user is following. 593 Fetch users the given user is following.
@@ -605,7 +605,7 @@ class Mastodon:
605 url = '/api/v1/accounts/{0}/following'.format(str(id)) 605 url = '/api/v1/accounts/{0}/following'.format(str(id))
606 return self.__api_request('GET', url, params) 606 return self.__api_request('GET', url, params)
607 607
608 @api_version("1.0.0", "1.0.0") 608 @api_version("1.0.0", "2.1.0")
609 def account_followers(self, id, max_id=None, since_id=None, limit=None): 609 def account_followers(self, id, max_id=None, since_id=None, limit=None):
610 """ 610 """
611 Fetch users the given user is followed by. 611 Fetch users the given user is followed by.
@@ -636,7 +636,7 @@ class Mastodon:
636 return self.__api_request('GET', '/api/v1/accounts/relationships', 636 return self.__api_request('GET', '/api/v1/accounts/relationships',
637 params) 637 params)
638 638
639 @api_version("1.0.0", "1.0.0") 639 @api_version("1.0.0", "2.1.0")
640 def account_search(self, q, limit=None): 640 def account_search(self, q, limit=None):
641 """ 641 """
642 Fetch matching accounts. Will lookup an account remotely if the search term is 642 Fetch matching accounts. Will lookup an account remotely if the search term is
@@ -717,7 +717,7 @@ class Mastodon:
717 ### 717 ###
718 # Reading data: Mutes and Blocks 718 # Reading data: Mutes and Blocks
719 ### 719 ###
720 @api_version("1.1.0", "1.1.0") 720 @api_version("1.1.0", "2.1.0")
721 def mutes(self, max_id=None, since_id=None, limit=None): 721 def mutes(self, max_id=None, since_id=None, limit=None):
722 """ 722 """
723 Fetch a list of users muted by the logged-in user. 723 Fetch a list of users muted by the logged-in user.
@@ -733,7 +733,7 @@ class Mastodon:
733 params = self.__generate_params(locals()) 733 params = self.__generate_params(locals())
734 return self.__api_request('GET', '/api/v1/mutes', params) 734 return self.__api_request('GET', '/api/v1/mutes', params)
735 735
736 @api_version("1.0.0", "1.0.0") 736 @api_version("1.0.0", "2.1.0")
737 def blocks(self, max_id=None, since_id=None, limit=None): 737 def blocks(self, max_id=None, since_id=None, limit=None):
738 """ 738 """
739 Fetch a list of users blocked by the logged-in user. 739 Fetch a list of users blocked by the logged-in user.
@@ -786,7 +786,7 @@ class Mastodon:
786 ### 786 ###
787 # Reading data: Follow requests 787 # Reading data: Follow requests
788 ### 788 ###
789 @api_version("1.0.0", "1.0.0") 789 @api_version("1.0.0", "2.1.0")
790 def follow_requests(self, max_id=None, since_id=None, limit=None): 790 def follow_requests(self, max_id=None, since_id=None, limit=None):
791 """ 791 """
792 Fetch the logged-in user's incoming follow requests. 792 Fetch the logged-in user's incoming follow requests.
@@ -1021,7 +1021,7 @@ class Mastodon:
1021 url = '/api/v1/accounts/{0}/follow'.format(str(id)) 1021 url = '/api/v1/accounts/{0}/follow'.format(str(id))
1022 return self.__api_request('POST', url) 1022 return self.__api_request('POST', url)
1023 1023
1024 @api_version("1.0.0", "1.0.0") 1024 @api_version("1.0.0", "2.1.0")
1025 def follows(self, uri): 1025 def follows(self, uri):
1026 """ 1026 """
1027 Follow a remote user by uri (username@domain). 1027 Follow a remote user by uri (username@domain).
@@ -1086,7 +1086,7 @@ class Mastodon:
1086 url = '/api/v1/accounts/{0}/unmute'.format(str(id)) 1086 url = '/api/v1/accounts/{0}/unmute'.format(str(id))
1087 return self.__api_request('POST', url) 1087 return self.__api_request('POST', url)
1088 1088
1089 @api_version("1.1.1", "1.6.0") 1089 @api_version("1.1.1", "2.1.0")
1090 def account_update_credentials(self, display_name=None, note=None, 1090 def account_update_credentials(self, display_name=None, note=None,
1091 avatar=None, header=None): 1091 avatar=None, header=None):
1092 """ 1092 """
Powered by cgit v1.2.3 (git 2.41.0)