pep — PEP support (XEP-0163)

This module provides support for using the Personal Eventing Protocol subset of Publish-Subscribe comfortably.

This protocol does not define any XSOs since PEP reuses the protocol defined by PubSub.

Note

Splitting PEP services into client and server parts is not well supported, since only one claim per PEP node can be made.

Note

Payload classes which are to be used with PEP must be registered with aioxmpp.pubsub.xso.as_payload_class().

class aioxmpp.PEPClient(client, **kwargs)

PEPClient simplifies working with PEP services.

Changed in version 0.10: Before version 0.10, this service did not depend on aioxmpp.EntityCapsService. This was surprising to users because the PEP relies on the functionality provided by the protocols implemented by EntityCapsService to provide key features. With the release 0.10, EntityCapsService is a dependency of this service. For backward compatibility, your application should still aioxmpp.Client.summon() the EntityCapsService explicitly.

Compared to PubSubClient it supports automatic checking for server support, a stream-lined API. It is intended to make PEP things easy. If you need more fine-grained control or do things which are not usually handled by the defaults when using PEP, use PubSubClient directly.

See register_pep_node for the high-level interface for claiming a PEP node and receiving event notifications.

There also is a low-level interface for claiming nodes:

is_claimed(node)

Return whether node is claimed.

claim_pep_node(node_namespace, *, register_feature=True, notify=False)

Claim node node_namespace.

Parameters

• node_namespace – the pubsub node whose events shall be handled.

• register_feature – Whether to publish the node_namespace as feature.

• notify – Whether to register the +notify feature to receive notification without explicit subscription.

Raises

RuntimeError – if a handler for node_namespace is already set.

Returns

a RegisteredPEPNode instance representing the claim.

See also

aioxmpp.pep.register_pep_node

a descriptor which can be used with Service subclasses to claim a PEP node automatically.

This registers node_namespace as feature for service discovery unless register_feature=False is passed.

Note

For notify to work, it is required that aioxmpp.EntityCapsService is loaded and that presence is re-sent soon after on_ver_changed() fires. See the documentation of the class and the signal for details.

Further we have a convenience method for publishing items in the client’s PEP service:

async publish(node, data, *, id_=None, access_model=None)

Publish an item data in the PubSub node node on the PEP service associated with the user’s JID.

Parameters

• node – The PubSub node to publish to.

• data (An XSO representing the paylaod.) – The item to publish.

• id – The id the published item shall have.

• access_model – The access model to enforce on the node. Defaults to not enforcing any access model.

Returns

The PubSub id of the published item or None if it is unknown.

Raises

• RuntimeError – if PEP is not supported.

• RuntimeError – if access_model is set and publish_options is not supported by the server

If no id_ is given it is generated by the server (and may be returned).

access_model defines a pre-condition on the access model used for the node. The valid values depend on the service; commonly useful "presence" (the default for PEP; allows access to anyone who can receive the presence) and "whitelist" (allows access only to a whitelist (which defaults to the own account only)).

Use the aioxmpp.PubSubClient For explicit subscription and unsubscription .

class aioxmpp.pep.register_pep_node(node_namespace, *, register_feature=True, notify=False)

Service descriptor claiming a PEP node.

Parameters

• node_namespace – The PubSub payload namespace to handle.

• register_feature – Whether to register the node namespace as feature.

• notify – Whether to register for notifications.

If notify is True it registers a +notify feature, for automatic pubsub subscription.

The value of the descriptor on an instance is the RegisteredPEPNode object representing the claim.

class aioxmpp.pep.service.RegisteredPEPNode

Handle for registered PEP nodes.

Never instantiate this class yourself. Use register_pep_node or claim_pep_node to obtain instances.

You have to keep a reference to the instance to uphold the claim, when a instance is garbage collected it is closed automatically. It is not enough to have a callback registered! It is strongly recommended to explicitly close the registered node if it is no longer needed or to use the register_pep_node descriptor for automatic life-cycle handling.

signal on_item_publish(jid, node, item, message=None)

Fires when an event is received for this PEP node. The arguments are as for aioxmpp.PubSubClient.on_item_publish.

Warning

Empty notifications and notifications whose payload namespace does not match the node namespace are filtered and will not cause this signal to fire (since they do not match the PEP specification).

notify

Whether we have enabled the +notify feature to automatically receive notifications.

When setting this property the feature is registered and unregistered appropriately.

Note

For notify to work, it is required that aioxmpp.EntityCapsService is loaded and that presence is re-sent soon after on_ver_changed() fires. See the documentation of the class and the signal for details.

feature_registered

Whether we have registered the node namespace as feature.

When setting this property the feature is registered and unregistered appropriately.

close()

Unclaim the PEP node and unregister the registered features.

It is not necessary to call close if this claim is managed by register_pep_node.