Merge branch 'pep-xeps-fix-returns' into 'master'

Fix return values and improve typing in "user *" PEP XEPs

See merge request poezio/slixmpp!115

11 files changed, 120 insertions, 160 deletions

diff --git a/slixmpp/plugins/xep_0107/stanza.py b/slixmpp/plugins/xep_0107/stanza.py
index 8384793a..406474c9 100644
--- a/slixmpp/plugins/xep_0107/stanza.py
+++ b/slixmpp/plugins/xep_0107/stanza.py
@@ -1,10 +1,7 @@
-"""
-    Slixmpp: The Slick XMPP Library
-    Copyright (C) 2012 Nathanael C. Fritz, Lance J.T. Stout
-    This file is part of Slixmpp.
-
-    See the file LICENSE for copying permission.
-"""
+# Slixmpp: The Slick XMPP Library
+# Copyright (C) 2012 Nathanael C. Fritz, Lance J.T. Stout
+# This file is part of Slixmpp.
+# See the file LICENSE for copying permission.
 
 from slixmpp.xmlstream import ElementBase, ET
 
diff --git a/slixmpp/plugins/xep_0107/user_mood.py b/slixmpp/plugins/xep_0107/user_mood.py
index 83155f92..26a6a062 100644
--- a/slixmpp/plugins/xep_0107/user_mood.py
+++ b/slixmpp/plugins/xep_0107/user_mood.py
@@ -1,13 +1,15 @@
-"""
-    Slixmpp: The Slick XMPP Library
-    Copyright (C) 2011 Nathanael C. Fritz, Lance J.T. Stout
-    This file is part of Slixmpp.
-
-    See the file LICENSE for copying permission.
-"""
+# Slixmpp: The Slick XMPP Library
+# Copyright (C) 2011 Nathanael C. Fritz, Lance J.T. Stout
+# This file is part of Slixmpp.
+# See the file LICENSE for copying permission.
 
 import logging
 
+from asyncio import Future
+from typing import (
+    Optional,
+)
+
 from slixmpp import Message
 from slixmpp.xmlstream import register_stanza_plugin
 from slixmpp.xmlstream.handler import Callback
@@ -20,7 +22,6 @@ log = logging.getLogger(__name__)
 
 
 class XEP_0107(BasePlugin):
-
     """
     XEP-0107: User Mood
     """
@@ -40,31 +41,30 @@ class XEP_0107(BasePlugin):
     def session_bind(self, jid):
         self.xmpp['xep_0163'].register_pep('user_mood', UserMood)
 
-    def publish_mood(self, value=None, text=None, options=None, ifrom=None,
-                     callback=None, timeout=None, timeout_callback=None):
+    def publish_mood(self, value: Optional[str] = None, text: Optional[str] = None, **pubsubkwargs) -> Future:
         """
         Publish the user's current mood.
 
         :param value: The name of the mood to publish.
         :param text: Optional natural-language description or reason
                      for the mood.
-        :param options: Optional form of publish options.
         """
         mood = UserMood()
         mood['value'] = value
         mood['text'] = text
-        self.xmpp['xep_0163'].publish(mood, node=UserMood.namespace,
-                                      options=options, ifrom=ifrom,
-                                      callback=callback, timeout=timeout,
-                                      timeout_callback=timeout_callback)
+        return self.xmpp['xep_0163'].publish(
+            mood,
+            node=UserMood.namespace,
+            **pubsubkwargs
+        )
 
-    def stop(self, ifrom=None, callback=None, timeout=None,
-             timeout_callback=None):
+    def stop(self, **pubsubkwargs) -> Future:
         """
         Clear existing user mood information to stop notifications.
         """
         mood = UserMood()
