jshiffer/slixmpp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update the documentation and examples

Browse Source 
- update most of the examples with slixmpp
- change the help channels pointed out in the doc
- add a page listing differences from slixmpp and how to use asyncio
  nicely with slixmpp
- fix some in-code rst documentation
This commit is contained in:
mathieui
2015-02-24 18:58:40 +01:00
parent e112e86475
commit c66a4d4097
36 changed files with 498 additions and 401 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
slixmpp/stanza/iq.py
View File

@@ -32,6 +32,9 @@ class Iq(RootStanza):
as a carrier stanza for an application-specific protocol instead.
Example <iq> Stanzas:
.. code-block:: xml
<iq to="user@example.com" type="get" id="314">
<query xmlns="http://jabber.org/protocol/disco#items" />
</iq>
@@ -47,20 +50,9 @@ class Iq(RootStanza):
</iq>
Stanza Interface:
query -- The namespace of the <query> element if one exists.
- **query**: The namespace of the <query> element if one exists.
Attributes:
types -- May be one of: get, set, result, or error.
Methods:
__init__ -- Overrides StanzaBase.__init__.
unhandled -- Send error if there are no handlers.
set_payload -- Overrides StanzaBase.set_payload.
set_query -- Add or modify a <query> element.
get_query -- Return the namespace of the <query> element.
del_query -- Remove the <query> element.
reply -- Overrides StanzaBase.reply
send -- Overrides StanzaBase.send
- **types**: May be one of: get, set, result, or error.
"""
namespace = 'jabber:client'
@@ -98,8 +90,9 @@ class Iq(RootStanza):
"""
Set the XML contents of the <iq> stanza.
Arguments:
value -- An XML object to use as the <iq> stanza's contents
:param value: An XML object or a list of XML objects to use as the <iq>
stanza's contents
:type value: list or XML object
"""
self.clear()
StanzaBase.set_payload(self, value)
@@ -111,8 +104,7 @@ class Iq(RootStanza):
Query elements are differentiated by their namespace.
Arguments:
value -- The namespace of the <query> element.
:param str value: The namespace of the <query> element.
"""
query = self.xml.find("{%s}query" % value)
if query is None and value:
@@ -126,7 +118,9 @@ class Iq(RootStanza):
return self
def get_query(self):
"""Return the namespace of the <query> element."""
"""Return the namespace of the <query> element.
:rtype: str"""
for child in self.xml:
if child.tag.endswith('query'):
ns = child.tag.split('}')[0]
@@ -144,16 +138,15 @@ class Iq(RootStanza):
def reply(self, clear=True):
"""
Send a reply <iq> stanza.
Create a new <iq> stanza replying to ``self``.
Overrides StanzaBase.reply
Sets the 'type' to 'result' in addition to the default
StanzaBase.reply behavior.
Arguments:
clear -- Indicates if existing content should be
removed before replying. Defaults to True.
:param bool clear: Indicates if existing content should be
removed before replying. Defaults to True.
"""
new_iq = StanzaBase.reply(self, clear=clear)
new_iq['type'] = 'result'
@@ -168,10 +161,8 @@ class Iq(RootStanza):
Overrides StanzaBase.send
Arguments:
timeout -- The length of time (in seconds) to wait for a
response before an IqTimeout is raised
:param int timeout: The length of time (in seconds) to wait for a
response before an IqTimeout is raised
"""
future = asyncio.Future()
@@ -216,20 +207,19 @@ class Iq(RootStanza):
Overrides StanzaBase.send
Arguments:
callback -- Optional reference to a stream handler
function. Will be executed when a reply stanza is
received.
timeout -- The length of time (in seconds) to wait for a
response before the timeout_callback is called,
instead of the regular callback
timeout_callback -- Optional reference to a stream handler
function. Will be executed when the timeout expires
before a response has been received with the
originally-sent IQ stanza.
coroutine -- This function will return a coroutine if this argument
is True.
:param function callback: Optional reference to a stream handler
function. Will be executed when a reply
stanza is received.
:param int timeout: The length of time (in seconds) to wait for a
response before the timeout_callback is called,
instead of the regular callback
:param function timeout_callback: Optional reference to a stream handler
function. Will be executed when the
timeout expires before a response has
been received for the originally-sent
IQ stanza.
:param bool coroutine: This function will return a coroutine if this
argument is True.
"""
if self.stream.session_bind_event.is_set():
matcher = MatchIDSender({

50
slixmpp/stanza/message.py
View File

@@ -23,6 +23,9 @@ class Message(RootStanza):
an error response.
Example <message> stanzas:
.. code-block:: xml
<message to="user1@example.com" from="user2@example.com">
<body>Hi!</body>
</message>
@@ -32,26 +35,13 @@ class Message(RootStanza):
</message>
Stanza Interface:
body -- The main contents of the message.
subject -- An optional description of the message's contents.
mucroom -- (Read-only) The name of the MUC room that sent the message.
mucnick -- (Read-only) The MUC nickname of message's sender.
- **body**: The main contents of the message.
- **subject**: An optional description of the message's contents.
- **mucroom**: (Read-only) The name of the MUC room that sent the message.
- **mucnick**: (Read-only) The MUC nickname of message's sender.
Attributes:
types -- May be one of: normal, chat, headline, groupchat, or error.
Methods:
setup -- Overrides StanzaBase.setup.
chat -- Set the message type to 'chat'.
normal -- Set the message type to 'normal'.
reply -- Overrides StanzaBase.reply
get_type -- Overrides StanzaBase interface
get_mucroom -- Return the name of the MUC room of the message.
set_mucroom -- Dummy method to prevent assignment.
del_mucroom -- Dummy method to prevent deletion.
get_mucnick -- Return the MUC nickname of the message's sender.
set_mucnick -- Dummy method to prevent assignment.
del_mucnick -- Dummy method to prevent deletion.
- **types**: May be one of: normal, chat, headline, groupchat, or error.
"""
name = 'message'
@@ -81,18 +71,25 @@ class Message(RootStanza):
Overrides default stanza interface behavior.
Returns 'normal' if no type attribute is present.
:rtype: str
"""
return self._get_attr('type', 'normal')
def get_parent_thread(self):
"""Return the message thread's parent thread."""
"""Return the message thread's parent thread.
:rtype: str
"""
thread = self.xml.find('{%s}thread' % self.namespace)
if thread is not None:
return thread.attrib.get('parent', '')
return ''
def set_parent_thread(self, value):
"""Add or change the message thread's parent thread."""
"""Add or change the message thread's parent thread.
:param str value: identifier of the thread"""
thread = self.xml.find('{%s}thread' % self.namespace)
if value:
if thread is None:
@@ -128,10 +125,11 @@ class Message(RootStanza):
Sets proper 'to' attribute if the message is from a MUC, and
adds a message body if one is given.
Arguments:
body -- Optional text content for the message.
clear -- Indicates if existing content should be removed
before replying. Defaults to True.
:param str body: Optional text content for the message.
:param bool clear: Indicates if existing content should be removed
before replying. Defaults to True.
:rtype: :class:`~.Message`
"""
new_message = StanzaBase.reply(self, clear)
@@ -152,6 +150,8 @@ class Message(RootStanza):
Return the name of the MUC room where the message originated.
Read-only stanza interface.
:rtype: str
"""
if self['type'] == 'groupchat':
return self['from'].bare
@@ -163,6 +163,8 @@ class Message(RootStanza):
Return the nickname of the MUC user that sent the message.
Read-only stanza interface.
:rtype: str
"""
if self['type'] == 'groupchat':
return self['from'].resource

43
slixmpp/stanza/presence.py
View File

@@ -27,6 +27,9 @@ class Presence(RootStanza):
to help keep the network running smoothly.
Example <presence> stanzas:
.. code-block:: xml
<presence />
<presence from="user@example.com">
@@ -40,24 +43,14 @@ class Presence(RootStanza):
<presence to="user@otherhost.com" type="subscribe" />
Stanza Interface:
priority -- A value used by servers to determine message routing.
show -- The type of status, such as away or available for chat.
status -- Custom, human readable status message.
- **priority**: A value used by servers to determine message routing.
- **show**: The type of status, such as away or available for chat.
- **status**: Custom, human readable status message.
Attributes:
types -- One of: available, unavailable, error, probe,
subscribe, subscribed, unsubscribe,
and unsubscribed.
showtypes -- One of: away, chat, dnd, and xa.
Methods:
setup -- Overrides StanzaBase.setup
reply -- Overrides StanzaBase.reply
set_show -- Set the value of the <show> element.
get_type -- Get the value of the type attribute or <show> element.
set_type -- Set the value of the type attribute or <show> element.
get_priority -- Get the value of the <priority> element.
set_priority -- Set the value of the <priority> element.
- **types**: One of: available, unavailable, error, probe,
subscribe, subscribed, unsubscribe, and unsubscribed.
- **showtypes**: One of: away, chat, dnd, and xa.
"""
name = 'presence'
@@ -93,8 +86,7 @@ class Presence(RootStanza):
"""
Set the value of the <show> element.
Arguments:
show -- Must be one of: away, chat, dnd, or xa.
:param str show: Must be one of: away, chat, dnd, or xa.
"""
if show is None:
self._del_sub('show')
@@ -119,8 +111,7 @@ class Presence(RootStanza):
Set the type attribute's value, and the <show> element
if applicable.
Arguments:
value -- Must be in either self.types or self.showtypes.
:param str value: Must be in either self.types or self.showtypes.
"""
if value in self.types:
self['show'] = None
@@ -146,14 +137,15 @@ class Presence(RootStanza):
Bot clients should typically use a priority of 0 if the same
JID is used elsewhere by a human-interacting client.
Arguments:
value -- An integer value greater than or equal to 0.
:param int value: An integer value greater than or equal to 0.
"""
self._set_sub_text('priority', text=str(value))
def get_priority(self):
"""
Return the value of the <presence> element as an integer.
:rtype: int
"""
p = self._get_sub_text('priority')
if not p:
@@ -166,13 +158,12 @@ class Presence(RootStanza):
def reply(self, clear=True):
"""
Set the appropriate presence reply type.
Create a new reply <presence/> stanza from ``self``.
Overrides StanzaBase.reply.
Arguments:
clear -- Indicates if the stanza contents should be removed
before replying. Defaults to True.
:param bool clear: Indicates if the stanza contents should be removed
before replying. Defaults to True.
"""
new_presence = StanzaBase.reply(self, clear)
if self['type'] == 'unsubscribe':

6
slixmpp/xmlstream/stanzabase.py
View File

@@ -1474,7 +1474,7 @@ class StanzaBase(ElementBase):
Only type values contained in :attr:`types` are accepted.
:param string value: One of the values contained in :attr:`types`
:param str value: One of the values contained in :attr:`types`
"""
if value in self.types:
self.xml.attrib['type'] = value
@@ -1499,8 +1499,8 @@ class StanzaBase(ElementBase):
def set_from(self, value):
"""Set the 'from' attribute of the stanza.
Arguments:
from -- A string or JID object representing the sender's JID.
:param from: A string or JID object representing the sender's JID.
:type from: str or :class:`.JID`
"""
return self._set_attr('from', str(value))