aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/index.rst37
1 files changed, 34 insertions, 3 deletions
diff --git a/docs/index.rst b/docs/index.rst
index de14554..48cea67 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -73,6 +73,28 @@ a loop without ever sleeping at all yourself. It is for applications that would
73just pretend there is no such thing as a rate limit and are fine with sometimes not 73just pretend there is no such thing as a rate limit and are fine with sometimes not
74being very interactive. 74being very interactive.
75 75
76A note about pagination
77-----------------------
78Many of Mastodons API endpoints are paginated. What this means is that if you request
79data from them, you might not get all the data at once - instead, you might only get the
80first few results.
81
82All endpoints that are paginated have three parameters: since_id, max_id and limit.
83since_id allows you to specify the smallest id you want in the returned data. max_id,
84similarly, allows you to specify the largest. By specifying either one (generally,
85only one, not both) of them you can go through pages forwards and backwards.
86
87limit allows you to specify how many results you would like returned. Note that an
88instance may choose to return less results than you requested.
89
90The responses returned by paginated endpoints contain a "link" header that specifies
91which parameters to use to get the next and previous pages. Mastodon.py parses these
92and stores them (if present) in the first (for the previous page) and last (for the
93next page) item of the returned list as _pagination_prev and _pagination_next.
94
95There are convenience functions available for fetching the previous and next page of
96a paginated request as well as for fetching all pages starting from a first page.
97
76A note about IDs 98A note about IDs
77---------------- 99----------------
78Mastodons API uses IDs in several places: User IDs, Toot IDs, ... 100Mastodons API uses IDs in several places: User IDs, Toot IDs, ...
@@ -257,8 +279,9 @@ you can simply pass them to the constructor of the class, too!
257Note that while it is perfectly reasonable to log back in whenever 279Note that while it is perfectly reasonable to log back in whenever
258your app starts, registering a new application on every 280your app starts, registering a new application on every
259startup is not, so don't do that - instead, register an application 281startup is not, so don't do that - instead, register an application
260once, and then persist your client id and secret. Convenience 282once, and then persist your client id and secret. A convenient method
261methods for this are provided. 283for this is provided by the functions dealing with registering the app,
284logging in and the Mastodon classes constructor.
262 285
263To talk to an instance different from the flagship instance, specify 286To talk to an instance different from the flagship instance, specify
264the api_base_url (usually, just the URL of the instance, i.e. 287the api_base_url (usually, just the URL of the instance, i.e.
@@ -405,12 +428,20 @@ Writing data: Reports
405 428
406Writing data: Domain blocks 429Writing data: Domain blocks
407--------------------------- 430---------------------------
408These methods allow you to block and unblock all statuses from a domain 431These functions allow you to block and unblock all statuses from a domain
409for the logged-in user. 432for the logged-in user.
410 433
411.. automethod:: Mastodon.domain_block 434.. automethod:: Mastodon.domain_block
412.. automethod:: Mastodon.domain_unblock 435.. automethod:: Mastodon.domain_unblock
413 436
437Pagination
438----------
439These functions allow for convenient retrieval of paginated data.
440
441.. automethod:: Mastodon.fetch_next
442.. automethod:: Mastodon.fetch_previous
443.. automethod:: Mastodon.fetch_remaining
444
414Streaming 445Streaming
415--------- 446---------
416These functions allow access to the streaming API. 447These functions allow access to the streaming API.
Powered by cgit v1.2.3 (git 2.41.0)