-        self.xmpp['xep_0163'].publish(mood, node=UserMood.namespace,
-                                      ifrom=ifrom, callback=callback,
-                                      timeout=timeout,
-                                      timeout_callback=timeout_callback)
+        return self.xmpp['xep_0163'].publish(
+            mood,
+            node=UserMood.namespace,
+            **pubsubkwargs
+        )
diff --git a/slixmpp/plugins/xep_0108/stanza.py b/slixmpp/plugins/xep_0108/stanza.py
index c9a3c362..4664f3c1 100644
--- a/slixmpp/plugins/xep_0108/stanza.py
+++ b/slixmpp/plugins/xep_0108/stanza.py
@@ -1,10 +1,7 @@
-"""
-    Slixmpp: The Slick XMPP Library
-    Copyright (C) 2012 Nathanael C. Fritz, Lance J.T. Stout
-    This file is part of Slixmpp.
-
-    See the file LICENSE for copying permission.
-"""
+# Slixmpp: The Slick XMPP Library
+# Copyright (C) 2012 Nathanael C. Fritz, Lance J.T. Stout
+# This file is part of Slixmpp.
+# See the file LICENSE for copying permission.
 
 from slixmpp.xmlstream import ElementBase, ET
 
diff --git a/slixmpp/plugins/xep_0108/user_activity.py b/slixmpp/plugins/xep_0108/user_activity.py
index 089269bd..4004ab8e 100644
--- a/slixmpp/plugins/xep_0108/user_activity.py
+++ b/slixmpp/plugins/xep_0108/user_activity.py
@@ -1,13 +1,12 @@
-"""
-    Slixmpp: The Slick XMPP Library
-    Copyright (C) 2011 Nathanael C. Fritz, Lance J.T. Stout
-    This file is part of Slixmpp.
-
-    See the file LICENSE for copying permission.
-"""
+# Slixmpp: The Slick XMPP Library
+# Copyright (C) 2011 Nathanael C. Fritz, Lance J.T. Stout
+# This file is part of Slixmpp.
+# See the file LICENSE for copying permission.
 
 import logging
 
+from asyncio import Future
+from typing import Optional
 from slixmpp.plugins.base import BasePlugin
 from slixmpp.plugins.xep_0108 import stanza, UserActivity
 
@@ -33,9 +32,8 @@ class XEP_0108(BasePlugin):
     def session_bind(self, jid):
         self.xmpp['xep_0163'].register_pep('user_activity', UserActivity)
 
-    def publish_activity(self, general, specific=None, text=None,
-                         options=None, ifrom=None, callback=None,
-                         timeout=None, timeout_callback=None):
+    def publish_activity(self, general: str, specific: Optional[str] = None,
+                         text: Optional[str] = None, **pubsubkwargs) -> Future:
         """
         Publish the user's current activity.
 
@@ -44,24 +42,23 @@ class XEP_0108(BasePlugin):
                          of the general category.
         :param text: Optional natural-language description or reason
                      for the activity.
-        :param options: Optional form of publish options.
         """
         activity = UserActivity()
         activity['value'] = (general, specific)
         activity['text'] = text
-        self.xmpp['xep_0163'].publish(activity, node=UserActivity.namespace,
-                                      options=options, ifrom=ifrom,
-                                      callback=callback,
-                                      timeout=timeout,
-                                      timeout_callback=timeout_callback)
+        return self.xmpp['xep_0163'].publish(
+            activity,
+            node=UserActivity.namespace,
+            **pubsubkwargs
+        )
 
-    def stop(self, ifrom=None, callback=None, timeout=None,
-             timeout_callback=None):
+    def stop(self, **pubsubkwargs) -> Future:
         """
         Clear existing user activity information to stop notifications.
         """
         activity = UserActivity()
-        self.xmpp['xep_0163'].publish(activity, node=UserActivity.namespace,
-                                      ifrom=ifrom, callback=callback,
-                                      timeout=timeout,
-                                      timeout_callback=timeout_callback)
+        return self.xmpp['xep_0163'].publish(
+            activity,
+            node=UserActivity.namespace,
+            **pubsubkwargs
+        )
diff --git a/slixmpp/plugins/xep_0118/stanza.py b/slixmpp/plugins/xep_0118/stanza.py
index 579fcbf0..ad66ddbb 100644
--- a/slixmpp/plugins/xep_0118/stanza.py
+++ b/slixmpp/plugins/xep_0118/stanza.py
@@ -1,10 +1,7 @@
-"""
-    Slixmpp: The Slick XMPP Library
-    Copyright (C) 2012 Nathanael C. Fritz, Lance J.T. Stout
-    This file is part of Slixmpp.
-
-    See the file LICENSE for copying permission.
-"""
+# Slixmpp: The Slick XMPP Library
+# Copyright (C) 2012 Nathanael C. Fritz, Lance J.T. Stout
+# This file is part of Slixmpp.
+# See the file LICENSE for copying permission.
 
 from slixmpp.xmlstream import ElementBase, ET
 
