diff options
author | halcy <halcy@ARARAGI-KUN> | 2022-11-29 00:50:02 +0200 |
---|---|---|
committer | halcy <halcy@ARARAGI-KUN> | 2022-11-29 00:50:02 +0200 |
commit | 43c7d7ceb8da17954aedee96bd6fb5444a4a728c (patch) | |
tree | bb7cdad59a16447841adc15cb047202b47661220 /docs/10_streaming.rst | |
parent | bd3db974d771d753e7732fabe6a050b779c466e2 (diff) | |
download | mastodon.py-43c7d7ceb8da17954aedee96bd6fb5444a4a728c.tar.gz |
Restructure the docs, a lot
Diffstat (limited to 'docs/10_streaming.rst')
-rw-r--r-- | docs/10_streaming.rst | 75 |
1 files changed, 75 insertions, 0 deletions
diff --git a/docs/10_streaming.rst b/docs/10_streaming.rst new file mode 100644 index 0000000..7a7723b --- /dev/null +++ b/docs/10_streaming.rst | |||
@@ -0,0 +1,75 @@ | |||
1 | Streaming | ||
2 | ========= | ||
3 | .. py:module:: mastodon | ||
4 | .. py:class: Mastodon | ||
5 | |||
6 | These functions allow access to the streaming API. For the public, local and hashtag streams, | ||
7 | access is generally possible without authenticating. | ||
8 | |||
9 | If `run_async` is False, these methods block forever (or until an error is encountered). | ||
10 | |||
11 | If `run_async` is True, the listener will listen on another thread and these methods | ||
12 | will return a handle corresponding to the open connection. If, in addition, `reconnect_async` is True, | ||
13 | the thread will attempt to reconnect to the streaming API if any errors are encountered, waiting | ||
14 | `reconnect_async_wait_sec` seconds between reconnection attempts. Note that no effort is made | ||
15 | to "catch up" - events created while the connection is broken will not be received. If you need to make | ||
16 | sure to get absolutely all notifications / deletes / toots, you will have to do that manually, e.g. | ||
17 | using the `on_abort` handler to fill in events since the last received one and then reconnecting. | ||
18 | Both `run_async` and `reconnect_async` default to false, and you'll have to set each to true | ||
19 | separately to get the behaviour described above. | ||
20 | |||
21 | The connection may be closed at any time by calling the handles close() method. The | ||
22 | current status of the handler thread can be checked with the handles is_alive() function, | ||
23 | and the streaming status can be checked by calling is_receiving(). | ||
24 | |||
25 | The streaming functions take instances of `StreamListener` as the `listener` parameter. | ||
26 | A `CallbackStreamListener` class that allows you to specify function callbacks | ||
27 | directly is included for convenience. | ||
28 | |||
29 | For new well-known events implement the streaming function in `StreamListener` or `CallbackStreamListener`. | ||
30 | The function name is `on_` + the event name. If the event name contains dots, they are replaced with | ||
31 | underscored, e.g. for an event called 'status.update' the listener function should be named `on_status_update`. | ||
32 | |||
33 | It may be that future Mastodon versions will come with completely new (unknown) event names. | ||
34 | If you want to do something when such an event is received, override the listener function `on_unknown_event`. | ||
35 | This has an additional parameter `name` which informs about the name of the event. `unknown_event` contains the | ||
36 | content of the event. Alternatively, a callback function can be passed in the `unknown_event_handler` parameter | ||
37 | in the `CallbackStreamListener` constructor. | ||
38 | |||
39 | Note that the `unknown_event` handler is *not* guaranteed to receive events once they have been implemented. | ||
40 | Events will only go to this handler temporarily, while Mastodon.py has not been updated. Changes to what events | ||
41 | do and do not go into the handler will not be considered a breaking change. If you want to handle a new event whose | ||
42 | name you _do_ know, define an appropriate handler in your StreamListener, which will work even if it is not listed here. | ||
43 | |||
44 | When in not-async mode or async mode without async_reconnect, the stream functions may raise | ||
45 | various exceptions: `MastodonMalformedEventError` if a received event cannot be parsed and | ||
46 | `MastodonNetworkError` if any connection problems occur. | ||
47 | |||
48 | Mastodon.py currently does not support websocket based, multiplexed streams, but might in the future. | ||
49 | |||
50 | Stream endpoints | ||
51 | ---------------- | ||
52 | .. automethod:: Mastodon.stream_user | ||
53 | .. automethod:: Mastodon.stream_public | ||
54 | .. automethod:: Mastodon.stream_local | ||
55 | .. automethod:: Mastodon.stream_hashtag | ||
56 | .. automethod:: Mastodon.stream_list | ||
57 | .. automethod:: Mastodon.stream_healthy | ||
58 | |||
59 | StreamListener | ||
60 | -------------- | ||
61 | |||
62 | .. autoclass:: StreamListener | ||
63 | .. automethod:: StreamListener.on_update | ||
64 | .. automethod:: StreamListener.on_notification | ||
65 | .. automethod:: StreamListener.on_delete | ||
66 | .. automethod:: StreamListener.on_conversation | ||
67 | .. automethod:: StreamListener.on_status_update | ||
68 | .. automethod:: StreamListener.on_unknown_event | ||
69 | .. automethod:: StreamListener.on_abort | ||
70 | .. automethod:: StreamListener.handle_heartbeat | ||
71 | |||
72 | CallbackStreamListener | ||
73 | ~~~~~~~~~~~~~~~~~~~~~~ | ||
74 | |||
75 | .. autoclass:: CallbackStreamListener \ No newline at end of file | ||