basexmpp: add more typing, fix some docs

1 files changed, 92 insertions, 47 deletions

diff --git a/slixmpp/basexmpp.py b/slixmpp/basexmpp.py
index e94883b1..25aa0d75 100644
--- a/slixmpp/basexmpp.py
+++ b/slixmpp/basexmpp.py
@@ -11,6 +11,9 @@ import asyncio
 import logging
 
 from typing import (
+    Dict,
+    Optional,
+    Union,
     TYPE_CHECKING,
 )
 
@@ -18,14 +21,22 @@ from slixmpp import plugins, roster, stanza
 from slixmpp.api import APIRegistry
 from slixmpp.exceptions import IqError, IqTimeout
 
-from slixmpp.stanza import Message, Presence, Iq, StreamError
+from slixmpp.stanza import (
+    Message,
+    Presence,
+    Iq,
+    StreamError,
+)
 from slixmpp.stanza.roster import Roster
 
 from slixmpp.xmlstream import XMLStream, JID
 from slixmpp.xmlstream import ET, register_stanza_plugin
 from slixmpp.xmlstream.matcher import MatchXPath
 from slixmpp.xmlstream.handler import Callback
-from slixmpp.xmlstream.stanzabase import XML_NS
+from slixmpp.xmlstream.stanzabase import (
+    ElementBase,
+    XML_NS,
+)
 
 from slixmpp.plugins import PluginManager, load_plugin
 
@@ -33,8 +44,16 @@ from slixmpp.plugins import PluginManager, load_plugin
 log = logging.getLogger(__name__)
 
 
+from slixmpp.types import (
+    PresenceShows,
+    PresenceTypes,
+    MessageTypes,
+    IqTypes,
+)
+
 if TYPE_CHECKING:
-    from slixmpp.types import PluginsDict
+    # Circular imports
+    from slixmpp.pluginsdict import PluginsDict
 
 
 class BaseXMPP(XMLStream):
@@ -229,7 +248,7 @@ class BaseXMPP(XMLStream):
                     self.plugin[name].post_init()
                 self.plugin[name].post_inited = True
 
-    def register_plugin(self, plugin, pconfig=None, module=None):
+    def register_plugin(self, plugin: str, pconfig: Optional[Dict] = None, module=None):
         """Register and configure  a plugin for use in this stream.
 
         :param plugin: The name of the plugin class. Plugin names must
@@ -279,32 +298,34 @@ class BaseXMPP(XMLStream):
         """Return a plugin given its name, if it has been registered."""
         return self.plugin.get(key, default)
 
-    def Message(self, *args, **kwargs):
+    def Message(self, *args, **kwargs) -> Message:
         """Create a Message stanza associated with this stream."""
         msg = Message(self, *args, **kwargs)
         msg['lang'] = self.default_lang
         return msg
 
-    def Iq(self, *args, **kwargs):
+    def Iq(self, *args, **kwargs) -> Iq:
         """Create an Iq stanza associated with this stream."""
         return Iq(self, *args, **kwargs)
 
-    def Presence(self, *args, **kwargs):
+    def Presence(self, *args, **kwargs) -> Presence:
         """Create a Presence stanza associated with this stream."""
         pres = Presence(self, *args, **kwargs)
         pres['lang'] = self.default_lang
         return pres
 
-    def make_iq(self, id=0, ifrom=None, ito=None, itype=None, iquery=None):
-        """Create a new Iq stanza with a given Id and from JID.
+    def make_iq(self, id: str = "0", ifrom: Optional[JID] = None,
+                ito: Optional[JID] = None, itype: Optional[IqTypes] = None,
+                iquery: Optional[str] = None) -> Iq:
+        """Create a new :class:`~.Iq` stanza with a given Id and from JID.
 
         :param id: An ideally unique ID value for this stanza thread.
                    Defaults to 0.
-        :param ifrom: The from :class:`~slixmpp.xmlstream.jid.JID`
+        :param ifrom: The from :class:`~.JID`
                       to use for this stanza.
-        :param ito: The destination :class:`~slixmpp.xmlstream.jid.JID`
+        :param ito: The destination :class:`~.JID`
                     for this stanza.
-        :param itype: The :class:`~slixmpp.stanza.iq.Iq`'s type,
+        :param itype: The :class:`~.Iq`'s type,
                       one of: ``'get'``, ``'set'``, ``'result'``,
                       or ``'error'``.
         :param iquery: Optional namespace for adding a query element.
@@ -317,15 +338,17 @@ class BaseXMPP(XMLStream):
         iq['query'] = iquery
         return iq
 
-    def make_iq_get(self, queryxmlns=None, ito=None, ifrom=None, iq=None):
-        """Create an :class:`~slixmpp.stanza.iq.Iq` stanza of type ``'get'``.
+    def make_iq_get(self, queryxmlns: Optional[str] =None,
+                    ito: Optional[JID] = None, ifrom: Optional[JID] = None,
+                    iq: Optional[Iq] = None) -> Iq:
+        """Create an :class:`~.Iq` stanza of type ``'get'``.
 
         Optionally, a query element may be added.
 
         :param queryxmlns: The namespace of the query to use.
-        :param ito: The destination :class:`~slixmpp.xmlstream.jid.JID`
+        :param ito: The destination :class:`~.JID`
                     for this stanza.
-        :param ifrom: The ``'from'`` :class:`~slixmpp.xmlstream.jid.JID`
+        :param ifrom: The ``'from'`` :class:`~.JID`
                       to use for this stanza.
         :param iq: Optionally use an existing stanza instead
                    of generating a new one.
@@ -340,15 +363,17 @@ class BaseXMPP(XMLStream):
             iq['from'] = ifrom
         return iq
 
-    def make_iq_result(self, id=None, ito=None, ifrom=None, iq=None):
+    def make_iq_result(self, id: Optional[str] = None,
+                       ito: Optional[JID] = None, ifrom: Optional[JID] = None,
+                       iq: Optional[Iq] = None) -> Iq:
         """
