pubsub — Publish-Subscribe support (XEP-0060)

This subpackage provides client-side support for XEP-0060 publish-subscribe services.

New in version 0.6.

Using Publish-Subscribe

To start using PubSub services in your application, you have to load the Service into the client, using summon().

class aioxmpp.pubsub.Service(client, **kwargs)

Client service implementing a Publish-Subscribe client. By loading it into a client, it is possible to subscribe to, publish to and otherwise interact with Publish-Subscribe nodes.

Note

Signal handlers attached to any of the signals below must accept arbitrary keyword arguments for forward compatibility. If any of the arguments is listed as positional in the signal signature, it is always present and handed as positional argument.

Subscriber use cases:

get_default_config(jid[, node])	Request the default configuration of the pubsub node hosted at jid.
get_items(jid, node, *[, max_items])	Request the most recent items from the pubsub node hosted at jid.
get_items_by_id(jid, node, ids)	Request specific items by their IDs from the pubsub node hosted at jid.
get_subscription_config(jid[, node, ...])	Request the current configuration of a subscription to the pubsub node hosted at jid.
get_subscriptions(jid[, node])	Return a xso.Subscriptions object which contains all the subscriptions of the local entity to the node located at jid.
set_subscription_config(jid, data[, node, ...])	Update the subscription configuration of a subscription to the pubsub node hosted at jid.
subscribe(jid[, node, subscription_jid, config])	Subscribe to the pubsub node hosted at jid.
unsubscribe(jid[, node, subscription_jid, subid])	Unsubscribe from the pubsub node hosted at jid.
on_affiliation_update	Fires when the affiliation with a node is updated.
on_item_published	Fires when a new item is published to a node to which we have a subscription.
on_item_retracted	Fires when an item is retracted from a node to which we have a subscription.
on_node_deleted	Fires when a node is deleted.
on_subscription_update	Fires when the subscription state is updated.

Publisher use cases:

notify(jid, node)	“Publish” to the node at jid without any item. This merely fans out
publish(jid, node, payload, *[, id_])	Publish the given payload (which must be a aioxmpp.xso.XSO registered with xso.Item.registered_payload).
retract(jid, node, id_, *[, notify])	Retract an item previously published to node at jid.

Owner use cases:

change_node_affiliations(jid, node, ...)	Update the affiliations of the pubsub node at jid.
change_node_subscriptions(jid, node, ...)	Update the subscriptions of the pubsub node at jid.
create(jid[, node])	Create a new pubsub node at the given jid.
delete(jid, node, *[, redirect_uri])	Delete an existing pubsub node at the given jid.
get_nodes(jid[, node])	Request the nodes available at jid.
get_node_affiliations(jid, node)	Return the affiliations of other jids at the pubsub node at jid.
get_node_subscriptions(jid, node)	Return the subscriptions of other jids at the pubsub node at jid.

Meta-information about the service:

coroutine get_features(jid)

Return the features as set of values from xso.Feature. To get the full feature information, resort to using disco.Service.query_info() directly on jid.

Features returned by the peer which are not valid pubsub features are not returned.

Subscribing, unsubscribing and listing subscriptions:

coroutine get_subscriptions(jid, node=None)

Return a xso.Subscriptions object which contains all the subscriptions of the local entity to the node located at jid.

If node is None, subscriptions on all nodes of the entity jid are listed.

coroutine subscribe(jid, node=None, *, subscription_jid=None, config=None)

Subscribe to the pubsub node hosted at jid.

By default, the subscription request will be for the bare JID of the client. It can be specified explicitly using the subscription_jid argument.

If the service requires it or if it makes sense for other reasons, the subscription configuration Data form can be passed using the config argument.

On success, the whole xso.Request object returned by the server is returned. It contains a xso.Subscription payload which has information on the nature of the subscription (it may be "pending" or "unconfigured") and the subid which may be required for other operations.

On failure, the corresponding XMPPError is raised.

coroutine unsubscribe(jid, node=None, *, subscription_jid=None, subid=None)

Unsubscribe from the pubsub node hosted at jid.

By default, the unsubscribe request will be for the bare JID of the client. It can be specified explicitly using the subscription_jid argument.

If available, the subid should also be specified.

If an error occurs, the corresponding XMPPError is raised.

Configuring subscriptions:

coroutine get_default_config(jid, node=None)

Request the default configuration of the pubsub node hosted at jid.

On success, the Data form is returned.

If an error occurs, the corresponding XMPPError is raised.

coroutine get_subscription_config(jid, node=None, *, subscription_jid=None, subid=None)

Request the current configuration of a subscription to the pubsub node hosted at jid.

By default, the request will be on behalf of the bare JID of the client. It can be overriden using the subscription_jid argument.

If available, the subid should also be specified.

On success, the Data form is returned.

If an error occurs, the corresponding XMPPError is raised.

coroutine set_subscription_config(jid, data, node=None, *, subscription_jid=None, subid=None)

Update the subscription configuration of a subscription to the pubsub node hosted at jid.

By default, the request will be on behalf of the bare JID of the client. It can be overriden using the subscription_jid argument.

If available, the subid should also be specified.

The configuration must be given as data as a Data instance.

If an error occurs, the corresponding XMPPError is raised.

Retrieving items:

coroutine get_items(jid, node, *, max_items=None)

Request the most recent items from the pubsub node hosted at jid.

By default, as many as possible items are requested. If max_items is given, it must be a positive integer specifying the maximum number of items which is to be returned by the server.

Return the xso.Request object, which has a Items payload.

coroutine get_items_by_id(jid, node, ids)

Request specific items by their IDs from the pubsub node hosted at jid.

ids must be an iterable of str of the IDs of the items to request from the pubsub node. If the iterable is empty, ValueError is raised (as otherwise, the request would be identical to calling get_items() without max_items).

Return the xso.Request object, which has a Items payload.

Publishing and retracting items:

coroutine notify(jid, node)

“Publish” to the node at jid without any item. This merely fans out a notification. The exact semantics can be checked in XEP-0060.

coroutine publish(jid, node, payload, *, id_=None)

Publish the given payload (which must be a aioxmpp.xso.XSO registered with xso.Item.registered_payload).

The item is published to node at jid. If id_ is given, it is used as the ID for the item. If an item with the same ID already exists at the node, it is replaced. If no ID is given, a ID is generated by the server.

Return the ID of the item as published.

coroutine retract(jid, node, id_, *, notify=False)

Retract an item previously published to node at jid. id_ must be the ItemID of the item to retract.

If notify is set to true, notifications will be generated (by setting the notify attribute on the retraction request).

Manage nodes:

coroutine change_node_affiliations(jid, node, affiliations_to_set)

Update the affiliations of the pubsub node at jid.

affiliations_to_set must be an iterable of pairs (jid, affiliation), where the jid indicates the JID for which the affiliation is to be set.

coroutine change_node_subscriptions(jid, node, subscriptions_to_set)

Update the subscriptions of the pubsub node at jid.

subscriptions_to_set must be an iterable of pairs (jid, subscription), where the jid indicates the JID for which the subscription is to be set.

coroutine create(jid, node=None)

Create a new pubsub node at the given jid.

If node is None, an instant node is created (see XEP-0060). The server may not support or allow the creation of instant nodes.

Return the actual node identifier.

coroutine delete(jid, node, *, redirect_uri=None)

Delete an existing pubsub node at the given jid.

Optionally, a redirect_uri can be given. The redirect_uri will be sent to subscribers in the message notifying them about the node deletion.

coroutine get_nodes(jid, node=None)

Request the nodes available at jid. If node is not None, the request returns the children of the XEP-0248 collection node node. Make sure to check for the appropriate server feature first.

Return a list of tuples consisting of the node names and their description (if available, otherwise None). If more information is needed, use disco.Service.get_items() directly.

Only nodes whose jid match the jid are returned.

coroutine get_node_affiliations(jid, node)

Return the affiliations of other jids at the pubsub node at jid.

The affiliations are returned as xso.OwnerRequest instance whose payload is a xso.OwnerAffiliations instance.

coroutine get_node_subscriptions(jid, node)

Return the subscriptions of other jids at the pubsub node at jid.

The subscriptions are returned as xso.OwnerRequest instance whose payload is a xso.OwnerSubscriptions instance.

Receiving notifications:

signal on_item_published(jid, node, item, *, message=None)

Fires when a new item is published to a node to which we have a subscription.

The node at which the item has been published is identified by jid and node. item is the xso.EventItem payload.

message is the Message which carried the notification. If a notification message contains more than one published item, the event is fired for each of the items, and message is passed to all of them.

signal on_item_retracted(jid, node, id_, *, message=None)

Fires when an item is retracted from a node to which we have a subscription.

The node at which the item has been retracted is identified by jid and node. id_ is the ID of the item which has been retract.

message is the Message which carried the notification. If a notification message contains more than one retracted item, the event is fired for each of the items, and message is passed to all of them.

signal on_node_deleted(jid, node, *, redirect_uri=None, message=None)

Fires when a node is deleted. jid and node identify the node.

If the notification included a redirection URI, it is passed as redirect_uri. Otherwise, None is passed for redirect_uri.

message is the Message which carried the notification.

signal on_affiliation_update(jid, node, affiliation, *, message=None)

Fires when the affiliation with a node is updated.

jid and node identify the node for which the affiliation was updated. affiliation is the new affiliaton.

message is the Message which carried the notification.

signal on_subscription_update(jid, node, state, *, subid=None, message=None)

Fires when the subscription state is updated.

jid and node identify the node for which the subscription was updated. subid is optional and if it is not None it is the affected subscription id. state is the new subscription state.

This event can happen in several cases, for example when a subscription request is approved by the node owner or when a subscription is cancelled.

message is the Message which carried the notification.s

XSOs

Registering payloads

PubSub payloads are must be registered at several places, so there is a short-hand function to handle that:

aioxmpp.pubsub.xso.as_payload_class(cls)

Register the given class cls as Publish-Subscribe payload on both Item and EventItem.

Return the class, to allow this to be used as decorator.

Features

class aioxmpp.pubsub.xso.Feature

Generic namespace

The top-level XSO is Request. Below that, several different XSOs are allowed, which are listed below the documentation of Request in alphabetical order.

class aioxmpp.pubsub.xso.Request(payload=None)

This XSO represents the <pubsub/> IQ payload from the generic pubsub namespace (http://jabber.org/protocol/pubsub). It can carry different types of payload.

payload

This is the generic payload attribute. It supports the following classes:

Affiliations([affiliations, node])
Create(*args, **kwargs)
Default(*[, node, data])
Items(node[, subid, max_items])
Publish(*args, **kwargs)
Retract(*args, **kwargs)
Subscribe(jid[, node])
Subscription(jid[, node, subid, subscription])
Subscriptions(*[, subscriptions, node])
Unsubscribe(jid[, node, subid])

options

As Options may both be used independently and along with another payload, they have their own attribute.

Independent of their use, Options objects are always available here. If they are used without another payload, the payload attribute is None.

configure

As Configure may both be used independently and along with another payload, it has its own attribute.

Independent of their use, Configure objects are always available here. If they are used without another payload, the payload attribute is None.

class aioxmpp.pubsub.xso.Affiliation(affiliation, node=None)

class aioxmpp.pubsub.xso.Affiliations(affiliations=[], node=None)

class aioxmpp.pubsub.xso.Configure(*args, **kwargs)

class aioxmpp.pubsub.xso.Create(*args, **kwargs)

class aioxmpp.pubsub.xso.Default(*, node=None, data=None)

class aioxmpp.pubsub.xso.Item(id_=None)

class aioxmpp.pubsub.xso.Items(node, subid=None, max_items=None)

class aioxmpp.pubsub.xso.Options(jid, node=None, subid=None)

class aioxmpp.pubsub.xso.Publish(*args, **kwargs)

class aioxmpp.pubsub.xso.Retract(*args, **kwargs)

class aioxmpp.pubsub.xso.Subscribe(jid, node=None)

class aioxmpp.pubsub.xso.SubscribeOptions(*args, **kwargs)

class aioxmpp.pubsub.xso.Subscription(jid, node=None, subid=None, *, subscription=None)

class aioxmpp.pubsub.xso.Subscriptions(*, subscriptions=[], node=None)

class aioxmpp.pubsub.xso.Unsubscribe(jid, node=None, subid=None)

Owner namespace

The top-level XSO is OwnerRequest. Below that, several different XSOs are allowed, which are listed below the documentation of OwnerRequest in alphabetical order.

class aioxmpp.pubsub.xso.OwnerRequest(payload)

class aioxmpp.pubsub.xso.OwnerAffiliation(jid, affiliation)

class aioxmpp.pubsub.xso.OwnerAffiliations(node, *, affiliations=[])

class aioxmpp.pubsub.xso.OwnerConfigure(*args, **kwargs)

class aioxmpp.pubsub.xso.OwnerDefault(*args, **kwargs)

class aioxmpp.pubsub.xso.OwnerDelete(node, *, redirect_uri=None)

class aioxmpp.pubsub.xso.OwnerPurge(*args, **kwargs)

class aioxmpp.pubsub.xso.OwnerRedirect(uri)

class aioxmpp.pubsub.xso.OwnerSubscription(jid, subscription)

class aioxmpp.pubsub.xso.OwnerSubscriptions(node, *, subscriptions=[])

Application-condition error XSOs

Application-condition XSOs for use in stanza.Error.application_condition are also defined for the error conditions specified by XEP-0060. They are listed in alphabetical order below:

class aioxmpp.pubsub.xso.ClosedNode

class aioxmpp.pubsub.xso.ConfigurationRequired

class aioxmpp.pubsub.xso.InvalidJID

class aioxmpp.pubsub.xso.InvalidOptions

class aioxmpp.pubsub.xso.InvalidPayload

class aioxmpp.pubsub.xso.InvalidSubID

class aioxmpp.pubsub.xso.ItemForbidden

class aioxmpp.pubsub.xso.ItemRequired

class aioxmpp.pubsub.xso.JIDRequired

class aioxmpp.pubsub.xso.MaxItemsExceeded

class aioxmpp.pubsub.xso.MaxNodesExceeded

class aioxmpp.pubsub.xso.NodeIDRequired

class aioxmpp.pubsub.xso.NotInRosterGroup

class aioxmpp.pubsub.xso.NotSubscribed

class aioxmpp.pubsub.xso.PayloadTooBig

class aioxmpp.pubsub.xso.PayloadRequired

class aioxmpp.pubsub.xso.PendingSubscription

class aioxmpp.pubsub.xso.PresenceSubscriptionRequired

class aioxmpp.pubsub.xso.SubIDRequired

class aioxmpp.pubsub.xso.TooManySubscriptions

class aioxmpp.pubsub.xso.Unsupported