aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/index.rst58
1 files changed, 50 insertions, 8 deletions
diff --git a/docs/index.rst b/docs/index.rst
index d8cf1fc..ae0a3ad 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -46,7 +46,7 @@ node running Mastodon by setting api_base_url when creating the
46api object (or creating an app). 46api object (or creating an app).
47 47
48Mastodon.py aims to implement the complete public Mastodon API. As 48Mastodon.py aims to implement the complete public Mastodon API. As
49of this time, it is feature complete for Mastodon version 1.4. 49of this time, it is feature complete for Mastodon version 1.6.
50 50
51A note about rate limits 51A note about rate limits
52------------------------ 52------------------------
@@ -107,10 +107,30 @@ web interface into your code. This will not work, as the IDs on the web
107interface and in the URLs are not the same as the IDs used internally 107interface and in the URLs are not the same as the IDs used internally
108in the API, so don't do that. 108in the API, so don't do that.
109 109
110Error handling
111--------------
112When Mastodon.py encounters an error, it will raise an exception, generally with
113some text included to tell you what went wrong.
114
115MastodonIllegalArgumentError is generally a programming problem - you asked the
116API to do something obviously invalid (i.e. specify a privacy scope that does
117not exist).
118
119MastodonFileNotFoundError and MastodonNetworkError are IO errors - could be you
120specified a wrong URL, could be the internet is down or your hard drive is dying.
121
122MastodonAPIError is an error returned from the Mastodon instance - the server
123has decided it can't fullfill your request (i.e. you requested info on a user that
124does not exist).
125
126MastodonRatelimitError is raised when you hit an API rate limit. You should try
127again after a while (see the rate limiting section above).
128
110Return values 129Return values
111------------- 130-------------
112Unless otherwise specified, all data is returned as python 131Unless otherwise specified, all data is returned as python dictionaries, matching
113dictionaries, matching the JSON format used by the API. 132the JSON format used by the API. Dates returned by the API are in ISO 8601 format
133and are parsed into python datetime objects.
114 134
115User dicts 135User dicts
116~~~~~~~~~~ 136~~~~~~~~~~
@@ -124,13 +144,16 @@ User dicts
124 'acct': # The user's account name as username@domain (@domain omitted for local users) 144 'acct': # The user's account name as username@domain (@domain omitted for local users)
125 'display_name': # The user's display name 145 'display_name': # The user's display name
126 'locked': # Denotes whether the account can be followed without a follow request 146 'locked': # Denotes whether the account can be followed without a follow request
147 'created_at': # Account creation time
127 'following_count': # How many people they follow 148 'following_count': # How many people they follow
128 'followers_count': # How many followers they have 149 'followers_count': # How many followers they have
129 'statuses_count': # How many statuses they have 150 'statuses_count': # How many statuses they have
130 'note': # Their bio 151 'note': # Their bio
131 'url': # Their URL; usually 'https://mastodon.social/users/<acct>' 152 'url': # Their URL; usually 'https://mastodon.social/users/<acct>'
132 'avatar': # URL for their avatar 153 'avatar': # URL for their avatar, can be animated
133 'header': # URL for their header image 154 'header': # URL for their header image, can be animated
155 'avatar_static': # URL for their avatar, never animated
156 'header_static': # URL for their header image, never animated
134 } 157 }
135 158
136Toot dicts 159Toot dicts
@@ -157,15 +180,33 @@ Toot dicts
157 'sensitive': # Denotes whether media attachments to the toot are marked sensitive 180 'sensitive': # Denotes whether media attachments to the toot are marked sensitive
158 'spoiler_text': # Warning text that should be displayed before the toot content 181 'spoiler_text': # Warning text that should be displayed before the toot content
159 'visibility': # Toot visibility ('public', 'unlisted', 'private', or 'direct') 182 'visibility': # Toot visibility ('public', 'unlisted', 'private', or 'direct')
160 'mentions': # A list of account dicts mentioned in the toot 183 'mentions': # A list of users dicts mentioned in the toot, as Mention dicts
161 'media_attachments': # list of media dicts of attached files. Only present 184 'media_attachments': # list of media dicts of attached files. Only present
162 # when there are attached files. 185 # when there are attached files.
163 'tags': # A list of hashtag dicts used in the toot 186 'tags': # A list of hashtag used in the toot, as Hashtag dicts
164 'application': # Application dict for the client used to post the toot 187 'application': # Application dict for the client used to post the toot
165 'language': # The language of the toot, if specified by the server. 188 'language': # The language of the toot, if specified by the server.
166 'muted': # oolean denoting whether the user has muted this status by way of conversation muting. 189 'muted': # Boolean denoting whether the user has muted this status by way of conversation muting.
167 } 190 }
168 191
192Mention dicts
193~~~~~~~~~~~~~
194.. code-block:: python
195 {
196 'url': # Mentioned users profile URL (potentially remote)
197 'username': # Mentioned users user name (not including domain)
198 'acct': # Mentioned users account name (including domain)
199 'id': # Mentioned users (local) account ID
200 }
201
202Hashtag dicts
203~~~~~~~~~~~~~
204.. code-block:: python
205 {
206 'name': # Hashtag name (not including the #)
207 'url': # Hashtag URL (can be remote)
208 }
209
169Relationship dicts 210Relationship dicts
170~~~~~~~~~~~~~~~~~~ 211~~~~~~~~~~~~~~~~~~
171.. code-block:: python 212.. code-block:: python
@@ -268,6 +309,7 @@ Instance dicts
268 'title': # The instances title 309 'title': # The instances title
269 'uri': # The instances URL 310 'uri': # The instances URL
270 'version': # The instances mastodon version 311 'version': # The instances mastodon version
312 'urls': # Additional URLs dict, presently only 'streaming_api' with the stream websocket address.
271 } 313 }
272 314
273App registration and user authentication 315App registration and user authentication
Powered by cgit v1.2.3 (git 2.41.0)