:orphan:

:py:mod:`slidge.slixfix.link_preview.stanza`
============================================

.. py:module:: slidge.slixfix.link_preview.stanza


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   slidge.slixfix.link_preview.stanza.LinkPreview
   slidge.slixfix.link_preview.stanza.OpenGraphMixin
   slidge.slixfix.link_preview.stanza.Title
   slidge.slixfix.link_preview.stanza.Description
   slidge.slixfix.link_preview.stanza.Url
   slidge.slixfix.link_preview.stanza.Image
   slidge.slixfix.link_preview.stanza.Type_
   slidge.slixfix.link_preview.stanza.SiteName




.. py:class:: LinkPreview(xml = None, parent = None)




   The core of Slixmpp's stanza XML manipulation and handling is provided
   by ElementBase. ElementBase wraps XML ElementTree objects and enables
   access to the XML contents through dictionary syntax, similar in style
   to the Ruby XMPP library Blather's stanza implementation.

   Stanzas are defined by their name, namespace, and interfaces. For
   example, a simplistic Message stanza could be defined as::

       >>> class Message(ElementBase):
       ...     name = "message"
       ...     namespace = "jabber:client"
       ...     interfaces = {'to', 'from', 'type', 'body'}
       ...     sub_interfaces = {'body'}

   The resulting Message stanza's contents may be accessed as so::

       >>> message['to'] = "user@example.com"
       >>> message['body'] = "Hi!"
       >>> message['body']
       "Hi!"
       >>> del message['body']
       >>> message['body']
       ""

   The interface values map to either custom access methods, stanza
   XML attributes, or (if the interface is also in sub_interfaces) the
   text contents of a stanza's subelement.

   Custom access methods may be created by adding methods of the
   form "getInterface", "setInterface", or "delInterface", where
   "Interface" is the titlecase version of the interface name.

   Stanzas may be extended through the use of plugins. A plugin
   is simply a stanza that has a plugin_attrib value. For example::

       >>> class MessagePlugin(ElementBase):
       ...     name = "custom_plugin"
       ...     namespace = "custom"
       ...     interfaces = {'useful_thing', 'custom'}
       ...     plugin_attrib = "custom"

   The plugin stanza class must be associated with its intended
   container stanza by using register_stanza_plugin as so::

       >>> register_stanza_plugin(Message, MessagePlugin)

   The plugin may then be accessed as if it were built-in to the parent
   stanza::

       >>> message['custom']['useful_thing'] = 'foo'

   If a plugin provides an interface that is the same as the plugin's
   plugin_attrib value, then the plugin's interface may be assigned
   directly from the parent stanza, as shown below, but retrieving
   information will require all interfaces to be used, as so::

       >>> # Same as using message['custom']['custom']
       >>> message['custom'] = 'bar'
       >>> # Must use all interfaces
       >>> message['custom']['custom']
       'bar'

   If the plugin sets :attr:`is_extension` to ``True``, then both setting
   and getting an interface value that is the same as the plugin's
   plugin_attrib value will work, as so::

       >>> message['custom'] = 'bar'  # Using is_extension=True
       >>> message['custom']
       'bar'


   :param xml: Initialize the stanza object with an existing XML object.
   :param parent: Optionally specify a parent stanza object will
                  contain this substanza.

   .. py:method:: setup(xml = None)

      Initialize the stanza's XML contents.

      Will return ``True`` if XML was generated according to the stanza's
      definition instead of building a stanza object from an existing
      XML object.

      :param xml: An existing XML object to use for the stanza's content
                  instead of generating new XML.


   .. py:method:: enable(attrib, lang = None)

      Enable and initialize a stanza plugin.

      Alias for :meth:`init_plugin`.

      :param string attrib: The :attr:`plugin_attrib` value of the
                            plugin to enable.


   .. py:method:: get_plugin(name, lang = None, check = False)

      Retrieve a stanza plugin.

      :param check: Return None instead of creating the object if True.
      :param name: Stanza plugin attribute name.
      :param lang: xml:lang of the element to retrieve.


   .. py:method:: init_plugin(attrib, lang = None, existing_xml = None, reuse = True, element = None)

      Enable and initialize a stanza plugin.

      :param string attrib: The :attr:`plugin_attrib` value of the
                            plugin to enable.


   .. py:method:: match(xpath)

      Compare a stanza object with an XPath-like expression.

      If the XPath matches the contents of the stanza object, the match
      is successful.

      The XPath expression may include checks for stanza attributes.
      For example::

          'presence@show=xa@priority=2/status'

      Would match a presence stanza whose show value is set to ``'xa'``,
      has a priority value of ``'2'``, and has a status element.

      :param string xpath: The XPath expression to check against. It
                           may be either a string or a list of element
                           names with attribute checks.


   .. py:method:: get(key, default = None)

      Return the value of a stanza interface.

      If the found value is None or an empty string, return the supplied
      default value.

      Allows stanza objects to be used like dictionaries.

      :param string key: The name of the stanza interface to check.
      :param default: Value to return if the stanza interface has a value
                      of ``None`` or ``""``. Will default to returning None.


   .. py:method:: keys()

      Return the names of all stanza interfaces provided by the
      stanza object.

      Allows stanza objects to be used like dictionaries.


   .. py:method:: append(item)

      Append either an XML object or a substanza to this stanza object.

      If a substanza object is appended, it will be added to the list
      of iterable stanzas.

      Allows stanza objects to be used like lists.

      :param item: Either an XML object or a stanza object to add to
                   this stanza's contents.


   .. py:method:: appendxml(xml)

      Append an XML object to the stanza's XML.

      The added XML will not be included in the list of
      iterable substanzas.

      :param XML xml: The XML object to add to the stanza.


   .. py:method:: pop(index = 0)

      Remove and return the last substanza in the list of
      iterable substanzas.

      Allows stanza objects to be used like lists.

      :param int index: The index of the substanza to remove.


   .. py:method:: next()

      Return the next iterable substanza.


   .. py:method:: clear()

      Remove all XML element contents and plugins.

      Any attribute values will be preserved.


   .. py:method:: tag_name()
      :classmethod:

      Return the namespaced name of the stanza's root element.

      The format for the tag name is::

          '{namespace}elementname'

      For example, for the stanza ``<foo xmlns="bar" />``,
      ``stanza.tag_name()`` would return ``"{bar}foo"``.