diff --git a/slixmpp/plugins/xep_0118/user_tune.py b/slixmpp/plugins/xep_0118/user_tune.py
index 4145dce6..112febbc 100644
--- a/slixmpp/plugins/xep_0118/user_tune.py
+++ b/slixmpp/plugins/xep_0118/user_tune.py
@@ -1,13 +1,12 @@
-"""
-    Slixmpp: The Slick XMPP Library
-    Copyright (C) 2011 Nathanael C. Fritz, Lance J.T. Stout
-    This file is part of Slixmpp.
-
-    See the file LICENSE for copying permission.
-"""
+# Slixmpp: The Slick XMPP Library
+# Copyright (C) 2011 Nathanael C. Fritz, Lance J.T. Stout
+# This file is part of Slixmpp.
+# See the file LICENSE for copying permission.
 
 import logging
 
+from asyncio import Future
+from typing import Optional
 from slixmpp.plugins.base import BasePlugin
 from slixmpp.plugins.xep_0118 import stanza, UserTune
 
@@ -33,9 +32,11 @@ class XEP_0118(BasePlugin):
     def session_bind(self, jid):
         self.xmpp['xep_0163'].register_pep('user_tune', UserTune)
 
-    def publish_tune(self, artist=None, length=None, rating=None, source=None,
-                     title=None, track=None, uri=None, options=None,
-                     ifrom=None, callback=None, timeout=None, timeout_callback=None):
+    def publish_tune(self, *, artist: Optional[str] = None,
+                     length: Optional[int] =None, rating: Optional[int] = None,
+                     source: Optional[str] = None, title: Optional[str] = None,
+                     track: Optional[str] = None, uri: Optional[str] = None,
+                     **pubsubkwargs) -> Future:
         """
         Publish the user's current tune.
 
@@ -46,7 +47,6 @@ class XEP_0118(BasePlugin):
         :param title: The title of the song.
         :param track: The song's track number, or other unique identifier.
         :param uri: A URL to more information about the song.
-        :param options: Optional form of publish options.
         """
         tune = UserTune()
         tune['artist'] = artist
@@ -56,22 +56,19 @@ class XEP_0118(BasePlugin):
         tune['title'] = title
         tune['track'] = track
         tune['uri'] = uri
-        return self.xmpp['xep_0163'].publish(tune,
-                node=UserTune.namespace,
-                options=options,
-                ifrom=ifrom,
-                callback=callback,
-                timeout=timeout,
-                timeout_callback=timeout_callback)
+        return self.xmpp['xep_0163'].publish(
+            tune,
+            node=UserTune.namespace,
+            **pubsubkwargs
+        )
 
-    def stop(self, ifrom=None, callback=None, timeout=None, timeout_callback=None):
+    def stop(self, **pubsubkwargs) -> Future:
         """
         Clear existing user tune information to stop notifications.
         """
         tune = UserTune()
