########################################################################
# File name: service.py
# This file is part of: aioxmpp
#
# LICENSE
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this program.  If not, see
# <http://www.gnu.org/licenses/>.
#
########################################################################
import asyncio

import aioxmpp.callbacks
import aioxmpp.disco
import aioxmpp.service
import aioxmpp.stanza
import aioxmpp.structs

from . import xso as pubsub_xso


class PubSubClient(aioxmpp.service.Service):
    """
    Client service implementing a Publish-Subscribe client. By loading it into
    a client, it is possible to subscribe to, publish to and otherwise interact
    with Publish-Subscribe nodes.

    .. note::

       Signal handlers attached to any of the signals below **must** accept
       arbitrary keyword arguments for forward compatibility. If any of the
       arguments is listed as positional in the signal signature, it is always
       present and handed as positional argument.

    Subscriber use cases:
       .. autosummary::

          get_default_config
          get_items
          get_items_by_id
          get_subscription_config
          get_subscriptions
          set_subscription_config
          subscribe
          unsubscribe
          on_affiliation_update
          on_item_published
          on_item_retracted
          on_node_deleted
          on_subscription_update

    Publisher use cases:
       .. autosummary::

          notify
          publish
          retract

    Owner use cases:
       .. autosummary::

          change_node_affiliations
          change_node_subscriptions
          create
          delete
          get_nodes
          get_node_affiliations
          get_node_subscriptions
          purge

    Meta-information about the service:

    .. automethod:: get_features

    Subscribing, unsubscribing and listing subscriptions:

    .. automethod:: get_subscriptions

    .. automethod:: subscribe

    .. automethod:: unsubscribe

    Configuring subscriptions:

    .. automethod:: get_default_config

    .. automethod:: get_subscription_config

    .. automethod:: set_subscription_config

    Retrieving items:

    .. automethod:: get_items

    .. automethod:: get_items_by_id

    Publishing and retracting items:

    .. automethod:: notify

    .. automethod:: publish

    .. automethod:: retract

    Manage nodes:

    .. automethod:: change_node_affiliations

    .. automethod:: change_node_subscriptions

    .. automethod:: create

    .. automethod:: delete

    .. automethod:: get_nodes

    .. automethod:: get_node_affiliations

    .. automethod:: get_node_subscriptions

    .. automethod:: purge

    Receiving notifications:

    .. autosignal:: on_item_published(jid, node, item, *, message=None)

    .. autosignal:: on_item_retracted(jid, node, id_, *, message=None)

    .. autosignal:: on_node_deleted(jid, node, *, redirect_uri=None, message=None)

    .. autosignal:: on_affiliation_update(jid, node, affiliation, *, message=None)

    .. autosignal:: on_subscription_update(jid, node, state, *, subid=None, message=None)

    .. versionchanged:: 0.8

       This class was formerly known as :class:`aioxmpp.pubsub.Service`. It
       is still available under that name, but the alias will be removed in
       1.0.
    """

    ORDER_AFTER = [
        aioxmpp.DiscoClient,
    ]

    on_item_published = aioxmpp.callbacks.Signal(doc=
    """
    Fires when a new item is published to a node to which we have a
    subscription.

    The node at which the item has been published is identified by `jid` and
    `node`. `item` is the :class:`xso.EventItem` payload.

    `message` is the :class:`.Message` which carried the notification.
    If a notification message contains more than one published item, the event
    is fired for each of the items, and `message` is passed to all of them.
    """)  # NOQA

    on_item_retracted = aioxmpp.callbacks.Signal(doc=
    """
    Fires when an item is retracted from a node to which we have a subscription.

    The node at which the item has been retracted is identified by `jid` and
    `node`. `id_` is the ID of the item which has been retract.

    `message` is the :class:`.Message` which carried the notification.
    If a notification message contains more than one retracted item, the event
    is fired for each of the items, and `message` is passed to all of them.
    """)  # NOQA

    on_node_deleted = aioxmpp.callbacks.Signal(doc=
    """
    Fires when a node is deleted. `jid` and `node` identify the node.

    If the notification included a redirection URI, it is passed as
    `redirect_uri`. Otherwise, :data:`None` is passed for `redirect_uri`.

    `message` is the :class:`.Message` which carried the notification.
    """)  # NOQA

    on_affiliation_update = aioxmpp.callbacks.Signal(doc=
    """
    Fires when the affiliation with a node is updated.

    `jid` and `node` identify the node for which the affiliation was updated.
    `affiliation` is the new affiliaton.

    `message` is the :class:`.Message` which carried the notification.
    """)  # NOQA

    on_subscription_update = aioxmpp.callbacks.Signal(doc=
    """
    Fires when the subscription state is updated.

    `jid` and `node` identify the node for which the subscription was updated.
    `subid` is optional and if it is not :data:`None` it is the affected
    subscription id. `state` is the new subscription state.

    This event can happen in several cases, for example when a subscription
    request is approved by the node owner or when a subscription is cancelled.

    `message` is the :class:`.Message` which carried the notification.s
    """)  # NOQA

    def __init__(self, client, **kwargs):
        super().__init__(client, **kwargs)
        self._disco = self.dependencies[aioxmpp.DiscoClient]

    @aioxmpp.service.inbound_message_filter
    def filter_inbound_message(self, msg):
        if (msg.xep0060_event is not None and
                msg.xep0060_event.payload is not None):
            payload = msg.xep0060_event.payload
            if isinstance(payload, pubsub_xso.EventItems):
                for item in payload.items:
                    node = item.node or payload.node
                    self.on_item_published(
                        msg.from_,
                        node,
                        item,
                        message=msg,
                    )
                for retract in payload.retracts:
                    node = payload.node
                    self.on_item_retracted(
                        msg.from_,
                        node,
                        retract.id_,
                        message=msg,
                    )
            elif isinstance(payload, pubsub_xso.EventDelete):
                self.on_node_deleted(
                    msg.from_,
                    payload.node,
                    redirect_uri=payload.redirect_uri,
                    message=msg,
                )

        elif (msg.xep0060_request is not None and
              msg.xep0060_request.payload is not None):
            payload = msg.xep0060_request.payload
            if isinstance(payload, pubsub_xso.Affiliations):
                for item in payload.affiliations:
                    self.on_affiliation_update(
                        msg.from_,
                        item.node,
                        item.affiliation,
                        message=msg,
                    )
            elif isinstance(payload, pubsub_xso.Subscriptions):
                for item in payload.subscriptions:
                    self.on_subscription_update(
                        msg.from_,
                        item.node,
                        item.subscription,
                        subid=item.subid,
                        message=msg,
                    )
        else:
            return msg

    @asyncio.coroutine
    def get_features(self, jid):
        """
        Return the features supported by a service.

        :param jid: Address of the PubSub service to query.
        :type jid: :class:`aioxmpp.JID`
        :return: Set of supported features
        :rtype: set containing :class:`~.pubsub.xso.Feature` enumeration
                members.

        This simply uses service discovery to obtain the set of features and
        converts the features to :class:`~.pubsub.xso.Feature` enumeration
        members. To get the full feature information, resort to using
        :meth:`.DiscoClient.query_info` directly on `jid`.

        Features returned by the peer which are not valid pubsub features are
        not returned.
        """

        response = yield from self._disco.query_info(jid)
        result = set()
        for feature in response.features:
            try:
                result.add(pubsub_xso.Feature(feature))
            except ValueError:
                continue
        return result

    @asyncio.coroutine
    def subscribe(self, jid, node=None, *,
                  subscription_jid=None,
                  config=None):
        """
        Subscribe to a node.

        :param jid: Address of the PubSub service.
        :type jid: :class:`aioxmpp.JID`
        :param node: Name of the PubSub node to subscribe to.
        :type node: :class:`str`
        :param subscription_jid: The address to subscribe to the service.
        :type subscription_jid: :class:`aioxmpp.JID`
        :param config: Optional configuration of the subscription
        :type config: :class:`~.forms.Data`
        :raises aioxmpp.errors.XMPPError: as returned by the service
        :return: The response from the server.
        :rtype: :class:`.xso.Request`

        By default, the subscription request will be for the bare JID of the
        client. It can be specified explicitly using the `subscription_jid`
        argument.

        If the service requires it or if it makes sense for other reasons, the
        subscription configuration :class:`~.forms.Data` form can be passed
        using the `config` argument.

        On success, the whole :class:`.xso.Request` object returned by the
        server is returned. It contains a :class:`.xso.Subscription`
        :attr:`~.xso.Request.payload` which has information on the nature of
        the subscription (it may be ``"pending"`` or ``"unconfigured"``) and
        the :attr:`~.xso.Subscription.subid` which may be required for other
        operations.

        On failure, the corresponding :class:`~.errors.XMPPError` is raised.
        """

        subscription_jid = subscription_jid or self.client.local_jid.bare()

        iq = aioxmpp.stanza.IQ(to=jid, type_=aioxmpp.structs.IQType.SET)
        iq.payload = pubsub_xso.Request(
            pubsub_xso.Subscribe(subscription_jid, node=node)
        )

        if config is not None:
            iq.payload.options = pubsub_xso.Options(
                subscription_jid,
                node=node
            )
            iq.payload.options.data = config

        response = yield from self.client.send(iq)
        return response

    @asyncio.coroutine
    def unsubscribe(self, jid, node=None, *,
                    subscription_jid=None,
                    subid=None):
        """
        Unsubscribe from a node.

        :param jid: Address of the PubSub service.
        :type jid: :class:`aioxmpp.JID`
        :param node: Name of the PubSub node to unsubscribe from.
        :type node: :class:`str`
        :param subscription_jid: The address to subscribe from the service.
        :type subscription_jid: :class:`aioxmpp.JID`
        :param subid: Unique ID of the subscription to remove.
        :type subid: :class:`str`
        :raises aioxmpp.errors.XMPPError: as returned by the service

        By default, the unsubscribe request will be for the bare JID of the
        client. It can be specified explicitly using the `subscription_jid`
        argument.

        If available, the `subid` should also be specified.

        If an error occurs, the corresponding :class:`~.errors.XMPPError` is
        raised.
        """

        subscription_jid = subscription_jid or self.client.local_jid.bare()

        iq = aioxmpp.stanza.IQ(to=jid, type_=aioxmpp.structs.IQType.SET)
        iq.payload = pubsub_xso.Request(
            pubsub_xso.Unsubscribe(subscription_jid, node=node, subid=subid)
        )

        yield from self.client.send(iq)

    @asyncio.coroutine
    def get_subscription_config(self, jid, node=None, *,
                                subscription_jid=None,
                                subid=None):
        """
        Request the current configuration of a subscription.

        :param jid: Address of the PubSub service.
        :type jid: :class:`aioxmpp.JID`
        :param node: Name of the PubSub node to query.
        :type node: :class:`str`
        :param subscription_jid: The address to query the configuration for.
        :type subscription_jid: :class:`aioxmpp.JID`
        :param subid: Unique ID of the subscription to query.
        :type subid: :class:`str`
        :raises aioxmpp.errors.XMPPError: as returned by the service
        :return: The current configuration of the subscription.
        :rtype: :class:`~.forms.Data`

        By default, the request will be on behalf of the bare JID of the
        client. It can be overriden using the `subscription_jid` argument.

        If available, the `subid` should also be specified.

        On success, the :class:`~.forms.Data` form is returned.

        If an error occurs, the corresponding :class:`~.errors.XMPPError` is
        raised.
        """

        subscription_jid = subscription_jid or self.client.local_jid.bare()

        iq = aioxmpp.stanza.IQ(to=jid, type_=aioxmpp.structs.IQType.GET)
        iq.payload = pubsub_xso.Request()
        iq.payload.options = pubsub_xso.Options(
            subscription_jid,
            node=node,
            subid=subid,
        )

        response = yield from self.client.send(iq)
        return response.options.data

    @asyncio.coroutine
    def set_subscription_config(self, jid, data, node=None, *,
                                subscription_jid=None,
                                subid=None):
        """
        Update the configuration of a subscription.

        :param jid: Address of the PubSub service.
        :type jid: :class:`aioxmpp.JID`
        :param data: The new configuration of the subscription.
        :type data: :class:`~.forms.Data`
        :param node: Name of the PubSub node to modify.
        :type node: :class:`str`
        :param subscription_jid: The address to modify the configuration for.
        :type subscription_jid: :class:`aioxmpp.JID`
        :param subid: Unique ID of the subscription to modify.
        :type subid: :class:`str`
        :raises aioxmpp.errors.XMPPError: as returned by the service

        By default, the request will be on behalf of the bare JID of the
        client. It can be overriden using the `subscription_jid` argument.

        If available, the `subid` should also be specified.

        The configuration must be given as `data` as a
        :class:`~.forms.Data` instance.

        If an error occurs, the corresponding :class:`~.errors.XMPPError` is
        raised.
        """

        subscription_jid = subscription_jid or self.client.local_jid.bare()

        iq = aioxmpp.stanza.IQ(to=jid, type_=aioxmpp.structs.IQType.SET)
        iq.payload = pubsub_xso.Request()
        iq.payload.options = pubsub_xso.Options(
            subscription_jid,
            node=node,
            subid=subid,
        )
        iq.payload.options.data = data

        yield from self.client.send(iq)

    @asyncio.coroutine
    def get_default_config(self, jid, node=None):
        """
        Request the default configuration of a node.

        :param jid: Address of the PubSub service.
        :type jid: :class:`aioxmpp.JID`
        :param node: Name of the PubSub node to query.
        :type node: :class:`str`
        :raises aioxmpp.errors.XMPPError: as returned by the service
        :return: The default configuration of subscriptions at the node.
        :rtype: :class:`~.forms.Data`

        On success, the :class:`~.forms.Data` form is returned.

        If an error occurs, the corresponding :class:`~.errors.XMPPError` is
        raised.
        """

        iq = aioxmpp.stanza.IQ(to=jid, type_=aioxmpp.structs.IQType.GET)
        iq.payload = pubsub_xso.Request(
            pubsub_xso.Default(node=node)
        )

        response = yield from self.client.send(iq)
        return response.payload.data

    @asyncio.coroutine
    def get_items(self, jid, node, *, max_items=None):
        """
        Request the most recent items from a node.

        :param jid: Address of the PubSub service.
        :type jid: :class:`aioxmpp.JID`
        :param node: Name of the PubSub node to query.
        :type node: :class:`str`
        :param max_items: Number of items to return at most.
        :type max_items: :class:`int` or :data:`None`
        :raises aioxmpp.errors.XMPPError: as returned by the service
        :return: The response from the server.
        :rtype: :class:`.xso.Request`.

        By default, as many as possible items are requested. If `max_items` is
        given, it must be a positive integer specifying the maximum number of
        items which is to be returned by the server.

        Return the :class:`.xso.Request` object, which has a
        :class:`~.xso.Items` :attr:`~.xso.Request.payload`.
        """

        iq = aioxmpp.stanza.IQ(to=jid, type_=aioxmpp.structs.IQType.GET)
        iq.payload = pubsub_xso.Request(
            pubsub_xso.Items(node, max_items=max_items)
        )

        return (yield from self.client.send(iq))

    @asyncio.coroutine
    def get_items_by_id(self, jid, node, ids):
        """
        Request specific items by their IDs from a node.

        :param jid: Address of the PubSub service.
        :type jid: :class:`aioxmpp.JID`
        :param node: Name of the PubSub node to query.
        :type node: :class:`str`
        :param ids: The item IDs to return.
        :type ids: :class:`~collections.abc.Iterable` of :class:`str`
        :raises aioxmpp.errors.XMPPError: as returned by the service
        :return: The response from the service
        :rtype: :class:`.xso.Request`

        `ids` must be an iterable of :class:`str` of the IDs of the items to
        request from the pubsub node. If the iterable is empty,
        :class:`ValueError` is raised (as otherwise, the request would be
        identical to calling :meth:`get_items` without `max_items`).

        Return the :class:`.xso.Request` object, which has a
        :class:`~.xso.Items` :attr:`~.xso.Request.payload`.
        """

        iq = aioxmpp.stanza.IQ(to=jid, type_=aioxmpp.structs.IQType.GET)
        iq.payload = pubsub_xso.Request(
            pubsub_xso.Items(node)
        )

        iq.payload.payload.items = [
            pubsub_xso.Item(id_)
            for id_ in ids
        ]

        if not iq.payload.payload.items:
            raise ValueError("ids must not be empty")

        return (yield from self.client.send(iq))

    @asyncio.coroutine
    def get_subscriptions(self, jid, node=None):
        """
        Return all subscriptions of the local entity to a node.

        :param jid: Address of the PubSub service.
        :type jid: :class:`aioxmpp.JID`
        :param node: Name of the PubSub node to query.
        :type node: :class:`str`
        :raises aioxmpp.errors.XMPPError: as returned by the service
        :return: The subscriptions response from the service.
        :rtype: :class:`.xso.Subscriptions.

        If `node` is :data:`None`, subscriptions on all nodes of the entity
        `jid` are listed.
        """

        iq = aioxmpp.stanza.IQ(to=jid, type_=aioxmpp.structs.IQType.GET)
        iq.payload = pubsub_xso.Request(
            pubsub_xso.Subscriptions(node=node)
        )

        response = yield from self.client.send(iq)
        return response.payload

    @asyncio.coroutine
    def publish(self, jid, node, payload, *, id_=None):
        """
        Publish an item to a node.

        :param jid: Address of the PubSub service.
        :type jid: :class:`aioxmpp.JID`
        :param node: Name of the PubSub node to publish to.
        :type node: :class:`str`
        :param payload: Registered payload to publish.
        :type payload: :class:`aioxmpp.xso.XSO`
        :param id_: Item ID to use for the item.
        :type id_: :class:`str` or :data:`None`.
        :raises aioxmpp.errors.XMPPError: as returned by the service
        :return: The Item ID which was used to publish the item.
        :rtype: :class:`str` or :data:`None`

        Publish the given `payload` (which must be a :class:`aioxmpp.xso.XSO`
        registered with :attr:`.xso.Item.registered_payload`).

        The item is published to `node` at `jid`. If `id_` is given, it is used
        as the ID for the item. If an item with the same ID already exists at
        the node, it is replaced. If no ID is given, a ID is generated by the
        server.

        Return the ID of the item as published (or :data:`None` if the server
        does not inform us; this is unfortunately common).
        """

        publish = pubsub_xso.Publish()
        publish.node = node

        if payload is not None:
            item = pubsub_xso.Item()
            item.id_ = id_
            item.registered_payload = payload
            publish.item = item

        iq = aioxmpp.stanza.IQ(to=jid, type_=aioxmpp.structs.IQType.SET)
        iq.payload = pubsub_xso.Request(
            publish
        )

        response = yield from self.client.send(iq)

        if response is not None and response.payload.item is not None:
            return response.payload.item.id_ or id_
        return id_

    @asyncio.coroutine
    def notify(self, jid, node):
        """
        Notify all subscribers of a node without publishing an item.

        :param jid: Address of the PubSub service.
        :type jid: :class:`aioxmpp.JID`
        :param node: Name of the PubSub node to send a notify from.
        :type node: :class:`str`
        :raises aioxmpp.errors.XMPPError: as returned by the service

        "Publish" to the `node` at `jid` without any item. This merely fans out
        a notification. The exact semantics can be checked in :xep:`60`.
        """
        yield from self.publish(jid, node, None)

    @asyncio.coroutine
    def retract(self, jid, node, id_, *, notify=False):
        """
        Retract a previously published item from a node.

        :param jid: Address of the PubSub service.
        :type jid: :class:`aioxmpp.JID`
        :param node: Name of the PubSub node to send a notify from.
        :type node: :class:`str`
        :param id_: The ID of the item to retract.
        :type id_: :class:`str`
        :param notify: Flag indicating whether subscribers shall be notified
            about the retraction.
        :type notify: :class:`bool`
        :raises aioxmpp.errors.XMPPError: as returned by the service

        Retract an item previously published to `node` at `jid`. `id_` must be
        the ItemID of the item to retract.

        If `notify` is set to true, notifications will be generated (by setting
        the `notify` attribute on the retraction request).
        """
        retract = pubsub_xso.Retract()
        retract.node = node
        item = pubsub_xso.Item()
        item.id_ = id_
        retract.item = item
        retract.notify = notify

        iq = aioxmpp.stanza.IQ(to=jid, type_=aioxmpp.structs.IQType.SET)
        iq.payload = pubsub_xso.Request(
            retract
        )

        yield from self.client.send(iq)

    @asyncio.coroutine
    def create(self, jid, node=None):
        """
        Create a new node at a service.

        :param jid: Address of the PubSub service.
        :type jid: :class:`aioxmpp.JID`
        :param node: Name of the PubSub node to create.
        :type node: :class:`str` or :data:`None`
        :raises aioxmpp.errors.XMPPError: as returned by the service
        :return: The name of the created node.
        :rtype: :class:`str`

        If `node` is :data:`None`, an instant node is created (see :xep:`60`).
        The server may not support or allow the creation of instant nodes.

        Return the actual `node` identifier.
        """

        create = pubsub_xso.Create()
        create.node = node

        iq = aioxmpp.stanza.IQ(
            type_=aioxmpp.structs.IQType.SET,
            to=jid,
            payload=pubsub_xso.Request(create)
        )

        response = yield from self.client.send(iq)

        if response is not None and response.payload.node is not None:
            return response.payload.node

        return node

    @asyncio.coroutine
    def delete(self, jid, node, *, redirect_uri=None):
        """
        Delete an existing node.

        :param jid: Address of the PubSub service.
        :type jid: :class:`aioxmpp.JID`
        :param node: Name of the PubSub node to delete.
        :type node: :class:`str` or :data:`None`
        :param redirect_uri: A URI to send to subscribers to indicate a
            replacement for the deleted node.
        :type redirect_uri: :class:`str` or :data:`None`
        :raises aioxmpp.errors.XMPPError: as returned by the service

        Optionally, a `redirect_uri` can be given. The `redirect_uri` will be
        sent to subscribers in the message notifying them about the node
        deletion.
        """

        iq = aioxmpp.stanza.IQ(
            type_=aioxmpp.structs.IQType.SET,
            to=jid,
            payload=pubsub_xso.OwnerRequest(
                pubsub_xso.OwnerDelete(
                    node,
                    redirect_uri=redirect_uri
                )
            )
        )

        yield from self.client.send(iq)

    @asyncio.coroutine
    def get_nodes(self, jid, node=None):
        """
        Request all nodes at a service or collection node.

        :param jid: Address of the PubSub service.
        :type jid: :class:`aioxmpp.JID`
        :param node: Name of the collection node to query
        :type node: :class:`str` or :data:`None`
        :raises aioxmpp.errors.XMPPError: as returned by the service
        :return: The list of nodes at the service or collection node.
        :rtype: :class:`~collections.abc.Sequence` of tuples consisting of the
            node name and its description.

        Request the nodes available at `jid`. If `node` is not :data:`None`,
        the request returns the children of the :xep:`248` collection node
        `node`. Make sure to check for the appropriate server feature first.

        Return a list of tuples consisting of the node names and their
        description (if available, otherwise :data:`None`). If more information
        is needed, use :meth:`.DiscoClient.get_items` directly.

        Only nodes whose :attr:`~.disco.xso.Item.jid` match the `jid` are
        returned.
        """

        response = yield from self._disco.query_items(
            jid,
            node=node,
        )

        result = []
        for item in response.items:
            if item.jid != jid:
                continue
            result.append((
                item.node,
                item.name,
            ))

        return result

    @asyncio.coroutine
    def get_node_affiliations(self, jid, node):
        """
        Return the affiliations of other jids at a node.

        :param jid: Address of the PubSub service.
        :type jid: :class:`aioxmpp.JID`
        :param node: Name of the node to query
        :type node: :class:`str`
        :raises aioxmpp.errors.XMPPError: as returned by the service
        :return: The response from the service.
        :rtype: :class:`.xso.OwnerRequest`

        The affiliations are returned as :class:`.xso.OwnerRequest` instance
        whose :attr:`~.xso.OwnerRequest.payload` is a
        :class:`.xso.OwnerAffiliations` instance.
        """
        iq = aioxmpp.stanza.IQ(
            type_=aioxmpp.structs.IQType.GET,
            to=jid,
            payload=pubsub_xso.OwnerRequest(
                pubsub_xso.OwnerAffiliations(node),
            )
        )

        return (yield from self.client.send(iq))

    @asyncio.coroutine
    def get_node_subscriptions(self, jid, node):
        """
        Return the subscriptions of other jids with a node.

        :param jid: Address of the PubSub service.
        :type jid: :class:`aioxmpp.JID`
        :param node: Name of the node to query
        :type node: :class:`str`
        :raises aioxmpp.errors.XMPPError: as returned by the service
        :return: The response from the service.
        :rtype: :class:`.xso.OwnerRequest`

        The subscriptions are returned as :class:`.xso.OwnerRequest` instance
        whose :attr:`~.xso.OwnerRequest.payload` is a
        :class:`.xso.OwnerSubscriptions` instance.
        """
        iq = aioxmpp.stanza.IQ(
            type_=aioxmpp.structs.IQType.GET,
            to=jid,
            payload=pubsub_xso.OwnerRequest(
                pubsub_xso.OwnerSubscriptions(node),
            )
        )

        return (yield from self.client.send(iq))

    @asyncio.coroutine
    def change_node_affiliations(self, jid, node, affiliations_to_set):
        """
        Update the affiliations at a node.

        :param jid: Address of the PubSub service.
        :type jid: :class:`aioxmpp.JID`
        :param node: Name of the node to modify
        :type node: :class:`str`
        :param affiliations_to_set: The affiliations to set at the node.
        :type affiliations_to_set: :class:`~collections.abc.Iterable` of tuples
            consisting of the JID to affiliate and the affiliation to use.
        :raises aioxmpp.errors.XMPPError: as returned by the service

        `affiliations_to_set` must be an iterable of pairs (`jid`,
        `affiliation`), where the `jid` indicates the JID for which the
        `affiliation` is to be set.
        """
        iq = aioxmpp.stanza.IQ(
            type_=aioxmpp.structs.IQType.SET,
            to=jid,
            payload=pubsub_xso.OwnerRequest(
                pubsub_xso.OwnerAffiliations(
                    node,
                    affiliations=[
                        pubsub_xso.OwnerAffiliation(
                            jid,
                            affiliation
                        )
                        for jid, affiliation in affiliations_to_set
                    ]
                )
            )
        )

        yield from self.client.send(iq)

    @asyncio.coroutine
    def change_node_subscriptions(self, jid, node, subscriptions_to_set):
        """
        Update the subscriptions at a node.

        :param jid: Address of the PubSub service.
        :type jid: :class:`aioxmpp.JID`
        :param node: Name of the node to modify
        :type node: :class:`str`
        :param subscriptions_to_set: The subscriptions to set at the node.
        :type subscriptions_to_set: :class:`~collections.abc.Iterable` of
            tuples consisting of the JID to (un)subscribe and the subscription
            level to use.
        :raises aioxmpp.errors.XMPPError: as returned by the service

        `subscriptions_to_set` must be an iterable of pairs (`jid`,
        `subscription`), where the `jid` indicates the JID for which the
        `subscription` is to be set.
        """
        iq = aioxmpp.stanza.IQ(
            type_=aioxmpp.structs.IQType.SET,
            to=jid,
            payload=pubsub_xso.OwnerRequest(
                pubsub_xso.OwnerSubscriptions(
                    node,
                    subscriptions=[
                        pubsub_xso.OwnerSubscription(
                            jid,
                            subscription
                        )
                        for jid, subscription in subscriptions_to_set
                    ]
                )
            )
        )

        yield from self.client.send(iq)

    @asyncio.coroutine
    def purge(self, jid, node):
        """
        Delete all items from a node.

        :param jid: JID of the PubSub service
        :param node: Name of the PubSub node
        :type node: :class:`str`

        Requires :attr:`.xso.Feature.PURGE`.
        """

        iq = aioxmpp.stanza.IQ(
            type_=aioxmpp.structs.IQType.SET,
            to=jid,
            payload=pubsub_xso.OwnerRequest(
                pubsub_xso.OwnerPurge(
                    node
                )
            )
        )

        yield from self.client.send(iq)