.. py:class:: OpenGraphMixin(xml = None, parent = None)




   The core of Slixmpp's stanza XML manipulation and handling is provided
   by ElementBase. ElementBase wraps XML ElementTree objects and enables
   access to the XML contents through dictionary syntax, similar in style
   to the Ruby XMPP library Blather's stanza implementation.

   Stanzas are defined by their name, namespace, and interfaces. For
   example, a simplistic Message stanza could be defined as::

       >>> class Message(ElementBase):
       ...     name = "message"
       ...     namespace = "jabber:client"
       ...     interfaces = {'to', 'from', 'type', 'body'}
       ...     sub_interfaces = {'body'}

   The resulting Message stanza's contents may be accessed as so::

       >>> message['to'] = "user@example.com"
       >>> message['body'] = "Hi!"
       >>> message['body']
       "Hi!"
       >>> del message['body']
       >>> message['body']
       ""

   The interface values map to either custom access methods, stanza
   XML attributes, or (if the interface is also in sub_interfaces) the
   text contents of a stanza's subelement.

   Custom access methods may be created by adding methods of the
   form "getInterface", "setInterface", or "delInterface", where
   "Interface" is the titlecase version of the interface name.

   Stanzas may be extended through the use of plugins. A plugin
   is simply a stanza that has a plugin_attrib value. For example::

       >>> class MessagePlugin(ElementBase):
       ...     name = "custom_plugin"
       ...     namespace = "custom"
       ...     interfaces = {'useful_thing', 'custom'}
       ...     plugin_attrib = "custom"

   The plugin stanza class must be associated with its intended
   container stanza by using register_stanza_plugin as so::

       >>> register_stanza_plugin(Message, MessagePlugin)

   The plugin may then be accessed as if it were built-in to the parent
   stanza::

       >>> message['custom']['useful_thing'] = 'foo'

   If a plugin provides an interface that is the same as the plugin's
   plugin_attrib value, then the plugin's interface may be assigned
   directly from the parent stanza, as shown below, but retrieving
   information will require all interfaces to be used, as so::

       >>> # Same as using message['custom']['custom']
       >>> message['custom'] = 'bar'
       >>> # Must use all interfaces
       >>> message['custom']['custom']
       'bar'

   If the plugin sets :attr:`is_extension` to ``True``, then both setting
   and getting an interface value that is the same as the plugin's
   plugin_attrib value will work, as so::

       >>> message['custom'] = 'bar'  # Using is_extension=True
       >>> message['custom']
       'bar'


   :param xml: Initialize the stanza object with an existing XML object.
   :param parent: Optionally specify a parent stanza object will
                  contain this substanza.

   .. py:method:: setup(xml = None)

      Initialize the stanza's XML contents.

      Will return ``True`` if XML was generated according to the stanza's
      definition instead of building a stanza object from an existing
      XML object.

      :param xml: An existing XML object to use for the stanza's content
                  instead of generating new XML.


   .. py:method:: enable(attrib, lang = None)

      Enable and initialize a stanza plugin.

      Alias for :meth:`init_plugin`.

      :param string attrib: The :attr:`plugin_attrib` value of the
                            plugin to enable.


   .. py:method:: get_plugin(name, lang = None, check = False)

      Retrieve a stanza plugin.

      :param check: Return None instead of creating the object if True.
      :param name: Stanza plugin attribute name.
      :param lang: xml:lang of the element to retrieve.


   .. py:method:: init_plugin(attrib, lang = None, existing_xml = None, reuse = True, element = None)

      Enable and initialize a stanza plugin.

      :param string attrib: The :attr:`plugin_attrib` value of the
                            plugin to enable.


   .. py:method:: match(xpath)

      Compare a stanza object with an XPath-like expression.

      If the XPath matches the contents of the stanza object, the match
      is successful.

      The XPath expression may include checks for stanza attributes.
      For example::

          'presence@show=xa@priority=2/status'

      Would match a presence stanza whose show value is set to ``'xa'``,
      has a priority value of ``'2'``, and has a status element.

      :param string xpath: The XPath expression to check against. It
                           may be either a string or a list of element
                           names with attribute checks.


   .. py:method:: get(key, default = None)

      Return the value of a stanza interface.

      If the found value is None or an empty string, return the supplied
      default value.

      Allows stanza objects to be used like dictionaries.

      :param string key: The name of the stanza interface to check.
      :param default: Value to return if the stanza interface has a value
                      of ``None`` or ``""``. Will default to returning None.


   .. py:method:: keys()

      Return the names of all stanza interfaces provided by the
      stanza object.

      Allows stanza objects to be used like dictionaries.


   .. py:method:: append(item)

      Append either an XML object or a substanza to this stanza object.

      If a substanza object is appended, it will be added to the list
      of iterable stanzas.

      Allows stanza objects to be used like lists.

      :param item: Either an XML object or a stanza object to add to
                   this stanza's contents.


   .. py:method:: appendxml(xml)

      Append an XML object to the stanza's XML.

      The added XML will not be included in the list of
      iterable substanzas.

      :param XML xml: The XML object to add to the stanza.


   .. py:method:: pop(index = 0)

      Remove and return the last substanza in the list of
      iterable substanzas.

      Allows stanza objects to be used like lists.

      :param int index: The index of the substanza to remove.


   .. py:method:: next()

      Return the next iterable substanza.


   .. py:method:: clear()

      Remove all XML element contents and plugins.

      Any attribute values will be preserved.


   .. py:method:: tag_name()
      :classmethod:

      Return the namespaced name of the stanza's root element.

      The format for the tag name is::

          '{namespace}elementname'

      For example, for the stanza ``<foo xmlns="bar" />``,
      ``stanza.tag_name()`` would return ``"{bar}foo"``.