-        return self.xmpp['xep_0163'].publish(tune,
-                node=UserTune.namespace,
-                ifrom=ifrom,
-                callback=callback,
-                timeout=timeout,
-                timeout_callback=timeout_callback)
+        return self.xmpp['xep_0163'].publish(
+            tune,
+            node=UserTune.namespace,
+            **pubsubkwargs
+        )
diff --git a/slixmpp/plugins/xep_0172/stanza.py b/slixmpp/plugins/xep_0172/stanza.py
index addba94a..dbc136d9 100644
--- a/slixmpp/plugins/xep_0172/stanza.py
+++ b/slixmpp/plugins/xep_0172/stanza.py
@@ -1,10 +1,7 @@
-"""
-    Slixmpp: The Slick XMPP Library
-    Copyright (C) 2012 Nathanael C. Fritz, Lance J.T. Stout
-    This file is part of Slixmpp.
-
-    See the file LICENSE for copying permission.
-"""
+# Slixmpp: The Slick XMPP Library
+# Copyright (C) 2012 Nathanael C. Fritz, Lance J.T. Stout
+# This file is part of Slixmpp.
+# See the file LICENSE for copying permission.
 
 from slixmpp.xmlstream import ElementBase, ET
 
diff --git a/slixmpp/plugins/xep_0172/user_nick.py b/slixmpp/plugins/xep_0172/user_nick.py
index ef96c51a..4f94c724 100644
--- a/slixmpp/plugins/xep_0172/user_nick.py
+++ b/slixmpp/plugins/xep_0172/user_nick.py
@@ -1,13 +1,11 @@
-"""
-    Slixmpp: The Slick XMPP Library
-    Copyright (C) 2011 Nathanael C. Fritz, Lance J.T. Stout
-    This file is part of Slixmpp.
-
-    See the file LICENSE for copying permission.
-"""
+# Slixmpp: The Slick XMPP Library
+# Copyright (C) 2011 Nathanael C. Fritz, Lance J.T. Stout
+# This file is part of Slixmpp.
+# See the file LICENSE for copying permission.
 
 import logging
 
+from asyncio import Future
 from typing import Optional, Callable
 from slixmpp import JID
 from slixmpp.stanza.message import Message
@@ -45,34 +43,27 @@ class XEP_0172(BasePlugin):
     def session_bind(self, jid):
         self.xmpp['xep_0163'].register_pep('user_nick', UserNick)
 
-    def publish_nick(self, nick: Optional[str] = None,
-                     options: Optional[Form] = None,
-                     ifrom: Optional[JID] = None,
-                     timeout_callback: Optional[Callable] = None,
-                     callback: Optional[Callable] = None,
-                     timeout: Optional[int] = None):
+    def publish_nick(self, nick: Optional[str] = None, **pubsubkwargs) -> Future:
         """
         Publish the user's current nick.
 
         :param nick: The user nickname to publish.
-        :param options: Optional form of publish options.
         """
         nickname = UserNick()
         nickname['nick'] = nick
-        self.xmpp['xep_0163'].publish(nickname, node=UserNick.namespace,
-                                      options=options, ifrom=ifrom,
-                                      callback=callback, timeout=timeout,
-                                      timeout_callback=timeout_callback)
+        return self.xmpp['xep_0163'].publish(
+            nickname,
+            node=UserNick.namespace,
+            **pubsubkwargs
+        )
 
-    def stop(self, ifrom: Optional[JID] = None,
-             timeout_callback: Optional[Callable] = None,
-              callback: Optional[Callable] = None,
-              timeout: Optional[int] = None):
+    def stop(self, **pubsubkwargs) -> Future:
         """
         Clear existing user nick information to stop notifications.
         """
         nick = UserNick()
-        return self.xmpp['xep_0163'].publish(nick, node=UserNick.namespace,
-                                             ifrom=ifrom, callback=callback,
-                                             timeout=timeout,
-                                             timeout_callback=timeout_callback)
+        return self.xmpp['xep_0163'].publish(
+            nick,
+            node=UserNick.namespace,
+            **pubsubkwargs
+        )
diff --git a/slixmpp/plugins/xep_0196/__init__.py b/slixmpp/plugins/xep_0196/__init__.py
index 89f0f89e..3a01dcb2 100644
--- a/slixmpp/plugins/xep_0196/__init__.py
+++ b/slixmpp/plugins/xep_0196/__init__.py
@@ -1,10 +1,7 @@
-"""
-    Slixmpp: The Slick XMPP Library
-    Copyright (C) 2012 Nathanael C. Fritz, Lance J.T. Stout
-    This file is part of Slixmpp.
-
-    See the file LICENSE for copying permission.
-"""
+# Slixmpp: The Slick XMPP Library
+# Copyright (C) 2012 Nathanael C. Fritz, Lance J.T. Stout
+# This file is part of Slixmpp.
+# See the file LICENSE for copying permission.
 
 from slixmpp.plugins.base import register_plugin
 
