1 files changed, 130 insertions, 0 deletions
diff --git a/docs/01_general.rst b/docs/01_general.rst
new file mode 100644
index 0000000..0ea3ac4
--- /dev/null
+++ b/docs/01_general.rst
@@ -0,0 +1,130 @@
+Rate limiting
+-------------
+Mastodon's API rate limits per user account. By default, the limit is 300 requests
+per 5 minute time slot. This can differ from instance to instance and is subject to change.
+Mastodon.py has three modes for dealing with rate limiting that you can pass to
+the constructor, "throw", "wait" and "pace", "wait" being the default.
+In "throw" mode, Mastodon.py makes no attempt to stick to rate limits. When
+a request hits the rate limit, it simply throws a `MastodonRateLimitError`. This is
+for applications that need to handle all rate limiting themselves (i.e. interactive apps),
+or applications wanting to use Mastodon.py in a multi-threaded context ("wait" and "pace"
+modes are not thread safe).
+.. note::
+   Rate limit information is available on the `Mastodon` object for applications that
+   implement their own rate limit handling.
+   .. attribute:: Mastodon.ratelimit_remaining
+      Number of requests allowed until the next reset.
+   .. attribute:: Mastodon.ratelimit_reset
+      Time at which the rate limit will next be reset, as a POSIX timestamp.
+   .. attribute:: Mastodon.ratelimit_limit
+      Total number of requests allowed between resets. Typically 300.
+   .. attribute:: Mastodon.ratelimit_lastcall
+      Time at which these values have last been seen and updated, as a POSIX timestamp.
+In "wait" mode, once a request hits the rate limit, Mastodon.py will wait until
+the rate limit resets and then try again, until the request succeeds or an error
+is encountered. This mode is for applications that would rather just not worry about rate limits
+much, don't poll the API all that often, and are okay with a call sometimes just taking
+a while.
+In "pace" mode, Mastodon.py will delay each new request after the first one such that,
+if requests were to continue at the same rate, only a certain fraction (set in the
+constructor as `ratelimit_pacefactor`) of the rate limit will be used up. The fraction can
+be (and by default, is) greater than one. If the rate limit is hit, "pace" behaves like
+"wait". This mode is probably the most advanced one and allows you to just poll in
+a loop without ever sleeping at all yourself. It is for applications that would rather
+just pretend there is no such thing as a rate limit and are fine with sometimes not
+being very interactive.
+In addition to the per-user limit, there is a per-IP limit of 7500 requests per 5
+minute time slot, and tighter limits on logins. Mastodon.py does not make any effort
+to respect these.
+If your application requires many hits to endpoints that are available without logging
+in, do consider using Mastodon.py without authenticating to get the full per-IP limit.
+Pagination
+----------
+Many of Mastodon's API endpoints are paginated. What this means is that if you request
+data from them, you might not get all the data at once - instead, you might only get the
+first few results.
+All endpoints that are paginated have four parameters: `since_id`, `max_id`, `min_id` and
+`limit`. `since_id` allows you to specify the smallest id you want in the returned data, but
+you will still always get the newest data, so if there are too many statuses between
+the newest one and `since_id`, some will not be returned. `min_id`, on the other hand, gives
+you statuses with that minimum id and newer, starting at the given id. `max_id`, similarly,
+allows you to specify the largest id you want. By specifying either min_id or `max_id`
+(generally, only one, not both, though specifying both is supported starting with Mastodon
+version 3.3.0) of them you can go through pages forwards and backwards.
+On Mastodon mainline, you can, pass datetime objects as IDs when fetching posts,
+since the IDs used are Snowflake IDs and dates can be approximately converted to those.
+This is guaranteed to work on mainline Mastodon servers and very likely to work on all
+forks, but will **not** work on other servers implementing the API, like Pleroma, Misskey
+or Gotosocial. You should not use this if you want your application to be universally
+compatible. It's also relatively coarse-grained.
+`limit` allows you to specify how many results you would like returned. Note that an
+instance may choose to return less results than you requested - by default, Mastodon
+will return no more than 40 statuses and no more than 80 accounts no matter how high
+you set the limit.
+The responses returned by paginated endpoints contain a "link" header that specifies
+which parameters to use to get the next and previous pages. Mastodon.py parses these
+and stores them (if present) in the first (for the previous page) and last (for the
+next page) item of the returned list as _pagination_prev and _pagination_next. They
+are accessible only via attribute-style access. Note that this means that if you
+want to persist pagination info with your data, you'll have to take care of that
+manually (or persist objects, not just dicts).
+There are convenience functions available for fetching the previous and next page of
+a paginated request as well as for fetching all pages starting from a first page.
+IDs and unpacking
+-----------------
+Mastodon's API uses IDs in several places: User IDs, Toot IDs, ...
+While debugging, it might be tempting to copy-paste IDs from the
+web interface into your code. This will not work, as the IDs on the web
+interface and in the URLs are not the same as the IDs used internally
+in the API, so don't do that.
+ID unpacking
+~~~~~~~~~~~~
+Wherever Mastodon.py expects an ID as a parameter, you can also pass a
+dict that contains an id - this means that, for example, instead of writing
+.. code-block:: python
+    mastodon.status_post("@somebody wow!", in_reply_to_id = toot["id"])
+you can also just write
+.. code-block:: python
+    mastodon.status_post("@somebody wow!", in_reply_to_id = toot)
+and everything will work as intended.
+A brief note on block lists
+---------------------------
+Mastodon.py used to block three instances because these were particularly notorious for
+harassing trans people and I don't feel like I have an obligation to let software I 
+distribute help people who want my friends to die. I don't want to be associated with 
+that, at all. 
+Those instances are now all gone, any point that could have been has been made, and 
+there is no list anymore.
+Trans rights are human rights.

