diff options
author | halcy <halcy@ARARAGI-KUN> | 2022-11-28 01:31:04 +0200 |
---|---|---|
committer | halcy <halcy@ARARAGI-KUN> | 2022-11-28 01:31:04 +0200 |
commit | c49364fcc4981eee500dcde34f2e494fdd15ff96 (patch) | |
tree | 18debe40c3bd42044f5f98a8bbab28be1e6aa60b /docs | |
parent | 13d6ff69e97452a014e40f8d511bbee6b39a392e (diff) | |
download | mastodon.py-c49364fcc4981eee500dcde34f2e494fdd15ff96.tar.gz |
Some more doc split tests
Diffstat (limited to 'docs')
-rw-r--r-- | docs/01_general.rst | 31 | ||||
-rw-r--r-- | docs/02_return_values.rst | 743 | ||||
-rw-r--r-- | docs/03_errors.rst | 36 | ||||
-rw-r--r-- | docs/04_auth.rst | 36 | ||||
-rw-r--r-- | docs/index.rst | 11 |
5 files changed, 855 insertions, 2 deletions
diff --git a/docs/01_general.rst b/docs/01_general.rst index 0ea3ac4..70c7e6e 100644 --- a/docs/01_general.rst +++ b/docs/01_general.rst | |||
@@ -1,3 +1,6 @@ | |||
1 | General information | ||
2 | =================== | ||
3 | |||
1 | Rate limiting | 4 | Rate limiting |
2 | ------------- | 5 | ------------- |
3 | Mastodon's API rate limits per user account. By default, the limit is 300 requests | 6 | Mastodon's API rate limits per user account. By default, the limit is 300 requests |
@@ -117,6 +120,34 @@ you can also just write | |||
117 | 120 | ||
118 | and everything will work as intended. | 121 | and everything will work as intended. |
119 | 122 | ||
123 | Versioning | ||
124 | ---------- | ||
125 | Mastodon.py will check if a certain endpoint is available before doing API | ||
126 | calls. By default, it checks against the version of Mastodon retrieved on | ||
127 | init(), or the version you specified. Mastodon.py can be set (in the | ||
128 | constructor) to either check if an endpoint is available at all (this is the | ||
129 | default) or to check if the endpoint is available and behaves as in the newest | ||
130 | Mastodon version (with regards to parameters as well as return values). | ||
131 | Version checking can also be disabled altogether. If a version check fails, | ||
132 | Mastodon.py throws a `MastodonVersionError`. | ||
133 | |||
134 | Some functions need to check what version of Mastodon they are talking to. | ||
135 | These will generally use a cached version to avoid sending a lot of pointless | ||
136 | requests. | ||
137 | |||
138 | Many non-mainline forks have various different formats for their versions and | ||
139 | they have different, incompatible ideas about how to report version. Mastodon.py | ||
140 | tries its best to figure out what is going on, but success is not guaranteed. | ||
141 | |||
142 | With the following functions, you can make Mastodon.py re-check the server | ||
143 | version or explicitly determine if a specific minimum Version is available. | ||
144 | Long-running applications that aim to support multiple Mastodon versions | ||
145 | should do this from time to time in case a server they are running against | ||
146 | updated. | ||
147 | |||
148 | .. automethod:: Mastodon.retrieve_mastodon_version | ||
149 | .. automethod:: Mastodon.verify_minimum_version | ||
150 | |||
120 | A brief note on block lists | 151 | A brief note on block lists |
121 | --------------------------- | 152 | --------------------------- |
122 | Mastodon.py used to block three instances because these were particularly notorious for | 153 | Mastodon.py used to block three instances because these were particularly notorious for |
diff --git a/docs/02_return_values.rst b/docs/02_return_values.rst new file mode 100644 index 0000000..52947e9 --- /dev/null +++ b/docs/02_return_values.rst | |||
@@ -0,0 +1,743 @@ | |||
1 | Return values | ||
2 | ============= | ||
3 | |||
4 | Unless otherwise specified, all data is returned as Python dictionaries, matching | ||
5 | the JSON format used by the API. Dates returned by the API are in ISO 8601 format | ||
6 | and are parsed into Python datetime objects. | ||
7 | |||
8 | To make access easier, the dictionaries returned are wrapped by a class that adds | ||
9 | read-only attributes for all dict values - this means that, for example, instead of | ||
10 | writing | ||
11 | |||
12 | .. code-block:: python | ||
13 | |||
14 | description = mastodon.account_verify_credentials()["source"]["note"] | ||
15 | |||
16 | you can also just write | ||
17 | |||
18 | .. code-block:: python | ||
19 | |||
20 | description = mastodon.account_verify_credentials().source.note | ||
21 | |||
22 | and everything will work as intended. The class used for this is exposed as | ||
23 | `AttribAccessDict`. | ||
24 | |||
25 | User / account dicts | ||
26 | -------------------- | ||
27 | .. _user dict: | ||
28 | .. _user dicts: | ||
29 | .. _account dict: | ||
30 | .. _account dicts: | ||
31 | |||
32 | .. code-block:: python | ||
33 | |||
34 | mastodon.account(<numerical id>) | ||
35 | # Returns the following dictionary: | ||
36 | { | ||
37 | 'id': # Same as <numerical id> | ||
38 | 'username': # The username (what you @ them with) | ||
39 | 'acct': # The user's account name as username@domain (@domain omitted for local users) | ||
40 | 'display_name': # The user's display name | ||
41 | 'discoverable': # True if the user is listed in the user directory, false if not. None | ||
42 | # for remote users. | ||
43 | 'group': # A boolean indicating whether the account represents a group rather than an | ||
44 | # individual. | ||
45 | 'locked': # Denotes whether the account can be followed without a follow request | ||
46 | 'created_at': # Account creation time | ||
47 | 'following_count': # How many people they follow | ||
48 | 'followers_count': # How many followers they have | ||
49 | 'statuses_count': # How many statuses they have | ||
50 | 'note': # Their bio | ||
51 | 'url': # Their URL; for example 'https://mastodon.social/users/<acct>' | ||
52 | 'avatar': # URL for their avatar, can be animated | ||
53 | 'header': # URL for their header image, can be animated | ||
54 | 'avatar_static': # URL for their avatar, never animated | ||
55 | 'header_static': # URL for their header image, never animated | ||
56 | 'source': # Additional information - only present for user dict returned | ||
57 | # from account_verify_credentials() | ||
58 | 'moved_to_account': # If set, a user dict of the account this user has | ||
59 | # set up as their moved-to address. | ||
60 | 'bot': # Boolean indicating whether this account is automated. | ||
61 | 'fields': # List of up to four dicts with free-form 'name' and 'value' profile info. | ||
62 | # For fields with "this is me" type verification, verified_at is set to the | ||
63 | # last verification date (It is None otherwise) | ||
64 | 'emojis': # List of custom emoji used in name, bio or fields | ||
65 | 'discoverable': # Indicates whether or not a user is visible on the discovery page | ||
66 | } | ||
67 | |||
68 | mastodon.account_verify_credentials()["source"] | ||
69 | # Returns the following dictionary: | ||
70 | { | ||
71 | 'privacy': # The user's default visibility setting ("private", "unlisted" or "public") | ||
72 | 'sensitive': # Denotes whether user media should be marked sensitive by default | ||
73 | 'note': # Plain text version of the user's bio | ||
74 | } | ||
75 | |||
76 | Toot / Status dicts | ||
77 | ---------- | ||
78 | .. _toot dict: | ||
79 | .. _toot dicts: | ||
80 | .. _status dict: | ||
81 | .. _status dicts: | ||
82 | |||
83 | .. code-block:: python | ||
84 | |||
85 | mastodon.toot("Hello from Python") | ||
86 | # Returns the following dictionary: | ||
87 | { | ||
88 | 'id': # Numerical id of this toot | ||
89 | 'uri': # Descriptor for the toot | ||
90 | # EG 'tag:mastodon.social,2016-11-25:objectId=<id>:objectType=Status' | ||
91 | 'url': # URL of the toot | ||
92 | 'account': # User dict for the account which posted the status | ||
93 | 'in_reply_to_id': # Numerical id of the toot this toot is in response to | ||
94 | 'in_reply_to_account_id': # Numerical id of the account this toot is in response to | ||
95 | 'reblog': # Denotes whether the toot is a reblog. If so, set to the original toot dict. | ||
96 | 'content': # Content of the toot, as HTML: '<p>Hello from Python</p>' | ||
97 | 'created_at': # Creation time | ||
98 | 'reblogs_count': # Number of reblogs | ||
99 | 'favourites_count': # Number of favourites | ||
100 | 'reblogged': # Denotes whether the logged in user has boosted this toot | ||
101 | 'favourited': # Denotes whether the logged in user has favourited this toot | ||
102 | 'sensitive': # Denotes whether media attachments to the toot are marked sensitive | ||
103 | 'spoiler_text': # Warning text that should be displayed before the toot content | ||
104 | 'visibility': # Toot visibility ('public', 'unlisted', 'private', or 'direct') | ||
105 | 'mentions': # A list of users dicts mentioned in the toot, as Mention dicts | ||
106 | 'media_attachments': # A list of media dicts of attached files | ||
107 | 'emojis': # A list of custom emojis used in the toot, as Emoji dicts | ||
108 | 'tags': # A list of hashtag used in the toot, as Hashtag dicts | ||
109 | 'bookmarked': # True if the status is bookmarked by the logged in user, False if not. | ||
110 | 'application': # Application dict for the client used to post the toot (Does not federate | ||
111 | # and is therefore always None for remote toots, can also be None for | ||
112 | # local toots for some legacy applications). | ||
113 | 'language': # The language of the toot, if specified by the server, | ||
114 | # as ISO 639-1 (two-letter) language code. | ||
115 | 'muted': # Boolean denoting whether the user has muted this status by | ||
116 | # way of conversation muting | ||
117 | 'pinned': # Boolean denoting whether or not the status is currently pinned for the | ||
118 | # associated account. | ||
119 | 'replies_count': # The number of replies to this status. | ||
120 | 'card': # A preview card for links from the status, if present at time of delivery, | ||
121 | # as card dict. | ||
122 | 'poll': # A poll dict if a poll is attached to this status. | ||
123 | } | ||
124 | |||
125 | Status edit dicts | ||
126 | ----------------- | ||
127 | .. _status edit dict: | ||
128 | |||
129 | .. code-block:: python | ||
130 | |||
131 | mastodonstatus_history(id)[0] | ||
132 | # Returns the following dictionary | ||
133 | { | ||
134 | TODO | ||
135 | } | ||
136 | |||
137 | Mention dicts | ||
138 | ------------- | ||
139 | .. _mention dict: | ||
140 | |||
141 | .. code-block:: python | ||
142 | |||
143 | { | ||
144 | 'url': # Mentioned user's profile URL (potentially remote) | ||
145 | 'username': # Mentioned user's user name (not including domain) | ||
146 | 'acct': # Mentioned user's account name (including domain) | ||
147 | 'id': # Mentioned user's (local) account ID | ||
148 | } | ||
149 | |||
150 | Scheduled status / toot dicts | ||
151 | ----------------------------- | ||
152 | .. _scheduled status dict: | ||
153 | .. _scheduled status dicts: | ||
154 | .. _scheduled toot dict: | ||
155 | .. _scheduled toot dicts: | ||
156 | |||
157 | .. code-block:: python | ||
158 | |||
159 | mastodon.status_post("text", scheduled_at=the_future) | ||
160 | # Returns the following dictionary: | ||
161 | { | ||
162 | 'id': # Scheduled toot ID (note: Not the id of the toot once it gets posted!) | ||
163 | 'scheduled_at': # datetime object describing when the toot is to be posted | ||
164 | 'params': # Parameters for the scheduled toot, specifically | ||
165 | { | ||
166 | 'text': # Toot text | ||
167 | 'in_reply_to_id': # ID of the toot this one is a reply to | ||
168 | 'media_ids': # IDs of media attached to this toot | ||
169 | 'sensitive': # Whether this toot is sensitive or not | ||
170 | 'visibility': # Visibility of the toot | ||
171 | 'idempotency': # Idempotency key for the scheduled toot | ||
172 | 'scheduled_at': # Present, but generally "None" | ||
173 | 'spoiler_text': # CW text for this toot | ||
174 | 'application_id': # ID of the application that scheduled the toot | ||
175 | 'poll': # Poll parameters, as a poll dict | ||
176 | }, | ||
177 | 'media_attachments': # Array of media dicts for the attachments to the scheduled toot | ||
178 | } | ||
179 | |||
180 | Poll dicts | ||
181 | ---------- | ||
182 | .. _poll dict: | ||
183 | |||
184 | .. code-block:: python | ||
185 | |||
186 | # Returns the following dictionary: | ||
187 | mastodon.poll(id) | ||
188 | { | ||
189 | 'id': # The polls ID | ||
190 | 'expires_at': # The time at which the poll is set to expire | ||
191 | 'expired': # Boolean denoting whether you can still vote in this poll | ||
192 | 'multiple': # Boolean indicating whether it is allowed to vote for more than one option | ||
193 | 'votes_count': # Total number of votes cast in this poll | ||
194 | 'voted': # Boolean indicating whether the logged-in user has already voted in this poll | ||
195 | 'options': # The poll options as a list of dicts, each option with a title and a | ||
196 | # votes_count field. votes_count can be None if the poll creator has | ||
197 | # chosen to hide vote totals until the poll expires and it hasn't yet. | ||
198 | 'emojis': # List of emoji dicts for all emoji used in answer strings, | ||
199 | 'own_votes': # The logged-in users votes, as a list of indices to the options. | ||
200 | } | ||
201 | |||
202 | |||
203 | Conversation dicts | ||
204 | ------------------ | ||
205 | .. _conversation dict: | ||
206 | |||
207 | .. code-block:: python | ||
208 | |||
209 | mastodon.conversations()[0] | ||
210 | # Returns the following dictionary: | ||
211 | { | ||
212 | 'id': # The ID of this conversation object | ||
213 | 'unread': # Boolean indicating whether this conversation has yet to be | ||
214 | # read by the user | ||
215 | 'accounts': # List of accounts (other than the logged-in account) that | ||
216 | # are part of this conversation | ||
217 | 'last_status': # The newest status in this conversation | ||
218 | } | ||
219 | |||
220 | Hashtag dicts | ||
221 | ------------- | ||
222 | .. _hashtag dict: | ||
223 | |||
224 | .. code-block:: python | ||
225 | |||
226 | { | ||
227 | 'name': # Hashtag name (not including the #) | ||
228 | 'url': # Hashtag URL (can be remote) | ||
229 | 'history': # List of usage history dicts for up to 7 days. Not present in statuses. | ||
230 | } | ||
231 | |||
232 | Hashtag usage history dicts | ||
233 | --------------------------- | ||
234 | .. _hashtag usage history dict: | ||
235 | |||
236 | .. code-block:: python | ||
237 | |||
238 | { | ||
239 | 'day': # Date of the day this history dict is for | ||
240 | 'uses': # Number of statuses using this hashtag on that day | ||
241 | 'accounts': # Number of accounts using this hashtag in at least one status on that day | ||
242 | } | ||
243 | |||
244 | Emoji dicts | ||
245 | ----------- | ||
246 | .. _emoji dict: | ||
247 | |||
248 | .. code-block:: python | ||
249 | |||
250 | { | ||
251 | 'shortcode': # Emoji shortcode, without surrounding colons | ||
252 | 'url': # URL for the emoji image, can be animated | ||
253 | 'static_url': # URL for the emoji image, never animated | ||
254 | 'visible_in_picker': # True if the emoji is enabled, False if not. | ||
255 | 'category': # The category to display the emoji under (not present if none is set) | ||
256 | } | ||
257 | |||
258 | Application dicts | ||
259 | ----------------- | ||
260 | .. _application dict: | ||
261 | |||
262 | .. code-block:: python | ||
263 | |||
264 | { | ||
265 | 'name': # The applications name | ||
266 | 'website': # The applications website | ||
267 | 'vapid_key': # A vapid key that can be used in web applications | ||
268 | } | ||
269 | |||
270 | |||
271 | Relationship dicts | ||
272 | ------------------ | ||
273 | .. _relationship dict: | ||
274 | |||
275 | .. code-block:: python | ||
276 | |||
277 | mastodon.account_follow(<numerical id>) | ||
278 | # Returns the following dictionary: | ||
279 | { | ||
280 | 'id': # Numerical id (same one as <numerical id>) | ||
281 | 'following': # Boolean denoting whether the logged-in user follows the specified user | ||
282 | 'followed_by': # Boolean denoting whether the specified user follows the logged-in user | ||
283 | 'blocking': # Boolean denoting whether the logged-in user has blocked the specified user | ||
284 | 'blocked_by': # Boolean denoting whether the logged-in user has been blocked by the specified user, if information is available | ||
285 | 'muting': # Boolean denoting whether the logged-in user has muted the specified user | ||
286 | 'muting_notifications': # Boolean denoting wheter the logged-in user has muted notifications | ||
287 | # related to the specified user | ||
288 | 'requested': # Boolean denoting whether the logged-in user has sent the specified | ||
289 | # user a follow request | ||
290 | 'domain_blocking': # Boolean denoting whether the logged-in user has blocked the | ||
291 | # specified users domain | ||
292 | 'showing_reblogs': # Boolean denoting whether the specified users reblogs show up on the | ||
293 | # logged-in users Timeline | ||
294 | 'endorsed': # Boolean denoting wheter the specified user is being endorsed / featured by the | ||
295 | # logged-in user | ||
296 | 'note': # A free text note the logged in user has created for this account (not publicly visible) | ||
297 | 'notifying' # Boolean denoting whether the logged-in user has requested to get notified every time the followed user posts | ||
298 | } | ||
299 | |||
300 | Filter dicts | ||
301 | ------------ | ||
302 | .. _filter dict: | ||
303 | |||
304 | .. code-block:: python | ||
305 | |||
306 | mastodon.filter(<numerical id>) | ||
307 | # Returns the following dictionary: | ||
308 | { | ||
309 | 'id': # Numerical id of the filter | ||
310 | 'phrase': # Filtered keyword or phrase | ||
311 | 'context': # List of places where the filters are applied ('home', 'notifications', 'public', 'thread') | ||
312 | 'expires_at': # Expiry date for the filter | ||
313 | 'irreversible': # Boolean denoting if this filter is executed server-side | ||
314 | # or if it should be ran client-side. | ||
315 | 'whole_word': # Boolean denoting whether this filter can match partial words | ||
316 | } | ||
317 | |||
318 | Notification dicts | ||
319 | ------------------ | ||
320 | .. _notification dict: | ||
321 | |||
322 | .. code-block:: python | ||
323 | |||
324 | mastodon.notifications()[0] | ||
325 | # Returns the following dictionary: | ||
326 | { | ||
327 | 'id': # id of the notification | ||
328 | 'type': # "mention", "reblog", "favourite", "follow", "poll" or "follow_request" | ||
329 | 'created_at': # The time the notification was created | ||
330 | 'account': # User dict of the user from whom the notification originates | ||
331 | 'status': # In case of "mention", the mentioning status | ||
332 | # In case of reblog / favourite, the reblogged / favourited status | ||
333 | } | ||
334 | |||
335 | Context dicts | ||
336 | ------------- | ||
337 | .. _context dict: | ||
338 | |||
339 | .. code-block:: python | ||
340 | |||
341 | mastodon.status_context(<numerical id>) | ||
342 | # Returns the following dictionary: | ||
343 | { | ||
344 | 'ancestors': # A list of toot dicts | ||
345 | 'descendants': # A list of toot dicts | ||
346 | } | ||
347 | |||
348 | List dicts | ||
349 | ---------- | ||
350 | .. _list dict: | ||
351 | |||
352 | .. code-block:: python | ||
353 | |||
354 | mastodon.list(<numerical id>) | ||
355 | # Returns the following dictionary: | ||
356 | { | ||
357 | 'id': # id of the list | ||
358 | 'title': # title of the list | ||
359 | } | ||
360 | |||
361 | Media dicts | ||
362 | ----------- | ||
363 | .. _media dict: | ||
364 | |||
365 | .. code-block:: python | ||
366 | |||
367 | mastodon.media_post("image.jpg", "image/jpeg") | ||
368 | # Returns the following dictionary: | ||
369 | { | ||
370 | 'id': # The ID of the attachment. | ||
371 | 'type': # Media type: 'image', 'video', 'gifv', 'audio' or 'unknown'. | ||
372 | 'url': # The URL for the image in the local cache | ||
373 | 'remote_url': # The remote URL for the media (if the image is from a remote instance) | ||
374 | 'preview_url': # The URL for the media preview | ||
375 | 'text_url': # The display text for the media (what shows up in toots) | ||
376 | 'meta': # Dictionary of two metadata dicts (see below), | ||
377 | # 'original' and 'small' (preview). Either may be empty. | ||
378 | # May additionally contain an "fps" field giving a videos frames per second (possibly | ||
379 | # rounded), and a "length" field giving a videos length in a human-readable format. | ||
380 | # Note that a video may have an image as preview. | ||
381 | # May also contain a 'focus' dict and a media 'colors' dict. | ||
382 | 'blurhash': # The blurhash for the image, used for preview / placeholder generation | ||
383 | 'description': # If set, the user-provided description for this media. | ||
384 | } | ||
385 | |||
386 | # Metadata dicts (image) - all fields are optional: | ||
387 | { | ||
388 | 'width': # Width of the image in pixels | ||
389 | 'height': # Height of the image in pixels | ||
390 | 'aspect': # Aspect ratio of the image as a floating point number | ||
391 | 'size': # Textual representation of the image size in pixels, e.g. '800x600' | ||
392 | } | ||
393 | |||
394 | # Metadata dicts (video, gifv) - all fields are optional: | ||
395 | { | ||
396 | 'width': # Width of the video in pixels | ||
397 | 'heigh': # Height of the video in pixels | ||
398 | 'frame_rate': # Exact frame rate of the video in frames per second. | ||
399 | # Can be an integer fraction (i.e. "20/7") | ||
400 | 'duration': # Duration of the video in seconds | ||
401 | 'bitrate': # Average bit-rate of the video in bytes per second | ||
402 | } | ||
403 | |||
404 | # Metadata dicts (audio) - all fields are optional: | ||
405 | { | ||
406 | 'duration': # Duration of the audio file in seconds | ||
407 | 'bitrate': # Average bit-rate of the audio file in bytes per second | ||
408 | } | ||
409 | |||
410 | # Focus Metadata dict: | ||
411 | { | ||
412 | 'x': # Focus point x coordinate (between -1 and 1) | ||
413 | 'y': # Focus point x coordinate (between -1 and 1) | ||
414 | } | ||
415 | |||
416 | # Media colors dict: | ||
417 | { | ||
418 | 'foreground': # Estimated foreground colour for the attachment thumbnail | ||
419 | 'background': # Estimated background colour for the attachment thumbnail | ||
420 | 'accent': # Estimated accent colour for the attachment thumbnail | ||
421 | |||
422 | Card dicts | ||
423 | ---------- | ||
424 | .. _card dict: | ||
425 | |||
426 | .. code-block:: python | ||
427 | |||
428 | mastodon.status_card(<numerical id>): | ||
429 | # Returns the following dictionary | ||
430 | { | ||
431 | 'url': # The URL of the card. | ||
432 | 'title': # The title of the card. | ||
433 | 'description': # The description of the card. | ||
434 | 'type': # Embed type: 'link', 'photo', 'video', or 'rich' | ||
435 | 'image': # (optional) The image associated with the card. | ||
436 | |||
437 | # OEmbed data (all optional): | ||
438 | 'author_name': # Name of the embedded contents author | ||
439 | 'author_url': # URL pointing to the embedded contents author | ||
440 | 'description': # Description of the embedded content | ||
441 | 'width': # Width of the embedded object | ||
442 | 'height': # Height of the embedded object | ||
443 | 'html': # HTML string of the embed | ||
444 | 'provider_name': # Name of the provider from which the embed originates | ||
445 | 'provider_url': # URL pointing to the embeds provider | ||
446 | 'blurhash': # (optional) Blurhash of the preview image | ||
447 | } | ||
448 | |||
449 | Search result dicts | ||
450 | ------------------- | ||
451 | .. _search result dict: | ||
452 | |||
453 | .. code-block:: python | ||
454 | |||
455 | mastodon.search("<query>") | ||
456 | # Returns the following dictionary | ||
457 | { | ||
458 | 'accounts': # List of user dicts resulting from the query | ||
459 | 'hashtags': # List of hashtag dicts resulting from the query | ||
460 | 'statuses': # List of toot dicts resulting from the query | ||
461 | } | ||
462 | |||
463 | Instance dicts | ||
464 | -------------- | ||
465 | .. _instance dict: | ||
466 | |||
467 | .. code-block:: python | ||
468 | |||
469 | mastodon.instance() | ||
470 | # Returns the following dictionary | ||
471 | { | ||
472 | 'domain': # The instances domain name | ||
473 | 'description': # A brief instance description set by the admin | ||
474 | 'short_description': # An even briefer instance description | ||
475 | 'email': # The admin contact email | ||
476 | 'title': # The instance's title | ||
477 | 'uri': # The instance's URL | ||
478 | 'version': # The instance's Mastodon version | ||
479 | 'urls': # Additional URLs dict, presently only 'streaming_api' with the | ||
480 | # stream websocket address. | ||
481 | 'stats': # A dictionary containing three stats, user_count (number of local users), | ||
482 | # status_count (number of local statuses) and domain_count (number of known | ||
483 | # instance domains other than this one). | ||
484 | 'contact_account': # User dict of the primary contact for the instance | ||
485 | 'languages': # Array of ISO 639-1 (two-letter) language codes the instance | ||
486 | # has chosen to advertise. | ||
487 | 'registrations': # Boolean indication whether registrations on this instance are open | ||
488 | # (True) or not (False) | ||
489 | 'approval_required': # True if account approval is required when registering, | ||
490 | 'rules': # List of dicts with `id` and `text` fields, one for each server rule set by the admin | ||
491 | } | ||
492 | |||
493 | Activity dicts | ||
494 | -------------- | ||
495 | .. _activity dict: | ||
496 | |||
497 | .. code-block:: python | ||
498 | |||
499 | mastodon.instance_activity()[0] | ||
500 | # Returns the following dictionary | ||
501 | { | ||
502 | 'week': # Date of the first day of the week the stats were collected for | ||
503 | 'logins': # Number of users that logged in that week | ||
504 | 'registrations': # Number of new users that week | ||
505 | 'statuses': # Number of statuses posted that week | ||
506 | } | ||
507 | |||
508 | Report dicts | ||
509 | ------------ | ||
510 | .. _report dict: | ||
511 | |||
512 | .. code-block:: python | ||
513 | |||
514 | mastodon.admin_reports()[0] | ||
515 | # Returns the following dictionary | ||
516 | { | ||
517 | 'id': # Numerical id of the report | ||
518 | 'action_taken': # True if a moderator or admin has processed the | ||
519 | # report, False otherwise. | ||
520 | |||
521 | # The following fields are only present in the report dicts returned by moderation API: | ||
522 | 'comment': # Text comment submitted with the report | ||
523 | 'created_at': # Time at which this report was created, as a datetime object | ||
524 | 'updated_at': # Last time this report has been updated, as a datetime object | ||
525 | 'account': # User dict of the user that filed this report | ||
526 | 'target_account': # Account that has been reported with this report | ||
527 | 'assigned_account': # If the report as been assigned to an account, | ||
528 | # User dict of that account (None if not) | ||
529 | 'action_taken_by_account': # User dict of the account that processed this report | ||
530 | 'statuses': # List of statuses attached to the report, as toot dicts | ||
531 | } | ||
532 | |||
533 | Push subscription dicts | ||
534 | ----------------------- | ||
535 | .. _push subscription dict: | ||
536 | |||
537 | .. code-block:: python | ||
538 | |||
539 | mastodon.push_subscription() | ||
540 | # Returns the following dictionary | ||
541 | { | ||
542 | 'id': # Numerical id of the push subscription | ||
543 | 'endpoint': # Endpoint URL for the subscription | ||
544 | 'server_key': # Server pubkey used for signature verification | ||
545 | 'alerts': # Subscribed events - dict that may contain keys 'follow', | ||
546 | # 'favourite', 'reblog' and 'mention', with value True | ||
547 | # if webpushes have been requested for those events. | ||
548 | } | ||
549 | |||
550 | Push notification dicts | ||
551 | ----------------------- | ||
552 | .. _push notification dict: | ||
553 | |||
554 | .. code-block:: python | ||
555 | |||
556 | mastodon.push_subscription_decrypt_push(...) | ||
557 | # Returns the following dictionary | ||
558 | { | ||
559 | 'access_token': # Access token that can be used to access the API as the | ||
560 | # notified user | ||
561 | 'body': # Text body of the notification | ||
562 | 'icon': # URL to an icon for the notification | ||
563 | 'notification_id': # ID that can be passed to notification() to get the full | ||
564 | # notification object, | ||
565 | 'notification_type': # 'mention', 'reblog', 'follow' or 'favourite' | ||
566 | 'preferred_locale': # The user's preferred locale | ||
567 | 'title': # Title for the notification | ||
568 | } | ||
569 | |||
570 | Preference dicts | ||
571 | ---------------- | ||
572 | .. _preference dict: | ||
573 | |||
574 | .. code-block:: python | ||
575 | |||
576 | mastodon.preferences() | ||
577 | # Returns the following dictionary | ||
578 | { | ||
579 | 'posting:default:visibility': # The default visibility setting for the user's posts, | ||
580 | # as a string | ||
581 | 'posting:default:sensitive': # Boolean indicating whether the user's uploads should | ||
582 | # be marked sensitive by default | ||
583 | 'posting:default:language': # The user's default post language, if set (None if not) | ||
584 | 'reading:expand:media': # How the user wishes to be shown sensitive media. Can be | ||
585 | # 'default' (hide if sensitive), 'hide_all' or 'show_all' | ||
586 | 'reading:expand:spoilers': # Boolean indicating whether the user wishes to expand | ||
587 | # content warnings by default | ||
588 | } | ||
589 | |||
590 | Featured tag dicts | ||
591 | ------------------ | ||
592 | .. _featured tag dict: | ||
593 | |||
594 | .. code-block:: python | ||
595 | |||
596 | mastodon.featured_tags()[0] | ||
597 | # Returns the following dictionary: | ||
598 | { | ||
599 | 'id': # The featured tags id | ||
600 | 'name': # The featured tags name (without leading #) | ||
601 | 'statuses_count': # Number of publicly visible statuses posted with this hashtag that this instance knows about | ||
602 | 'last_status_at': # The last time a public status containing this hashtag was added to this instance's database | ||
603 | # (can be None if there are none) | ||
604 | } | ||
605 | |||
606 | Read marker dicts | ||
607 | ----------------- | ||
608 | .. _read marker dict: | ||
609 | |||
610 | .. code-block:: python | ||
611 | |||
612 | mastodon.markers_get()["home"] | ||
613 | # Returns the following dictionary: | ||
614 | { | ||
615 | 'last_read_id': # ID of the last read object in the timeline | ||
616 | 'version': # A counter that is incremented whenever the marker is set to a new status | ||
617 | 'updated_at': # The time the marker was last set, as a datetime object | ||
618 | } | ||
619 | |||
620 | Announcement dicts | ||
621 | ------------------ | ||
622 | .. _announcement dict: | ||
623 | |||
624 | .. code-block:: python | ||
625 | |||
626 | mastodon.annoucements()[0] | ||
627 | # Returns the following dictionary: | ||
628 | { | ||
629 | 'id': # The annoucements id | ||
630 | 'content': # The contents of the annoucement, as an html string | ||
631 | 'starts_at': # The annoucements start time, as a datetime object. Can be None | ||
632 | 'ends_at': # The annoucements end time, as a datetime object. Can be None | ||
633 | 'all_day': # Boolean indicating whether the annoucement represents an "all day" event | ||
634 | 'published_at': # The annoucements publish time, as a datetime object | ||
635 | 'updated_at': # The annoucements last updated time, as a datetime object | ||
636 | 'read': # A boolean indicating whether the logged in user has dismissed the annoucement | ||
637 | 'mentions': # Users mentioned in the annoucement, as a list of mention dicts | ||
638 | 'tags': # Hashtags mentioned in the announcement, as a list of hashtag dicts | ||
639 | 'emojis': # Custom emoji used in the annoucement, as a list of emoji dicts | ||
640 | 'reactions': # Reactions to the annoucement, as a list of reaction dicts (documented inline here): | ||
641 | [ { | ||
642 | 'name': # Name of the custom emoji or unicode emoji of the reaction | ||
643 | 'count': # Reaction counter (i.e. number of users who have added this reaction) | ||
644 | 'me': # True if the logged-in user has reacted with this emoji, false otherwise | ||
645 | 'url': # URL for the custom emoji image | ||
646 | 'static_url': # URL for a never-animated version of the custom emoji image | ||
647 | } ], | ||
648 | } | ||
649 | |||
650 | Familiar follower dicts | ||
651 | ----------------------- | ||
652 | .. _familiar follower dict: | ||
653 | |||
654 | .. code-block:: python | ||
655 | |||
656 | mastodon.account_familiar_followers(1)[0] | ||
657 | # Returns the following dictionary: | ||
658 | { | ||
659 | |||
660 | } | ||
661 | |||
662 | Admin account dicts | ||
663 | ------------------- | ||
664 | .. _admin account dict: | ||
665 | |||
666 | .. code-block:: python | ||
667 | |||
668 | mastodon.admin_account(id) | ||
669 | # Returns the following dictionary | ||
670 | { | ||
671 | 'id': # The users id, | ||
672 | 'username': # The users username, no leading @ | ||
673 | 'domain': # The users domain | ||
674 | 'created_at': # The time of account creation | ||
675 | 'email': # For local users, the user's email | ||
676 | 'ip': # For local users, the user's last known IP address | ||
677 | 'role': # 'admin', 'moderator' or None | ||
678 | 'confirmed': # For local users, False if the user has not confirmed their email, True otherwise | ||
679 | 'suspended': # Boolean indicating whether the user has been suspended | ||
680 | 'silenced': # Boolean indicating whether the user has been suspended | ||
681 | 'disabled': # For local users, boolean indicating whether the user has had their login disabled | ||
682 | 'approved': # For local users, False if the user is pending, True otherwise | ||
683 | 'locale': # For local users, the locale the user has set, | ||
684 | 'invite_request': # If the user requested an invite, the invite request comment of that user. (TODO permanent?) | ||
685 | 'invited_by_account_id': # Present if the user was invited by another user and set to the inviting users id. | ||
686 | 'account': # The user's account, as a standard user dict | ||
687 | } | ||
688 | |||
689 | Admin domain block dicts | ||
690 | ------------------------ | ||
691 | .. _admin domain block dict: | ||
692 | |||
693 | .. code-block::python | ||
694 | |||
695 | mastodon.domain_blocks(id=1) | ||
696 | #Returns the following dictionary: | ||
697 | { | ||
698 | 'id': #Str. The database id of a domain block, | ||
699 | 'domain': #Str. The root domain of a block, ie: "example.com", | ||
700 | 'created_at': #Datetime of the block creation. | ||
701 | 'severity': #Str. Severity of the domain block, ie: "suspend". | ||
702 | 'reject_media': #Boolean. True if media is not downloaded from this domain. | ||
703 | 'reject_reports': #Boolean. True if reports are automatically ignored from this domain. | ||
704 | 'private_comment': #Str. Private admin comment for a block. None if not set. | ||
705 | 'public_comment': #Str. Publicly viewable (depending on settings) comment about this domain. None if not set. | ||
706 | 'obfuscate': #Boolean. True if domain name is obfuscated when listing. | ||
707 | } | ||
708 | |||
709 | Admin measure dicts | ||
710 | ------------------- | ||
711 | .. _admin measure dict: | ||
712 | |||
713 | .. code-block:: python | ||
714 | |||
715 | api.admin_measures(datetime.now() - timedelta(hours=24*5), datetime.now(), active_users=True) | ||
716 | # Returns the following dictionary | ||
717 | { | ||
718 | TODO | ||
719 | } | ||
720 | |||
721 | Admin dimension dicts | ||
722 | --------------------- | ||
723 | .. _admin dimension dict: | ||
724 | |||
725 | .. code-block:: python | ||
726 | |||
727 | api.admin_dimensions(datetime.now() - timedelta(hours=24*5), datetime.now(), languages=True) | ||
728 | # Returns the following dictionary | ||
729 | { | ||
730 | TODO | ||
731 | } | ||
732 | |||
733 | Admin retention dicts | ||
734 | --------------------- | ||
735 | .. _admin retention dict: | ||
736 | |||
737 | .. code-block:: python | ||
738 | |||
739 | api.admin_retention(datetime.now() - timedelta(hours=24*5), datetime.now()) | ||
740 | # Returns the following dictionary | ||
741 | { | ||
742 | TODO | ||
743 | } | ||
diff --git a/docs/03_errors.rst b/docs/03_errors.rst new file mode 100644 index 0000000..fce7af7 --- /dev/null +++ b/docs/03_errors.rst | |||
@@ -0,0 +1,36 @@ | |||
1 | Error handling | ||
2 | ============== | ||
3 | When Mastodon.py encounters an error, it will raise an exception, generally with | ||
4 | some text included to tell you what went wrong. | ||
5 | |||
6 | The base class that all Mastodon exceptions inherit from is `MastodonError`. | ||
7 | If you are only interested in the fact an error was raised somewhere in | ||
8 | Mastodon.py, and not the details, this is the exception you can catch. | ||
9 | |||
10 | `MastodonIllegalArgumentError` is generally a programming problem - you asked the | ||
11 | API to do something obviously invalid (i.e. specify a privacy option that does | ||
12 | not exist). | ||
13 | |||
14 | `MastodonFileNotFoundError` and `MastodonNetworkError` are IO errors - could be you | ||
15 | specified a wrong URL, could be the internet is down or your hard drive is | ||
16 | dying. They inherit from `MastodonIOError`, for easy catching. There is a sub-error | ||
17 | of `MastodonNetworkError`, `MastodonReadTimeout`, which is thrown when a streaming | ||
18 | API stream times out during reading. | ||
19 | |||
20 | `MastodonAPIError` is an error returned from the Mastodon instance - the server | ||
21 | has decided it can't fulfil your request (i.e. you requested info on a user that | ||
22 | does not exist). It is further split into `MastodonNotFoundError` (API returned 404) | ||
23 | and `MastodonUnauthorizedError` (API returned 401). Different error codes might exist, | ||
24 | but are not currently handled separately. | ||
25 | |||
26 | `MastodonMalformedEventError` is raised when a streaming API listener receives an | ||
27 | invalid event. There have been reports that this can sometimes happen after prolonged | ||
28 | operation due to an upstream problem in the requests/urllib libraries. | ||
29 | |||
30 | `MastodonRatelimitError` is raised when you hit an API rate limit. You should try | ||
31 | again after a while (see the rate limiting section above). | ||
32 | |||
33 | `MastodonServerError` is raised when the server throws an internal error, likely due | ||
34 | to server misconfiguration. | ||
35 | |||
36 | `MastodonVersionError` is raised when a version check for an API call fails. | ||
diff --git a/docs/04_auth.rst b/docs/04_auth.rst new file mode 100644 index 0000000..454d6a2 --- /dev/null +++ b/docs/04_auth.rst | |||
@@ -0,0 +1,36 @@ | |||
1 | App registration and user authentication | ||
2 | ======================================== | ||
3 | |||
4 | Before you can use the Mastodon API, you have to register your | ||
5 | application (which gets you a client key and client secret) | ||
6 | and then log in (which gets you an access token) and out (revoking | ||
7 | the access token you are logged in with). These functions | ||
8 | allow you to do those things. Additionally, it is also possible | ||
9 | to programmatically register a new user. | ||
10 | |||
11 | For convenience, once you have a client id, secret and access token, | ||
12 | you can simply pass them to the constructor of the class, too! | ||
13 | |||
14 | Note that while it is perfectly reasonable to log back in whenever | ||
15 | your app starts, registering a new application on every | ||
16 | startup is not, so don't do that - instead, register an application | ||
17 | once, and then persist your client id and secret. A convenient method | ||
18 | for this is provided by the functions dealing with registering the app, | ||
19 | logging in and the Mastodon classes constructor. | ||
20 | |||
21 | To talk to an instance different from the flagship instance, specify | ||
22 | the api_base_url (usually, just the URL of the instance, i.e. | ||
23 | https://mastodon.social/ for the flagship instance). If no protocol | ||
24 | is specified, Mastodon.py defaults to https. | ||
25 | |||
26 | .. automethod:: Mastodon.create_app | ||
27 | .. automethod:: Mastodon.__init__ | ||
28 | .. _log_in(): | ||
29 | .. automethod:: Mastodon.log_in | ||
30 | .. _auth_request_url(): | ||
31 | .. automethod:: Mastodon.auth_request_url | ||
32 | .. _set_language(): | ||
33 | .. automethod:: Mastodon.set_language | ||
34 | .. automethod:: Mastodon.revoke_access_token | ||
35 | .. automethod:: Mastodon.create_account | ||
36 | .. automethod:: Mastodon.email_resend_confirmation | ||
diff --git a/docs/index.rst b/docs/index.rst index 7597bc4..69a7b3d 100644 --- a/docs/index.rst +++ b/docs/index.rst | |||
@@ -58,6 +58,13 @@ about who helped with which particular feature or fix in the changelog. | |||
58 | .. _Official Mastodon API docs: https://docs.joinmastodon.org/client/intro/ | 58 | .. _Official Mastodon API docs: https://docs.joinmastodon.org/client/intro/ |
59 | 59 | ||
60 | .. toctree:: | 60 | .. toctree:: |
61 | :caption: Introduction | ||
62 | Mastodon.py <self> | ||
63 | 01_general | ||
64 | 02_return_values | ||
65 | 03_errors | ||
61 | 66 | ||
62 | Mastodon.py <self> | 67 | .. toctree:: |
63 | 01_general | 68 | :caption: API methods |
69 | Mastodon.py <self> | ||
70 | 04_auth | ||