aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--CHANGELOG.rst6
-rw-r--r--docs/conf.py4
-rw-r--r--docs/index.rst17
-rw-r--r--mastodon/streaming.py18
-rw-r--r--setup.py2
5 files changed, 23 insertions, 24 deletions
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index c027b91..87de0a2 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -2,8 +2,9 @@ A note on versioning: This librarys major version will grow with the APIs
2version number. Breaking changes will be indicated by a change in the minor 2version number. Breaking changes will be indicated by a change in the minor
3(or major) version number, and will generally be avoided. 3(or major) version number, and will generally be avoided.
4 4
5v1.5.3 (in progress) 5v1.6.0
6-------------------- 6------
7* 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.
7* 3.1.3 support 8* 3.1.3 support
8 * Added v2 media_post api 9 * Added v2 media_post api
9* 3.1.4 support 10* 3.1.4 support
@@ -25,6 +26,7 @@ v1.5.3 (in progress)
25 * Changed URLs from "tootsuite" to "mastodon" in several places (thanks andypiper) 26 * Changed URLs from "tootsuite" to "mastodon" in several places (thanks andypiper)
26 * Fixed some fields not converting to datetimes (thanks SouthFox-D) 27 * Fixed some fields not converting to datetimes (thanks SouthFox-D)
27 * Improved oauth web flow support 28 * Improved oauth web flow support
29 * Improved documentation consistency (thanks andypiper)
28 30
29v1.5.2 31v1.5.2
30------ 32------
diff --git a/docs/conf.py b/docs/conf.py
index ac8858f..306563e 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -66,9 +66,9 @@ author = u'Lorenz Diener'
66# built documents. 66# built documents.
67# 67#
68# The short X.Y version. 68# The short X.Y version.
69version = u'1.5' 69version = u'1.6'
70# The full version, including alpha/beta/rc tags. 70# The full version, including alpha/beta/rc tags.
71release = u'1.5.2' 71release = u'1.6.0'
72 72
73# The language for content autogenerated by Sphinx. Refer to documentation 73# The language for content autogenerated by Sphinx. Refer to documentation
74# for a list of supported languages. 74# for a list of supported languages.
diff --git a/docs/index.rst b/docs/index.rst
index 025896d..7fc59d2 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1307,13 +1307,16 @@ For new well-known events implement the streaming function in `StreamListener` o
1307The function name is `on_` + the event name. If the event name contains dots, they are replaced with 1307The function name is `on_` + the event name. If the event name contains dots, they are replaced with
1308underscored, e.g. for an event called 'status.update' the listener function should be named `on_status_update`. 1308underscored, e.g. for an event called 'status.update' the listener function should be named `on_status_update`.
1309 1309
1310It may be that future Mastodon versions will come with completely new (unknown) event names. In this 1310It may be that future Mastodon versions will come with completely new (unknown) event names.
1311case a (deprecated) Mastodon.py would throw an error. If you want to avoid this in general, you can 1311If you want to do something when such an event is received, override the listener function `on_unknown_event`.
1312override the listener function `on_unknown_event`. This has an additional parameter `name` which informs 1312This has an additional parameter `name` which informs about the name of the event. `unknown_event` contains the
1313about the name of the event. `unknown_event` contains the content of the event. 1313content of the event. Alternatively, a callback function can be passed in the `unknown_event_handler` parameter
1314 1314in the `CallbackStreamListener` constructor.
1315Alternatively, a callback function can be passed in the `unknown_event_handler` parameter in the 1315
1316`CallbackStreamListener` constructor. 1316Note that the `unknown_event` handler is *not* guaranteed to receive events once they have been implemented.
1317Events will only go to this handler temporarily, while Mastodon.py has not been updated. Changes to what events
1318do and do not go into the handler will not be considered a breaking change. If you want to handle a new event whose
1319name you _do_ know, define an appropriate handler in your StreamListener, which will work even if it is not listed here.
1317 1320
1318When in not-async mode or async mode without async_reconnect, the stream functions may raise 1321When in not-async mode or async mode without async_reconnect, the stream functions may raise
1319various exceptions: `MastodonMalformedEventError` if a received event cannot be parsed and 1322various exceptions: `MastodonMalformedEventError` if a received event cannot be parsed and
diff --git a/mastodon/streaming.py b/mastodon/streaming.py
index 2080908..e43d7d6 100644
--- a/mastodon/streaming.py
+++ b/mastodon/streaming.py
@@ -59,13 +59,9 @@ class StreamListener(object):
59 def on_unknown_event(self, name, unknown_event=None): 59 def on_unknown_event(self, name, unknown_event=None):
60 """An unknown mastodon API event has been received. The name contains the event-name and unknown_event 60 """An unknown mastodon API event has been received. The name contains the event-name and unknown_event
61 contains the content of the unknown event. 61 contains the content of the unknown event.
62
63 This function must be implemented, if unknown events should be handled without an error.
64 """ 62 """
65 exception = MastodonMalformedEventError('Bad event type', name) 63 pass
66 self.on_abort(exception) 64
67 raise exception
68
69 def handle_heartbeat(self): 65 def handle_heartbeat(self):
70 """The server has sent us a keep-alive message. This callback may be 66 """The server has sent us a keep-alive message. This callback may be
71 useful to carry out periodic housekeeping tasks, or just to confirm 67 useful to carry out periodic housekeeping tasks, or just to confirm
@@ -171,6 +167,7 @@ class StreamListener(object):
171 exception, 167 exception,
172 err 168 err
173 ) 169 )
170
174 # New mastodon API also supports event names with dots, 171 # New mastodon API also supports event names with dots,
175 # specifically, status_update. 172 # specifically, status_update.
176 handler_name = 'on_' + name.replace('.', '_') 173 handler_name = 'on_' + name.replace('.', '_')
@@ -200,8 +197,9 @@ class CallbackStreamListener(StreamListener):
200 """ 197 """
201 Simple callback stream handler class. 198 Simple callback stream handler class.
202 Can optionally additionally send local update events to a separate handler. 199 Can optionally additionally send local update events to a separate handler.
203 Define an unknown_event_handler for new Mastodon API events. If not, the 200 Define an unknown_event_handler for new Mastodon API events. This handler is
204 listener will raise an error on new, not handled, events from the API. 201 *not* guaranteed to receive these events forever, and should only be used
202 for diagnostics.
205 """ 203 """
206 204
207 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): 205 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):
242 def on_unknown_event(self, name, unknown_event=None): 240 def on_unknown_event(self, name, unknown_event=None):
243 if self.unknown_event_handler != None: 241 if self.unknown_event_handler != None:
244 self.unknown_event_handler(name, unknown_event) 242 self.unknown_event_handler(name, unknown_event)
245 else:
246 exception = MastodonMalformedEventError('Bad event type', name)
247 self.on_abort(exception)
248 raise exception
249 243
250 def on_status_update(self, status): 244 def on_status_update(self, status):
251 if self.status_update_handler != None: 245 if self.status_update_handler != None:
diff --git a/setup.py b/setup.py
index 93e5ce3..498246b 100644
--- a/setup.py
+++ b/setup.py
@@ -26,7 +26,7 @@ extras = {
26} 26}
27 27
28setup(name='Mastodon.py', 28setup(name='Mastodon.py',
29 version='1.5.2', 29 version='1.6.0',
30 description='Python wrapper for the Mastodon API', 30 description='Python wrapper for the Mastodon API',
31 packages=['mastodon'], 31 packages=['mastodon'],
32 install_requires=[ 32 install_requires=[
Powered by cgit v1.2.3 (git 2.41.0)