diff options
-rw-r--r-- | docs/index.rst | 30 | ||||
-rw-r--r-- | mastodon/Mastodon.py | 26 |
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. | |||
110 | ID unpacking | 110 | ID unpacking |
111 | ~~~~~~~~~~~~ | 111 | ~~~~~~~~~~~~ |
112 | Wherever Mastodon.py expects an ID as a parameter, you can also pass a | 112 | Wherever Mastodon.py expects an ID as a parameter, you can also pass a |
113 | dict that contains an id - this means that, for example, instead of saying | 113 | dict 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 | |||
156 | the JSON format used by the API. Dates returned by the API are in ISO 8601 format | 156 | the JSON format used by the API. Dates returned by the API are in ISO 8601 format |
157 | and are parsed into python datetime objects. | 157 | and are parsed into python datetime objects. |
158 | 158 | ||
159 | To make access easier, the dictionaries returned are wrapped by a class that adds | ||
160 | read-only attributes for all dict values - this means that, for example, instead of | ||
161 | writing | ||
162 | |||
163 | .. code-block:: python | ||
164 | |||
165 | description = mastodon.account_verify_credentials()["source"]["note"] | ||
166 | |||
167 | you can also just write | ||
168 | |||
169 | .. code-block:: python | ||
170 | |||
171 | description = mastodon.account_verify_credentials().source.note | ||
172 | |||
173 | and everything will work as intended. | ||
174 | |||
175 | |||
159 | User dicts | 176 | User 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 | |||
474 | Mastodon.py will check if a certain endpoint is available before doing API | 493 | Mastodon.py will check if a certain endpoint is available before doing API |
475 | calls. By default, it checks against the version of Mastodon retrieved on | 494 | calls. By default, it checks against the version of Mastodon retrieved on |
476 | init(), or the version you specified. Mastodon.py can be set (in the | 495 | init(), or the version you specified. Mastodon.py can be set (in the |
477 | constructor) to either check if an endpoint is available at all or to check | 496 | constructor) to either check if an endpoint is available at all (this is the |
478 | if the endpoint is available and behaves as in the newest Mastodon version | 497 | default) 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. | 498 | Mastodon version (with regards to parameters as well as return values). |
480 | If a version check fails, Mastodon.py throws a `MastodonVersionError`. | 499 | Version checking can also be disabled altogether. If a version check fails, |
500 | Mastodon.py throws a `MastodonVersionError`. | ||
481 | 501 | ||
482 | With the following functions, you can make Mastodon.py re-check the server | 502 | With the following functions, you can make Mastodon.py re-check the server |
483 | version or explicitly determine if a specific minimum Version is available. | 503 | version 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 | """ |