diff --git a/docs/01_general.rst b/docs/01_general.rst new file mode 100644 index 0000000..0ea3ac4 --- /dev/null +++ b/docs/01_general.rst
@@ -0,0 +1,130 @@
	1	Rate limiting
	2	-------------
	3	Mastodon's API rate limits per user account. By default, the limit is 300 requests
	4	per 5 minute time slot. This can differ from instance to instance and is subject to change.
	5	Mastodon.py has three modes for dealing with rate limiting that you can pass to
	6	the constructor, "throw", "wait" and "pace", "wait" being the default.
	7
	8	In "throw" mode, Mastodon.py makes no attempt to stick to rate limits. When
	9	a request hits the rate limit, it simply throws a `MastodonRateLimitError`. This is
	10	for applications that need to handle all rate limiting themselves (i.e. interactive apps),
	11	or applications wanting to use Mastodon.py in a multi-threaded context ("wait" and "pace"
	12	modes are not thread safe).
	13
	14	.. note::
	15	Rate limit information is available on the `Mastodon` object for applications that
	16	implement their own rate limit handling.
	17
	18	.. attribute:: Mastodon.ratelimit_remaining
	19
	20	Number of requests allowed until the next reset.
	21
	22	.. attribute:: Mastodon.ratelimit_reset
	23
	24	Time at which the rate limit will next be reset, as a POSIX timestamp.
	25
	26	.. attribute:: Mastodon.ratelimit_limit
	27
	28	Total number of requests allowed between resets. Typically 300.
	29
	30	.. attribute:: Mastodon.ratelimit_lastcall
	31
	32	Time at which these values have last been seen and updated, as a POSIX timestamp.
	33
	34	In "wait" mode, once a request hits the rate limit, Mastodon.py will wait until
	35	the rate limit resets and then try again, until the request succeeds or an error
	36	is encountered. This mode is for applications that would rather just not worry about rate limits
	37	much, don't poll the API all that often, and are okay with a call sometimes just taking
	38	a while.
	39
	40	In "pace" mode, Mastodon.py will delay each new request after the first one such that,
	41	if requests were to continue at the same rate, only a certain fraction (set in the
	42	constructor as `ratelimit_pacefactor`) of the rate limit will be used up. The fraction can
	43	be (and by default, is) greater than one. If the rate limit is hit, "pace" behaves like
	44	"wait". This mode is probably the most advanced one and allows you to just poll in
	45	a loop without ever sleeping at all yourself. It is for applications that would rather
	46	just pretend there is no such thing as a rate limit and are fine with sometimes not
	47	being very interactive.
	48
	49	In addition to the per-user limit, there is a per-IP limit of 7500 requests per 5
	50	minute time slot, and tighter limits on logins. Mastodon.py does not make any effort
	51	to respect these.
	52
	53	If your application requires many hits to endpoints that are available without logging
	54	in, do consider using Mastodon.py without authenticating to get the full per-IP limit.
	55
	56	Pagination
	57	----------
	58	Many of Mastodon's API endpoints are paginated. What this means is that if you request
	59	data from them, you might not get all the data at once - instead, you might only get the
	60	first few results.
	61
	62	All endpoints that are paginated have four parameters: `since_id`, `max_id`, `min_id` and
	63	`limit`. `since_id` allows you to specify the smallest id you want in the returned data, but
	64	you will still always get the newest data, so if there are too many statuses between
	65	the newest one and `since_id`, some will not be returned. `min_id`, on the other hand, gives
	66	you statuses with that minimum id and newer, starting at the given id. `max_id`, similarly,
	67	allows you to specify the largest id you want. By specifying either min_id or `max_id`
	68	(generally, only one, not both, though specifying both is supported starting with Mastodon
	69	version 3.3.0) of them you can go through pages forwards and backwards.
	70
	71	On Mastodon mainline, you can, pass datetime objects as IDs when fetching posts,
	72	since the IDs used are Snowflake IDs and dates can be approximately converted to those.
	73	This is guaranteed to work on mainline Mastodon servers and very likely to work on all
	74	forks, but will not work on other servers implementing the API, like Pleroma, Misskey
	75	or Gotosocial. You should not use this if you want your application to be universally
	76	compatible. It's also relatively coarse-grained.
	77
	78	`limit` allows you to specify how many results you would like returned. Note that an
	79	instance may choose to return less results than you requested - by default, Mastodon
	80	will return no more than 40 statuses and no more than 80 accounts no matter how high
	81	you set the limit.
	82
	83	The responses returned by paginated endpoints contain a "link" header that specifies
	84	which parameters to use to get the next and previous pages. Mastodon.py parses these
	85	and stores them (if present) in the first (for the previous page) and last (for the
	86	next page) item of the returned list as _pagination_prev and _pagination_next. They
	87	are accessible only via attribute-style access. Note that this means that if you
	88	want to persist pagination info with your data, you'll have to take care of that
	89	manually (or persist objects, not just dicts).
	90
	91	There are convenience functions available for fetching the previous and next page of
	92	a paginated request as well as for fetching all pages starting from a first page.
	93
	94	IDs and unpacking
	95	-----------------
	96	Mastodon's API uses IDs in several places: User IDs, Toot IDs, ...
	97
	98	While debugging, it might be tempting to copy-paste IDs from the
	99	web interface into your code. This will not work, as the IDs on the web
	100	interface and in the URLs are not the same as the IDs used internally
	101	in the API, so don't do that.
	102
	103	ID unpacking
	104	~~~~~~~~~~~~
	105	Wherever Mastodon.py expects an ID as a parameter, you can also pass a
	106	dict that contains an id - this means that, for example, instead of writing
	107
	108	.. code-block:: python
	109
	110	mastodon.status_post("@somebody wow!", in_reply_to_id = toot["id"])
	111
	112	you can also just write
	113
	114	.. code-block:: python
	115
	116	mastodon.status_post("@somebody wow!", in_reply_to_id = toot)
	117
	118	and everything will work as intended.
	119
	120	A brief note on block lists
	121	---------------------------
	122	Mastodon.py used to block three instances because these were particularly notorious for
	123	harassing trans people and I don't feel like I have an obligation to let software I
	124	distribute help people who want my friends to die. I don't want to be associated with
	125	that, at all.
	126
	127	Those instances are now all gone, any point that could have been has been made, and
	128	there is no list anymore.
	129
	130	Trans rights are human rights.