From 9e97fce2d6f350c45603f200d5cda0962b63cb86 Mon Sep 17 00:00:00 2001 From: Lorenz Diener Date: Fri, 24 Nov 2017 15:25:38 +0100 Subject: Break streaming entirely, update docs --- docs/index.rst | 38 ++++++++++++++++++++++++++++---------- mastodon/Mastodon.py | 8 ++++---- 2 files changed, 32 insertions(+), 14 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 63a8594..a8181b1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -112,23 +112,23 @@ Error handling When Mastodon.py encounters an error, it will raise an exception, generally with some text included to tell you what went wrong. -The base class that all mastodon exceptions inherit from is the MastodonError -class. If you are only interested in the fact an error was raised somewhere in +The base class that all mastodon exceptions inherit from is `MastodonError`. +If you are only interested in the fact an error was raised somewhere in Mastodon.py, and not the details, this is the exception you can catch. -MastodonIllegalArgumentError is generally a programming problem - you asked the +`MastodonIllegalArgumentError` is generally a programming problem - you asked the API to do something obviously invalid (i.e. specify a privacy scope that does not exist). -MastodonFileNotFoundError and MastodonNetworkError are IO errors - could be you +`MastodonFileNotFoundError` and `MastodonNetworkError` are IO errors - could be you specified a wrong URL, could be the internet is down or your hard drive is dying. They inherit from MastodonIOError, for easy catching. -MastodonAPIError is an error returned from the Mastodon instance - the server +`MastodonAPIError` is an error returned from the Mastodon instance - the server has decided it can't fullfill your request (i.e. you requested info on a user that does not exist). -MastodonRatelimitError is raised when you hit an API rate limit. You should try +`MastodonRatelimitError` is raised when you hit an API rate limit. You should try again after a while (see the rate limiting section above). Return values @@ -538,10 +538,28 @@ If async is True, the listener will listen on another thread and these methods will return a handle corresponding to the open connection. The connection may be closed at any time by calling its close() method. -.. automethod:: Mastodon.user_stream -.. automethod:: Mastodon.public_stream -.. automethod:: Mastodon.local_stream -.. automethod:: Mastodon.hashtag_stream +The streaming functions take instances of `StreamListener` as a parameter. +A `CallbackStreamListener` class that allows you to specify function callbacks +directly is included for convenience. + +.. automethod:: Mastodon.stream_user +.. automethod:: Mastodon.stream_public +.. automethod:: Mastodon.stream_local +.. automethod:: Mastodon.stream_hashtag + +StreamListener +~~~~~~~~~~~~~~ + +.. autoclass:: StreamListener +.. automethod:: StreamListener.on_update +.. automethod:: StreamListener.on_notification +.. automethod:: StreamListener.on_delete +.. automethod:: StreamListener.handle_heartbeat + +CallbackStreamListener +~~~~~~~~~~~~~~~~~~~~~~ + +.. autoclass:: CallbackStreamListener .. _Mastodon: https://github.com/tootsuite/mastodon .. _Mastodon flagship instance: http://mastodon.social/ diff --git a/mastodon/Mastodon.py b/mastodon/Mastodon.py index 9b28861..011d731 100644 --- a/mastodon/Mastodon.py +++ b/mastodon/Mastodon.py @@ -1010,7 +1010,7 @@ class Mastodon: ### # Streaming ### - def user_stream(self, listener, async=False): + def stream_user(self, listener, async=False): """ Streams events that are relevant to the authorized user, i.e. home timeline and notifications. 'listener' should be a subclass of @@ -1018,14 +1018,14 @@ class Mastodon: """ return self.__stream('/api/v1/streaming/user', listener, async=async) - def public_stream(self, listener, async=False): + def stream_public(self, listener, async=False): """ Streams public events. 'listener' should be a subclass of StreamListener which will receive callbacks for incoming events. """ return self.__stream('/api/v1/streaming/public', listener, async=async) - def local_stream(self, listener, async=False): + def stream_local(self, listener, async=False): """ Streams local events. 'listener' should be a subclass of StreamListener which will receive callbacks for incoming events. @@ -1033,7 +1033,7 @@ class Mastodon: """ return self.__stream('/api/v1/streaming/public/local', listener, async=async) - def hashtag_stream(self, tag, listener, async=False): + def stream_hashtag(self, tag, listener, async=False): """ Returns all public statuses for the hashtag 'tag'. 'listener' should be a subclass of StreamListener which will receive callbacks for incoming -- cgit v1.2.3