aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/index.rst194
1 files changed, 89 insertions, 105 deletions
diff --git a/docs/index.rst b/docs/index.rst
index 2d61f14..f388182 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,5 +1,7 @@
1Mastodon.py 1Mastodon.py
2=========== 2===========
3.. py:module:: mastodon
4.. py:class: Mastodon
3 5
4.. code-block:: python 6.. code-block:: python
5 7
@@ -37,14 +39,96 @@ as a single python module. By default, it talks to the
37`Mastodon flagship instance`_, but it can be set to talk to any 39`Mastodon flagship instance`_, but it can be set to talk to any
38node running Mastodon. 40node running Mastodon.
39 41
42Return values
43-------------
44
40Unless otherwise specified, all data is returned as python 45Unless otherwise specified, all data is returned as python
41dictionaries, matching the JSON format used by the API. 46dictionaries, matching the JSON format used by the API.
42For complete documentation on what every function returns,
43check the `Mastodon API docs`_, or just play around a bit - the
44format of the data is generally very easy to understand.
45 47
46.. py:module:: mastodon 48User dicts
47.. py:class: Mastodon 49~~~~~~~~~~
50
51.. code-block:: python
52
53 {
54 'display_name': The user's display name
55 'acct': The user's account name as username@domain (@domain omitted for local users)
56 'following_count': How many people they follow
57 'url': Their URL; usually 'https://mastodon.social/users/<acct>'
58 'statuses_count': How many statuses they have
59 'followers_count': How many followers they have
60 'avatar': URL for their avatar
61 'note': Their bio
62 'header': URL for their header image
63 'id': Same as <numerical id>
64 'username': The username (what you @ them with)
65 }
66
67Toot dicts
68~~~~~~~~~~
69.. code-block:: python
70
71 mastodon.toot("Hello from Python")
72 # Returns the following dictionary:
73 {
74 'sensitive': Denotes whether the toot is marked sensitive
75 'created_at': Creation time
76 'mentions': A list of account dicts mentioned in the toot
77 'uri': Descriptor for the toot
78 EG 'tag:mastodon.social,2016-11-25:objectId=<id>:objectType=Status'
79 'tags': A list of hashtag dicts used in the toot
80 'in_reply_to_id': Numerical id of the toot this toot is in response to
81 'id': Numerical id of this toot
82 'reblogs_count': Number of reblogs
83 'favourites_count': Number of favourites
84 'reblog': Denotes whether the toot is a reblog
85 'url': URL of the toot
86 'content': Content of the toot, as HTML: '<p>Hello from Python</p>'
87 'favourited': Denotes whether the logged in user has favourited this toot
88 'account': Account dict for the logged in account
89 }
90
91Relationship dicts
92~~~~~~~~~~~~~~~~~~
93
94.. code-block:: python
95
96 mastodon.account_follow(<numerical id>)
97 # Returns
98 {
99 'followed_by': Boolean denoting whether they follow you back
100 'following': Boolean denoting whether you follow them
101 'id': Numerical id (same one as <numerical id>)
102 'blocking': Boolean denoting whether you are blocking them
103 }
104
105Context dicts
106~~~~~~~~~~~~~
107
108.. code-block:: python
109
110 mastodon.status_context(<numerical id>)
111 # Returns
112 {
113 'descendants': A list of toot dicts
114 'ancestors': A list of toot dicts
115 }
116
117Media dicts
118~~~~~~~~~~~
119
120.. code-block:: python
121
122 mastodon.media_post("image.jpg", "image/jpeg")
123 # Returns
124 {
125 'text_url': The display text for the media (what shows up in toots)
126 'preview_url': The URL for the media preview
127 'type': Media type, EG 'image'
128 'url': The URL for the media
129 }
130
131
48 132
49App registration and user authentication 133App registration and user authentication
50---------------------------------------- 134----------------------------------------
@@ -81,20 +165,7 @@ Reading data: Statuses
81These functions allow you to get information about single statuses. 165These functions allow you to get information about single statuses.
82 166
83.. automethod:: Mastodon.status 167.. automethod:: Mastodon.status
84
85Returns a single toot dict for the given status.
86
87.. automethod:: Mastodon.status_context 168.. automethod:: Mastodon.status_context
88
89.. code-block:: python
90
91 mastodon.status_context(<numerical id>)
92 # Returns
93 {
94 'descendants': A list of toot dicts
95 'ancestors': A list of toot dicts
96 }
97
98.. automethod:: Mastodon.status_reblogged_by 169.. automethod:: Mastodon.status_reblogged_by
99.. automethod:: Mastodon.status_favourited_by 170.. automethod:: Mastodon.status_favourited_by
100 171
@@ -104,9 +175,6 @@ This function allows you to get information about a users notifications.
104 175
105.. automethod:: Mastodon.notifications 176.. automethod:: Mastodon.notifications
106 177
107Returns a list of toot dicts for toots mentioning the current logged-in user.
108
109
110Reading data: Accounts 178Reading data: Accounts
111---------------------- 179----------------------
112These functions allow you to get information about accounts and 180These functions allow you to get information about accounts and
@@ -114,39 +182,12 @@ their relationships.
114 182
115.. automethod:: Mastodon.account 183.. automethod:: Mastodon.account
116.. automethod:: Mastodon.account_verify_credentials 184.. automethod:: Mastodon.account_verify_credentials
117
118These methods return an account dict:
119
120.. code-block:: python
121
122 mastodon.account(<numerical id>)
123 # Returns
124 {
125 'display_name': The user's display name
126 'acct': The user's account name as username@domain (@domain omitted for local users)
127 'following_count': How many people they follow
128 'url': Their URL; usually 'https://mastodon.social/users/<acct>'
129 'statuses_count': How many statuses they have
130 'followers_count': How many followers they have
131 'avatar': URL for their avatar
132 'note': Their bio
133 'header': URL for their header image
134 'id': Same as <numerical id>
135 'username': The username (what you @ them with)
136 }
137
138.. automethod:: Mastodon.account_statuses 185.. automethod:: Mastodon.account_statuses
139.. automethod:: Mastodon.account_following 186.. automethod:: Mastodon.account_following
140.. automethod:: Mastodon.account_followers 187.. automethod:: Mastodon.account_followers
141.. automethod:: Mastodon.account_relationships 188.. automethod:: Mastodon.account_relationships
142
143See following below for format of relationship dicts.
144
145.. automethod:: Mastodon.account_suggestions
146.. automethod:: Mastodon.account_search 189.. automethod:: Mastodon.account_search
147 190
148Returns a list of user dicts.
149
150Writing data: Statuses 191Writing data: Statuses
151---------------------- 192----------------------
152These functions allow you to post statuses to Mastodon and to 193These functions allow you to post statuses to Mastodon and to
@@ -158,58 +199,13 @@ interact with already posted statuses.
158.. automethod:: Mastodon.status_unreblog 199.. automethod:: Mastodon.status_unreblog
159.. automethod:: Mastodon.status_favourite 200.. automethod:: Mastodon.status_favourite
160.. automethod:: Mastodon.status_unfavourite 201.. automethod:: Mastodon.status_unfavourite
161
162These methods return a toot dict:
163
164.. code-block:: python
165
166 mastodon.toot("Hello from Python")
167 # Returns the following dictionary:
168 {
169 'sensitive': Denotes whether the toot is marked sensitive
170 'created_at': Creation time
171 'mentions': A list of account dicts mentioned in the toot
172 'uri': Descriptor for the toot
173 EG 'tag:mastodon.social,2016-11-25:objectId=<id>:objectType=Status'
174 'tags': A list of hashtag dicts used in the toot
175 'in_reply_to_id': Numerical id of the toot this toot is in response to
176 'id': Numerical id of this toot
177 'reblogs_count': Number of reblogs
178 'favourites_count': Number of favourites
179 'reblog': Denotes whether the toot is a reblog
180 'url': URL of the toot
181 'content': Content of the toot, as HTML: '<p>Hello from Python</p>'
182 'favourited': Denotes whether the logged in user has favourited this toot
183 'account': Account dict for the logged in account
184 }
185
186.. automethod:: Mastodon.status_delete 202.. automethod:: Mastodon.status_delete
187Returns an empty dict:
188
189.. code-block:: python
190
191 mastodon.delete_status(<numerical id>)
192 # Returns
193 {}
194 203
195Writing data: Accounts 204Writing data: Accounts
196---------------------- 205----------------------
197These functions allow you to interact with other accounts: To (un)follow and 206These functions allow you to interact with other accounts: To (un)follow and
198(un)block. 207(un)block.
199 208
200They return a relationship dict:
201
202.. code-block:: python
203
204 mastodon.account_follow(<numerical id>)
205 # Returns
206 {
207 'followed_by': Boolean denoting whether they follow you back
208 'following': Boolean denoting whether you follow them
209 'id': Numerical id (same one as <numerical id>)
210 'blocking': Boolean denoting whether you are blocking them
211 }
212
213.. automethod:: Mastodon.account_follow 209.. automethod:: Mastodon.account_follow
214.. automethod:: Mastodon.account_unfollow 210.. automethod:: Mastodon.account_unfollow
215.. automethod:: Mastodon.account_block 211.. automethod:: Mastodon.account_block
@@ -223,18 +219,6 @@ to attach media to statuses.
223 219
224.. automethod:: Mastodon.media_post 220.. automethod:: Mastodon.media_post
225 221
226Returns a media dict:
227
228.. code-block:: python
229
230 mastodon.media_post("image.jpg", "image/jpeg")
231 # Returns
232 {
233 'text_url': The display text for the media (what shows up in toots)
234 'preview_url': The URL for the media preview
235 'type': Media type, EG 'image'
236 'url': The URL for the media
237 }
238 222
239.. _Mastodon: https://github.com/Gargron/mastodon 223.. _Mastodon: https://github.com/Gargron/mastodon
240.. _Mastodon flagship instance: http://mastodon.social/ 224.. _Mastodon flagship instance: http://mastodon.social/
Powered by cgit v1.2.3 (git 2.41.0)