.. py:class:: Title(xml = None, parent = None)




   The core of Slixmpp's stanza XML manipulation and handling is provided
   by ElementBase. ElementBase wraps XML ElementTree objects and enables
   access to the XML contents through dictionary syntax, similar in style
   to the Ruby XMPP library Blather's stanza implementation.

   Stanzas are defined by their name, namespace, and interfaces. For
   example, a simplistic Message stanza could be defined as::

       >>> class Message(ElementBase):
       ...     name = "message"
       ...     namespace = "jabber:client"
       ...     interfaces = {'to', 'from', 'type', 'body'}
       ...     sub_interfaces = {'body'}

   The resulting Message stanza's contents may be accessed as so::

       >>> message['to'] = "user@example.com"
       >>> message['body'] = "Hi!"
       >>> message['body']
       "Hi!"
       >>> del message['body']
       >>> message['body']
       ""

   The interface values map to either custom access methods, stanza
   XML attributes, or (if the interface is also in sub_interfaces) the
   text contents of a stanza's subelement.

   Custom access methods may be created by adding methods of the
   form "getInterface", "setInterface", or "delInterface", where
   "Interface" is the titlecase version of the interface name.

   Stanzas may be extended through the use of plugins. A plugin
   is simply a stanza that has a plugin_attrib value. For example::

       >>> class MessagePlugin(ElementBase):
       ...     name = "custom_plugin"
       ...     namespace = "custom"
       ...     interfaces = {'useful_thing', 'custom'}
       ...     plugin_attrib = "custom"

   The plugin stanza class must be associated with its intended
   container stanza by using register_stanza_plugin as so::

       >>> register_stanza_plugin(Message, MessagePlugin)

   The plugin may then be accessed as if it were built-in to the parent
   stanza::

       >>> message['custom']['useful_thing'] = 'foo'

   If a plugin provides an interface that is the same as the plugin's
   plugin_attrib value, then the plugin's interface may be assigned
   directly from the parent stanza, as shown below, but retrieving
   information will require all interfaces to be used, as so::

       >>> # Same as using message['custom']['custom']
       >>> message['custom'] = 'bar'
       >>> # Must use all interfaces
       >>> message['custom']['custom']
       'bar'

   If the plugin sets :attr:`is_extension` to ``True``, then both setting
   and getting an interface value that is the same as the plugin's
   plugin_attrib value will work, as so::

       >>> message['custom'] = 'bar'  # Using is_extension=True
       >>> message['custom']
       'bar'


   :param xml: Initialize the stanza object with an existing XML object.
   :param parent: Optionally specify a parent stanza object will
                  contain this substanza.

   .. py:method:: setup(xml = None)

      Initialize the stanza's XML contents.

      Will return ``True`` if XML was generated according to the stanza's
      definition instead of building a stanza object from an existing
      XML object.

      :param xml: An existing XML object to use for the stanza's content
                  instead of generating new XML.


   .. py:method:: enable(attrib, lang = None)

      Enable and initialize a stanza plugin.

      Alias for :meth:`init_plugin`.

      :param string attrib: The :attr:`plugin_attrib` value of the
                            plugin to enable.


   .. py:method:: get_plugin(name, lang = None, check = False)

      Retrieve a stanza plugin.

      :param check: Return None instead of creating the object if True.
      :param name: Stanza plugin attribute name.
      :param lang: xml:lang of the element to retrieve.


   .. py:method:: init_plugin(attrib, lang = None, existing_xml = None, reuse = True, element = None)

      Enable and initialize a stanza plugin.

      :param string attrib: The :attr:`plugin_attrib` value of the
                            plugin to enable.


   .. py:method:: match(xpath)

      Compare a stanza object with an XPath-like expression.

      If the XPath matches the contents of the stanza object, the match
      is successful.

      The XPath expression may include checks for stanza attributes.
      For example::

          'presence@show=xa@priority=2/status'

      Would match a presence stanza whose show value is set to ``'xa'``,
      has a priority value of ``'2'``, and has a status element.

      :param string xpath: The XPath expression to check against. It
                           may be either a string or a list of element
                           names with attribute checks.


   .. py:method:: get(key, default = None)

      Return the value of a stanza interface.

      If the found value is None or an empty string, return the supplied
      default value.

      Allows stanza objects to be used like dictionaries.

      :param string key: The name of the stanza interface to check.
      :param default: Value to return if the stanza interface has a value
                      of ``None`` or ``""``. Will default to returning None.


   .. py:method:: keys()

      Return the names of all stanza interfaces provided by the
      stanza object.

      Allows stanza objects to be used like dictionaries.


   .. py:method:: append(item)

      Append either an XML object or a substanza to this stanza object.

      If a substanza object is appended, it will be added to the list
      of iterable stanzas.

      Allows stanza objects to be used like lists.

      :param item: Either an XML object or a stanza object to add to
                   this stanza's contents.


   .. py:method:: appendxml(xml)

      Append an XML object to the stanza's XML.

      The added XML will not be included in the list of
      iterable substanzas.

      :param XML xml: The XML object to add to the stanza.


   .. py:method:: pop(index = 0)

      Remove and return the last substanza in the list of
      iterable substanzas.

      Allows stanza objects to be used like lists.

      :param int index: The index of the substanza to remove.


   .. py:method:: next()

      Return the next iterable substanza.


   .. py:method:: clear()

      Remove all XML element contents and plugins.

      Any attribute values will be preserved.


   .. py:method:: tag_name()
      :classmethod:

      Return the namespaced name of the stanza's root element.

      The format for the tag name is::

          '{namespace}elementname'

      For example, for the stanza ``<foo xmlns="bar" />``,
      ``stanza.tag_name()`` would return ``"{bar}foo"``.



