summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authormathieui <mathieui@mathieui.net>2021-02-06 12:29:14 +0100
committermathieui <mathieui@mathieui.net>2021-02-06 12:29:14 +0100
commit622cfd4ed73b6fada9b445772ab0805d893f7678 (patch)
treeade7b21f6540736554649277904947837e338a78
parentd850b9a9f7e18d72c84ccce22b97726a561e866a (diff)
downloadslixmpp-622cfd4ed73b6fada9b445772ab0805d893f7678.tar.gz
slixmpp-622cfd4ed73b6fada9b445772ab0805d893f7678.tar.bz2
slixmpp-622cfd4ed73b6fada9b445772ab0805d893f7678.tar.xz
slixmpp-622cfd4ed73b6fada9b445772ab0805d893f7678.zip
basexmpp: add more typing, fix some docs
-rw-r--r--slixmpp/basexmpp.py139
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.