-        Create an :class:`~slixmpp.stanza.iq.Iq` stanza of type
+        Create an :class:`~.Iq` stanza of type
         ``'result'`` with the given ID value.
 
         :param id: An ideally unique ID value. May use :meth:`new_id()`.
-        :param ito: The destination :class:`~slixmpp.xmlstream.jid.JID`
+        :param ito: The destination :class:`~.JID`
                     for this stanza.
-        :param ifrom: The ``'from'`` :class:`~slixmpp.xmlstream.jid.JID`
+        :param ifrom: The ``'from'`` :class:`~.JID`
                       to use for this stanza.
         :param iq: Optionally use an existing stanza instead
                    of generating a new one.
@@ -365,21 +390,23 @@ class BaseXMPP(XMLStream):
             iq['from'] = ifrom
         return iq
 
-    def make_iq_set(self, sub=None, ito=None, ifrom=None, iq=None):
+    def make_iq_set(self, sub: Optional[Union[ElementBase, ET.Element]] = None,
+                    ito: Optional[JID] = None, ifrom: Optional[JID] = None,
+                    iq: Optional[Iq] = None) -> Iq:
         """
-        Create an :class:`~slixmpp.stanza.iq.Iq` stanza of type ``'set'``.
+        Create an :class:`~.Iq` stanza of type ``'set'``.
 
         Optionally, a substanza may be given to use as the
         stanza's payload.
 
         :param sub: Either an
-                    :class:`~slixmpp.xmlstream.stanzabase.ElementBase`
+                    :class:`~.ElementBase`
                     stanza object or an
                     :class:`~xml.etree.ElementTree.Element` XML object
-                    to use as the :class:`~slixmpp.stanza.iq.Iq`'s payload.
-        :param ito: The destination :class:`~slixmpp.xmlstream.jid.JID`
+                    to use as the :class:`~.Iq`'s payload.
+        :param ito: The destination :class:`~.JID`
                     for this stanza.
-        :param ifrom: The ``'from'`` :class:`~slixmpp.xmlstream.jid.JID`
+        :param ifrom: The ``'from'`` :class:`~.JID`
                       to use for this stanza.
         :param iq: Optionally use an existing stanza instead
                    of generating a new one.
@@ -399,7 +426,7 @@ class BaseXMPP(XMLStream):
                       condition='feature-not-implemented',
                       text=None, ito=None, ifrom=None, iq=None):
         """
-        Create an :class:`~slixmpp.stanza.iq.Iq` stanza of type ``'error'``.
+        Create an :class:`~.Iq` stanza of type ``'error'``.
 
         :param id: An ideally unique ID value. May use :meth:`new_id()`.
         :param type: The type of the error, such as ``'cancel'`` or
@@ -407,9 +434,9 @@ class BaseXMPP(XMLStream):
         :param condition: The error condition. Defaults to
                           ``'feature-not-implemented'``.
         :param text: A message describing the cause of the error.
-        :param ito: The destination :class:`~slixmpp.xmlstream.jid.JID`
+        :param ito: The destination :class:`~.JID`
                     for this stanza.
-        :param ifrom: The ``'from'`` :class:`~slixmpp.xmlstream.jid.JID`
+        :param ifrom: The ``'from'`` :class:`~jid.JID`
                       to use for this stanza.
         :param iq: Optionally use an existing stanza instead
                    of generating a new one.
@@ -426,17 +453,19 @@ class BaseXMPP(XMLStream):
             iq['from'] = ifrom
         return iq
 