.. py:class:: Description(xml = None, parent = None)




   The core of Slixmpp's stanza XML manipulation and handling is provided
   by ElementBase. ElementBase wraps XML ElementTree objects and enables
   access to the XML contents through dictionary syntax, similar in style
   to the Ruby XMPP library Blather's stanza implementation.

   Stanzas are defined by their name, namespace, and interfaces. For
   example, a simplistic Message stanza could be defined as::

       >>> class Message(ElementBase):
       ...     name = "message"
       ...     namespace = "jabber:client"
       ...     interfaces = {'to', 'from', 'type', 'body'}
       ...     sub_interfaces = {'body'}

   The resulting Message stanza's contents may be accessed as so::

       >>> message['to'] = "user@example.com"
       >>> message['body'] = "Hi!"
       >>> message['body']
       "Hi!"
       >>> del message['body']
       >>> message['body']
       ""

   The interface values map to either custom access methods, stanza
   XML attributes, or (if the interface is also in sub_interfaces) the
   text contents of a stanza's subelement.

   Custom access methods may be created by adding methods of the
   form "getInterface", "setInterface", or "delInterface", where
   "Interface" is the titlecase version of the interface name.

   Stanzas may be extended through the use of plugins. A plugin
   is simply a stanza that has a plugin_attrib value. For example::

       >>> class MessagePlugin(ElementBase):
       ...     name = "custom_plugin"
       ...     namespace = "custom"
       ...     interfaces = {'useful_thing', 'custom'}
       ...     plugin_attrib = "custom"

   The plugin stanza class must be associated with its intended
   container stanza by using register_stanza_plugin as so::

       >>> register_stanza_plugin(Message, MessagePlugin)

   The plugin may then be accessed as if it were built-in to the parent
   stanza::

       >>> message['custom']['useful_thing'] = 'foo'

   If a plugin provides an interface that is the same as the plugin's
   plugin_attrib value, then the plugin's interface may be assigned
   directly from the parent stanza, as shown below, but retrieving
   information will require all interfaces to be used, as so::

       >>> # Same as using message['custom']['custom']
       >>> message['custom'] = 'bar'
       >>> # Must use all interfaces
       >>> message['custom']['custom']
       'bar'

   If the plugin sets :attr:`is_extension` to ``True``, then both setting
   and getting an interface value that is the same as the plugin's
   plugin_attrib value will work, as so::

       >>> message['custom'] = 'bar'  # Using is_extension=True
       >>> message['custom']
       'bar'


   :param xml: Initialize the stanza object with an existing XML object.
   :param parent: Optionally specify a parent stanza object will
                  contain this substanza.

   .. py:method:: setup(xml = None)

      Initialize the stanza's XML contents.

      Will return ``True`` if XML was generated according to the stanza's
      definition instead of building a stanza object from an existing
      XML object.

      :param xml: An existing XML object to use for the stanza's content
                  instead of generating new XML.


   .. py:method:: enable(attrib, lang = None)

      Enable and initialize a stanza plugin.

      Alias for :meth:`init_plugin`.

      :param string attrib: The :attr:`plugin_attrib` value of the
                            plugin to enable.


   .. py:method:: get_plugin(name, lang = None, check = False)

      Retrieve a stanza plugin.

      :param check: Return None instead of creating the object if True.
      :param name: Stanza plugin attribute name.
      :param lang: xml:lang of the element to retrieve.


   .. py:method:: init_plugin(attrib, lang = None, existing_xml = None, reuse = True, element = None)

      Enable and initialize a stanza plugin.

      :param string attrib: The :attr:`plugin_attrib` value of the
                            plugin to enable.


   .. py:method:: match(xpath)

      Compare a stanza object with an XPath-like expression.

      If the XPath matches the contents of the stanza object, the match
      is successful.

      The XPath expression may include checks for stanza attributes.
      For example::

          'presence@show=xa@priority=2/status'

      Would match a presence stanza whose show value is set to ``'xa'``,
      has a priority value of ``'2'``, and has a status element.

      :param string xpath: The XPath expression to check against. It
                           may be either a string or a list of element
                           names with attribute checks.


   .. py:method:: get(key, default = None)

      Return the value of a stanza interface.

      If the found value is None or an empty string, return the supplied
      default value.

      Allows stanza objects to be used like dictionaries.

      :param string key: The name of the stanza interface to check.
      :param default: Value to return if the stanza interface has a value
                      of ``None`` or ``""``. Will default to returning None.


   .. py:method:: keys()

      Return the names of all stanza interfaces provided by the
      stanza object.

      Allows stanza objects to be used like dictionaries.


   .. py:method:: append(item)

      Append either an XML object or a substanza to this stanza object.

      If a substanza object is appended, it will be added to the list
      of iterable stanzas.

      Allows stanza objects to be used like lists.

      :param item: Either an XML object or a stanza object to add to
                   this stanza's contents.


   .. py:method:: appendxml(xml)

      Append an XML object to the stanza's XML.

      The added XML will not be included in the list of
      iterable substanzas.

      :param XML xml: The XML object to add to the stanza.


   .. py:method:: pop(index = 0)

      Remove and return the last substanza in the list of
      iterable substanzas.

      Allows stanza objects to be used like lists.

      :param int index: The index of the substanza to remove.


   .. py:method:: next()

      Return the next iterable substanza.


   .. py:method:: clear()

      Remove all XML element contents and plugins.

      Any attribute values will be preserved.


   .. py:method:: tag_name()
      :classmethod:

      Return the namespaced name of the stanza's root element.

      The format for the tag name is::

          '{namespace}elementname'

      For example, for the stanza ``<foo xmlns="bar" />``,
      ``stanza.tag_name()`` would return ``"{bar}foo"``.