diff --git a/slixmpp/plugins/xep_0196/stanza.py b/slixmpp/plugins/xep_0196/stanza.py
index 756208b2..d676a9ad 100644
--- a/slixmpp/plugins/xep_0196/stanza.py
+++ b/slixmpp/plugins/xep_0196/stanza.py
@@ -1,10 +1,7 @@
-"""
-    Slixmpp: The Slick XMPP Library
-    Copyright (C) 2012 Nathanael C. Fritz, Lance J.T. Stout
-    This file is part of Slixmpp.
-
-    See the file LICENSE for copying permission.
-"""
+# Slixmpp: The Slick XMPP Library
+# Copyright (C) 2012 Nathanael C. Fritz, Lance J.T. Stout
+# This file is part of Slixmpp.
+# See the file LICENSE for copying permission.
 
 from slixmpp.xmlstream import ElementBase, ET
 
diff --git a/slixmpp/plugins/xep_0196/user_gaming.py b/slixmpp/plugins/xep_0196/user_gaming.py
index 623410a1..40c74e84 100644
--- a/slixmpp/plugins/xep_0196/user_gaming.py
+++ b/slixmpp/plugins/xep_0196/user_gaming.py
@@ -1,13 +1,11 @@
-"""
-    Slixmpp: The Slick XMPP Library
-    Copyright (C) 2011 Nathanael C. Fritz, Lance J.T. Stout
-    This file is part of Slixmpp.
-
-    See the file LICENSE for copying permission.
-"""
+# Slixmpp: The Slick XMPP Library
+# Copyright (C) 2011 Nathanael C. Fritz, Lance J.T. Stout
+# This file is part of Slixmpp.
+# See the file LICENSE for copying permission.
 
 import logging
 
+from asyncio import Future
 from slixmpp import JID
 from typing import Optional, Callable
 from slixmpp.plugins.base import BasePlugin
@@ -43,11 +41,7 @@ class XEP_0196(BasePlugin):
                        character_name: Optional[str] = None,
                        character_profile: Optional[str] = None,
                        server_address: Optional[str] = None,
-                       options: Optional[Form] = None,
-                       ifrom: Optional[JID] = None,
-                       callback: Optional[Callable] = None,
-                       timeout: Optional[int] = None,
-                       timeout_callback: Optional[Callable]=None):
+                       **pubsubkwargs) -> Future:
         """
         Publish the user's current gaming status.
 
@@ -69,20 +63,19 @@ class XEP_0196(BasePlugin):
         gaming['character_profile'] = character_profile
         gaming['server_name'] = server_name
         gaming['server_address'] = server_address
-        return self.xmpp['xep_0163'].publish(gaming,
-                                             node=UserGaming.namespace,
-                                             options=options, ifrom=ifrom,
-                                             callback=callback, timeout=timeout,
-                                             timeout_callback=timeout_callback)
+        return self.xmpp['xep_0163'].publish(
+            gaming,
+            node=UserGaming.namespace,
+            **pubsubkwargs
+        )
 
-    def stop(self, ifrom=None, callback=None, timeout=None,
-                   timeout_callback=None):
+    def stop(self, **pubsubkwargs) -> Future:
         """
         Clear existing user gaming information to stop notifications.
         """
         gaming = UserGaming()
-        return self.xmpp['xep_0163'].publish(gaming,
-                                             node=UserGaming.namespace,
-                                             ifrom=ifrom, callback=callback,
-                                             timeout=timeout,
-                                             timeout_callback=timeout_callback)
+        return self.xmpp['xep_0163'].publish(
+            gaming,
+            node=UserGaming.namespace,
+            **pubsubkwargs
+        )