# `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:

  `publish`(node, data, *, id_=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.

    Returns: | The PubSub id of the published item or `None` if it is unknown.
    Raises: | RuntimeError – if PEP is not supported.

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

  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 instanciate 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`.