entitycaps — Entity Capabilities support (XEP-0115)

This module provides support for XEP-0115 (Entity Capabilities). To use it, summon the Service on a AbstractClient. See the service documentation for more information.

New in version 0.5.

Service

class aioxmpp.entitycaps.Service(node)

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

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.

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

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 ver of the local client changes. This happens when the set of features or identities announced in the disco.Service 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.

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(hash_, node)

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(hash_, node)

coroutine lookup(hash_, node)

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.

entitycaps.xso — Presence payload

The submodule aioxmpp.entitycaps.xso contains the XSO subclasses which describe the presence payload used by the implementation.

In general, you will not need to use these classes directly, nor encounter them, as the service filters them off the presence stanzas. If the filter is not loaded, the Caps instance is available at stanza.Presence.xep0115_caps.

class aioxmpp.entitycaps.xso.Caps(node, ver, hash_)

An entity capabilities extension for Presence.

node

The indicated node, for use with the corresponding info query.

hash_

The hash algorithm used. This is None if the legacy format is used.

ver

The version (in the legacy format) or the calculated hash.

ext

Only there for backwards compatibility. Not used anymore.