-    def make_iq_query(self, iq=None, xmlns='', ito=None, ifrom=None):
+    def make_iq_query(self, iq: Optional[Iq] = None, xmlns: str = '',
+                      ito: Optional[JID] = None,
+                      ifrom: Optional[JID] = None) -> Iq:
         """
-        Create or modify an :class:`~slixmpp.stanza.iq.Iq` stanza
+        Create or modify an :class:`~.Iq` stanza
         to use the given query namespace.
 
         :param iq: Optionally use an existing stanza instead
                    of generating a new one.
         :param xmlns: The query's namespace.
-        :param ito: The destination :class:`~slixmpp.xmlstream.jid.JID`
+        :param ito: The destination :class:`~.JID`
                     for this stanza.
-        :param ifrom: The ``'from'`` :class:`~slixmpp.xmlstream.jid.JID`
+        :param ifrom: The ``'from'`` :class:`~.JID`
                       to use for this stanza.
         """
         if not iq:
@@ -448,7 +477,7 @@ class BaseXMPP(XMLStream):
             iq['from'] = ifrom
         return iq
 
-    def make_query_roster(self, iq=None):
+    def make_query_roster(self, iq: Optional[Iq] = None) -> ET.Element:
         """Create a roster query element.
 
         :param iq: Optionally use an existing stanza instead
@@ -458,11 +487,14 @@ class BaseXMPP(XMLStream):
             iq['query'] = 'jabber:iq:roster'
         return ET.Element("{jabber:iq:roster}query")
 
-    def make_message(self, mto, mbody=None, msubject=None, mtype=None,
-                     mhtml=None, mfrom=None, mnick=None):
+    def make_message(self, mto: JID, mbody: Optional[str] = None,
+                     msubject: Optional[str] = None,
+                     mtype: Optional[MessageTypes] = None,
+                     mhtml: Optional[str] = None, mfrom: Optional[JID] = None,
+                     mnick: Optional[str] = None) -> Message:
         """
         Create and initialize a new
-        :class:`~slixmpp.stanza.message.Message` stanza.
+        :class:`~.Message` stanza.
 
         :param mto: The recipient of the message.
         :param mbody: The main contents of the message.
@@ -484,11 +516,16 @@ class BaseXMPP(XMLStream):
             message['html']['body'] = mhtml
         return message
 
-    def make_presence(self, pshow=None, pstatus=None, ppriority=None,
-                      pto=None, ptype=None, pfrom=None, pnick=None):
+    def make_presence(self, pshow: Optional[PresenceShows] = None,
+                      pstatus: Optional[str] = None,
+                      ppriority: Optional[int] = None,
+                      pto: Optional[JID] = None,
+                      ptype: Optional[PresenceTypes] = None,
+                      pfrom: Optional[JID] = None,
+                      pnick: Optional[str] = None) -> Presence:
         """
         Create and initialize a new
-        :class:`~slixmpp.stanza.presence.Presence` stanza.
+        :class:`~.Presence` stanza.
 
         :param pshow: The presence's show value.
         :param pstatus: The presence's status message.
@@ -508,11 +545,14 @@ class BaseXMPP(XMLStream):
         presence['nick'] = pnick
         return presence
 
-    def send_message(self, mto, mbody, msubject=None, mtype=None,
-                     mhtml=None, mfrom=None, mnick=None):
+    def send_message(self, mto: JID, mbody: Optional[str] = None,
+                     msubject: Optional[str] = None,
+                     mtype: Optional[MessageTypes] = None,
+                     mhtml: Optional[str] = None, mfrom: Optional[JID] = None,
+                     mnick: Optional[str] = None):
         """
         Create, initialize, and send a new
-        :class:`~slixmpp.stanza.message.Message` stanza.
+        :class:`~.Message` stanza.
 
         :param mto: The recipient of the message.
         :param mbody: The main contents of the message.
@@ -528,11 +568,16 @@ class BaseXMPP(XMLStream):
         self.make_message(mto, mbody, msubject, mtype,
                           mhtml, mfrom, mnick).send()
 
-    def send_presence(self, pshow=None, pstatus=None, ppriority=None,
-                      pto=None, pfrom=None, ptype=None, pnick=None):
+    def send_presence(self, pshow: Optional[PresenceShows] = None,
+                      pstatus: Optional[str] = None,
+                      ppriority: Optional[int] = None,
+                      pto: Optional[JID] = None,
+                      ptype: Optional[PresenceTypes] = None,
+                      pfrom: Optional[JID] = None,
+                      pnick: Optional[str] = None):
         """
         Create, initialize, and send a new
-        :class:`~slixmpp.stanza.presence.Presence` stanza.
+        :class:`~.Presence` stanza.
 
         :param pshow: The presence's show value.
         :param pstatus: The presence's status message.
@@ -549,7 +594,7 @@ class BaseXMPP(XMLStream):
                                    ptype='subscribe', pnick=None):
         """
         Create, initialize, and send a new
-        :class:`~slixmpp.stanza.presence.Presence` stanza of
+        :class:`~.Presence` stanza of
         type ``'subscribe'``.
 
         :param pto: The recipient of a directed presence.