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 PubSubClient into the client, using summon().

class aioxmpp.PubSubClient(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 a node.
get_items(jid, node, *[, max_items])	Request the most recent items from a node.
get_items_by_id(jid, node, ids)	Request specific items by their IDs from a node.
get_subscription_config(jid[, node, …])	Request the current configuration of a subscription.
get_subscriptions(jid[, node])	Return all subscriptions of the local entity to a node.
set_subscription_config(jid, data[, node, …])	Update the configuration of a subscription.
subscribe(jid[, node, subscription_jid, config])	Subscribe to a node.
unsubscribe(jid[, node, subscription_jid, subid])	Unsubscribe from a node.
on_affiliation_update
on_item_published
on_item_retracted
on_node_deleted
on_subscription_update

Publisher use cases:

notify(jid, node)	Notify all subscribers of a node without publishing an item.
publish(jid, node, payload, *[, id_, …])	Publish an item to a node.
retract(jid, node, id_, *[, notify])	Retract a previously published item from a node.

Owner use cases:

change_node_affiliations(jid, node, …)	Update the affiliations at a node.
change_node_subscriptions(jid, node, …)	Update the subscriptions at a node.
create(jid[, node])	Create a new node at a service.
delete(jid, node, *[, redirect_uri])	Delete an existing node.
get_nodes(jid[, node])	Request all nodes at a service or collection node.
get_node_affiliations(jid, node)	Return the affiliations of other jids at a node.
get_node_config(jid[, node])	Request the configuration of a node.
get_node_subscriptions(jid, node)	Return the subscriptions of other jids with a node.
purge(jid, node)	Delete all items from a node.
set_node_config(jid, config[, node])	Update the configuration of a node.

Meta-information about the service:

Subscribing, unsubscribing and listing subscriptions:

Configuring subscriptions:

Retrieving items:

Publishing and retracting items:

Manage nodes:

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.

Changed in version 0.8: This class was formerly known as aioxmpp.pubsub.Service. It is still available under that name, but the alias will be removed in 1.0.

class aioxmpp.pubsub.Service

Alias of PubSubClient.

Deprecated since version 0.8: The alias will be removed in 1.0.

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(value)

An enumeration.

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(*args, **kwargs)

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(*args, **kwargs)
Create(*args, **kwargs)
Default(*args, **kwargs)
Items(*args, **kwargs)
Publish(*args, **kwargs)
Retract(*args, **kwargs)
Subscribe(*args, **kwargs)
Subscription(*args, **kwargs)
Subscriptions(*args, **kwargs)
Unsubscribe(*args, **kwargs)

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(*args, **kwargs)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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(*args, **kwargs)

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

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

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

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

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

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

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

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

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

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

Forms

class aioxmpp.pubsub.NodeConfigForm(*args, **kwargs)

Declaration of the form with type http://jabber.org/protocol/pubsub#node_config

access_model

list-single field pubsub#access_model

Who may subscribe and retrieve items

body_xslt

text-single field pubsub#body_xslt

The URL of an XSL transformation which can be applied to payloads in order to generate an appropriate message body element.

children_association_policy

list-single field pubsub#children_association_policy

Who may associate leaf nodes with a collection

children_association_whitelist

jid-multi field pubsub#children_association_whitelist

The list of JIDs that may associate leaf nodes with a collection

children

text-multi field pubsub#children

The child nodes (leaf or collection) associated with a collection

children_max

text-single field pubsub#children_max

The maximum number of child nodes that can be associated with a collection

collection

text-multi field pubsub#collection

The collection(s) with which a node is affiliated

contact

jid-multi field pubsub#contact

The JIDs of those to contact with questions

dataform_xslt

text-single field pubsub#dataform_xslt

The URL of an XSL transformation which can be applied to the payload format in order to generate a valid Data Forms result that the client could display using a generic Data Forms rendering engine

deliver_notifications

boolean field pubsub#deliver_notifications

Whether to deliver event notifications

deliver_payloads

boolean field pubsub#deliver_payloads

Whether to deliver payloads with event notifications; applies only to leaf nodes

description

text-single field pubsub#description

A description of the node

item_expire

text-single field pubsub#item_expire

Number of seconds after which to automatically purge items

itemreply

list-single field pubsub#itemreply

Whether owners or publisher should receive replies to items

language

list-single field pubsub#language

The default language of the node

max_items

text-single field pubsub#max_items

The maximum number of items to persist

max_payload_size

text-single field pubsub#max_payload_size

The maximum payload size in bytes

node_type

list-single field pubsub#node_type

Whether the node is a leaf (default) or a collection

notification_type

list-single field pubsub#notification_type

Specify the delivery style for notifications

notify_config

boolean field pubsub#notify_config

Whether to notify subscribers when the node configuration changes

notify_delete

boolean field pubsub#notify_delete

Whether to notify subscribers when the node is deleted

notify_retract

boolean field pubsub#notify_retract

Whether to notify subscribers when items are removed from the node

notify_sub

boolean field pubsub#notify_sub

Whether to notify owners about new subscribers and unsubscribes

persist_items

boolean field pubsub#persist_items

Whether to persist items to storage

presence_based_delivery

boolean field pubsub#presence_based_delivery

Whether to deliver notifications to available users only

publish_model

list-single field pubsub#publish_model

The publisher model

purge_offline

boolean field pubsub#purge_offline

Whether to purge all items when the relevant publisher goes offline

roster_groups_allowed

list-multi field pubsub#roster_groups_allowed

The roster group(s) allowed to subscribe and retrieve items

send_last_published_item

list-single field pubsub#send_last_published_item

When to send the last published item

tempsub

boolean field pubsub#tempsub

Whether to make all subscriptions temporary, based on subscriber presence

subscribe

boolean field pubsub#subscribe

Whether to allow subscriptions

title

text-single field pubsub#title

A friendly name for the node

type

text-single field pubsub#type

The type of node data, usually specified by the namespace of the payload (if any)