From 2586fdffda9dac5ee56664c74e71bd54ae47ee18 Mon Sep 17 00:00:00 2001 From: Lance Stout Date: Sun, 4 Dec 2011 16:26:14 -0800 Subject: [PATCH] Update api docs for handlers and matchers --- docs/api/xmlstream/handler.rst | 24 +++++++ docs/api/{ => xmlstream}/jid.rst | 0 docs/api/xmlstream/matcher.rst | 41 +++++++++++ docs/index.rst | 4 +- sleekxmpp/xmlstream/handler/base.py | 83 ++++++++++------------- sleekxmpp/xmlstream/handler/callback.py | 80 ++++++++++------------ sleekxmpp/xmlstream/handler/waiter.py | 76 ++++++++------------- sleekxmpp/xmlstream/matcher/base.py | 23 +++---- sleekxmpp/xmlstream/matcher/id.py | 25 +++---- sleekxmpp/xmlstream/matcher/stanzapath.py | 28 ++++---- sleekxmpp/xmlstream/matcher/xpath.py | 43 +++++++----- 11 files changed, 225 insertions(+), 202 deletions(-) create mode 100644 docs/api/xmlstream/handler.rst rename docs/api/{ => xmlstream}/jid.rst (100%) create mode 100644 docs/api/xmlstream/matcher.rst diff --git a/docs/api/xmlstream/handler.rst b/docs/api/xmlstream/handler.rst new file mode 100644 index 0000000..33c0bf4 --- /dev/null +++ b/docs/api/xmlstream/handler.rst @@ -0,0 +1,24 @@ +Stanza Handlers +=============== + +The Basic Handler +----------------- +.. module:: sleekxmpp.xmlstream.handler.base + +.. autoclass:: BaseHandler + :members: + +Callback +-------- +.. module:: sleekxmpp.xmlstream.handler.callback + +.. autoclass:: Callback + :members: + + +Waiter +------ +.. module:: sleekxmpp.xmlstream.handler.waiter + +.. autoclass:: Waiter + :members: diff --git a/docs/api/jid.rst b/docs/api/xmlstream/jid.rst similarity index 100% rename from docs/api/jid.rst rename to docs/api/xmlstream/jid.rst diff --git a/docs/api/xmlstream/matcher.rst b/docs/api/xmlstream/matcher.rst new file mode 100644 index 0000000..df3591b --- /dev/null +++ b/docs/api/xmlstream/matcher.rst @@ -0,0 +1,41 @@ +Stanza Matchers +=============== + +The Basic Matcher +----------------- +.. module:: sleekxmpp.xmlstream.matcher.base + +.. autoclass:: MatcherBase + :members: + + +ID Matching +----------- +.. module:: sleekxmpp.xmlstream.matcher.id + +.. autoclass:: MatcherId + :members: + + +Stanza Path Matching +-------------------- +.. module:: sleekxmpp.xmlstream.matcher.stanzapath + +.. autoclass:: StanzaPath + :members: + + +XPath +----- +.. module:: sleekxmpp.xmlstream.matcher.xpath + +.. autoclass:: MatchXPath + :members: + + +XMLMask +------- +.. module:: sleekxmpp.xmlstream.matcher.xmlmask + +.. autoclass:: MatchXMLMask + :members: diff --git a/docs/index.rst b/docs/index.rst index 76c3741..5d2577d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -112,8 +112,10 @@ API Reference api/clientxmpp api/componentxmpp api/basexmpp - api/jid + api/xmlstream/jid api/xmlstream/stanzabase + api/xmlstream/handler + api/xmlstream/matcher api/xmlstream/tostring api/xmlstream/filesocket diff --git a/sleekxmpp/xmlstream/handler/base.py b/sleekxmpp/xmlstream/handler/base.py index 7f05c75..59dcb30 100644 --- a/sleekxmpp/xmlstream/handler/base.py +++ b/sleekxmpp/xmlstream/handler/base.py @@ -1,9 +1,12 @@ +# -*- coding: utf-8 -*- """ - SleekXMPP: The Sleek XMPP Library - Copyright (C) 2010 Nathanael C. Fritz - This file is part of SleekXMPP. + sleekxmpp.xmlstream.handler.base + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 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 """ import weakref @@ -16,78 +19,62 @@ class BaseHandler(object): incoming stanzas so that the stanza may be processed in some way. Stanzas may be matched with multiple handlers. - Handler execution may take place in two phases. The first is during - the stream processing itself. The second is after stream processing - and during SleekXMPP's main event loop. The prerun method is used - for execution during stream processing, and the run method is used - during the main event loop. + Handler execution may take place in two phases: during the incoming + stream processing, and in the main event loop. The :meth:`prerun()` + method is executed in the first case, and :meth:`run()` is called + during the second. - Attributes: - name -- The name of the handler. - stream -- The stream this handler is assigned to. - - Methods: - match -- Compare a stanza with the handler's matcher. - prerun -- Handler execution during stream processing. - run -- Handler execution during the main event loop. - check_delete -- Indicate if the handler may be removed from use. + :param string name: The name of the handler. + :param matcher: A :class:`~sleekxmpp.xmlstream.matcher.base.MatcherBase` + derived object that will be used to determine if a + stanza should be accepted by this handler. + :param stream: The :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream` + instance that the handle will respond to. """ def __init__(self, name, matcher, stream=None): - """ - Create a new stream handler. - - Arguments: - name -- The name of the handler. - matcher -- A matcher object from xmlstream.matcher that will be - used to determine if a stanza should be accepted by - this handler. - stream -- The XMLStream instance the handler should monitor. - """ + #: The name of the handler self.name = name + + #: The XML stream this handler is assigned to + self.stream = None if stream is not None: self.stream = weakref.ref(stream) - else: - self.stream = None + stream.register_handler(self) + self._destroy = False self._payload = None self._matcher = matcher - if stream is not None: - stream.registerHandler(self) def match(self, xml): - """ - Compare a stanza or XML object with the handler's matcher. + """Compare a stanza or XML object with the handler's matcher. - Arguments - xml -- An XML or stanza object. + :param xml: An XML or + :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object """ return self._matcher.match(xml) def prerun(self, payload): - """ - Prepare the handler for execution while the XML stream is being - processed. + """Prepare the handler for execution while the XML + stream is being processed. - Arguments: - payload -- A stanza object. + :param payload: A :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` + object. """ self._payload = payload def run(self, payload): - """ - Execute the handler after XML stream processing and during the + """Execute the handler after XML stream processing and during the main event loop. - Arguments: - payload -- A stanza object. + :param payload: A :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` + object. """ self._payload = payload def check_delete(self): - """ - Check if the handler should be removed from the list of stream - handlers. + """Check if the handler should be removed from the list + of stream handlers. """ return self._destroy diff --git a/sleekxmpp/xmlstream/handler/callback.py b/sleekxmpp/xmlstream/handler/callback.py index 7fadab4..37f5333 100644 --- a/sleekxmpp/xmlstream/handler/callback.py +++ b/sleekxmpp/xmlstream/handler/callback.py @@ -1,9 +1,12 @@ +# -*- coding: utf-8 -*- """ - SleekXMPP: The Sleek XMPP Library - Copyright (C) 2010 Nathanael C. Fritz - This file is part of SleekXMPP. + sleekxmpp.xmlstream.handler.callback + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 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 """ from sleekxmpp.xmlstream.handler.base import BaseHandler @@ -18,48 +21,42 @@ class Callback(BaseHandler): The handler may execute the callback either during stream processing or during the main event loop. - Callback functions are all executed in the same thread, so be - aware if you are executing functions that will block for extended - periods of time. Typically, you should signal your own events using the - SleekXMPP object's event() method to pass the stanza off to a threaded - event handler for further processing. + Callback functions are all executed in the same thread, so be aware if + you are executing functions that will block for extended periods of + time. Typically, you should signal your own events using the SleekXMPP + object's :meth:`~sleekxmpp.xmlstream.xmlstream.XMLStream.event()` + method to pass the stanza off to a threaded event handler for further + processing. - Methods: - prerun -- Overrides BaseHandler.prerun - run -- Overrides BaseHandler.run + + :param string name: The name of the handler. + :param matcher: A :class:`~sleekxmpp.xmlstream.matcher.base.MatcherBase` + derived object for matching stanza objects. + :param pointer: The function to execute during callback. + :param bool thread: **DEPRECATED.** Remains only for + backwards compatibility. + :param bool once: Indicates if the handler should be used only + once. Defaults to False. + :param bool instream: Indicates if the callback should be executed + during stream processing instead of in the + main event loop. + :param stream: The :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream` + instance this handler should monitor. """ def __init__(self, name, matcher, pointer, thread=False, once=False, instream=False, stream=None): - """ - Create a new callback handler. - - Arguments: - name -- The name of the handler. - matcher -- A matcher object for matching stanza objects. - pointer -- The function to execute during callback. - thread -- DEPRECATED. Remains only for backwards compatibility. - once -- Indicates if the handler should be used only - once. Defaults to False. - instream -- Indicates if the callback should be executed - during stream processing instead of in the - main event loop. - stream -- The XMLStream instance this handler should monitor. - """ BaseHandler.__init__(self, name, matcher, stream) self._pointer = pointer self._once = once self._instream = instream def prerun(self, payload): - """ - Execute the callback during stream processing, if - the callback was created with instream=True. + """Execute the callback during stream processing, if + the callback was created with ``instream=True``. - Overrides BaseHandler.prerun - - Arguments: - payload -- The matched stanza object. + :param payload: The matched + :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object. """ if self._once: self._destroy = True @@ -67,16 +64,13 @@ class Callback(BaseHandler): self.run(payload, True) def run(self, payload, instream=False): - """ - Execute the callback function with the matched stanza payload. + """Execute the callback function with the matched stanza payload. - Overrides BaseHandler.run - - Arguments: - payload -- The matched stanza object. - instream -- Force the handler to execute during - stream processing. Used only by prerun. - Defaults to False. + :param payload: The matched + :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object. + :param bool instream: Force the handler to execute during stream + processing. This should only be used by + :meth:`prerun()`. Defaults to ``False``. """ if not self._instream or instream: self._pointer(payload) diff --git a/sleekxmpp/xmlstream/handler/waiter.py b/sleekxmpp/xmlstream/handler/waiter.py index a64b6a9..01ff5d6 100644 --- a/sleekxmpp/xmlstream/handler/waiter.py +++ b/sleekxmpp/xmlstream/handler/waiter.py @@ -1,9 +1,12 @@ +# -*- coding: utf-8 -*- """ - SleekXMPP: The Sleek XMPP Library - Copyright (C) 2010 Nathanael C. Fritz - This file is part of SleekXMPP. + sleekxmpp.xmlstream.handler.waiter + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 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 """ import logging @@ -22,67 +25,46 @@ log = logging.getLogger(__name__) class Waiter(BaseHandler): """ - The Waiter handler allows an event handler to block - until a particular stanza has been received. The handler - will either be given the matched stanza, or False if the - waiter has timed out. + The Waiter handler allows an event handler to block until a + particular stanza has been received. The handler will either be + given the matched stanza, or ``False`` if the waiter has timed out. - Methods: - check_delete -- Overrides BaseHandler.check_delete - prerun -- Overrides BaseHandler.prerun - run -- Overrides BaseHandler.run - wait -- Wait for a stanza to arrive and return it to - an event handler. + :param string name: The name of the handler. + :param matcher: A :class:`~sleekxmpp.xmlstream.matcher.base.MatcherBase` + derived object for matching stanza objects. + :param stream: The :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream` + instance this handler should monitor. """ def __init__(self, name, matcher, stream=None): - """ - Create a new Waiter. - - Arguments: - name -- The name of the waiter. - matcher -- A matcher object to detect the desired stanza. - stream -- Optional XMLStream instance to monitor. - """ BaseHandler.__init__(self, name, matcher, stream=stream) self._payload = queue.Queue() def prerun(self, payload): - """ - Store the matched stanza. + """Store the matched stanza when received during processing. - Overrides BaseHandler.prerun - - Arguments: - payload -- The matched stanza object. + :param payload: The matched + :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object. """ self._payload.put(payload) def run(self, payload): - """ - Do not process this handler during the main event loop. - - Overrides BaseHandler.run - - Arguments: - payload -- The matched stanza object. - """ + """Do not process this handler during the main event loop.""" pass def wait(self, timeout=None): - """ - Block an event handler while waiting for a stanza to arrive. + """Block an event handler while waiting for a stanza to arrive. Be aware that this will impact performance if called from a non-threaded event handler. - Will return either the received stanza, or False if the waiter - timed out. + Will return either the received stanza, or ``False`` if the + waiter timed out. - Arguments: - timeout -- The number of seconds to wait for the stanza to - arrive. Defaults to the global default timeout - value sleekxmpp.xmlstream.RESPONSE_TIMEOUT. + :param int timeout: The number of seconds to wait for the stanza + to arrive. Defaults to the the stream's + :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream.response_timeout` + value. """ if timeout is None: timeout = self.stream().response_timeout @@ -101,9 +83,5 @@ class Waiter(BaseHandler): return stanza def check_delete(self): - """ - Always remove waiters after use. - - Overrides BaseHandler.check_delete - """ + """Always remove waiters after use.""" return True diff --git a/sleekxmpp/xmlstream/matcher/base.py b/sleekxmpp/xmlstream/matcher/base.py index 701ab32..83c2668 100644 --- a/sleekxmpp/xmlstream/matcher/base.py +++ b/sleekxmpp/xmlstream/matcher/base.py @@ -1,9 +1,12 @@ +# -*- coding: utf-8 -*- """ - SleekXMPP: The Sleek XMPP Library - Copyright (C) 2010 Nathanael C. Fritz - This file is part of SleekXMPP. + sleekxmpp.xmlstream.matcher.base + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 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,21 +16,15 @@ class MatcherBase(object): Base class for stanza matchers. Stanza matchers are used to pick stanzas out of the XML stream and pass them to the appropriate stream handlers. + + :param criteria: Object to compare some aspect of a stanza against. """ def __init__(self, criteria): - """ - Create a new stanza matcher. - - Arguments: - criteria -- Object to compare some aspect of a stanza - against. - """ self._criteria = criteria def match(self, xml): - """ - Check if a stanza matches the stored criteria. + """Check if a stanza matches the stored criteria. Meant to be overridden. """ diff --git a/sleekxmpp/xmlstream/matcher/id.py b/sleekxmpp/xmlstream/matcher/id.py index 0c8ce2d..11ab70b 100644 --- a/sleekxmpp/xmlstream/matcher/id.py +++ b/sleekxmpp/xmlstream/matcher/id.py @@ -1,9 +1,12 @@ +# -*- coding: utf-8 -*- """ - SleekXMPP: The Sleek XMPP Library - Copyright (C) 2010 Nathanael C. Fritz - This file is part of SleekXMPP. + sleekxmpp.xmlstream.matcher.id + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 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 """ from sleekxmpp.xmlstream.matcher.base import MatcherBase @@ -14,19 +17,13 @@ class MatcherId(MatcherBase): """ The ID matcher selects stanzas that have the same stanza 'id' interface value as the desired ID. - - Methods: - match -- Overrides MatcherBase.match. """ def match(self, xml): - """ - Compare the given stanza's 'id' attribute to the stored - id value. + """Compare the given stanza's ``'id'`` attribute to the stored + ``id`` value. - Overrides MatcherBase.match. - - Arguments: - xml -- The stanza to compare against. + :param xml: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` + stanza to compare against. """ return xml['id'] == self._criteria diff --git a/sleekxmpp/xmlstream/matcher/stanzapath.py b/sleekxmpp/xmlstream/matcher/stanzapath.py index f8ff283..61c5332 100644 --- a/sleekxmpp/xmlstream/matcher/stanzapath.py +++ b/sleekxmpp/xmlstream/matcher/stanzapath.py @@ -1,9 +1,12 @@ +# -*- coding: utf-8 -*- """ - SleekXMPP: The Sleek XMPP Library - Copyright (C) 2010 Nathanael C. Fritz - This file is part of SleekXMPP. + sleekxmpp.xmlstream.matcher.stanzapath + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 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 """ from sleekxmpp.xmlstream.matcher.base import MatcherBase @@ -15,24 +18,17 @@ class StanzaPath(MatcherBase): The StanzaPath matcher selects stanzas that match a given "stanza path", which is similar to a normal XPath except that it uses the interfaces and plugins of the stanza instead of the actual, underlying XML. - - In most cases, the stanza path and XPath should be identical, but be - aware that differences may occur. - - Methods: - match -- Overrides MatcherBase.match. """ def match(self, stanza): """ Compare a stanza against a "stanza path". A stanza path is similar to an XPath expression, but uses the stanza's interfaces and plugins - instead of the underlying XML. For most cases, the stanza path and - XPath should be identical, but be aware that differences may occur. + instead of the underlying XML. See the documentation for the stanza + :meth:`~sleekxmpp.xmlstream.stanzabase.ElementBase.match()` method + for more information. - Overrides MatcherBase.match. - - Arguments: - stanza -- The stanza object to compare against. + :param stanza: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` + stanza to compare against. """ return stanza.match(self._criteria) diff --git a/sleekxmpp/xmlstream/matcher/xpath.py b/sleekxmpp/xmlstream/matcher/xpath.py index 669c9f1..b6af060 100644 --- a/sleekxmpp/xmlstream/matcher/xpath.py +++ b/sleekxmpp/xmlstream/matcher/xpath.py @@ -1,9 +1,12 @@ +# -*- coding: utf-8 -*- """ - SleekXMPP: The Sleek XMPP Library - Copyright (C) 2010 Nathanael C. Fritz - This file is part of SleekXMPP. + sleekxmpp.xmlstream.matcher.xpath + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 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 """ from sleekxmpp.xmlstream.stanzabase import ET @@ -22,30 +25,34 @@ class MatchXPath(MatcherBase): The XPath matcher selects stanzas whose XML contents matches a given XPath expression. - Note that using this matcher may not produce expected behavior when using - attribute selectors. For Python 2.6 and 3.1, the ElementTree find method - does not support the use of attribute selectors. If you need to support - Python 2.6 or 3.1, it might be more useful to use a StanzaPath matcher. + .. warning:: - If the value of IGNORE_NS is set to true, then XPath expressions will - be matched without using namespaces. + Using this matcher may not produce expected behavior when using + attribute selectors. For Python 2.6 and 3.1, the ElementTree + :meth:`~xml.etree.ElementTree.Element.find()` method does + not support the use of attribute selectors. If you need to + support Python 2.6 or 3.1, it might be more useful to use a + :class:`~sleekxmpp.xmlstream.matcher.stanzapath.StanzaPath` matcher. - Methods: - match -- Overrides MatcherBase.match. + If the value of :data:`IGNORE_NS` is set to ``True``, then XPath + expressions will be matched without using namespaces. """ def match(self, xml): """ Compare a stanza's XML contents to an XPath expression. - If the value of IGNORE_NS is set to true, then XPath expressions - will be matched without using namespaces. + If the value of :data:`IGNORE_NS` is set to ``True``, then XPath + expressions will be matched without using namespaces. - Note that in Python 2.6 and 3.1 the ElementTree find method does - not support attribute selectors in the XPath expression. + .. warning:: - Arguments: - xml -- The stanza object to compare against. + In Python 2.6 and 3.1 the ElementTree + :meth:`~xml.etree.ElementTree.Element.find()` method does not + support attribute selectors in the XPath expression. + + :param xml: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` + stanza to compare against. """ if hasattr(xml, 'xml'): xml = xml.xml