kopia lustrzana https://github.com/halcy/Mastodon.py
First attempt at making docs a bit more neat
rodzic
dbceccb210
commit
2045183dee
|
@ -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.
|
1491
docs/index.rst
1491
docs/index.rst
Plik diff jest za duży
Load Diff
Ładowanie…
Reference in New Issue