summaryrefslogtreecommitdiff
path: root/sleekxmpp
diff options
context:
space:
mode:
Diffstat (limited to 'sleekxmpp')
-rw-r--r--sleekxmpp/clientxmpp.py193
-rw-r--r--sleekxmpp/componentxmpp.py103
2 files changed, 147 insertions, 149 deletions
diff --git a/sleekxmpp/clientxmpp.py b/sleekxmpp/clientxmpp.py
index 3778ccf6..20012b5f 100644
--- a/sleekxmpp/clientxmpp.py
+++ b/sleekxmpp/clientxmpp.py
@@ -1,9 +1,15 @@
+# -*- coding: utf-8 -*-
"""
- SleekXMPP: The Sleek XMPP Library
- Copyright (C) 2010 Nathanael C. Fritz
- This file is part of SleekXMPP.
+ sleekxmpp.clientxmpp
+ ~~~~~~~~~~~~~~~~~~~~
- See the file LICENSE for copying permission.
+ This module provides XMPP functionality that
+ is specific to client connections.
+
+ Part of SleekXMPP: The Sleek XMPP Library
+
+ :copyright: (c) 2011 Nathanael C. Fritz
+ :license: MIT, see LICENSE for more details
"""
from __future__ import absolute_import, unicode_literals
@@ -41,37 +47,30 @@ log = logging.getLogger(__name__)
class ClientXMPP(BaseXMPP):
"""
- SleekXMPP's client class. ( Use only for good, not for evil.)
-
- Typical Use:
- xmpp = ClientXMPP('user@server.tld/resource', 'password')
- xmpp.process(block=False) // when block is True, it blocks the current
- // thread. False by default.
-
- Attributes:
-
- Methods:
- connect -- Overrides XMLStream.connect.
- del_roster_item -- Delete a roster item.
- get_roster -- Retrieve the roster from the server.
- register_feature -- Register a stream feature.
- update_roster -- Update a roster item.
+ SleekXMPP's client class. (Use only for good, not for evil.)
+
+ Typical use pattern:
+
+ .. code-block:: python
+
+ xmpp = ClientXMPP('user@server.tld/resource', 'password')
+ # ... Register plugins and event handlers ...
+ xmpp.connect()
+ xmpp.process(block=False) # block=True will block the current
+ # thread. By default, block=False
+
+ :param jid: The JID of the XMPP user account.
+ :param password: The password for the XMPP user account.
+ :param ssl: **Deprecated.**
+ :param plugin_config: A dictionary of plugin configurations.
+ :param plugin_whitelist: A list of approved plugins that
+ will be loaded when calling
+ :meth:`~sleekxmpp.basexmpp.BaseXMPP.register_plugins()`.
+ :param escape_quotes: **Deprecated.**
"""
def __init__(self, jid, password, ssl=False, plugin_config={},
plugin_whitelist=[], escape_quotes=True, sasl_mech=None):
- """
- Create a new SleekXMPP client.
-
- Arguments:
- jid -- The JID of the XMPP user account.
- password -- The password for the XMPP user account.
- ssl -- Deprecated.
- plugin_config -- A dictionary of plugin configurations.
- plugin_whitelist -- A list of approved plugins that will be loaded
- when calling register_plugins.
- escape_quotes -- Deprecated.
- """
BaseXMPP.__init__(self, jid, 'jabber:client')
self.set_jid(jid)
@@ -121,21 +120,19 @@ class ClientXMPP(BaseXMPP):
def connect(self, address=tuple(), reattempt=True,
use_tls=True, use_ssl=False):
- """
- Connect to the XMPP server.
+ """Connect to the XMPP server.
When no address is given, a SRV lookup for the server will
be attempted. If that fails, the server user in the JID
will be used.
- Arguments:
- address -- A tuple containing the server's host and port.
- reattempt -- If True, reattempt the connection if an
- error occurs. Defaults to True.
- use_tls -- Indicates if TLS should be used for the
- connection. Defaults to True.
- use_ssl -- Indicates if the older SSL connection method
- should be used. Defaults to False.
+ :param address -- A tuple containing the server's host and port.
+ :param reattempt: If ``True``, repeat attempting to connect if an
+ error occurs. Defaults to ``True``.
+ :param use_tls: Indicates if TLS should be used for the
+ connection. Defaults to ``True``.
+ :param use_ssl: Indicates if the older SSL connection method
+ should be used. Defaults to ``False``.
"""
self.session_started_event.clear()
if not address:
@@ -146,13 +143,10 @@ class ClientXMPP(BaseXMPP):
reattempt=reattempt)
def get_dns_records(self, domain, port=None):
- """
- Get the DNS records for a domain.
- Overriddes XMLStream.get_dns_records to use SRV.
+ """Get the DNS records for a domain, including SRV records.
- Arguments:
- domain -- The domain in question.
- port -- If the results don't include a port, use this one.
+ :param domain: The domain in question.
+ :param port: If the results don't include a port, use this one.
"""
if port is None:
port = self.default_port
@@ -177,17 +171,15 @@ class ClientXMPP(BaseXMPP):
return [((domain, port), 0, 0)]
def register_feature(self, name, handler, restart=False, order=5000):
- """
- Register a stream feature.
-
- Arguments:
- name -- The name of the stream feature.
- handler -- The function to execute if the feature is received.
- restart -- Indicates if feature processing should halt with
- this feature. Defaults to False.
- order -- The relative ordering in which the feature should
- be negotiated. Lower values will be attempted
- earlier when available.
+ """Register a stream feature handler.
+
+ :param name: The name of the stream feature.
+ :param handler: The function to execute if the feature is received.
+ :param restart: Indicates if feature processing should halt with
+ this feature. Defaults to ``False``.
+ :param order: The relative ordering in which the feature should
+ be negotiated. Lower values will be attempted
+ earlier when available.
"""
self._stream_feature_handlers[name] = (handler, restart)
self._stream_feature_order.append((order, name))
@@ -195,53 +187,51 @@ class ClientXMPP(BaseXMPP):
def update_roster(self, jid, name=None, subscription=None, groups=[],
block=True, timeout=None, callback=None):
- """
- Add or change a roster item.
-
- Arguments:
- jid -- The JID of the entry to modify.
- name -- The user's nickname for this JID.
- subscription -- The subscription status. May be one of
- 'to', 'from', 'both', or 'none'. If set
- to 'remove', the entry will be deleted.
- groups -- The roster groups that contain this item.
- block -- Specify if the roster request will block
- until a response is received, or a timeout
- occurs. Defaults to True.
- timeout -- The length of time (in seconds) to wait
- for a response before continuing if blocking
- is used. Defaults to self.response_timeout.
- callback -- Optional reference to a stream handler function.
- Will be executed when the roster is received.
- Implies block=False.
+ """Add or change a roster item.
+
+ :param jid: The JID of the entry to modify.
+ :param name: The user's nickname for this JID.
+ :param subscription: The subscription status. May be one of
+ ``'to'``, ``'from'``, ``'both'``, or
+ ``'none'``. If set to ``'remove'``,
+ the entry will be deleted.
+ :param groups: The roster groups that contain this item.
+ :param block: Specify if the roster request will block
+ until a response is received, or a timeout
+ occurs. Defaults to ``True``.
+ :param timeout: The length of time (in seconds) to wait
+ for a response before continuing if blocking
+ is used. Defaults to
+ :attr:`~sleekxmpp.xmlstream.xmlstream.XMLStream.response_timeout`.
+ :param callback: Optional reference to a stream handler function.
+ Will be executed when the roster is received.
+ Implies ``block=False``.
"""
return self.client_roster.update(jid, name, subscription, groups,
block, timeout, callback)
def del_roster_item(self, jid):
- """
- Remove an item from the roster by setting its subscription
- status to 'remove'.
+ """Remove an item from the roster.
+
+ This is done by setting its subscription status to ``'remove'``.
- Arguments:
- jid -- The JID of the item to remove.
+ :param jid: The JID of the item to remove.
"""
return self.client_roster.remove(jid)
def get_roster(self, block=True, timeout=None, callback=None):
- """
- Request the roster from the server.
+ """Request the roster from the server.
- Arguments:
- block -- Specify if the roster request will block until a
- response is received, or a timeout occurs.
- Defaults to True.
- timeout -- The length of time (in seconds) to wait for a response
+ :param block: Specify if the roster request will block until a
+ response is received, or a timeout occurs.
+ Defaults to ``True``.
+ :param timeout: The length of time (in seconds) to wait for a response
before continuing if blocking is used.
- Defaults to self.response_timeout.
- callback -- Optional reference to a stream handler function. Will
- be executed when the roster is received.
- Implies block=False.
+ Defaults to
+ :attr:`~sleekxmpp.xmlstream.xmlstream.XMLStream.response_timeout`.
+ :param callback: Optional reference to a stream handler function. Will
+ be executed when the roster is received.
+ Implies ``block=False``.
"""
iq = self.Iq()
iq['type'] = 'get'
@@ -260,11 +250,9 @@ class ClientXMPP(BaseXMPP):
self.features = set()
def _handle_stream_features(self, features):
- """
- Process the received stream features.
+ """Process the received stream features.
- Arguments:
- features -- The features stanza.
+ :param features: The features stanza.
"""
for order, name in self._stream_feature_order:
if name in features['features']:
@@ -275,13 +263,12 @@ class ClientXMPP(BaseXMPP):
return True
def _handle_roster(self, iq, request=False):
- """
- Update the roster after receiving a roster stanza.
+ """Update the roster after receiving a roster stanza.
- Arguments:
- iq -- The roster stanza.
- request -- Indicates if this stanza is a response
- to a request for the roster.
+ :param iq: The roster stanza.
+ :param request: Indicates if this stanza is a response
+ to a request for the roster, and not an
+ empty acknowledgement from the server.
"""
if iq['type'] == 'set' or (iq['type'] == 'result' and request):
for jid in iq['roster']['items']:
diff --git a/sleekxmpp/componentxmpp.py b/sleekxmpp/componentxmpp.py
index e98ad50e..5b16c5ef 100644
--- a/sleekxmpp/componentxmpp.py
+++ b/sleekxmpp/componentxmpp.py
@@ -1,9 +1,15 @@
+# -*- coding: utf-8 -*-
"""
- SleekXMPP: The Sleek XMPP Library
- Copyright (C) 2010 Nathanael C. Fritz
- This file is part of SleekXMPP.
+ sleekxmpp.clientxmpp
+ ~~~~~~~~~~~~~~~~~~~~
- See the file LICENSE for copying permission.
+ This module provides XMPP functionality that
+ is specific to external server component connections.
+
+ Part of SleekXMPP: The Sleek XMPP Library
+
+ :copyright: (c) 2011 Nathanael C. Fritz
+ :license: MIT, see LICENSE for more details
"""
from __future__ import absolute_import
@@ -32,28 +38,22 @@ class ComponentXMPP(BaseXMPP):
Use only for good, not for evil.
- Methods:
- connect -- Overrides XMLStream.connect.
- incoming_filter -- Overrides XMLStream.incoming_filter.
- start_stream_handler -- Overrides XMLStream.start_stream_handler.
+ :param jid: The JID of the component.
+ :param secret: The secret or password for the component.
+ :param host: The server accepting the component.
+ :param port: The port used to connect to the server.
+ :param plugin_config: A dictionary of plugin configurations.
+ :param plugin_whitelist: A list of approved plugins that
+ will be loaded when calling
+ :meth:`~sleekxmpp.basexmpp.BaseXMPP.register_plugins()`.
+ :param use_jc_ns: Indicates if the ``'jabber:client'`` namespace
+ should be used instead of the standard
+ ``'jabber:component:accept'`` namespace.
+ Defaults to ``False``.
"""
- def __init__(self, jid, secret, host, port,
+ def __init__(self, jid, secret, host=None, port=None,
plugin_config={}, plugin_whitelist=[], use_jc_ns=False):
- """
- Arguments:
- jid -- The JID of the component.
- secret -- The secret or password for the component.
- host -- The server accepting the component.
- port -- The port used to connect to the server.
- plugin_config -- A dictionary of plugin configurations.
- plugin_whitelist -- A list of desired plugins to load
- when using register_plugins.
- use_js_ns -- Indicates if the 'jabber:client' namespace
- should be used instead of the standard
- 'jabber:component:accept' namespace.
- Defaults to False.
- """
if use_jc_ns:
default_ns = 'jabber:client'
else:
@@ -81,26 +81,42 @@ class ComponentXMPP(BaseXMPP):
self.add_event_handler('presence_probe',
self._handle_probe)
- def connect(self):
+ def connect(self, host=None, port=None, use_ssl=False,
+ use_tls=True, reattempt=True):
+ """Connect to the server.
+
+ Setting ``reattempt`` to ``True`` will cause connection attempts to
+ be made every second until a successful connection is established.
+
+ :param host: The name of the desired server for the connection.
+ Defaults to :attr:`server_host`.
+ :param port: Port to connect to on the server.
+ Defauts to :attr:`server_port`.
+ :param use_ssl: Flag indicating if SSL should be used by connecting
+ directly to a port using SSL.
+ :param use_tls: Flag indicating if TLS should be used, allowing for
+ connecting to a port without using SSL immediately and
+ later upgrading the connection.
+ :param reattempt: Flag indicating if the socket should reconnect
+ after disconnections.
"""
- Connect to the server.
-
- Overrides XMLStream.connect.
- """
- log.debug("Connecting to %s:%s", self.server_host,
- self.server_port)
- return XMLStream.connect(self, self.server_host,
- self.server_port)
+ if host is None:
+ host = self.server_host
+ if port is None:
+ port = self.server_port
+ log.debug("Connecting to %s:%s", host, port)
+ return XMLStream.connect(self, host=host, port=port,
+ use_ssl=use_ssl,
+ use_tls=use_tls,
+ reattempt=reattempt)
def incoming_filter(self, xml):
"""
- Pre-process incoming XML stanzas by converting any 'jabber:client'
- namespaced elements to the component's default namespace.
-
- Overrides XMLStream.incoming_filter.
+ Pre-process incoming XML stanzas by converting any
+ ``'jabber:client'`` namespaced elements to the component's
+ default namespace.
- Arguments:
- xml -- The XML stanza to pre-process.
+ :param xml: The XML stanza to pre-process.
"""
if xml.tag.startswith('{jabber:client}'):
xml.tag = xml.tag.replace('jabber:client', self.default_ns)
@@ -117,10 +133,7 @@ class ComponentXMPP(BaseXMPP):
Once the streams are established, attempt to handshake
with the server to be accepted as a component.
- Overrides BaseXMPP.start_stream_handler.
-
- Arguments:
- xml -- The incoming stream's root element.
+ :param xml: The incoming stream's root element.
"""
BaseXMPP.start_stream_handler(self, xml)
@@ -136,11 +149,9 @@ class ComponentXMPP(BaseXMPP):
self.send_xml(handshake, now=True)
def _handle_handshake(self, xml):
- """
- The handshake has been accepted.
+ """The handshake has been accepted.
- Arguments:
- xml -- The reply handshake stanza.
+ :param xml: The reply handshake stanza.
"""
self.session_started_event.set()
self.event("session_start")