.. py:class:: Url(xml = None, parent = None)




   The core of Slixmpp's stanza XML manipulation and handling is provided
   by ElementBase. ElementBase wraps XML ElementTree objects and enables
   access to the XML contents through dictionary syntax, similar in style
   to the Ruby XMPP library Blather's stanza implementation.

   Stanzas are defined by their name, namespace, and interfaces. For
   example, a simplistic Message stanza could be defined as::

       >>> class Message(ElementBase):
       ...     name = "message"
       ...     namespace = "jabber:client"
       ...     interfaces = {'to', 'from', 'type', 'body'}
       ...     sub_interfaces = {'body'}

   The resulting Message stanza's contents may be accessed as so::

       >>> message['to'] = "user@example.com"
       >>> message['body'] = "Hi!"
       >>> message['body']
       "Hi!"
       >>> del message['body']
       >>> message['body']
       ""

   The interface values map to either custom access methods, stanza
   XML attributes, or (if the interface is also in sub_interfaces) the
   text contents of a stanza's subelement.

   Custom access methods may be created by adding methods of the
   form "getInterface", "setInterface", or "delInterface", where
   "Interface" is the titlecase version of the interface name.

   Stanzas may be extended through the use of plugins. A plugin
   is simply a stanza that has a plugin_attrib value. For example::

       >>> class MessagePlugin(ElementBase):
       ...     name = "custom_plugin"
       ...     namespace = "custom"
       ...     interfaces = {'useful_thing', 'custom'}
       ...     plugin_attrib = "custom"

   The plugin stanza class must be associated with its intended
   container stanza by using register_stanza_plugin as so::

       >>> register_stanza_plugin(Message, MessagePlugin)

   The plugin may then be accessed as if it were built-in to the parent
   stanza::

       >>> message['custom']['useful_thing'] = 'foo'

   If a plugin provides an interface that is the same as the plugin's
   plugin_attrib value, then the plugin's interface may be assigned
   directly from the parent stanza, as shown below, but retrieving
   information will require all interfaces to be used, as so::

       >>> # Same as using message['custom']['custom']
       >>> message['custom'] = 'bar'
       >>> # Must use all interfaces
       >>> message['custom']['custom']
       'bar'

   If the plugin sets :attr:`is_extension` to ``True``, then both setting
   and getting an interface value that is the same as the plugin's
   plugin_attrib value will work, as so::

       >>> message['custom'] = 'bar'  # Using is_extension=True
       >>> message['custom']
       'bar'


   :param xml: Initialize the stanza object with an existing XML object.
   :param parent: Optionally specify a parent stanza object will
                  contain this substanza.

   .. py:method:: setup(xml = None)

      Initialize the stanza's XML contents.

      Will return ``True`` if XML was generated according to the stanza's
      definition instead of building a stanza object from an existing
      XML object.

      :param xml: An existing XML object to use for the stanza's content
                  instead of generating new XML.


   .. py:method:: enable(attrib, lang = None)

      Enable and initialize a stanza plugin.

      Alias for :meth:`init_plugin`.

      :param string attrib: The :attr:`plugin_attrib` value of the
                            plugin to enable.


   .. py:method:: get_plugin(name, lang = None, check = False)

      Retrieve a stanza plugin.

      :param check: Return None instead of creating the object if True.
      :param name: Stanza plugin attribute name.
      :param lang: xml:lang of the element to retrieve.


   .. py:method:: init_plugin(attrib, lang = None, existing_xml = None, reuse = True, element = None)

      Enable and initialize a stanza plugin.

      :param string attrib: The :attr:`plugin_attrib` value of the
                            plugin to enable.


   .. py:method:: match(xpath)

      Compare a stanza object with an XPath-like expression.

      If the XPath matches the contents of the stanza object, the match
      is successful.

      The XPath expression may include checks for stanza attributes.
      For example::

          'presence@show=xa@priority=2/status'

      Would match a presence stanza whose show value is set to ``'xa'``,
      has a priority value of ``'2'``, and has a status element.

      :param string xpath: The XPath expression to check against. It
                           may be either a string or a list of element
                           names with attribute checks.


   .. py:method:: get(key, default = None)

      Return the value of a stanza interface.

      If the found value is None or an empty string, return the supplied
      default value.

      Allows stanza objects to be used like dictionaries.

      :param string key: The name of the stanza interface to check.
      :param default: Value to return if the stanza interface has a value
                      of ``None`` or ``""``. Will default to returning None.


   .. py:method:: keys()

      Return the names of all stanza interfaces provided by the
      stanza object.

      Allows stanza objects to be used like dictionaries.


   .. py:method:: append(item)

      Append either an XML object or a substanza to this stanza object.

      If a substanza object is appended, it will be added to the list
      of iterable stanzas.

      Allows stanza objects to be used like lists.

      :param item: Either an XML object or a stanza object to add to
                   this stanza's contents.


   .. py:method:: appendxml(xml)

      Append an XML object to the stanza's XML.

      The added XML will not be included in the list of
      iterable substanzas.

      :param XML xml: The XML object to add to the stanza.


   .. py:method:: pop(index = 0)

      Remove and return the last substanza in the list of
      iterable substanzas.

      Allows stanza objects to be used like lists.

      :param int index: The index of the substanza to remove.


   .. py:method:: next()

      Return the next iterable substanza.


   .. py:method:: clear()

      Remove all XML element contents and plugins.

      Any attribute values will be preserved.


   .. py:method:: tag_name()
      :classmethod:

      Return the namespaced name of the stanza's root element.

      The format for the tag name is::

          '{namespace}elementname'

      For example, for the stanza ``<foo xmlns="bar" />``,
      ``stanza.tag_name()`` would return ``"{bar}foo"``.



