XEP-0054: API changes

- ``get_vcard``, ``publish_vcard`` are now coroutines.

docs/api/plugins/xep_0054.rst

@@ -8,6 +8,38 @@ XEP-0054: vcard-temp
     :members:
     :exclude-members: session_bind, plugin_init, plugin_end
 
+Internal API methods
+--------------------
+
+This plugin maintains by default an in-memory cache of the received
+VCards.
+
+.. glossary::
+
+    set_vcard
+        - **jid**: :class:`~.JID` of whom to set the vcard
+        - **node**: unused
+        - **ifrom**: unused
+        - **args**: :class:`~.VCardTemp` object to store for this JID.
+
+        Set a VCard for a JID.
+
+    get_vcard
+        - **jid**: :class:`~.JID` of whom to set the vcard
+        - **node**: unused
+        - **ifrom**: :class:`~.JID` the request is coming from
+        - **args**: unused
+        - **returns**: :class:`~.VCardTemp` object for this JID or None.
+
+        Get a stored VCard for a JID.
+
+    del_vcard
+        - **jid**: :class:`~.JID` of whom to set the vcard
+        - **node**: unused
+        - **ifrom**: unused
+        - **args**: unused
+
+        Delete a stored VCard for a JID.
 
 Stanza elements
 ---------------

slixmpp/plugins/xep_0054/vcard_temp.py

@@ -11,7 +11,7 @@ from slixmpp import JID
 from slixmpp.stanza import Iq
 from slixmpp.exceptions import XMPPError
 from slixmpp.xmlstream import register_stanza_plugin
-from slixmpp.xmlstream.handler import Callback
+from slixmpp.xmlstream.handler import CoroutineCallback
 from slixmpp.xmlstream.matcher import StanzaPath
 from slixmpp.plugins import BasePlugin
 from slixmpp.plugins.xep_0054 import VCardTemp, stanza
@@ -46,7 +46,7 @@ class XEP_0054(BasePlugin):
         self._vcard_cache = {}
 
         self.xmpp.register_handler(
-                Callback('VCardTemp',
+                CoroutineCallback('VCardTemp',
                     StanzaPath('iq/vcard_temp'),
                     self._handle_get_vcard))
 
@@ -61,13 +61,15 @@ class XEP_0054(BasePlugin):
         """Return an empty vcard element."""
         return VCardTemp()
 
-    @future_wrapper
+    async def get_vcard(self, jid: Optional[JID] = None, *,
-    def get_vcard(self, jid: Optional[JID] = None, *,
                         local: Optional[bool] = None, cached: bool = False,
                         ifrom: Optional[JID] = None,
-                  **iqkwargs) -> Future:
+                        **iqkwargs) -> Iq:
         """Retrieve a VCard.
 
+        .. versionchanged:: 1.8.0
+            This function is now a coroutine.
+
         :param jid: JID of the entity to fetch the VCard from.
         :param local: Only check internally for a vcard.
         :param cached: Whether to check in the local cache before
@@ -87,7 +89,7 @@ class XEP_0054(BasePlugin):
                 local = True
 
         if local:
-            vcard = self.api['get_vcard'](jid, None, ifrom)
+            vcard = await self.api['get_vcard'](jid, None, ifrom)
             if not isinstance(vcard, Iq):
                 iq = self.xmpp.Iq()
                 if vcard is None:
@@ -97,7 +99,7 @@ class XEP_0054(BasePlugin):
             return vcard
 
         if cached:
-            vcard = self.api['get_vcard'](jid, None, ifrom)
+            vcard = await self.api['get_vcard'](jid, None, ifrom)
             if vcard is not None:
                 if not isinstance(vcard, Iq):
                     iq = self.xmpp.Iq()
@@ -107,31 +109,33 @@ class XEP_0054(BasePlugin):
 
         iq = self.xmpp.make_iq_get(ito=jid, ifrom=ifrom)
         iq.enable('vcard_temp')
-        return iq.send(**iqkwargs)
+        return await iq.send(**iqkwargs)
 
-    @future_wrapper
+    async def publish_vcard(self, vcard: Optional[VCardTemp] = None,
-    def publish_vcard(self, vcard: Optional[VCardTemp] = None,
                             jid: Optional[JID] = None,
-                      ifrom: Optional[JID] = None, **iqkwargs) -> Future:
+                            ifrom: Optional[JID] = None, **iqkwargs):
         """Publish a vcard.
 
+        .. versionchanged:: 1.8.0
+            This function is now a coroutine.
+
         :param vcard: The VCard to publish.
         :param jid: The JID to publish the VCard to.
         """
-        self.api['set_vcard'](jid, None, ifrom, vcard)
+        await self.api['set_vcard'](jid, None, ifrom, vcard)
         if self.xmpp.is_component:
             return
 
         iq = self.xmpp.make_iq_set(ito=jid, ifrom=ifrom)
         iq.append(vcard)
-        return iq.send(**iqkwargs)
+        await iq.send(**iqkwargs)
 
-    def _handle_get_vcard(self, iq: Iq):
+    async def _handle_get_vcard(self, iq: Iq):
         if iq['type'] == 'result':
-            self.api['set_vcard'](jid=iq['from'], args=iq['vcard_temp'])
+            await self.api['set_vcard'](jid=iq['from'], args=iq['vcard_temp'])
             return
         elif iq['type'] == 'get' and self.xmpp.is_component:
-            vcard = self.api['get_vcard'](iq['to'].bare, ifrom=iq['from'])
+            vcard = await self.api['get_vcard'](iq['to'].bare, ifrom=iq['from'])
             if isinstance(vcard, Iq):
                 vcard.send()
             else: