# Source code for aioxmpp.disco.service

    ########################################################################
    # 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 contextlib
    import functools
    import itertools

    import aioxmpp.cache
    import aioxmpp.callbacks
    import aioxmpp.errors as errors
    import aioxmpp.service as service
    import aioxmpp.structs as structs
    import aioxmpp.stanza as stanza

    from aioxmpp.utils import namespaces

    from . import xso as disco_xso

    class Node(object):
        """
        A :class:`Node` holds the information related to a specific node within the
        entity referred to by a JID, with respect to :xep:`30` semantics.

        A :class:`Node` always has at least one identity (or it will return
        as ``<item-not-found/>``). It may have zero or more features beyond the
        :xep:`30` features which are statically included.

        To manage the identities and the features of a node, use the following
        methods:

        .. automethod:: register_feature

        .. automethod:: unregister_feature

        .. automethod:: register_identity

        .. automethod:: set_identity_names

        .. automethod:: unregister_identity

        To access the declared features and identities, use:

        .. automethod:: iter_features

        .. automethod:: iter_identities

        .. automethod:: as_info_xso

        To access items, use:

        .. automethod:: iter_items

        Signals provide information about changes:

        .. signal:: on_info_changed()

           This signal emits when a feature or identity is registered or
           unregistered.

        As mentioned, bare :class:`Node` objects have no items; there are
        subclasses of :class:`Node` which support items:

        ======================  ==================================================
        :class:`StaticNode`     Support for a list of :class:`.xso.Item` instances
        :class:`.DiscoServer`   Support for "mountpoints" for node subtrees
        ======================  ==================================================

        """
        STATIC_FEATURES = frozenset({namespaces.xep0030_info})

        on_info_changed = aioxmpp.callbacks.Signal()

        def __init__(self):
            super().__init__()
            self._identities = {}
            self._features = set()

        def iter_identities(self, stanza=None):
            """
            Return an iterator of tuples describing the identities of the node.

            :param stanza: The IQ request stanza
            :type stanza: :class:`~aioxmpp.IQ` or :data:`None`
            :rtype: iterable of (:class:`str`, :class:`str`, :class:`str` or
                :data:`None`, :class:`str` or :data:`None`) tuples
            :return: :xep:`30` identities of this node

            `stanza` can be the :class:`aioxmpp.IQ` stanza of the request. This can
            be used to hide a node depending on who is asking. If the returned
            iterable is empty, the :class:`~.DiscoServer` returns an
            ``<item-not-found/>`` error.

            `stanza` may be :data:`None` if the identities are queried without
            a specific request context. In that case, implementors should assume
            that the result is visible to everybody.

            .. note::

               Subclasses must allow :data:`None` for `stanza` and default it to
               :data:`None`.

            Return an iterator which yields tuples consisting of the category, the
            type, the language code and the name of each identity declared in this
            :class:`Node`.

            Both the language code and the name may be :data:`None`, if no names or
            a name without language code have been declared.
            """
            for (category, type_), names in self._identities.items():
                for lang, name in names.items():
                    yield category, type_, lang, name
                if not names:
                    yield category, type_, None, None

        def iter_features(self, stanza=None):
            """
            Return an iterator which yields the features of the node.

            :param stanza: The IQ request stanza
            :type stanza: :class:`~aioxmpp.IQ`
            :rtype: iterable of :class:`str`
            :return: :xep:`30` features of this node

            `stanza` is the :class:`aioxmpp.IQ` stanza of the request. This can be
            used to filter the list according to who is asking (not recommended).

            `stanza` may be :data:`None` if the features are queried without
            a specific request context. In that case, implementors should assume
            that the result is visible to everybody.

            .. note::

               Subclasses must allow :data:`None` for `stanza` and default it to
               :data:`None`.

            The features are returned as strings. The features demanded by
            :xep:`30` are always returned.

            """
            return itertools.chain(
                iter(self.STATIC_FEATURES),
                iter(self._features)
            )

        def iter_items(self, stanza=None):
            """
            Return an iterator which yields the items of the node.

            :param stanza: The IQ request stanza
            :type stanza: :class:`~aioxmpp.IQ`
            :rtype: iterable of :class:`~.disco.xso.Item`
            :return: Items of the node

            `stanza` is the :class:`aioxmpp.IQ` stanza of the request. This can be
            used to localize the list to the language of the stanza or filter it
            according to who is asking.

            `stanza` may be :data:`None` if the items are queried without
            a specific request context. In that case, implementors should assume
            that the result is visible to everybody.

            .. note::

               Subclasses must allow :data:`None` for `stanza` and default it to
               :data:`None`.

            A bare :class:`Node` cannot hold any items and will thus return an
            iterator which does not yield any element.
            """
            return iter([])

        def register_feature(self, var):
            """
            Register a feature with the namespace variable `var`.

            If the feature is already registered or part of the default :xep:`30`
            features, a :class:`ValueError` is raised.
            """
            if var in self._features or var in self.STATIC_FEATURES:
                raise ValueError("feature already claimed: {!r}".format(var))
            self._features.add(var)
            self.on_info_changed()

        def register_identity(self, category, type_, *, names={}):
            """
            Register an identity with the given `category` and `type_`.

            If there is already a registered identity with the same `category` and
            `type_`, :class:`ValueError` is raised.

            `names` may be a mapping which maps :class:`.structs.LanguageTag`
            instances to strings. This mapping will be used to produce
            ``<identity/>`` declarations with the respective ``xml:lang`` and
            ``name`` attributes.
            """
            key = category, type_
            if key in self._identities:
                raise ValueError("identity already claimed: {!r}".format(key))
            self._identities[key] = names
            self.on_info_changed()

        def set_identity_names(self, category, type_, names={}):
            """
            Update the names of an identity.

            :param category: The category of the identity to update.
            :type category: :class:`str`
            :param type_: The type of the identity to update.
            :type type_: :class:`str`
            :param names: The new internationalised names to set for the identity.
            :type names: :class:`~.abc.Mapping` from
                :class:`.structs.LanguageTag` to :class:`str`
            :raises ValueError: if no identity with the given category and type
                is currently registered.
            """
            key = category, type_
            if key not in self._identities:
                raise ValueError("identity not registered: {!r}".format(key))
            self._identities[key] = names
            self.on_info_changed()

        def unregister_feature(self, var):
            """
            Unregister a feature which has previously been registered using
            :meth:`register_feature`.

            If the feature has not been registered previously, :class:`KeyError` is
            raised.

            .. note::

               The features which are mandatory per :xep:`30` are always registered
               and cannot be unregistered. For the purpose of unregistration, they
               behave as if they had never been registered; for the purpose of
               registration, they behave as if they had been registered before.

            """
            self._features.remove(var)
            self.on_info_changed()

        def unregister_identity(self, category, type_):
            """
            Unregister an identity previously registered using
            :meth:`register_identity`.

            If no identity with the given `category` and `type_` has been
            registered before, :class:`KeyError` is raised.

            If the identity to remove is the last identity of the :class:`Node`,
            :class:`ValueError` is raised; a node must always have at least one
            identity.
            """
            key = category, type_
            if key not in self._identities:
                raise KeyError(key)
            if len(self._identities) == 1:
                raise ValueError("cannot remove last identity")
            del self._identities[key]
            self.on_info_changed()

        def as_info_xso(self, stanza=None):
            """
            Construct a :class:`~.disco.xso.InfoQuery` response object for this
            node.

            :param stanza: The IQ request stanza
            :type stanza: :class:`~aioxmpp.IQ`
            :rtype: iterable of :class:`~.disco.xso.InfoQuery`
            :return: The disco#info response for this node.

            The resulting :class:`~.disco.xso.InfoQuery` carries the features and
            identities as returned by :meth:`iter_features` and
            :meth:`iter_identities`. The :attr:`~.disco.xso.InfoQuery.node`
            attribute is at its default value and may need to be set by the caller
            accordingly.

            `stanza` is passed to :meth:`iter_features` and
            :meth:`iter_identities`. See those methods for information on the
            effects.

            .. versionadded:: 0.9
            """

            result = disco_xso.InfoQuery()
            result.features.update(self.iter_features(stanza))
            result.identities[:] = (
                disco_xso.Identity(
                    category=category,
                    type_=type_,
                    lang=lang,
                    name=name,
                )
                for category, type_, lang, name in self.iter_identities(stanza)
            )
            return result

    class StaticNode(Node):
        """
        A :class:`StaticNode` is a :class:`Node` with a non-dynamic set of items.

        .. attribute:: items

           A list of :class:`.xso.Item` instances. These items will be returned
           when the node is queried for it’s :xep:`30` items.

           It is the responsibility of the user to ensure that the set of items is
           valid. This includes avoiding duplicate items.

        .. automethod:: clone

        """

        def __init__(self):
            super().__init__()
            self.items = []

        def iter_items(self, stanza=None):
            return iter(self.items)

        @classmethod
        def clone(cls, other_node):
            """
            Clone another :class:`Node` and return as :class:`StaticNode`.

            :param other_node: The node which shall be cloned
            :type other_node: :class:`Node`
            :rtype: :class:`StaticNode`
            :return: A static node which has the exact same features, identities
                and items as `other_node`.

            The features and identities are copied over into the resulting
            :class:`StaticNode`. The items of `other_node` are not copied but
            merely referenced, so changes to the item *objects* of `other_node`
            will be reflected in the result.

            .. versionadded:: 0.9
            """

            result = cls()
            result._features = {
                feature for feature in other_node.iter_features()
                if feature not in cls.STATIC_FEATURES
            }
            for category, type_, lang, name in other_node.iter_identities():
                names = result._identities.setdefault(
                    (category, type_),
                    aioxmpp.structs.LanguageMap()
                )
                names[lang] = name
            result.items = list(other_node.iter_items())
            return result

    class DiscoServer(service.Service, Node):
        """
        Answer Service Discovery (:xep:`30`) requests sent to this client.

        This service implements handlers for ``…disco#info`` and ``…disco#items``
        IQ requests. It provides methods to configure the contents of these
        responses.

        .. seealso::

           :class:`DiscoClient`
              for a service which provides methods to query Service Discovery
              information from other entities.

        The :class:`DiscoServer` inherits from :class:`~.disco.Node` to manage the
        identities and features of the client. The identities and features declared
        in the service using the :class:`~.disco.Node` interface on the
        :class:`DiscoServer` instance are returned when a query is received for the
        JID with an empty or unset ``node`` attribute. For completeness, the
        relevant methods are listed here. Refer to the :class:`~.disco.Node`
        documentation for details.

        .. autosummary::

           .disco.Node.register_feature
           .disco.Node.unregister_feature
           .disco.Node.register_identity
           .disco.Node.unregister_identity

        .. note::

           Upon construction, the :class:`DiscoServer` adds a default identity with
           category ``"client"`` and type ``"bot"`` to the root
           :class:`~.disco.Node`. This is to comply with :xep:`30`, which specifies
           that at least one identity must always be returned. Otherwise, the
           service would be forced to send a malformed response or reply with
           ``<feature-not-implemented/>``.

           After having added another identity, that default identity can be
           removed.

        Other :class:`~.disco.Node` instances can be registered with the service
        using the following methods:

        .. automethod:: mount_node

        .. automethod:: unmount_node

        """

        on_info_result = aioxmpp.callbacks.Signal()

        def __init__(self, client, **kwargs):
            super().__init__(client, **kwargs)

            self._node_mounts = {
                None: self
            }

            self.register_identity(
                "client", "bot",
                names={
                    structs.LanguageTag.fromstr("en"): "aioxmpp default identity"
                }
            )

        @aioxmpp.service.iq_handler(
            aioxmpp.structs.IQType.GET,
            disco_xso.InfoQuery)
        @asyncio.coroutine
        def handle_info_request(self, iq):
            request = iq.payload

            try:
                node = self._node_mounts[request.node]
            except KeyError:
                raise errors.XMPPModifyError(
                    condition=errors.ErrorCondition.ITEM_NOT_FOUND
                )

            response = node.as_info_xso(iq)
            response.node = request.node

            if not response.identities:
                raise errors.XMPPModifyError(
                    condition=errors.ErrorCondition.ITEM_NOT_FOUND,
                )

            return response

        @aioxmpp.service.iq_handler(
            aioxmpp.structs.IQType.GET,
            disco_xso.ItemsQuery)
        @asyncio.coroutine
        def handle_items_request(self, iq):
            request = iq.payload

            try:
                node = self._node_mounts[request.node]
            except KeyError:
                raise errors.XMPPModifyError(
                    condition=errors.ErrorCondition.ITEM_NOT_FOUND
                )

            response = disco_xso.ItemsQuery()
            response.items.extend(node.iter_items(iq))

            return response

        def mount_node(self, mountpoint, node):
            """
            Mount the :class:`Node` `node` to be returned when a peer requests
            :xep:`30` information for the node `mountpoint`.
            """
            self._node_mounts[mountpoint] = node

        def unmount_node(self, mountpoint):
            """
            Unmount the node mounted at `mountpoint`.

            .. seealso::

               :meth:`mount_node`
                  for a way for mounting :class:`~.disco.Node` instances.

            """
            del self._node_mounts[mountpoint]

    class DiscoClient(service.Service):
        """
        Provide cache-backed Service Discovery (:xep:`30`) queries.

        This service provides methods to query Service Discovery information from
        other entities in the XMPP network. The results are cached transparently.

        .. seealso::

           :class:`.DiscoServer`
              for a service which answers Service Discovery queries sent to the
              client by other entities.
           :class:`.EntityCapsService`
              for a service which uses :xep:`115` to fill the cache of the
              :class:`DiscoClient` with offline information.

        Querying other entities’ service discovery information:

        .. automethod:: query_info

        .. automethod:: query_items

        To prime the cache with information, the following methods can be used:

        .. automethod:: set_info_cache

        .. automethod:: set_info_future

        To control the size of caches, the following properties are available:

        .. autoattribute:: info_cache_size
           :annotation: = 10000

        .. autoattribute:: items_cache_size
           :annotation: = 100

        .. automethod:: flush_cache

        Usage example, assuming that you have a :class:`.node.Client` `client`::

          import aioxmpp.disco as disco
          # load service into node
          sd = client.summon(aioxmpp.DiscoClient)

          # retrieve server information
          server_info = yield from sd.query_info(
              node.local_jid.replace(localpart=None, resource=None)
          )

          # retrieve resources
          resources = yield from sd.query_items(
              node.local_jid.bare()
          )

        """

        on_info_result = aioxmpp.callbacks.Signal()

        def __init__(self, client, **kwargs):
            super().__init__(client, **kwargs)

            self._info_pending = aioxmpp.cache.LRUDict()
            self._info_pending.maxsize = 10000
            self._items_pending = aioxmpp.cache.LRUDict()
            self._items_pending.maxsize = 100

            self.client.on_stream_destroyed.connect(
                self._clear_cache
            )

        @property
        def info_cache_size(self):
            """
            Maximum number of cache entries in the cache for :meth:`query_info`.

            This is mostly a measure to prevent malicious peers from exhausting
            memory by spamming :mod:`aioxmpp.entitycaps` capability hashes.

            .. versionadded:: 0.9
            """
            return self._info_pending.maxsize

        @info_cache_size.setter
        def info_cache_size(self, value):
            self._info_pending.maxsize = value

        @property
        def items_cache_size(self):
            """
            Maximum number of cache entries in the cache for :meth:`query_items`.

            .. versionadded:: 0.9
            """
            return self._items_pending.maxsize

        @items_cache_size.setter
        def items_cache_size(self, value):
            self._items_pending.maxsize = value

        def _clear_cache(self):
            for fut in self._info_pending.values():
                if not fut.done():
                    fut.cancel()
            self._info_pending.clear()

            for fut in self._items_pending.values():
                if not fut.done():
                    fut.cancel()
            self._items_pending.clear()

        def _handle_info_received(self, jid, node, task):
            try:
                result = task.result()
            except Exception:
                return
            self.on_info_result(jid, node, result)

        def flush_cache(self):
            """
            Clear the cache.

            This clears the internal cache in a way which lets existing queries
            continue, but the next query for each target will behave as if
            `require_fresh` had been set to true.
            """
            self._info_pending.clear()
            self._items_pending.clear()

        @asyncio.coroutine
        def send_and_decode_info_query(self, jid, node):
            request_iq = stanza.IQ(to=jid, type_=structs.IQType.GET)
            request_iq.payload = disco_xso.InfoQuery(node=node)

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

            return response

        @asyncio.coroutine
        def query_info(self, jid, *,
                       node=None, require_fresh=False, timeout=None,
                       no_cache=False):
            """
            Query the features and identities of the specified entity.

            :param jid: The entity to query.
            :type jid: :class:`aioxmpp.JID`
            :param node: The node to query.
            :type node: :class:`str` or :data:`None`
            :param require_fresh: Boolean flag to discard previous caches.
            :type require_fresh: :class:`bool`
            :param timeout: Optional timeout for the response.
            :type timeout: :class:`float`
            :param no_cache: Boolean flag to forbid caching of the request.
            :type no_cache: :class:`bool`
            :rtype: :class:`.xso.InfoQuery`
            :return: Service discovery information of the `node` at `jid`.

            The requests are cached. This means that only one request is ever fired
            for a given target (identified by the `jid` and the `node`). The
            request is re-used for all subsequent requests to that identity.

            If `require_fresh` is set to true, the above does not hold and a fresh
            request is always created. The new request is the request which will be
            used as alias for subsequent requests to the same identity.

            The visible effects of this are twofold:

            * Caching: Results of requests are implicitly cached
            * Aliasing: Two concurrent requests will be aliased to one request to
              save computing resources

            Both can be turned off by using `require_fresh`. In general, you should
            not need to use `require_fresh`, as all requests are implicitly
            cancelled whenever the underlying session gets destroyed.

            `no_cache` can be set to true to prevent future requests to be aliased
            to this request, i.e. the request is not stored in the internal request
            cache. This does not affect `require_fresh`, i.e. if a cached result is
            available, it is used.

            The `timeout` can be used to restrict the time to wait for a
            response. If the timeout triggers, :class:`TimeoutError` is raised.

            If :meth:`~.Client.send` raises an
            exception, all queries which were running simultanously for the same
            target re-raise that exception. The result is not cached though. If a
            new query is sent at a later point for the same target, a new query is
            actually sent, independent of the value chosen for `require_fresh`.

            .. versionchanged:: 0.9

                The `no_cache` argument was added.
            """
            key = jid, node

            if not require_fresh:
                try:
                    request = self._info_pending[key]
                except KeyError:
                    pass
                else:
                    try:
                        return (yield from request)
                    except asyncio.CancelledError:
                        pass

            request = asyncio.ensure_future(
                self.send_and_decode_info_query(jid, node)
            )
            request.add_done_callback(
                functools.partial(
                    self._handle_info_received,
                    jid,
                    node
                )
            )

            if not no_cache:
                self._info_pending[key] = request
            try:
                if timeout is not None:
                    try:
                        result = yield from asyncio.wait_for(
                            request,
                            timeout=timeout)
                    except asyncio.TimeoutError:
                        raise TimeoutError()
                else:
                    result = yield from request
            except:  # NOQA
                if request.done():
                    try:
                        pending = self._info_pending[key]
                    except KeyError:
                        pass
                    else:
                        if pending is request:
                            del self._info_pending[key]
                raise

            return result

        @asyncio.coroutine
        def query_items(self, jid, *,
                        node=None, require_fresh=False, timeout=None):
            """
            Query the items of the specified entity.

            :param jid: The entity to query.
            :type jid: :class:`aioxmpp.JID`
            :param node: The node to query.
            :type node: :class:`str` or :data:`None`
            :param require_fresh: Boolean flag to discard previous caches.
            :type require_fresh: :class:`bool`
            :param timeout: Optional timeout for the response.
            :type timeout: :class:`float`
            :rtype: :class:`.xso.ItemsQuery`
            :return: Service discovery items of the `node` at `jid`.

            The arguments have the same semantics as with :meth:`query_info`, as
            does the caching and error handling.
            """
            key = jid, node

            if not require_fresh:
                try:
                    request = self._items_pending[key]
                except KeyError:
                    pass
                else:
                    try:
                        return (yield from request)
                    except asyncio.CancelledError:
                        pass

            request_iq = stanza.IQ(to=jid, type_=structs.IQType.GET)
            request_iq.payload = disco_xso.ItemsQuery(node=node)

            request = asyncio.ensure_future(
                self.client.send(request_iq)
            )

            self._items_pending[key] = request
            try:
                if timeout is not None:
                    try:
                        result = yield from asyncio.wait_for(
                            request,
                            timeout=timeout)
                    except asyncio.TimeoutError:
                        raise TimeoutError()
                else:
                    result = yield from request
            except:  # NOQA
                if request.done():
                    try:
                        pending = self._items_pending[key]
                    except KeyError:
                        pass
                    else:
                        if pending is request:
                            del self._items_pending[key]
                raise

            return result

        def set_info_cache(self, jid, node, info):
            """
            This is a wrapper around :meth:`set_info_future` which creates a future
            and immediately assigns `info` as its result.

            .. versionadded:: 0.5
            """
            fut = asyncio.Future()
            fut.set_result(info)
            self.set_info_future(jid, node, fut)

        def set_info_future(self, jid, node, fut):
            """
            Override the cache entry (if one exists) for :meth:`query_info` of the
            `jid` and `node` combination with the given :class:`asyncio.Future`
            fut.

            The future must receive a :class:`dict` compatible to the output of
            :meth:`.xso.InfoQuery.to_dict`.

            As usual, the cache can be bypassed and cleared by passing
            `require_fresh` to :meth:`query_info`.

            .. seealso::

               Module :mod:`aioxmpp.entitycaps`
                 :xep:`0115` implementation which uses this method to prime the
                 cache with information derived from Entity Capability
                 announcements.

            .. note::

               If a future is set to exception state, it will still remain and make
               all queries for that target fail with that exception, until a query
               uses `require_fresh`.

            .. versionadded:: 0.5
            """
            self._info_pending[jid, node] = fut

    class mount_as_node(service.Descriptor):
        """
        Service descriptor which mounts the :class:`~.service.Service` as
        :class:`.DiscoServer` node.

        :param mountpoint: The mountpoint at which to mount the node.
        :type mountpoint: :class:`str`

        .. versionadded:: 0.8

        When the service is instaniated, it is mounted as :class:`~.disco.Node` at
        the given `mountpoint`; it must thus also inherit from
        :class:`~.disco.Node` or implement a compatible interface.

        .. autoattribute:: mountpoint
        """

        def __init__(self, mountpoint):
            super().__init__()
            self._mountpoint = mountpoint

        @property
        def mountpoint(self):
            """
            The mountpoint at which the node is mounted.
            """
            return self._mountpoint

        @property
        def required_dependencies(self):
            return [DiscoServer]

        @contextlib.contextmanager
        def init_cm(self, instance):
            disco = instance.dependencies[DiscoServer]
            disco.mount_node(self._mountpoint, instance)
            try:
                yield
            finally:
                disco.unmount_node(self._mountpoint)

        @property
        def value_type(self):
            return type(None)

    class RegisteredFeature:
        """
        Manage registration of a feature with a :class:`DiscoServer`.

        :param service: The service implementing the service discovery server.
        :type service: :class:`DiscoServer`
        :param feature: The feature to register.
        :type feature: :class:`str`

        .. note::

            Normally, you would not create an instance of this object manually.
            Use the :class:`register_feature` descriptor on your
            :class:`aioxmpp.Service` which will provide a
            :class:`RegisteredFeature` object::

                class Foo(aioxmpp.Service):
                    _some_feature = aioxmpp.disco.register_feature(
                        "urn:of:the:feature"
                    )

                    # after __init__, self._some_feature is a RegisteredFeature
                    # instance.

                    @property
                    def some_feature_enabled(self):
                        # better do not expose the enabled boolean directly; this
                        # gives you the opportunity to do additional things when it
                        # is changed, such as disabling multiple features at once.
                        return self._some_feature.enabled

                    @some_feature_enabled.setter
                    def some_feature_enabled(self, value):
                        self._some_feature.enabled = value

        .. versionadded:: 0.9

        This object can be used as a context manager. Upon entering the context,
        the feature is registered. When the context is left, the feature is
        unregistered.

        .. note::

            The context-manager use does not nest sensibly. Thus, do not use
            th context-manager feature on :class:`RegisteredFeature` instances
            which are created by :class:`register_feature`, as
            :class:`register_feature` uses the context manager to
            register/unregister the feature on initialisation/shutdown.

        Independently, it is possible to control the registration status of the
        feature using :attr:`enabled`.

        .. autoattribute:: enabled

        .. autoattribute:: feature

        """

        def __init__(self, service, feature):
            self.__service = service
            self.__feature = feature
            self.__enabled = False

        @property
        def enabled(self):
            """
            Boolean indicating whether the feature is registered by this object
            or not.

            When this attribute is changed to :data:`True`, the feature is
            registered. When the attribute is changed to :data:`False`, the feature
            is unregisterd.
            """
            return self.__enabled

        @enabled.setter
        def enabled(self, value):
            value = bool(value)
            if value == self.__enabled:
                return

            if value:
                self.__service.register_feature(self.__feature)
            else:
                self.__service.unregister_feature(self.__feature)

            self.__enabled = value

        @property
        def feature(self):
            """
            The feature this object is controlling (read-only).
            """
            return self.__feature

        def __enter__(self):
            self.enabled = True
            return self

        def __exit__(self, exc_type, exc_value, tb):
            self.enabled = False

    class register_feature(service.Descriptor):
        """
        Service descriptor which registers a service discovery feature.

        :param feature: The feature to register.
        :type feature: :class:`str`

        .. versionadded:: 0.8

        When the service is instaniated, the `feature` is registered at the
        :class:`~.DiscoServer`.

        On instances, the attribute which is described with this is a
        :class:`RegisteredFeature` instance.

        .. versionchanged:: 0.9

            :class:`RegisteredFeature` was added; before, the attribute reads as
            :data:`None`.
        """

        def __init__(self, feature):
            super().__init__()
            self._feature = feature

        @property
        def feature(self):
            """
            The feature which is registered.
            """
            return self._feature

        @property
        def required_dependencies(self):
            return [DiscoServer]

        def init_cm(self, instance):
            disco = instance.dependencies[DiscoServer]
            return RegisteredFeature(disco, self._feature)

        @property
        def value_type(self):
            return RegisteredFeature