.. py:class:: Image(xml = None, parent = None)




   The core of Slixmpp's stanza XML manipulation and handling is provided
   by ElementBase. ElementBase wraps XML ElementTree objects and enables
   access to the XML contents through dictionary syntax, similar in style
   to the Ruby XMPP library Blather's stanza implementation.

   Stanzas are defined by their name, namespace, and interfaces. For
   example, a simplistic Message stanza could be defined as::

       >>> class Message(ElementBase):
       ...     name = "message"
       ...     namespace = "jabber:client"
       ...     interfaces = {'to', 'from', 'type', 'body'}
       ...     sub_interfaces = {'body'}

   The resulting Message stanza's contents may be accessed as so::

       >>> message['to'] = "user@example.com"
       >>> message['body'] = "Hi!"
       >>> message['body']
       "Hi!"
       >>> del message['body']
       >>> message['body']
       ""

   The interface values map to either custom access methods, stanza
   XML attributes, or (if the interface is also in sub_interfaces) the
   text contents of a stanza's subelement.

   Custom access methods may be created by adding methods of the
   form "getInterface", "setInterface", or "delInterface", where
   "Interface" is the titlecase version of the interface name.

   Stanzas may be extended through the use of plugins. A plugin
   is simply a stanza that has a plugin_attrib value. For example::

       >>> class MessagePlugin(ElementBase):
       ...     name = "custom_plugin"
       ...     namespace = "custom"
       ...     interfaces = {'useful_thing', 'custom'}
       ...     plugin_attrib = "custom"

   The plugin stanza class must be associated with its intended
   container stanza by using register_stanza_plugin as so::

       >>> register_stanza_plugin(Message, MessagePlugin)

   The plugin may then be accessed as if it were built-in to the parent
   stanza::

       >>> message['custom']['useful_thing'] = 'foo'

   If a plugin provides an interface that is the same as the plugin's
   plugin_attrib value, then the plugin's interface may be assigned
   directly from the parent stanza, as shown below, but retrieving
   information will require all interfaces to be used, as so::

       >>> # Same as using message['custom']['custom']
       >>> message['custom'] = 'bar'
       >>> # Must use all interfaces
       >>> message['custom']['custom']
       'bar'

   If the plugin sets :attr:`is_extension` to ``True``, then both setting
   and getting an interface value that is the same as the plugin's
   plugin_attrib value will work, as so::

       >>> message['custom'] = 'bar'  # Using is_extension=True
       >>> message['custom']
       'bar'


   :param xml: Initialize the stanza object with an existing XML object.
   :param parent: Optionally specify a parent stanza object will
                  contain this substanza.

   .. py:method:: setup(xml = None)

      Initialize the stanza's XML contents.

      Will return ``True`` if XML was generated according to the stanza's
      definition instead of building a stanza object from an existing
      XML object.

      :param xml: An existing XML object to use for the stanza's content
                  instead of generating new XML.


   .. py:method:: enable(attrib, lang = None)

      Enable and initialize a stanza plugin.

      Alias for :meth:`init_plugin`.

      :param string attrib: The :attr:`plugin_attrib` value of the
                            plugin to enable.


   .. py:method:: get_plugin(name, lang = None, check = False)

      Retrieve a stanza plugin.

      :param check: Return None instead of creating the object if True.
      :param name: Stanza plugin attribute name.
      :param lang: xml:lang of the element to retrieve.


   .. py:method:: init_plugin(attrib, lang = None, existing_xml = None, reuse = True, element = None)

      Enable and initialize a stanza plugin.

      :param string attrib: The :attr:`plugin_attrib` value of the
                            plugin to enable.


   .. py:method:: match(xpath)

      Compare a stanza object with an XPath-like expression.

      If the XPath matches the contents of the stanza object, the match
      is successful.

      The XPath expression may include checks for stanza attributes.
      For example::

          'presence@show=xa@priority=2/status'

      Would match a presence stanza whose show value is set to ``'xa'``,
      has a priority value of ``'2'``, and has a status element.

      :param string xpath: The XPath expression to check against. It
                           may be either a string or a list of element
                           names with attribute checks.


   .. py:method:: get(key, default = None)

      Return the value of a stanza interface.

      If the found value is None or an empty string, return the supplied
      default value.

      Allows stanza objects to be used like dictionaries.

      :param string key: The name of the stanza interface to check.
      :param default: Value to return if the stanza interface has a value
                      of ``None`` or ``""``. Will default to returning None.


   .. py:method:: keys()

      Return the names of all stanza interfaces provided by the
      stanza object.

      Allows stanza objects to be used like dictionaries.


   .. py:method:: append(item)

      Append either an XML object or a substanza to this stanza object.

      If a substanza object is appended, it will be added to the list
      of iterable stanzas.

      Allows stanza objects to be used like lists.

      :param item: Either an XML object or a stanza object to add to
                   this stanza's contents.


   .. py:method:: appendxml(xml)

      Append an XML object to the stanza's XML.

      The added XML will not be included in the list of
      iterable substanzas.

      :param XML xml: The XML object to add to the stanza.


   .. py:method:: pop(index = 0)

      Remove and return the last substanza in the list of
      iterable substanzas.

      Allows stanza objects to be used like lists.

      :param int index: The index of the substanza to remove.


   .. py:method:: next()

      Return the next iterable substanza.


   .. py:method:: clear()

      Remove all XML element contents and plugins.

      Any attribute values will be preserved.


   .. py:method:: tag_name()
      :classmethod:

      Return the namespaced name of the stanza's root element.

      The format for the tag name is::

          '{namespace}elementname'

      For example, for the stanza ``<foo xmlns="bar" />``,
      ``stanza.tag_name()`` would return ``"{bar}foo"``.



