This module provides support for XEP-0030 (Service Discovery). For this, it provides a Service subclass which can be loaded into a client using AbstractClient.summon().
A service implementing XEP-0030. The service provides methods for managing the own features and identities as well as querying others features and identities.
Querying other entities’ service discovery information:
Query the features and identities of the specified entity. The entity is identified by the jid and the optional node.
Return the xso.InfoQuery instance returned by the peer. If an error is returned, that error is raised as errors.XMPPError.
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:
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.
timeout is passed to StanzaStream.send_iq_and_wait_for_reply().
Services inherit from Node to manage the identities and features of the JID itself. The identities and features declared in the service using the Node interface on the Service 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 Node documentation for details.
| Node.register_feature(var) | Register a feature with the namespace variable var. |
| Node.unregister_feature(var) | Unregister a feature which has previously been registered using register_feature(). |
| Node.register_identity(category, type_, *[, ...]) | Register an identity with the given category and type_. |
| Node.unregister_identity(category, type_) | Unregister an identity previously registered using register_identity(). |
Note
Upon construction, the Service adds a default identity with category "client" and type "bot" to the root Node. This is to comply with XEP-0030 of always having an identity and not being forced to reply with <feature-not-implemented/> or a similar error.
After having added another identity, that default identity can be removed.
Usage example, assuming that you have a node.AbstractClient node:
import aioxmpp.disco as disco
# load service into node
sd = node.summon(disco.Service)
# 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()
)
A Node holds the information related to a specific node within the entity referred to by a JID, with respect to XEP-0030 semantics.
A 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-0030 features which are statically included.
To manage the identities and the features of a node, use the following methods:
Register a feature with the namespace variable var.
If the feature is already registered or part of the default XEP-0030 features, a ValueError is raised.
Unregister a feature which has previously been registered using register_feature().
If the feature has not been registered previously, KeyError is raised.
Note
The features which are mandatory per XEP-0030 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.
Register an identity with the given category and type_.
If there is already a registered identity with the same category and type_, ValueError is raised.
names may be a mapping which maps structs.LanguageTag instances to strings. This mapping will be used to produce <identity/> declarations with the respective xml:lang and name attributes.
Unregister an identity previously registered using register_identity().
If no identity with the given category and type_ has been registered before, KeyError is raised.
If the identity to remove is the last identity of the Node, ValueError is raised; a node must always have at least one identity.
To access the declared features and identities, use:
Return an iterator which yields the var values of each feature declared in this Node, including the statically declared XEP-0030 features.
Return an iterator which yields tuples consisting of the category, the type, the language code and the name of each identity declared in this Node.
Both the language code and the name may be None, if no names or a name without language code have been declared.
To access items, use:
Return an iterator which yields the xso.Item objects which this node holds.
A bare Node cannot hold any items and will thus return an iterator which does not yield any element.
As mentioned, bare Node objects have no items; there are subclasses of Node which support items:
| StaticNode | Support for a list of xso.Item instances |
| Service | Support for “mountpoints” for node subtrees |
A StaticNode is a Node with a non-dynamic set of items.
The submodule aioxmpp.disco.xso contains the XSO classes which describe the IQ payloads used by this subpackage.
You will encounter some of these in return values, but there should never be a need to construct them by yourself; the Service handles it all.
A query for features and identities of an entity. The keyword arguments to the constructor can be used to initialize the attributes. Note that identities and features must be iterables of Identity and Feature, respectively; these iterables are evaluated and the items are stored in the respective attributes.
The node at which the query is directed.
A feature declaration. The keyword argument to the constructor can be used to initialize the attribute of the Feature instance.
The namespace which identifies the feature.
An identity declaration. The keyword arguments to the constructor can be used to initialize attributes of the Identity instance.
A query for items at a specific entity. The keyword arguments to the constructor can be used to initialize the attributes of the ItemsQuery. Note that items must be an iterable of Item instances. The iterable will be evaluated and the items will be stored in the items attribute.
Node at which the query is directed
The items at the addressed entity.