aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/index.rst98
-rw-r--r--mastodon/Mastodon.py71
2 files changed, 135 insertions, 34 deletions
diff --git a/docs/index.rst b/docs/index.rst
index 87e6fb5..80687de 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -88,18 +88,18 @@ User dicts
88 mastodon.account(<numerical id>) 88 mastodon.account(<numerical id>)
89 # Returns the following dictionary: 89 # Returns the following dictionary:
90 { 90 {
91 'display_name': # The user's display name 91 'id': # Same as <numerical id>
92 'username': # The username (what you @ them with)
92 'acct': # The user's account name as username@domain (@domain omitted for local users) 93 'acct': # The user's account name as username@domain (@domain omitted for local users)
94 'display_name': # The user's display name
95 'locked': # Denotes whether the account can be followed without a follow request
93 'following_count': # How many people they follow 96 'following_count': # How many people they follow
94 'url': # Their URL; usually 'https://mastodon.social/users/<acct>'
95 'statuses_count': # How many statuses they have
96 'followers_count': # How many followers they have 97 'followers_count': # How many followers they have
97 'avatar': # URL for their avatar 98 'statuses_count': # How many statuses they have
98 'note': # Their bio 99 'note': # Their bio
100 'url': # Their URL; usually 'https://mastodon.social/users/<acct>'
101 'avatar': # URL for their avatar
99 'header': # URL for their header image 102 'header': # URL for their header image
100 'id': # Same as <numerical id>
101 'username': # The username (what you @ them with)
102 'locked': # Denotes whether the account can be followed without a follow request
103 } 103 }
104 104
105Toot dicts 105Toot dicts
@@ -109,24 +109,28 @@ Toot dicts
109 mastodon.toot("Hello from Python") 109 mastodon.toot("Hello from Python")
110 # Returns the following dictionary: 110 # Returns the following dictionary:
111 { 111 {
112 'sensitive': # Denotes whether media attachments to the toot are marked sensitive 112 'id': # Numerical id of this toot
113 'created_at': # Creation time
114 'mentions': # A list of account dicts mentioned in the toot
115 'uri': # Descriptor for the toot 113 'uri': # Descriptor for the toot
116 # EG 'tag:mastodon.social,2016-11-25:objectId=<id>:objectType=Status' 114 # EG 'tag:mastodon.social,2016-11-25:objectId=<id>:objectType=Status'
117 'tags': # A list of hashtag dicts used in the toot 115 'url': # URL of the toot
116 'account': # Account dict for the account which posted the status
118 'in_reply_to_id': # Numerical id of the toot this toot is in response to 117 'in_reply_to_id': # Numerical id of the toot this toot is in response to
119 'media_attachments': # list of media dicts of attached files. Only present 118 'in_reply_to_account_id': # Numerical id of the account this toot is in response to
120 # when there are attached files.
121 'id': # Numerical id of this toot
122 'reblogs_count': # Number of reblogs
123 'favourites_count': # Number of favourites
124 'reblog': # Denotes whether the toot is a reblog 119 'reblog': # Denotes whether the toot is a reblog
125 'url': # URL of the toot
126 'content': # Content of the toot, as HTML: '<p>Hello from Python</p>' 120 'content': # Content of the toot, as HTML: '<p>Hello from Python</p>'
127 'spoiler_text': # Warning text that should be displayed before the toot content 121 'created_at': # Creation time
122 'reblogs_count': # Number of reblogs
123 'favourites_count': # Number of favourites
124 'reblogged': # Denotes whether the logged in user has boosted this toot
128 'favourited': # Denotes whether the logged in user has favourited this toot 125 'favourited': # Denotes whether the logged in user has favourited this toot
129 'account': # Account dict for the logged in account 126 'sensitive': # Denotes whether media attachments to the toot are marked sensitive
127 'spoiler_text': # Warning text that should be displayed before the toot content
128 'visibility': # Toot visibility ('public', 'unlisted', 'private', or 'direct')
129 'mentions': # A list of account dicts mentioned in the toot
130 'media_attachments': # list of media dicts of attached files. Only present
131 # when there are attached files.
132 'tags': # A list of hashtag dicts used in the toot
133 'application': # Application dict for the client used to post the toot
130 } 134 }
131 135
132Relationship dicts 136Relationship dicts
@@ -136,9 +140,9 @@ Relationship dicts
136 mastodon.account_follow(<numerical id>) 140 mastodon.account_follow(<numerical id>)
137 # Returns the following dictionary: 141 # Returns the following dictionary:
138 { 142 {
139 'followed_by': # Boolean denoting whether they follow you back
140 'following': # Boolean denoting whether you follow them
141 'id': # Numerical id (same one as <numerical id>) 143 'id': # Numerical id (same one as <numerical id>)
144 'following': # Boolean denoting whether you follow them
145 'followed_by': # Boolean denoting whether they follow you back
142 'blocking': # Boolean denoting whether you are blocking them 146 'blocking': # Boolean denoting whether you are blocking them
143 'muting': # Boolean denoting whether you are muting them 147 'muting': # Boolean denoting whether you are muting them
144 'requested': # Boolean denoting whether you have sent them a follow request 148 'requested': # Boolean denoting whether you have sent them a follow request
@@ -153,9 +157,10 @@ Notification dicts
153 { 157 {
154 'id': # id of the notification. 158 'id': # id of the notification.
155 'type': # "mention", "reblog", "favourite" or "follow". 159 'type': # "mention", "reblog", "favourite" or "follow".
160 'created_at': # The time the notification was created.
161 'account': # User dict of the user from whom the notification originates.
156 'status': # In case of "mention", the mentioning status. 162 'status': # In case of "mention", the mentioning status.
157 # In case of reblog / favourite, the reblogged / favourited status. 163 # In case of reblog / favourite, the reblogged / favourited status.
158 'account': # User dict of the user from whom the notification originates.
159 } 164 }
160 165
161Context dicts 166Context dicts
@@ -165,8 +170,8 @@ Context dicts
165 mastodon.status_context(<numerical id>) 170 mastodon.status_context(<numerical id>)
166 # Returns the following dictionary: 171 # Returns the following dictionary:
167 { 172 {
168 'descendants': # A list of toot dicts
169 'ancestors': # A list of toot dicts 173 'ancestors': # A list of toot dicts
174 'descendants': # A list of toot dicts
170 } 175 }
171 176
172Media dicts 177Media dicts
@@ -176,10 +181,25 @@ Media dicts
176 mastodon.media_post("image.jpg", "image/jpeg") 181 mastodon.media_post("image.jpg", "image/jpeg")
177 # Returns the following dictionary: 182 # Returns the following dictionary:
178 { 183 {
179 'text_url': # The display text for the media (what shows up in toots) 184 'id': # The ID of the attachment.
180 'preview_url': # The URL for the media preview
181 'type': # Media type, EG 'image' 185 'type': # Media type, EG 'image'
182 'url': # The URL for the media 186 'url': # The URL for the image in the local cache
187 'remote_url': # The remote URL for the media (if the image is from a remote instance)
188 'preview_url': # The URL for the media preview
189 'text_url': # The display text for the media (what shows up in toots)
190 }
191
192Card dicts
193~~~~~~~~~~
194..code-block:: python
195
196 mastodon.status_card(<numerical id>):
197 # Returns the folowing dictionary
198 {
199 'url': The URL of the card.
200 'title': The title of the card.
201 'description': The description of the card.
202 'image': (optional) The image associated with the card.
183 } 203 }
184 204
185App registration and user authentication 205App registration and user authentication
@@ -202,6 +222,13 @@ methods for this are provided.
202.. automethod:: Mastodon.log_in 222.. automethod:: Mastodon.log_in
203.. automethod:: Mastodon.auth_request_url 223.. automethod:: Mastodon.auth_request_url
204 224
225Reading data: Instance
226-----------------------
227This function allows you to fetch information associated with the
228current instance.
229
230.. automethod:: Mastodon.instance
231
205Reading data: Timelines 232Reading data: Timelines
206----------------------- 233-----------------------
207This function allows you to access the timelines a logged in 234This function allows you to access the timelines a logged in
@@ -221,6 +248,7 @@ These functions allow you to get information about single statuses.
221.. automethod:: Mastodon.status_context 248.. automethod:: Mastodon.status_context
222.. automethod:: Mastodon.status_reblogged_by 249.. automethod:: Mastodon.status_reblogged_by
223.. automethod:: Mastodon.status_favourited_by 250.. automethod:: Mastodon.status_favourited_by
251.. automethod:: Mastodon.status_card
224 252
225Reading data: Notifications 253Reading data: Notifications
226--------------------------- 254---------------------------
@@ -241,6 +269,11 @@ their relationships.
241.. automethod:: Mastodon.account_relationships 269.. automethod:: Mastodon.account_relationships
242.. automethod:: Mastodon.account_search 270.. automethod:: Mastodon.account_search
243 271
272Reading data: Follows
273---------------------
274
275.. automethod:: Mastodon.follows
276
244Reading data: Searching 277Reading data: Searching
245----------------------- 278-----------------------
246This function allows you to search for content. 279This function allows you to search for content.
@@ -256,6 +289,14 @@ muted or blocked by the logged in user.
256.. automethod:: Mastodon.mutes 289.. automethod:: Mastodon.mutes
257.. automethod:: Mastodon.blocks 290.. automethod:: Mastodon.blocks
258 291
292Reading data: Reports
293------------------------------
294These functions allow you to retrieve information about reports filed
295by the authenticated user, and file a report against a user.
296
297.. automethod:: Mastodon.reports
298.. automethod:: Mastodon.report
299
259Reading data: Favourites 300Reading data: Favourites
260------------------------ 301------------------------
261This function allows you to get information about statuses favourited 302This function allows you to get information about statuses favourited
@@ -295,6 +336,7 @@ These functions allow you to interact with other accounts: To (un)follow and
295.. automethod:: Mastodon.account_unblock 336.. automethod:: Mastodon.account_unblock
296.. automethod:: Mastodon.account_mute 337.. automethod:: Mastodon.account_mute
297.. automethod:: Mastodon.account_unmute 338.. automethod:: Mastodon.account_unmute
339.. automethod:: Mastodon.account_update_credentials
298 340
299Writing data: Follow requests 341Writing data: Follow requests
300----------------------------- 342-----------------------------
@@ -320,6 +362,6 @@ These functions allow access to the streaming API.
320.. automethod:: Mastodon.hashtag_stream 362.. automethod:: Mastodon.hashtag_stream
321 363
322 364
323.. _Mastodon: https://github.com/Gargron/mastodon 365.. _Mastodon: https://github.com/tootsuite/mastodon
324.. _Mastodon flagship instance: http://mastodon.social/ 366.. _Mastodon flagship instance: http://mastodon.social/
325.. _Mastodon api docs: https://github.com/Gargron/mastodon/wiki/API \ No newline at end of file 367.. _Mastodon api docs: https://github.com/tootsuite/documentation/
diff --git a/mastodon/Mastodon.py b/mastodon/Mastodon.py
index 003402f..3b00f37 100644
--- a/mastodon/Mastodon.py
+++ b/mastodon/Mastodon.py
@@ -211,6 +211,17 @@ class Mastodon:
211 return response['access_token'] 211 return response['access_token']
212 212
213 ### 213 ###
214 # Reading data: Instance
215 ###
216 def instance(self):
217 """
218 Retrieve basic information about the instance, including the URI and administrative contact email.
219
220 Returns a dict.
221 """
222 return self.__api_request('GET', '/api/v1/instance/')
223
224 ###
214 # Reading data: Timelines 225 # Reading data: Timelines
215 ## 226 ##
216 def timeline(self, timeline = "home", max_id = None, since_id = None, limit = None): 227 def timeline(self, timeline = "home", max_id = None, since_id = None, limit = None):
@@ -274,6 +285,14 @@ class Mastodon:
274 """ 285 """
275 return self.__api_request('GET', '/api/v1/statuses/' + str(id)) 286 return self.__api_request('GET', '/api/v1/statuses/' + str(id))
276 287
288 def status_card(self, id):
289 """
290 Fetch a card associated with a status.
291
292 Returns a card dict.
293 """
294 return self.__api_request('GET', '/api/v1/statuses/' + str(id) + '/card')
295
277 def status_context(self, id): 296 def status_context(self, id):
278 """ 297 """
279 Fetch information about ancestors and descendants of a toot. 298 Fetch information about ancestors and descendants of a toot.
@@ -380,7 +399,6 @@ class Mastodon:
380 """ 399 """
381 params = self.__generate_params(locals()) 400 params = self.__generate_params(locals())
382 return self.__api_request('GET', '/api/v1/accounts/search', params) 401 return self.__api_request('GET', '/api/v1/accounts/search', params)
383
384 402
385 ### 403 ###
386 # Reading data: Searching 404 # Reading data: Searching
@@ -415,6 +433,17 @@ class Mastodon:
415 return self.__api_request('GET', '/api/v1/blocks') 433 return self.__api_request('GET', '/api/v1/blocks')
416 434
417 ### 435 ###
436 # Reading data: Reports
437 ###
438 def reports(self):
439 """
440 Fetch a list of reports made by the authenticated user.
441
442 Returns a list of report dicts.
443 """
444 return self.__api_request('GET', '/api/v1/reports')
445
446 ###
418 # Reading data: Favourites 447 # Reading data: Favourites
419 ### 448 ###
420 def favourites(self): 449 def favourites(self):
@@ -608,6 +637,32 @@ class Mastodon:
608 """ 637 """
609 return self.__api_request('POST', '/api/v1/accounts/' + str(id) + "/unmute") 638 return self.__api_request('POST', '/api/v1/accounts/' + str(id) + "/unmute")
610 639
640 def account_update_credentials(self, display_name = None, note = None, avatar = None, header = None):
641 """
642 Update the profile for the currently authenticated user.
643
644 'note' is the user's bio.
645
646 'avatar' and 'header' are images encoded in base64, prepended by a content-type
647 (for example: 'data:image/png;base64,iVBORw0KGgoAAAA[...]')
648 """
649 params = self.__generate_params(locals())
650 return self.__api_request('PATCH', '/api/v1/accounts/update_credentials', params)
651
652 ###
653 # Writing data: Reports
654 ###
655 def report(self, account_id, status_ids, comment):
656 """
657 Report a user to the admin.
658
659 Accepts a list of toot IDs associated with the report, and a comment.
660
661 Returns a report dict.
662 """
663 params = self.__generate_params(locals())
664 return self.__api_request('POST', '/api/v1/reports/', params)
665
611 ### 666 ###
612 # Writing data: Follow requests 667 # Writing data: Follow requests
613 ### 668 ###
@@ -759,6 +814,9 @@ class Mastodon:
759 if method == 'POST': 814 if method == 'POST':
760 response_object = requests.post(self.api_base_url + endpoint, data = params, headers = headers, files = files, timeout = self.request_timeout) 815 response_object = requests.post(self.api_base_url + endpoint, data = params, headers = headers, files = files, timeout = self.request_timeout)
761 816
817 if method == 'PATCH':
818 response_object = requests.patch(self.api_base_url + endpoint, data = params, headers = headers, files = files, timeout = self.request_timeout)
819
762 if method == 'DELETE': 820 if method == 'DELETE':
763 response_object = requests.delete(self.api_base_url + endpoint, data = params, headers = headers, files = files, timeout = self.request_timeout) 821 response_object = requests.delete(self.api_base_url + endpoint, data = params, headers = headers, files = files, timeout = self.request_timeout)
764 except Exception as e: 822 except Exception as e:
@@ -794,11 +852,12 @@ class Mastodon:
794 self.ratelimit_reset = self.__datetime_to_epoch(ratelimit_reset_datetime) 852 self.ratelimit_reset = self.__datetime_to_epoch(ratelimit_reset_datetime)
795 853
796 # Adjust server time to local clock 854 # Adjust server time to local clock
797 server_time_datetime = dateutil.parser.parse(response_object.headers['Date']) 855 if 'Date' in response_object.headers:
798 server_time = self.__datetime_to_epoch(server_time_datetime) 856 server_time_datetime = dateutil.parser.parse(response_object.headers['Date'])
799 server_time_diff = time.time() - server_time 857 server_time = self.__datetime_to_epoch(server_time_datetime)
800 self.ratelimit_reset += server_time_diff 858 server_time_diff = time.time() - server_time
801 self.ratelimit_lastcall = time.time() 859 self.ratelimit_reset += server_time_diff
860 self.ratelimit_lastcall = time.time()
802 except Exception as e: 861 except Exception as e:
803 raise MastodonRatelimitError("Rate limit time calculations failed: %s" % e) 862 raise MastodonRatelimitError("Rate limit time calculations failed: %s" % e)
804 863
Powered by cgit v1.2.3 (git 2.41.0)