.. py:class:: Type_(xml = None, parent = None)




   The core of Slixmpp's stanza XML manipulation and handling is provided
   by ElementBase. ElementBase wraps XML ElementTree objects and enables
   access to the XML contents through dictionary syntax, similar in style
   to the Ruby XMPP library Blather's stanza implementation.

   Stanzas are defined by their name, namespace, and interfaces. For
   example, a simplistic Message stanza could be defined as::

       >>> class Message(ElementBase):
       ...     name = "message"
       ...     namespace = "jabber:client"
       ...     interfaces = {'to', 'from', 'type', 'body'}
       ...     sub_interfaces = {'body'}

   The resulting Message stanza's contents may be accessed as so::

       >>> message['to'] = "user@example.com"
       >>> message['body'] = "Hi!"
       >>> message['body']
       "Hi!"
       >>> del message['body']
       >>> message['body']
       ""

   The interface values map to either custom access methods, stanza
   XML attributes, or (if the interface is also in sub_interfaces) the
   text contents of a stanza's subelement.

   Custom access methods may be created by adding methods of the
   form "getInterface", "setInterface", or "delInterface", where
   "Interface" is the titlecase version of the interface name.

   Stanzas may be extended through the use of plugins. A plugin
   is simply a stanza that has a plugin_attrib value. For example::

       >>> class MessagePlugin(ElementBase):
       ...     name = "custom_plugin"
       ...     namespace = "custom"
       ...     interfaces = {'useful_thing', 'custom'}
       ...     plugin_attrib = "custom"

   The plugin stanza class must be associated with its intended
   container stanza by using register_stanza_plugin as so::

       >>> register_stanza_plugin(Message, MessagePlugin)

   The plugin may then be accessed as if it were built-in to the parent
   stanza::

       >>> message['custom']['useful_thing'] = 'foo'

   If a plugin provides an interface that is the same as the plugin's
   plugin_attrib value, then the plugin's interface may be assigned
   directly from the parent stanza, as shown below, but retrieving
   information will require all interfaces to be used, as so::

       >>> # Same as using message['custom']['custom']
       >>> message['custom'] = 'bar'
       >>> # Must use all interfaces
       >>> message['custom']['custom']
       'bar'

   If the plugin sets :attr:`is_extension` to ``True``, then both setting
   and getting an interface value that is the same as the plugin's
   plugin_attrib value will work, as so::

       >>> message['custom'] = 'bar'  # Using is_extension=True
       >>> message['custom']
       'bar'


   :param xml: Initialize the stanza object with an existing XML object.
   :param parent: Optionally specify a parent stanza object will
                  contain this substanza.

   .. py:method:: setup(xml = None)

      Initialize the stanza's XML contents.

      Will return ``True`` if XML was generated according to the stanza's
      definition instead of building a stanza object from an existing
      XML object.

      :param xml: An existing XML object to use for the stanza's content
                  instead of generating new XML.


   .. py:method:: enable(attrib, lang = None)

      Enable and initialize a stanza plugin.

      Alias for :meth:`init_plugin`.

      :param string attrib: The :attr:`plugin_attrib` value of the
                            plugin to enable.


   .. py:method:: get_plugin(name, lang = None, check = False)

      Retrieve a stanza plugin.

      :param check: Return None instead of creating the object if True.
      :param name: Stanza plugin attribute name.
      :param lang: xml:lang of the element to retrieve.


   .. py:method:: init_plugin(attrib, lang = None, existing_xml = None, reuse = True, element = None)

      Enable and initialize a stanza plugin.

      :param string attrib: The :attr:`plugin_attrib` value of the
                            plugin to enable.


   .. py:method:: match(xpath)

      Compare a stanza object with an XPath-like expression.

      If the XPath matches the contents of the stanza object, the match
      is successful.

      The XPath expression may include checks for stanza attributes.
      For example::

          'presence@show=xa@priority=2/status'

      Would match a presence stanza whose show value is set to ``'xa'``,
      has a priority value of ``'2'``, and has a status element.

      :param string xpath: The XPath expression to check against. It
                           may be either a string or a list of element
                           names with attribute checks.


   .. py:method:: get(key, default = None)

      Return the value of a stanza interface.

      If the found value is None or an empty string, return the supplied
      default value.

      Allows stanza objects to be used like dictionaries.

      :param string key: The name of the stanza interface to check.
      :param default: Value to return if the stanza interface has a value
                      of ``None`` or ``""``. Will default to returning None.


   .. py:method:: keys()

      Return the names of all stanza interfaces provided by the
      stanza object.

      Allows stanza objects to be used like dictionaries.


   .. py:method:: append(item)

      Append either an XML object or a substanza to this stanza object.

      If a substanza object is appended, it will be added to the list
      of iterable stanzas.

      Allows stanza objects to be used like lists.

      :param item: Either an XML object or a stanza object to add to
                   this stanza's contents.


   .. py:method:: appendxml(xml)

      Append an XML object to the stanza's XML.

      The added XML will not be included in the list of
      iterable substanzas.

      :param XML xml: The XML object to add to the stanza.


   .. py:method:: pop(index = 0)

      Remove and return the last substanza in the list of
      iterable substanzas.

      Allows stanza objects to be used like lists.

      :param int index: The index of the substanza to remove.


   .. py:method:: next()

      Return the next iterable substanza.


   .. py:method:: clear()

      Remove all XML element contents and plugins.

      Any attribute values will be preserved.


   .. py:method:: tag_name()
      :classmethod:

      Return the namespaced name of the stanza's root element.

      The format for the tag name is::

          '{namespace}elementname'

      For example, for the stanza ``<foo xmlns="bar" />``,
      ``stanza.tag_name()`` would return ``"{bar}foo"``.



