XEP-0319: API changes

- ``idle`` and ``active`` are now coroutines.

docs/api/plugins/xep_0319.rst

@@ -8,6 +8,30 @@ XEP-0319: Last User Interaction in Presence
     :members:
     :exclude-members: session_bind, plugin_init, plugin_end
 
+Internal API methods
+--------------------
+
+The default API manages an in-memory cache of idle periods.
+
+.. glossary::
+
+    set_idle
+        - **jid**: :class:`~.JID` who has been idling
+        - **node**: unused
+        - **ifrom**: unused
+        - **args**: :class:`datetime`, timestamp of the idle start
+
+        Set the idle start for a JID.
+
+    get_idle
+        - **jid**: :class:`~.JID` to get the idle time of
+        - **node**: unused
+        - **ifrom**: unused
+        - **args**: : unused
+        - **returns**: :class:`datetime`
+
+        Get the idle start timestamp for a JID.
+
 
 Stanza elements
 ---------------

slixmpp/plugins/xep_0319/idle.py

@@ -3,8 +3,11 @@
 # Copyright (C) 2013 Nathanael C. Fritz, Lance J.T. Stout
 # This file is part of Slixmpp.
 # See the file LICENSE for copying permission.
-from datetime import datetime, timedelta, timezone
+from datetime import datetime, timezone
 
+from typing import Optional
+
+from slixmpp import JID
 from slixmpp.stanza import Presence
 from slixmpp.plugins import BasePlugin
 from slixmpp.xmlstream import register_stanza_plugin
@@ -26,16 +29,13 @@ class XEP_0319(BasePlugin):
     def plugin_init(self):
         self._idle_stamps = {}
         register_stanza_plugin(Presence, stanza.Idle)
-        self.api.register(self._set_idle,
+        self.api.register(self._set_idle, 'set_idle', default=True)
-                'set_idle',
+        self.api.register(self._get_idle, 'get_idle', default=True)
-                default=True)
+        self.xmpp.register_handler(Callback(
-        self.api.register(self._get_idle,
+            'Idle Presence',
-                'get_idle',
+            StanzaPath('presence/idle'),
-                default=True)
+            self._idle_presence
-        self.xmpp.register_handler(
+        ))
-                Callback('Idle Presence',
-                    StanzaPath('presence/idle'),
-                    self._idle_presence))
         self.xmpp.add_filter('out', self._stamp_idle_presence)
 
     def session_bind(self, jid):
@@ -46,19 +46,30 @@ class XEP_0319(BasePlugin):
         self.xmpp.del_filter('out', self._stamp_idle_presence)
         self.xmpp.remove_handler('Idle Presence')
 
-    def idle(self, jid=None, since=None):
+    async def idle(self, jid: Optional[JID] = None,
+                   since: Optional[datetime] = None):
+        """Set an idle duration for a JID
+
+        .. versionchanged:: 1.8.0
+            This function is now a coroutine.
+        """
         seconds = None
         timezone = get_local_timezone()
         if since is None:
             since = datetime.now(timezone)
         else:
             seconds = datetime.now(timezone) - since
-        self.api['set_idle'](jid, None, None, since)
+        await self.api['set_idle'](jid, None, None, since)
-        self.xmpp['xep_0012'].set_last_activity(jid=jid, seconds=seconds)
+        await self.xmpp['xep_0012'].set_last_activity(jid=jid, seconds=seconds)
 
-    def active(self, jid=None):
+    async def active(self, jid: Optional[JID] = None):
-        self.api['set_idle'](jid, None, None, None)
+        """Reset the idle timer.
-        self.xmpp['xep_0012'].del_last_activity(jid)
+
+        .. versionchanged:: 1.8.0
+            This function is now a coroutine.
+        """
+        await self.api['set_idle'](jid, None, None, None)
+        await self.xmpp['xep_0012'].del_last_activity(jid)
 
     def _set_idle(self, jid, node, ifrom, data):
         self._idle_stamps[jid] = data
@@ -69,9 +80,9 @@ class XEP_0319(BasePlugin):
     def _idle_presence(self, pres):
         self.xmpp.event('presence_idle', pres)
 
-    def _stamp_idle_presence(self, stanza):
+    async def _stamp_idle_presence(self, stanza):
         if isinstance(stanza, Presence):
-            since = self.api['get_idle'](stanza['from'] or self.xmpp.boundjid)
+            since = await self.api['get_idle'](stanza['from'] or self.xmpp.boundjid)
             if since:
                 stanza['idle']['since'] = since
         return stanza