Prep 1.6.0

CHANGELOG.rst

@@ -2,8 +2,9 @@ A note on versioning: This librarys major version will grow with the APIs
 version number. Breaking changes will be indicated by a change in the minor
 (or major) version number, and will generally be avoided.  
 
-v1.5.3 (in progress)
---------------------
+v1.6.0
+------
+* BREAKING CHANGE: Change behaviour of streaming api handlers to no longer raise an exception when an unknown event is received and change the contract of the unknown event handler to explicitly state that it will not receive events once Mastodon.py updates.
 * 3.1.3 support
     * Added v2 media_post api
 * 3.1.4 support
@@ -25,6 +26,7 @@ v1.5.3 (in progress)
     * Changed URLs from "tootsuite" to "mastodon" in several places (thanks andypiper)
     * Fixed some fields not converting to datetimes (thanks SouthFox-D)
     * Improved oauth web flow support
+    * Improved documentation consistency (thanks andypiper)
 
 v1.5.2
 ------

docs/conf.py

@@ -66,9 +66,9 @@ author = u'Lorenz Diener'
 # built documents.
 #
 # The short X.Y version.
-version = u'1.5'
+version = u'1.6'
 # The full version, including alpha/beta/rc tags.
-release = u'1.5.2'
+release = u'1.6.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/index.rst

@@ -1307,13 +1307,16 @@ For new well-known events implement the streaming function in `StreamListener` o
 The function name is `on_` + the event name. If the event name contains dots, they are replaced with
 underscored, e.g. for an event called 'status.update' the listener function should be named `on_status_update`.
 
-It may be that future Mastodon versions will come with completely new (unknown) event names. In this
-case a (deprecated) Mastodon.py would throw an error. If you want to avoid this in general, you can
-override the listener function `on_unknown_event`. This has an additional parameter `name` which informs
-about the name of the event. `unknown_event` contains the content of the event.
+It may be that future Mastodon versions will come with completely new (unknown) event names.
+If you want to do something when such an event is received, override the listener function `on_unknown_event`. 
+This has an additional parameter `name` which informs about the name of the event. `unknown_event` contains the 
+content of the event. Alternatively, a callback function can be passed in the `unknown_event_handler` parameter 
+in the `CallbackStreamListener` constructor.
 
-Alternatively, a callback function can be passed in the `unknown_event_handler` parameter in the
-`CallbackStreamListener` constructor.
+Note that the `unknown_event` handler is *not* guaranteed to receive events once they have been implemented.
+Events will only go to this handler temporarily, while Mastodon.py has not been updated. Changes to what events
+do and do not go into the handler will not be considered a breaking change. If you want to handle a new event whose
+name you _do_ know, define an appropriate handler in your StreamListener, which will work even if it is not listed here.
 
 When in not-async mode or async mode without async_reconnect, the stream functions may raise
 various exceptions: `MastodonMalformedEventError` if a received event cannot be parsed and

mastodon/streaming.py

@@ -59,13 +59,9 @@ class StreamListener(object):
     def on_unknown_event(self, name, unknown_event=None):
         """An unknown mastodon API event has been received. The name contains the event-name and unknown_event
         contains the content of the unknown event.
-
-        This function must be implemented, if unknown events should be handled without an error.
         """
-        exception = MastodonMalformedEventError('Bad event type', name)
-        self.on_abort(exception)
-        raise exception
-
+        pass
+    
     def handle_heartbeat(self):
         """The server has sent us a keep-alive message. This callback may be
         useful to carry out periodic housekeeping tasks, or just to confirm
@@ -171,6 +167,7 @@ class StreamListener(object):
                 exception,
                 err
             )
+
         # New mastodon API also supports event names with dots,
         # specifically, status_update.
         handler_name = 'on_' + name.replace('.', '_')
@@ -200,8 +197,9 @@ class CallbackStreamListener(StreamListener):
     """
     Simple callback stream handler class.
     Can optionally additionally send local update events to a separate handler.
-    Define an unknown_event_handler for new Mastodon API events. If not, the
-    listener will raise an error on new, not handled, events from the API.
+    Define an unknown_event_handler for new Mastodon API events. This handler is
+    *not* guaranteed to receive these events forever, and should only be used
+    for diagnostics.
     """
 
     def __init__(self, update_handler=None, local_update_handler=None, delete_handler=None, notification_handler=None, conversation_handler=None, unknown_event_handler=None, status_update_handler=None):
@@ -242,10 +240,6 @@ class CallbackStreamListener(StreamListener):
     def on_unknown_event(self, name, unknown_event=None):
         if self.unknown_event_handler != None:
             self.unknown_event_handler(name, unknown_event)
-        else:
-            exception = MastodonMalformedEventError('Bad event type', name)
-            self.on_abort(exception)
-            raise exception
 
     def on_status_update(self, status):
         if self.status_update_handler != None:

setup.py

@@ -26,7 +26,7 @@ extras = {
 }
 
 setup(name='Mastodon.py',
-      version='1.5.2',
+      version='1.6.0',
       description='Python wrapper for the Mastodon API',
       packages=['mastodon'],
       install_requires=[