diff options
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 | ||