aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/index.rst117
1 files changed, 109 insertions, 8 deletions
diff --git a/docs/index.rst b/docs/index.rst
index a91cfb7..e7c9366 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,114 @@ 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
42A note about IDs
43----------------
44Mastodons API uses IDs in several places: User IDs, Toot IDs, ...
45
46While debugging, it might be tempting to copy-paste in IDs from the
47web interface into your code. This will not work, as the IDs on the web
48interface and in the URLs are not the same as the IDs used internally
49in the API, so don't do that.
50
51Return values
52-------------
40Unless otherwise specified, all data is returned as python 53Unless otherwise specified, all data is returned as python
41dictionaries, matching the JSON format used by the API. 54dictionaries, 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 55
46.. py:module:: mastodon 56User dicts
47.. py:class: Mastodon 57~~~~~~~~~~
58.. code-block:: python
59
60 mastodon.account(<numerical id>)
61 # Returns the following dictionary:
62 {
63 'display_name': The user's display name
64 'acct': The user's account name as username@domain (@domain omitted for local users)
65 'following_count': How many people they follow
66 'url': Their URL; usually 'https://mastodon.social/users/<acct>'
67 'statuses_count': How many statuses they have
68 'followers_count': How many followers they have
69 'avatar': URL for their avatar
70 'note': Their bio
71 'header': URL for their header image
72 'id': Same as <numerical id>
73 'username': The username (what you @ them with)
74 }
75
76Toot dicts
77~~~~~~~~~~
78.. code-block:: python
79
80 mastodon.toot("Hello from Python")
81 # Returns the following dictionary:
82 {
83 'sensitive': Denotes whether the toot is marked sensitive
84 'created_at': Creation time
85 'mentions': A list of account dicts mentioned in the toot
86 'uri': Descriptor for the toot
87 EG 'tag:mastodon.social,2016-11-25:objectId=<id>:objectType=Status'
88 'tags': A list of hashtag dicts used in the toot
89 'in_reply_to_id': Numerical id of the toot this toot is in response to
90 'id': Numerical id of this toot
91 'reblogs_count': Number of reblogs
92 'favourites_count': Number of favourites
93 'reblog': Denotes whether the toot is a reblog
94 'url': URL of the toot
95 'content': Content of the toot, as HTML: '<p>Hello from Python</p>'
96 'favourited': Denotes whether the logged in user has favourited this toot
97 'account': Account dict for the logged in account
98 }
99
100Relationship dicts
101~~~~~~~~~~~~~~~~~~
102.. code-block:: python
103
104 mastodon.account_follow(<numerical id>)
105 # Returns the following dictionary:
106 {
107 'followed_by': Boolean denoting whether they follow you back
108 'following': Boolean denoting whether you follow them
109 'id': Numerical id (same one as <numerical id>)
110 'blocking': Boolean denoting whether you are blocking them
111 }
112
113Notification dicts
114~~~~~~~~~~~~~~~~~~
115.. code-block:: python
116
117 mastodon.notifications()[0]
118 # Returns the following dictionary:
119 {
120 'id': id of the notification.
121 'type': "mention", "reblog", "favourite" or "follow".
122 'status': In case of "mention", the mentioning status.
123 In case of reblog / favourite, the reblogged / favourited status.
124 'account': User dict of the user from whom the notification originates.
125 }
126
127Context dicts
128~~~~~~~~~~~~~
129.. code-block:: python
130
131 mastodon.status_context(<numerical id>)
132 # Returns the following dictionary:
133 {
134 'descendants': A list of toot dicts
135 'ancestors': A list of toot dicts
136 }
137
138Media dicts
139~~~~~~~~~~~
140.. code-block:: python
141
142 mastodon.media_post("image.jpg", "image/jpeg")
143 # Returns the following dictionary:
144 {
145 'text_url': The display text for the media (what shows up in toots)
146 'preview_url': The URL for the media preview
147 'type': Media type, EG 'image'
148 'url': The URL for the media
149 }
48 150
49App registration and user authentication 151App registration and user authentication
50---------------------------------------- 152----------------------------------------
@@ -91,7 +193,6 @@ This function allows you to get information about a users notifications.
91 193
92.. automethod:: Mastodon.notifications 194.. automethod:: Mastodon.notifications
93 195
94
95Reading data: Accounts 196Reading data: Accounts
96---------------------- 197----------------------
97These functions allow you to get information about accounts and 198These functions allow you to get information about accounts and
@@ -103,7 +204,6 @@ their relationships.
103.. automethod:: Mastodon.account_following 204.. automethod:: Mastodon.account_following
104.. automethod:: Mastodon.account_followers 205.. automethod:: Mastodon.account_followers
105.. automethod:: Mastodon.account_relationships 206.. automethod:: Mastodon.account_relationships
106.. automethod:: Mastodon.account_suggestions
107.. automethod:: Mastodon.account_search 207.. automethod:: Mastodon.account_search
108 208
109Writing data: Statuses 209Writing data: Statuses
@@ -113,11 +213,11 @@ interact with already posted statuses.
113 213
114.. automethod:: Mastodon.status_post 214.. automethod:: Mastodon.status_post
115.. automethod:: Mastodon.toot 215.. automethod:: Mastodon.toot
116.. automethod:: Mastodon.status_delete
117.. automethod:: Mastodon.status_reblog 216.. automethod:: Mastodon.status_reblog
118.. automethod:: Mastodon.status_unreblog 217.. automethod:: Mastodon.status_unreblog
119.. automethod:: Mastodon.status_favourite 218.. automethod:: Mastodon.status_favourite
120.. automethod:: Mastodon.status_unfavourite 219.. automethod:: Mastodon.status_unfavourite
220.. automethod:: Mastodon.status_delete
121 221
122Writing data: Accounts 222Writing data: Accounts
123---------------------- 223----------------------
@@ -137,6 +237,7 @@ to attach media to statuses.
137 237
138.. automethod:: Mastodon.media_post 238.. automethod:: Mastodon.media_post
139 239
240
140.. _Mastodon: https://github.com/Gargron/mastodon 241.. _Mastodon: https://github.com/Gargron/mastodon
141.. _Mastodon flagship instance: http://mastodon.social/ 242.. _Mastodon flagship instance: http://mastodon.social/
142.. _Mastodon api docs: https://github.com/Gargron/mastodon/wiki/API 243.. _Mastodon api docs: https://github.com/Gargron/mastodon/wiki/API
Powered by cgit v1.2.3 (git 2.41.0)