Commit 622cfd4e authored by mathieui's avatar mathieui

basexmpp: add more typing, fix some docs

parent d850b9a9
......@@ -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.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment