Each interface, say foo, may be overridden in three ways:
set_foo
get_foo
del_foo
To declare an override in a plugin, add the class field
overrides as so:
overrides = ['set_foo', 'del_foo']
Each override must have a matching set_foo(), etc method
for implementing the new behaviour.
To enable the overrides for a particular parent stanza,
pass the option overrides=True to register_stanza_plugin.
register_stanza_plugin(Stanza, Plugin, overrides=True)
Example code:
class Test(ElementBase):
name = 'test'
namespace = 'testing'
interfaces = set(('foo', 'bar'))
sub_interfaces = set(('bar',))
class TestOverride(ElementBase):
name = 'test-override'
namespace = 'testing'
plugin_attrib = 'override'
interfaces = set(('foo',))
overrides = ['set_foo']
def setup(self, xml):
# Don't include an XML element in the parent stanza
# since we're adding just an attribute.
# If adding a regular subelement, no need to do this.
self.xml = ET.Element('')
def set_foo(self, value):
print("overrides!")
self.parent()._set_attr('foo', 'override-%s' % value)
register_stanza_plugin(Test, TestOverride, overrides=True)
Example usage:
>>> t = TestStanza()
>>> t['foo'] = 'bar'
>>> t['foo']
'override-bar'
Backward incompatibility alert!
Please see examples/adhoc_provider.py for how to use the new
plugin implementation, or the test examples in the files
tests/test_stream_xep_0050.py and tests/test_stanza_xep_0050.py.
Major changes:
- May now have zero-step commands. Useful if a command is
intended to be a dynamic status report that doesn't
require any user input.
- May use payloads other than data forms, such as a
completely custom stanza type.
- May include multiple payload items, such as multiple
data forms, or a form and a custom stanza type.
- Includes a command user API for calling adhoc commands
on remote agents and managing the workflow.
- Added support for note elements.
Todo:
- Add prev action support.
You may use register_plugin('old_0050') to continue using the
previous XEP-0050 implementation.
Can now be used as so:
>>> msg['chat_state']
''
>>> msg
<message />
>>> msg['chat_state'] = 'paused'
>>> msg
<message>
<paused xmlns="http://jabber.org/protocol/chatstates" />
</message>
>>> msg['chat_state']
'paused'
>>> del msg['chat_state']
>>> msg
<message />
This allows exceptions to include the original
content of a stanza in the error response by including
the parameter clear=False when raising the exception.
Will now always show top-level namespace, unless it is the same
as the stream's default namespace. Also added the XMPP stream
namespace to the namespace map as 'stream'.
Now with dynamic node handling goodness.
Some things are not quite working yet, in particular:
set_items
set_info
set_identities
set_features
And still need more unit tests to round things out.
Support is only for adding literal XML content
to stanzas. Full support for things like multiple
message bodies with different xml:lang values is
still in the works.
The callback will be a stream level handler, and will not
execute in its own thread. If you must have a thread, have the
callback function raise a custom event, which can be processed
by another event handler, which may run in an individual thread,
like so:
def handle_reply(self, iq):
self.event('custom_event', iq)
def do_long_operation_in_thread(self, iq):
...
self.add_event_handler('custom_event', self.do_long_operation_in_thread)
...take out already prepared iq stanza...
iq.send(callback=self.handle_reply)
SleekTest can now use matchers when checking stanzas, using
the method parameter for self.check(), self.recv(), and self.send():
method='exact' - Same behavior as before
'xpath' - Use xpath matcher
'id' - Use ID matcher
'mask' - Use XML mask matcher
'stanzapath' - Use StanzaPath matcher
recv_feature and send_feature only accept 'exact' and 'mask' for now.
* check_stanza does not require stanza_class parameter. Introspection!
* check_message, check_iq, and check_presence removed -- use check
instead.
* stream_send_stanza, stream_send_message, stream_send_iq, and
stream_send_presence removed -- use send instead.
* Use recv instead of recv_message, recv_presence, etc.
* check_jid instead of check_JID
* stream_start may accept multi=True to return a new SleekTest instance
for testing multiple streams at once.
Raising an XMPPError exception from an event handler now works, even if
from a threaded handler.
Added stream tests to verify.
We should start using XMPPError, it really makes things simple!
Stanza objects now accept the use of underscored names.
The CamelCase versions are still available for backwards compatibility,
but are discouraged.
The property stanza.values now maps to the old getStanzaValues and
setStanzaValues, in addition to _set_stanza_values and
_get_stanza_values.
Moved SleekTest to sleekxmpp.test.
Organized test suites by their focus.
- Suites focused on testing stanza objects are named test_stanza_X.py
- Suites focused on testing stream behavior are name test_stream_X.py
Updated XMLStream to return True or False from removeHandler to indicate if the handler
existed and was removed.
Waiter handlers now unregister themselves after timing out.
_setSubText can now handle elements specified by an XPath expression, and
will build up the element tree as needed, reusing an existing elements in
the path.
Updated tests for Iq stanzas to not start a stream for every test; tests now run a lot faster.
The call to streamClose must still be in the tearDown method to ensure it is called in the
case of an error.
Forms have default type of 'form'
setFields now uses a list of tuples instead of a dictionary because ordering is important.
getFields defaults to returning a list of tuples, but the use_dict parameter can change that
Can now use: (where self is a SleekTest instance)
self.stanzaPlugin(stanza, plugin)
self.Message() \
self.Iq() > Just like basexmpp.Message(), etc.
self.Presence() /
self.checkMessage(msg, xmlstring)
self.checkIq(iq, xmlstring)
self.checkPresence(pres, xmlstring) <- Not implemented yet, but stub is there.
The check* methods also accept a use_values keyword argument that defaults to True.
When this value is True, an additional test is executed by creating a stanza using
getValues() and setValues(). Since some stanza objects can override these two methods,
disabling this test is sometimes required.
Chat states may be set using:
msg['chat_state'].active()
msg['chat_state'].composing()
msg['chat_state'].gone()
msg['chat_state'].inactive()
msg['chat_state'].paused()
Checking a chat state can be done with either:
msg['chat_state'].getState()
msg['chat_state'].name
When a message with a chat state is receieved, the following events
may occur:
chatstate_active
chatstate_composing
chatstate_gone
chatstate_inactive
chatstate_paused
where the event data is the message stanza. Note that currently these
events are also triggered for messages sent by SleekXMPP, not just those
received.
* added stanza.keys()
* stanza.getValues() now return substanzas and plugins
* stanza.setValues() now can read substanzas and plugins
* stanzas can now be iterable if stanza.subitem is set to a class
