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.