github/SleekXMPP
1
0
Fork 0
mirror of https://github.com/correl/SleekXMPP.git synced 2024-11-27 11:09:56 +00:00
Code Issues Projects Releases Packages Wiki Activity

More doc updates

Browse source
This commit is contained in:
Lance Stout 2011-12-05 08:55:05 -08:00
parent 8922e2050a
commit e01c2d222a
3 changed files with 239 additions and 268 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
docs/index.rst
View file

@ -112,6 +112,7 @@ API Reference
api/clientxmpp api/clientxmpp
api/componentxmpp api/componentxmpp
api/basexmpp api/basexmpp
api/exceptions
api/xmlstream/jid api/xmlstream/jid
api/xmlstream/stanzabase api/xmlstream/stanzabase
api/xmlstream/handler api/xmlstream/handler

446
sleekxmpp/basexmpp.py
View file

@ -1,9 +1,15 @@
# -*- coding: utf-8 -*-
""" """
SleekXMPP: The Sleek XMPP Library sleekxmpp.basexmpp
Copyright (C) 2010 Nathanael C. Fritz ~~~~~~~~~~~~~~~~~~
This file is part of SleekXMPP.
See the file LICENSE for copying permission. This module provides the common XMPP functionality
for both clients and components.
Part of SleekXMPP: The Sleek XMPP Library
:copyright: (c) 2011 Nathanael C. Fritz
:license: MIT, see LICENSE for more details
""" """
from __future__ import with_statement, unicode_literals from __future__ import with_statement, unicode_literals
@ -43,71 +49,59 @@ class BaseXMPP(XMLStream):
with XMPP. It also provides a plugin mechanism to easily extend with XMPP. It also provides a plugin mechanism to easily extend
and add support for new XMPP features. and add support for new XMPP features.
Attributes: :param default_ns: Ensure that the correct default XML namespace
auto_authorize -- Manage automatically accepting roster is used during initialization.
subscriptions.
auto_subscribe -- Manage automatically requesting mutual
subscriptions.
is_component -- Indicates if this stream is for an XMPP component.
jid -- The XMPP JID for this stream.
plugin -- A dictionary of loaded plugins.
plugin_config -- A dictionary of plugin configurations.
plugin_whitelist -- A list of approved plugins.
sentpresence -- Indicates if an initial presence has been sent.
roster -- A dictionary containing subscribed JIDs and
their presence statuses.
Methods:
Iq -- Factory for creating an Iq stanzas.
Message -- Factory for creating Message stanzas.
Presence -- Factory for creating Presence stanzas.
get -- Return a plugin given its name.
make_iq -- Create and initialize an Iq stanza.
make_iq_error -- Create an Iq stanza of type 'error'.
make_iq_get -- Create an Iq stanza of type 'get'.
make_iq_query -- Create an Iq stanza with a given query.
make_iq_result -- Create an Iq stanza of type 'result'.
make_iq_set -- Create an Iq stanza of type 'set'.
make_message -- Create and initialize a Message stanza.
make_presence -- Create and initialize a Presence stanza.
make_query_roster -- Create a roster query.
process -- Overrides XMLStream.process.
register_plugin -- Load and configure a plugin.
register_plugins -- Load and configure multiple plugins.
send_message -- Create and send a Message stanza.
send_presence -- Create and send a Presence stanza.
send_presence_subscribe -- Send a subscription request.
""" """
def __init__(self, jid='', default_ns='jabber:client'): def __init__(self, jid='', default_ns='jabber:client'):
"""
Adapt an XML stream for use with XMPP.
Arguments:
default_ns -- Ensure that the correct default XML namespace
is used during initialization.
"""
XMLStream.__init__(self) XMLStream.__init__(self)
# To comply with PEP8, method names now use underscores.
# Deprecated method names are re-mapped for backwards compatibility.
self.default_ns = default_ns self.default_ns = default_ns
self.stream_ns = 'http://etherx.jabber.org/streams' self.stream_ns = 'http://etherx.jabber.org/streams'
self.namespace_map[self.stream_ns] = 'stream' self.namespace_map[self.stream_ns] = 'stream'
#: An identifier for the stream as given by the server.
self.stream_id = None
#: The JabberID (JID) used by this connection.
self.boundjid = JID(jid) self.boundjid = JID(jid)
#: A dictionary mapping plugin names to plugins.
self.plugin = {} self.plugin = {}
#: Configuration options for whitelisted plugins.
#: If a plugin is registered without any configuration,
#: and there is an entry here, it will be used.
self.plugin_config = {} self.plugin_config = {}
#: A list of plugins that will be loaded if
#: :meth:`register_plugins` is called.
self.plugin_whitelist = [] self.plugin_whitelist = []
#: The main roster object. This roster supports multiple
#: owner JIDs, as in the case for components. For clients
#: which only have a single JID, see :attr:`client_roster`.
self.roster = roster.Roster(self) self.roster = roster.Roster(self)
self.roster.add(self.boundjid.bare) self.roster.add(self.boundjid.bare)
#: The single roster for the bound JID. This is the
#: equivalent of::
#:
#: self.roster[self.boundjid.bare]
self.client_roster = self.roster[self.boundjid.bare] self.client_roster = self.roster[self.boundjid.bare]
#: The distinction between clients and components can be
#: important, primarily for choosing how to handle the
#: ``'to'`` and ``'from'`` JIDs of stanzas.
self.is_component = False self.is_component = False
#: Flag indicating that the initial presence broadcast has
#: been sent. Until this happens, some servers may not
#: behave as expected when sending stanzas.
self.sentpresence = False self.sentpresence = False
#: A reference to :mod:`sleekxmpp.stanza` to make accessing
#: stanza classes easier.
self.stanza = sleekxmpp.stanza self.stanza = sleekxmpp.stanza
self.register_handler( self.register_handler(
@ -161,40 +155,36 @@ class BaseXMPP(XMLStream):
register_stanza_plugin(Message, HTMLIM) register_stanza_plugin(Message, HTMLIM)
def start_stream_handler(self, xml): def start_stream_handler(self, xml):
""" """Save the stream ID once the streams have been established.
Save the stream ID once the streams have been established.
Overrides XMLStream.start_stream_handler. :param xml: The incoming stream's root element.
Arguments:
xml -- The incoming stream's root element.
""" """
self.stream_id = xml.get('id', '') self.stream_id = xml.get('id', '')
def process(self, *args, **kwargs): def process(self, *args, **kwargs):
""" """Initialize plugins and begin processing the XML stream.
Overrides XMLStream.process.
Initialize the XML streams and begin processing events.
The number of threads used for processing stream events is determined The number of threads used for processing stream events is determined
by HANDLER_THREADS. by :data:`HANDLER_THREADS`.
Arguments: :param bool block: If ``False``, then event dispatcher will run
block -- If block=False then event dispatcher will run in a separate thread, allowing for the stream to be
in a separate thread, allowing for the stream to be used in the background for another application.
used in the background for another application. Otherwise, ``process(block=True)`` blocks the current
Otherwise, process(block=True) blocks the current thread. thread. Defaults to ``False``.
Defaults to False. :param bool threaded: **DEPRECATED**
If ``True``, then event dispatcher will run
in a separate thread, allowing for the stream to be
used in the background for another application.
Defaults to ``True``. This does **not** mean that no
threads are used at all if ``threaded=False``.
**threaded is deprecated and included for API compatibility** Regardless of these threading options, these threads will
threaded -- If threaded=True then event dispatcher will run always exist:
in a separate thread, allowing for the stream to be
used in the background for another application.
Defaults to True.
Event handlers and the send queue will be threaded - The event queue processor
regardless of these parameters. - The send queue processor
- The scheduler
""" """
for name in self.plugin: for name in self.plugin:
if not self.plugin[name].post_inited: if not self.plugin[name].post_inited:
@ -202,15 +192,13 @@ class BaseXMPP(XMLStream):
return XMLStream.process(self, *args, **kwargs) return XMLStream.process(self, *args, **kwargs)
def register_plugin(self, plugin, pconfig={}, module=None): def register_plugin(self, plugin, pconfig={}, module=None):
""" """Register and configure a plugin for use in this stream.
Register and configure a plugin for use in this stream.
Arguments: :param plugin: The name of the plugin class. Plugin names must
plugin -- The name of the plugin class. Plugin names must
be unique. be unique.
pconfig -- A dictionary of configuration data for the plugin. :param pconfig: A dictionary of configuration data for the plugin.
Defaults to an empty dictionary. Defaults to an empty dictionary.
module -- Optional refence to the module containing the plugin :param module: Optional refence to the module containing the plugin
class if using custom plugins. class if using custom plugins.
""" """
try: try:
@ -251,13 +239,12 @@ class BaseXMPP(XMLStream):
log.exception("Unable to load plugin: %s", plugin) log.exception("Unable to load plugin: %s", plugin)
def register_plugins(self): def register_plugins(self):
""" """Register and initialize all built-in plugins.
Register and initialize all built-in plugins.
Optionally, the list of plugins loaded may be limited to those Optionally, the list of plugins loaded may be limited to those
contained in self.plugin_whitelist. contained in :attr:`plugin_whitelist`.
Plugin configurations stored in self.plugin_config will be used. Plugin configurations stored in :attr:`plugin_config` will be used.
""" """
if self.plugin_whitelist: if self.plugin_whitelist:
plugin_list = self.plugin_whitelist plugin_list = self.plugin_whitelist
@ -276,9 +263,7 @@ class BaseXMPP(XMLStream):
self.plugin[plugin].post_init() self.plugin[plugin].post_init()
def __getitem__(self, key): def __getitem__(self, key):
""" """Return a plugin given its name, if it has been registered."""
Return a plugin given its name, if it has been registered.
"""
if key in self.plugin: if key in self.plugin:
return self.plugin[key] return self.plugin[key]
else: else:
@ -286,9 +271,7 @@ class BaseXMPP(XMLStream):
return False return False
def get(self, key, default): def get(self, key, default):
""" """Return a plugin given its name, if it has been registered."""
Return a plugin given its name, if it has been registered.
"""
return self.plugin.get(key, default) return self.plugin.get(key, default)
def Message(self, *args, **kwargs): def Message(self, *args, **kwargs):
@ -304,16 +287,18 @@ class BaseXMPP(XMLStream):
return Presence(self, *args, **kwargs) return Presence(self, *args, **kwargs)
def make_iq(self, id=0, ifrom=None, ito=None, itype=None, iquery=None): 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.
Create a new Iq stanza with a given Id and from JID.
Arguments: :param id: An ideally unique ID value for this stanza thread.
id -- An ideally unique ID value for this stanza thread. Defaults to 0.
Defaults to 0. :param ifrom: The from :class:`~sleekxmpp.xmlstream.jid.JID`
ifrom -- The from JID to use for this stanza. to use for this stanza.
ito -- The destination JID for this stanza. :param ito: The destination :class:`~sleekxmpp.xmlstream.jid.JID`
itype -- The Iq's type, one of: get, set, result, or error. for this stanza.
iquery -- Optional namespace for adding a query element. :param itype: The :class:`~sleekxmpp.stanza.iq.Iq`'s type,
one of: ``'get'``, ``'set'``, ``'result'``,
or ``'error'``.
:param iquery: Optional namespace for adding a query element.
""" """
iq = self.Iq() iq = self.Iq()
iq['id'] = str(id) iq['id'] = str(id)
@ -324,17 +309,17 @@ class BaseXMPP(XMLStream):
return iq return iq
def make_iq_get(self, queryxmlns=None, ito=None, ifrom=None, iq=None): def make_iq_get(self, queryxmlns=None, ito=None, ifrom=None, iq=None):
""" """Create an :class:`~sleekxmpp.stanza.iq.Iq` stanza of type ``'get'``.
Create an Iq stanza of type 'get'.
Optionally, a query element may be added. Optionally, a query element may be added.
Arguments: :param queryxmlns: The namespace of the query to use.
queryxmlns -- The namespace of the query to use. :param ito: The destination :class:`~sleekxmpp.xmlstream.jid.JID`
ito -- The destination JID for this stanza. for this stanza.
ifrom -- The from JID to use for this stanza. :param ifrom: The ``'from'`` :class:`~sleekxmpp.xmlstream.jid.JID`
iq -- Optionally use an existing stanza instead to use for this stanza.
of generating a new one. :param iq: Optionally use an existing stanza instead
of generating a new one.
""" """
if not iq: if not iq:
iq = self.Iq() iq = self.Iq()
@ -348,14 +333,16 @@ class BaseXMPP(XMLStream):
def make_iq_result(self, id=None, ito=None, ifrom=None, iq=None): def make_iq_result(self, id=None, ito=None, ifrom=None, iq=None):
""" """
Create an Iq stanza of type 'result' with the given ID value. Create an :class:`~sleekxmpp.stanza.iq.Iq` stanza of type
``'result'`` with the given ID value.
Arguments: :param id: An ideally unique ID value. May use :meth:`new_id()`.
id -- An ideally unique ID value. May use self.new_id(). :param ito: The destination :class:`~sleekxmpp.xmlstream.jid.JID`
ito -- The destination JID for this stanza. for this stanza.
ifrom -- The from JID to use for this stanza. :param ifrom: The ``'from'`` :class:`~sleekxmpp.xmlstream.jid.JID`
iq -- Optionally use an existing stanza instead to use for this stanza.
of generating a new one. :param iq: Optionally use an existing stanza instead
of generating a new one.
""" """
if not iq: if not iq:
iq = self.Iq() iq = self.Iq()
@ -371,17 +358,22 @@ class BaseXMPP(XMLStream):
def make_iq_set(self, sub=None, ito=None, ifrom=None, iq=None): def make_iq_set(self, sub=None, ito=None, ifrom=None, iq=None):
""" """
Create an Iq stanza of type 'set'. Create an :class:`~sleekxmpp.stanza.iq.Iq` stanza of type ``'set'``.
Optionally, a substanza may be given to use as the Optionally, a substanza may be given to use as the
stanza's payload. stanza's payload.
Arguments: :param sub: Either an
sub -- A stanza or XML object to use as the Iq's payload. :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
ito -- The destination JID for this stanza. stanza object or an
ifrom -- The from JID to use for this stanza. :class:`~xml.etree.ElementTree.Element` XML object
iq -- Optionally use an existing stanza instead to use as the :class:`~sleekxmpp.stanza.iq.Iq`'s payload.
of generating a new one. :param ito: The destination :class:`~sleekxmpp.xmlstream.jid.JID`
for this stanza.
:param ifrom: The ``'from'`` :class:`~sleekxmpp.xmlstream.jid.JID`
to use for this stanza.
:param iq: Optionally use an existing stanza instead
of generating a new one.
""" """
if not iq: if not iq:
iq = self.Iq() iq = self.Iq()
@ -398,19 +390,20 @@ class BaseXMPP(XMLStream):
condition='feature-not-implemented', condition='feature-not-implemented',
text=None, ito=None, ifrom=None, iq=None): text=None, ito=None, ifrom=None, iq=None):
""" """
Create an Iq stanza of type 'error'. Create an :class:`~sleekxmpp.stanza.iq.Iq` stanza of type ``'error'``.
Arguments: :param id: An ideally unique ID value. May use :meth:`new_id()`.
id -- An ideally unique ID value. May use self.new_id(). :param type: The type of the error, such as ``'cancel'`` or
type -- The type of the error, such as 'cancel' or 'modify'. ``'modify'``. Defaults to ``'cancel'``.
Defaults to 'cancel'. :param condition: The error condition. Defaults to
condition -- The error condition. ``'feature-not-implemented'``.
Defaults to 'feature-not-implemented'. :param text: A message describing the cause of the error.
text -- A message describing the cause of the error. :param ito: The destination :class:`~sleekxmpp.xmlstream.jid.JID`
ito -- The destination JID for this stanza. for this stanza.
ifrom -- The from JID to use for this stanza. :param ifrom: The ``'from'`` :class:`~sleekxmpp.xmlstream.jid.JID`
iq -- Optionally use an existing stanza instead to use for this stanza.
of generating a new one. :param iq: Optionally use an existing stanza instead
of generating a new one.
""" """
if not iq: if not iq:
iq = self.Iq() iq = self.Iq()
@ -426,15 +419,16 @@ class BaseXMPP(XMLStream):
def make_iq_query(self, iq=None, xmlns='', ito=None, ifrom=None): def make_iq_query(self, iq=None, xmlns='', ito=None, ifrom=None):
""" """
Create or modify an Iq stanza to use the given Create or modify an :class:`~sleekxmpp.stanza.iq.Iq` stanza
query namespace. to use the given query namespace.
Arguments: :param iq: Optionally use an existing stanza instead
iq -- Optional Iq stanza to modify. A new of generating a new one.
stanza is created otherwise. :param xmlns: The query's namespace.
xmlns -- The query's namespace. :param ito: The destination :class:`~sleekxmpp.xmlstream.jid.JID`
ito -- The destination JID for this stanza. for this stanza.
ifrom -- The from JID to use for this stanza. :param ifrom: The ``'from'`` :class:`~sleekxmpp.xmlstream.jid.JID`
to use for this stanza.
""" """
if not iq: if not iq:
iq = self.Iq() iq = self.Iq()
@ -446,12 +440,10 @@ class BaseXMPP(XMLStream):
return iq return iq
def make_query_roster(self, iq=None): def make_query_roster(self, iq=None):
""" """Create a roster query element.
Create a roster query element.
Arguments: :param iq: Optionally use an existing stanza instead
iq -- Optional Iq stanza to modify. A new stanza of generating a new one.
is created otherwise.
""" """
if iq: if iq:
iq['query'] = 'jabber:iq:roster' iq['query'] = 'jabber:iq:roster'
@ -460,18 +452,19 @@ class BaseXMPP(XMLStream):
def make_message(self, mto, mbody=None, msubject=None, mtype=None, def make_message(self, mto, mbody=None, msubject=None, mtype=None,
mhtml=None, mfrom=None, mnick=None): mhtml=None, mfrom=None, mnick=None):
""" """
Create and initialize a new Message stanza. Create and initialize a new
:class:`~sleekxmpp.stanza.message.Message` stanza.
Arguments: :param mto: The recipient of the message.
mto -- The recipient of the message. :param mbody: The main contents of the message.
mbody -- The main contents of the message. :param msubject: Optional subject for the message.
msubject -- Optional subject for the message. :param mtype: The message's type, such as ``'chat'`` or
mtype -- The message's type, such as 'chat' or 'groupchat'. ``'groupchat'``.
mhtml -- Optional HTML body content. :param mhtml: Optional HTML body content in the form of a string.
mfrom -- The sender of the message. if sending from a client, :param mfrom: The sender of the message. if sending from a client,
be aware that some servers require that the full JID be aware that some servers require that the full JID
of the sender be used. of the sender be used.
mnick -- Optional nickname of the sender. :param mnick: Optional nickname of the sender.
""" """
message = self.Message(sto=mto, stype=mtype, sfrom=mfrom) message = self.Message(sto=mto, stype=mtype, sfrom=mfrom)
message['body'] = mbody message['body'] = mbody
@ -485,16 +478,16 @@ class BaseXMPP(XMLStream):
def make_presence(self, pshow=None, pstatus=None, ppriority=None, def make_presence(self, pshow=None, pstatus=None, ppriority=None,
pto=None, ptype=None, pfrom=None, pnick=None): pto=None, ptype=None, pfrom=None, pnick=None):
""" """
Create and initialize a new Presence stanza. Create and initialize a new
:class:`~sleekxmpp.stanza.presence.Presence` stanza.
Arguments: :param pshow: The presence's show value.
pshow -- The presence's show value. :param pstatus: The presence's status message.
pstatus -- The presence's status message. :param ppriority: This connection's priority.
ppriority -- This connections' priority. :param pto: The recipient of a directed presence.
pto -- The recipient of a directed presence. :param ptype: The type of presence, such as ``'subscribe'``.
ptype -- The type of presence, such as 'subscribe'. :param pfrom: The sender of the presence.
pfrom -- The sender of the presence. :param pnick: Optional nickname of the presence's sender.
pnick -- Optional nickname of the presence's sender.
""" """
presence = self.Presence(stype=ptype, sfrom=pfrom, sto=pto) presence = self.Presence(stype=ptype, sfrom=pfrom, sto=pto)
if pshow is not None: if pshow is not None:
@ -509,18 +502,19 @@ class BaseXMPP(XMLStream):
def send_message(self, mto, mbody, msubject=None, mtype=None, def send_message(self, mto, mbody, msubject=None, mtype=None,
mhtml=None, mfrom=None, mnick=None): mhtml=None, mfrom=None, mnick=None):
""" """
Create, initialize, and send a Message stanza. Create, initialize, and send a new
:class:`~sleekxmpp.stanza.message.Message` stanza.
Arguments: :param mto: The recipient of the message.
mto -- The recipient of the message. :param mbody: The main contents of the message.
mbody -- The main contents of the message. :param msubject: Optional subject for the message.
msubject -- Optional subject for the message. :param mtype: The message's type, such as ``'chat'`` or
mtype -- The message's type, such as 'chat' or 'groupchat'. ``'groupchat'``.
mhtml -- Optional HTML body content. :param mhtml: Optional HTML body content in the form of a string.
mfrom -- The sender of the message. if sending from a client, :param mfrom: The sender of the message. if sending from a client,
be aware that some servers require that the full JID be aware that some servers require that the full JID
of the sender be used. of the sender be used.
mnick -- Optional nickname of the sender. :param mnick: Optional nickname of the sender.
""" """
self.make_message(mto, mbody, msubject, mtype, self.make_message(mto, mbody, msubject, mtype,
mhtml, mfrom, mnick).send() mhtml, mfrom, mnick).send()
@ -528,16 +522,16 @@ class BaseXMPP(XMLStream):
def send_presence(self, pshow=None, pstatus=None, ppriority=None, def send_presence(self, pshow=None, pstatus=None, ppriority=None,
pto=None, pfrom=None, ptype=None, pnick=None): pto=None, pfrom=None, ptype=None, pnick=None):
""" """
Create, initialize, and send a Presence stanza. Create, initialize, and send a new
:class:`~sleekxmpp.stanza.presence.Presence` stanza.
Arguments: :param pshow: The presence's show value.
pshow -- The presence's show value. :param pstatus: The presence's status message.
pstatus -- The presence's status message. :param ppriority: This connection's priority.
ppriority -- This connections' priority. :param pto: The recipient of a directed presence.
pto -- The recipient of a directed presence. :param ptype: The type of presence, such as ``'subscribe'``.
ptype -- The type of presence, such as 'subscribe'. :param pfrom: The sender of the presence.
pfrom -- The sender of the presence. :param pnick: Optional nickname of the presence's sender.
pnick -- Optional nickname of the presence's sender.
""" """
# Python2.6 chokes on Unicode strings for dict keys. # Python2.6 chokes on Unicode strings for dict keys.
args = {str('pto'): pto, args = {str('pto'): pto,
@ -555,13 +549,14 @@ class BaseXMPP(XMLStream):
def send_presence_subscription(self, pto, pfrom=None, def send_presence_subscription(self, pto, pfrom=None,
ptype='subscribe', pnick=None): ptype='subscribe', pnick=None):
""" """
Create, initialize, and send a Presence stanza of type 'subscribe'. Create, initialize, and send a new
:class:`~sleekxmpp.stanza.presence.Presence` stanza of
type ``'subscribe'``.
Arguments: :param pto: The recipient of a directed presence.
pto -- The recipient of a directed presence. :param pfrom: The sender of the presence.
pfrom -- The sender of the presence. :param ptype: The type of presence, such as ``'subscribe'``.
ptype -- The type of presence. Defaults to 'subscribe'. :param pnick: Optional nickname of the presence's sender.
pnick -- Nickname of the presence's sender.
""" """
presence = self.makePresence(ptype=ptype, presence = self.makePresence(ptype=ptype,
pfrom=pfrom, pfrom=pfrom,
@ -574,9 +569,7 @@ class BaseXMPP(XMLStream):
@property @property
def jid(self): def jid(self):
""" """Attribute accessor for bare jid"""
Attribute accessor for bare jid
"""
log.warning("jid property deprecated. Use boundjid.bare") log.warning("jid property deprecated. Use boundjid.bare")
return self.boundjid.bare return self.boundjid.bare
@ -587,9 +580,7 @@ class BaseXMPP(XMLStream):
@property @property
def fulljid(self): def fulljid(self):
""" """Attribute accessor for full jid"""
Attribute accessor for full jid
"""
log.warning("fulljid property deprecated. Use boundjid.full") log.warning("fulljid property deprecated. Use boundjid.full")
return self.boundjid.full return self.boundjid.full
@ -600,9 +591,7 @@ class BaseXMPP(XMLStream):
@property @property
def resource(self): def resource(self):
""" """Attribute accessor for jid resource"""
Attribute accessor for jid resource
"""
log.warning("resource property deprecated. Use boundjid.resource") log.warning("resource property deprecated. Use boundjid.resource")
return self.boundjid.resource return self.boundjid.resource
@ -613,9 +602,7 @@ class BaseXMPP(XMLStream):
@property @property
def username(self): def username(self):
""" """Attribute accessor for jid usernode"""
Attribute accessor for jid usernode
"""
log.warning("username property deprecated. Use boundjid.user") log.warning("username property deprecated. Use boundjid.user")
return self.boundjid.user return self.boundjid.user
@ -626,9 +613,7 @@ class BaseXMPP(XMLStream):
@property @property
def server(self): def server(self):
""" """Attribute accessor for jid host"""
Attribute accessor for jid host
"""
log.warning("server property deprecated. Use boundjid.host") log.warning("server property deprecated. Use boundjid.host")
return self.boundjid.server return self.boundjid.server
@ -639,42 +624,28 @@ class BaseXMPP(XMLStream):
@property @property
def auto_authorize(self): def auto_authorize(self):
""" """Auto accept or deny subscription requests.
Auto accept or deny subscription requests.
If True, auto accept subscription requests. If ``True``, auto accept subscription requests.
If False, auto deny subscription requests. If ``False``, auto deny subscription requests.
If None, don't automatically respond. If ``None``, don't automatically respond.
""" """
return self.roster.auto_authorize return self.roster.auto_authorize
@auto_authorize.setter @auto_authorize.setter
def auto_authorize(self, value): def auto_authorize(self, value):
"""
Auto accept or deny subscription requests.
If True, auto accept subscription requests.
If False, auto deny subscription requests.
If None, don't automatically respond.
"""
self.roster.auto_authorize = value self.roster.auto_authorize = value
@property @property
def auto_subscribe(self): def auto_subscribe(self):
""" """Auto send requests for mutual subscriptions.
Auto send requests for mutual subscriptions.
If True, auto send mutual subscription requests. If ``True``, auto send mutual subscription requests.
""" """
return self.roster.auto_subscribe return self.roster.auto_subscribe
@auto_subscribe.setter @auto_subscribe.setter
def auto_subscribe(self, value): def auto_subscribe(self, value):
"""
Auto send requests for mutual subscriptions.
If True, auto send mutual subscription requests.
"""
self.roster.auto_subscribe = value self.roster.auto_subscribe = value
def set_jid(self, jid): def set_jid(self, jid):
@ -713,17 +684,16 @@ class BaseXMPP(XMLStream):
self.roster[pto][pfrom].handle_unavailable(presence) self.roster[pto][pfrom].handle_unavailable(presence)
def _handle_new_subscription(self, stanza): def _handle_new_subscription(self, stanza):
""" """Attempt to automatically handle subscription requests.
Attempt to automatically handle subscription requests.
Subscriptions will be approved if the request is from Subscriptions will be approved if the request is from
a whitelisted JID, of self.auto_authorize is True. They a whitelisted JID, of :attr:`auto_authorize` is True. They
will be rejected if self.auto_authorize is False. Setting will be rejected if :attr:`auto_authorize` is False. Setting
self.auto_authorize to None will disable automatic :attr:`auto_authorize` to ``None`` will disable automatic
subscription handling (except for whitelisted JIDs). subscription handling (except for whitelisted JIDs).
If a subscription is accepted, a request for a mutual If a subscription is accepted, a request for a mutual
subscription will be sent if self.auto_subscribe is True. subscription will be sent if :attr:`auto_subscribe` is ``True``.
""" """
roster = self.roster[stanza['to'].bare] roster = self.roster[stanza['to'].bare]
item = self.roster[stanza['to'].bare][stanza['from'].bare] item = self.roster[stanza['to'].bare][stanza['from'].bare]
@ -762,8 +732,7 @@ class BaseXMPP(XMLStream):
self.roster[pto][pfrom].handle_unsubscribed(presence) self.roster[pto][pfrom].handle_unsubscribed(presence)
def _handle_presence(self, presence): def _handle_presence(self, presence):
""" """Process incoming presence stanzas.
Process incoming presence stanzas.
Update the roster with presence information. Update the roster with presence information.
""" """
@ -779,14 +748,11 @@ class BaseXMPP(XMLStream):
return return
def exception(self, exception): def exception(self, exception):
""" """Process any uncaught exceptions, notably
Process any uncaught exceptions, notably IqError and :class:`~sleekxmpp.exceptions.IqError` and
IqTimeout exceptions. :class:`~sleekxmpp.exceptions.IqTimeout` exceptions.
Overrides XMLStream.exception. :param exception: An unhandled :class:`Exception` object.
Arguments:
exception -- An unhandled exception object.
""" """
if isinstance(exception, IqError): if isinstance(exception, IqError):
iq = exception.iq iq = exception.iq

60
sleekxmpp/exceptions.py
View file

@ -1,9 +1,12 @@
# -*- coding: utf-8 -*-
""" """
SleekXMPP: The Sleek XMPP Library sleekxmpp.exceptions
Copyright (C) 2010 Nathanael C. Fritz ~~~~~~~~~~~~~~~~~~~~
This file is part of SleekXMPP.
See the file LICENSE for copying permission. Part of SleekXMPP: The Sleek XMPP Library
:copyright: (c) 2011 Nathanael C. Fritz
:license: MIT, see LICENSE for more details
""" """
@ -13,37 +16,35 @@ class XMPPError(Exception):
A generic exception that may be raised while processing an XMPP stanza A generic exception that may be raised while processing an XMPP stanza
to indicate that an error response stanza should be sent. to indicate that an error response stanza should be sent.
The exception method for stanza objects extending RootStanza will create The exception method for stanza objects extending
an error stanza and initialize any additional substanzas using the :class:`~sleekxmpp.stanza.rootstanza.RootStanza` will create an error
extension information included in the exception. stanza and initialize any additional substanzas using the extension
information included in the exception.
Meant for use in SleekXMPP plugins and applications using SleekXMPP. Meant for use in SleekXMPP plugins and applications using SleekXMPP.
Extension information can be included to add additional XML elements
to the generated error stanza.
:param condition: The XMPP defined error condition.
Defaults to ``'undefined-condition'``.
:param text: Human readable text describing the error.
:param etype: The XMPP error type, such as ``'cancel'`` or ``'modify'``.
Defaults to ``'cancel'``.
:param extension: Tag name of the extension's XML content.
:param extension_ns: XML namespace of the extensions' XML content.
:param extension_args: Content and attributes for the extension
element. Same as the additional arguments to
the :class:`~xml.etree.ElementTree.Element`
constructor.
:param clear: Indicates if the stanza's contents should be
removed before replying with an error.
Defaults to ``True``.
""" """
def __init__(self, condition='undefined-condition', text=None, def __init__(self, condition='undefined-condition', text=None,
etype='cancel', extension=None, extension_ns=None, etype='cancel', extension=None, extension_ns=None,
extension_args=None, clear=True): extension_args=None, clear=True):
"""
Create a new XMPPError exception.
Extension information can be included to add additional XML elements
to the generated error stanza.
Arguments:
condition -- The XMPP defined error condition.
Defaults to 'undefined-condition'.
text -- Human readable text describing the error.
etype -- The XMPP error type, such as cancel or modify.
Defaults to 'cancel'.
extension -- Tag name of the extension's XML content.
extension_ns -- XML namespace of the extensions' XML content.
extension_args -- Content and attributes for the extension
element. Same as the additional arguments to
the ET.Element constructor.
clear -- Indicates if the stanza's contents should be
removed before replying with an error.
Defaults to True.
"""
if extension_args is None: if extension_args is None:
extension_args = {} extension_args = {}
@ -68,6 +69,8 @@ class IqTimeout(XMPPError):
condition='remote-server-timeout', condition='remote-server-timeout',
etype='cancel') etype='cancel')
#: The :class:`~sleekxmpp.stanza.iq.Iq` stanza whose response
#: did not arrive before the timeout expired.
self.iq = iq self.iq = iq
class IqError(XMPPError): class IqError(XMPPError):
@ -83,4 +86,5 @@ class IqError(XMPPError):
text=iq['error']['text'], text=iq['error']['text'],
etype=iq['error']['type']) etype=iq['error']['type'])
#: The :class:`~sleekxmpp.stanza.iq.Iq` error result stanza.
self.iq = iq self.iq = iq