# `entitycaps` — Entity Capabilities support (XEP-0390, XEP-0115)

This module provides support for XEP-0115 (Entity Capabilities) and XEP-0390 (Entity Capabilities 2.0). To use it, `Client.summon()` the `aioxmpp.EntityCapsService` on a `Client`. See the service documentation for more information.

New in version 0.5.

Changed in version 0.9: Support for XEP-0390 was added.

## Service

class aioxmpp.EntityCapsService(node, **kwargs)

  Make use and provide service discovery information in presence broadcasts.

  This service implements XEP-0115 and XEP-0390, transparently. Besides loading the service, no interaction is required to get some of the benefits of XEP-0115 and XEP-0390.

  Two additional things need to be done by users to get full support and performance:

  1. To make sure that peers are always up-to-date with the current capabilities, it is required that users listen on the `on_ver_changed()` signal and re-emit their current presence when it fires.

     Note

     Keeping peers up-to-date is a MUST in XEP-0390.

     The service takes care of attaching capabilities information on the outgoing stanza, using a stanza filter.

     Warning

     `on_ver_changed()` may be emitted at a considerable rate when services are loaded or certain features (such as PEP-based services) are configured. It is up to the application to limit the rate at which presences are sent for the sole purpose of updating peers with new capability information.

  2. Users should use a process-wide `Cache` instance and assign it to the `cache` of each `entitycaps.Service` they use. This improves performance by sharing (verified) hashes among `Service` instances.

     In addition, the hashes should be saved and restored on shutdown/start of the process. See the `Cache` for details.

  signal on_ver_changed()

    The signal emits whenever the Capability Hashset of the local client changes. This happens when the set of features or identities announced in the `DiscoServer` changes.

  cache

    The `Cache` instance used for this `Service`. Deleting this attribute will automatically create a new `Cache` instance.

    The attribute can be used to share a single `Cache` among multiple `Service` instances.

  xep115_support

    Boolean to control whether XEP-0115 support is enabled or not.

    Defaults to `True`.

    If set to false, inbound XEP-0115 capabilities will not be processed and no XEP-0115 capabilities will be emitted.

    Note

    At some point, this will default to `False` to save bandwidth. The exact release depends on the adoption of XEP-0390 and will be announced in time. If you depend on XEP-0115 support, set this boolean to `True`.

    The attribute itself will not be removed until XEP-0115 support is removed from `aioxmpp` entirely, which is unlikely to happen any time soon.

    New in version 0.9.

  xep390_support

    Boolean to control whether XEP-0390 support is enabled or not.

    Defaults to `True`.

    If set to false, inbound XEP-0390 Capability Hash Sets will not be processed and no Capability Hash Sets or Capability Nodes will be generated.

    The hash algorithms used for generating Capability Hash Sets are those from `aioxmpp.hashes.default_hash_algorithms`.

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

  Changed in version 0.9: Support for XEP-0390 was added.

class aioxmpp.entitycaps.Service

  Alias of `EntityCapsService`.

  Deprecated since version 0.8: The alias will be removed in 1.0.

class aioxmpp.entitycaps.Cache

  This provides a two-level cache for entity capabilities information. The idea is to have a trusted database, e.g. installed system-wide or shipped with `aioxmpp` and in addition a user-level database which is automatically filled with hashes which have been found by the `Service`.

  The trusted database is taken as read-only and overrides the user-collected database. When a hash is in both databases, it is removed from the user-collected database (to save space).

  In addition to serving the databases, it provides deduplication for queries by holding a cache of futures looking up the same hash.

  Database management (user API):

  set_system_db_path(path)
  set_user_db_path(path)

  Queries (API intended for `Service`):

  create_query_future(key)

    Create and return a `asyncio.Future` for the given hash_ function and node URL. The future is referenced internally and used by any calls to `lookup()` which are made while the future is pending. The future is removed from the internal storage automatically when a result or exception is set for it.

    This allows for deduplication of queries for the same hash.

  lookup_in_database(key)
  async lookup(key)

    Look up the given node URL using the given hash_ first in the database and then by waiting on the futures created with `create_query_future()` for that node URL and hash.

    If the hash is not in the database, `lookup()` iterates as long as there are pending futures for the given hash_ and node. If there are no pending futures, `KeyError` is raised. If a future raises a `ValueError`, it is ignored. If the future returns a value, it is used as the result.