.. py:class:: SiteName(xml = None, parent = None)




   The core of Slixmpp's stanza XML manipulation and handling is provided
   by ElementBase. ElementBase wraps XML ElementTree objects and enables
   access to the XML contents through dictionary syntax, similar in style
   to the Ruby XMPP library Blather's stanza implementation.

   Stanzas are defined by their name, namespace, and interfaces. For
   example, a simplistic Message stanza could be defined as::

       >>> class Message(ElementBase):
       ...     name = "message"
       ...     namespace = "jabber:client"
       ...     interfaces = {'to', 'from', 'type', 'body'}
       ...     sub_interfaces = {'body'}

   The resulting Message stanza's contents may be accessed as so::

       >>> message['to'] = "user@example.com"
       >>> message['body'] = "Hi!"
       >>> message['body']
       "Hi!"
       >>> del message['body']
       >>> message['body']
       ""

   The interface values map to either custom access methods, stanza
   XML attributes, or (if the interface is also in sub_interfaces) the
   text contents of a stanza's subelement.

   Custom access methods may be created by adding methods of the
   form "getInterface", "setInterface", or "delInterface", where
   "Interface" is the titlecase version of the interface name.

   Stanzas may be extended through the use of plugins. A plugin
   is simply a stanza that has a plugin_attrib value. For example::

       >>> class MessagePlugin(ElementBase):
       ...     name = "custom_plugin"
       ...     namespace = "custom"
       ...     interfaces = {'useful_thing', 'custom'}
       ...     plugin_attrib = "custom"

   The plugin stanza class must be associated with its intended
   container stanza by using register_stanza_plugin as so::

       >>> register_stanza_plugin(Message, MessagePlugin)

   The plugin may then be accessed as if it were built-in to the parent
   stanza::

       >>> message['custom']['useful_thing'] = 'foo'

   If a plugin provides an interface that is the same as the plugin's
   plugin_attrib value, then the plugin's interface may be assigned
   directly from the parent stanza, as shown below, but retrieving
   information will require all interfaces to be used, as so::

       >>> # Same as using message['custom']['custom']
       >>> message['custom'] = 'bar'
       >>> # Must use all interfaces
       >>> message['custom']['custom']
       'bar'

   If the plugin sets :attr:`is_extension` to ``True``, then both setting
   and getting an interface value that is the same as the plugin's
   plugin_attrib value will work, as so::

       >>> message['custom'] = 'bar'  # Using is_extension=True
       >>> message['custom']
       'bar'


   :param xml: Initialize the stanza object with an existing XML object.
   :param parent: Optionally specify a parent stanza object will
                  contain this substanza.

   .. py:method:: setup(xml = None)

      Initialize the stanza's XML contents.

      Will return ``True`` if XML was generated according to the stanza's
      definition instead of building a stanza object from an existing
      XML object.

      :param xml: An existing XML object to use for the stanza's content
                  instead of generating new XML.


   .. py:method:: enable(attrib, lang = None)

      Enable and initialize a stanza plugin.

      Alias for :meth:`init_plugin`.

      :param string attrib: The :attr:`plugin_attrib` value of the
                            plugin to enable.


   .. py:method:: get_plugin(name, lang = None, check = False)

      Retrieve a stanza plugin.

      :param check: Return None instead of creating the object if True.
      :param name: Stanza plugin attribute name.
      :param lang: xml:lang of the element to retrieve.


   .. py:method:: init_plugin(attrib, lang = None, existing_xml = None, reuse = True, element = None)

      Enable and initialize a stanza plugin.

      :param string attrib: The :attr:`plugin_attrib` value of the
                            plugin to enable.


   .. py:method:: match(xpath)

      Compare a stanza object with an XPath-like expression.

      If the XPath matches the contents of the stanza object, the match
      is successful.

      The XPath expression may include checks for stanza attributes.
      For example::

          'presence@show=xa@priority=2/status'

      Would match a presence stanza whose show value is set to ``'xa'``,
      has a priority value of ``'2'``, and has a status element.

      :param string xpath: The XPath expression to check against. It
                           may be either a string or a list of element
                           names with attribute checks.


   .. py:method:: get(key, default = None)

      Return the value of a stanza interface.

      If the found value is None or an empty string, return the supplied
      default value.

      Allows stanza objects to be used like dictionaries.

      :param string key: The name of the stanza interface to check.
      :param default: Value to return if the stanza interface has a value
                      of ``None`` or ``""``. Will default to returning None.


   .. py:method:: keys()

      Return the names of all stanza interfaces provided by the
      stanza object.

      Allows stanza objects to be used like dictionaries.


   .. py:method:: append(item)

      Append either an XML object or a substanza to this stanza object.

      If a substanza object is appended, it will be added to the list
      of iterable stanzas.

      Allows stanza objects to be used like lists.

      :param item: Either an XML object or a stanza object to add to
                   this stanza's contents.


   .. py:method:: appendxml(xml)

      Append an XML object to the stanza's XML.

      The added XML will not be included in the list of
      iterable substanzas.

      :param XML xml: The XML object to add to the stanza.


   .. py:method:: pop(index = 0)

      Remove and return the last substanza in the list of
      iterable substanzas.

      Allows stanza objects to be used like lists.

      :param int index: The index of the substanza to remove.


   .. py:method:: next()

      Return the next iterable substanza.


   .. py:method:: clear()

      Remove all XML element contents and plugins.

      Any attribute values will be preserved.


   .. py:method:: tag_name()
      :classmethod:

      Return the namespaced name of the stanza's root element.

      The format for the tag name is::

          '{namespace}elementname'

      For example, for the stanza ``<foo xmlns="bar" />``,
      ``stanza.tag_name()`` would return ``"{bar}foo"``.



