`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)[source]¶

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:

async get_features(jid)[source]¶

Return the features supported by a service.

Parameters: jid (aioxmpp.JID) – Address of the PubSub service to query.
Returns: Set of supported features
Return type: set containing Feature enumeration members.

This simply uses service discovery to obtain the set of features and converts the features to Feature enumeration members. To get the full feature information, resort to using DiscoClient.query_info() directly on jid.

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

Subscribing, unsubscribing and listing subscriptions:

async get_subscriptions(jid, node=None)[source]¶

Return all subscriptions of the local entity to a node.

Parameters

jid (aioxmpp.JID) – Address of the PubSub service.
node (str) – Name of the PubSub node to query.

Raises

aioxmpp.errors.XMPPError – as returned by the service

Returns

The subscriptions response from the service.

Return type

xso.Subscriptions

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

async subscribe(jid, node=None, *, subscription_jid=None, config=None)[source]¶

Subscribe to a node.

Parameters

jid (aioxmpp.JID) – Address of the PubSub service.
node (str) – Name of the PubSub node to subscribe to.
subscription_jid (aioxmpp.JID) – The address to subscribe to the service.
config (Data) – Optional configuration of the subscription

Raises

aioxmpp.errors.XMPPError – as returned by the service

Returns

The response from the server.

Return type

xso.Request

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.

async unsubscribe(jid, node=None, *, subscription_jid=None, subid=None)[source]¶

Unsubscribe from a node.

Parameters

jid (aioxmpp.JID) – Address of the PubSub service.
node (str) – Name of the PubSub node to unsubscribe from.
subscription_jid (aioxmpp.JID) – The address to subscribe from the service.
subid (str) – Unique ID of the subscription to remove.

Raises

aioxmpp.errors.XMPPError – as returned by the service

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:

async get_default_config(jid, node=None)[source]¶

Request the default configuration of a node.

Parameters

jid (aioxmpp.JID) – Address of the PubSub service.
node (str) – Name of the PubSub node to query.

Raises

aioxmpp.errors.XMPPError – as returned by the service

Returns

The default configuration of subscriptions at the node.

Return type

Data

On success, the Data form is returned.

If an error occurs, the corresponding XMPPError is raised.

async get_subscription_config(jid, node=None, *, subscription_jid=None, subid=None)[source]¶

Request the current configuration of a subscription.

Parameters

jid (aioxmpp.JID) – Address of the PubSub service.
node (str) – Name of the PubSub node to query.
subscription_jid (aioxmpp.JID) – The address to query the configuration for.
subid (str) – Unique ID of the subscription to query.

Raises

aioxmpp.errors.XMPPError – as returned by the service

Returns

The current configuration of the subscription.

Return type

Data

By default, the request will be on behalf of the bare JID of the client. It can be overridden 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.

async set_subscription_config(jid, data, node=None, *, subscription_jid=None, subid=None)[source]¶

Update the configuration of a subscription.

Parameters

jid (aioxmpp.JID) – Address of the PubSub service.
data (Data) – The new configuration of the subscription.
node (str) – Name of the PubSub node to modify.
subscription_jid (aioxmpp.JID) – The address to modify the configuration for.
subid (str) – Unique ID of the subscription to modify.

Raises

aioxmpp.errors.XMPPError – as returned by the service

By default, the request will be on behalf of the bare JID of the client. It can be overridden 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:

async get_items(jid, node, *, max_items=None)[source]¶

Request the most recent items from a node.

Parameters

jid (aioxmpp.JID) – Address of the PubSub service.
node (str) – Name of the PubSub node to query.
max_items (int or None) – Number of items to return at most.

Raises

aioxmpp.errors.XMPPError – as returned by the service

Returns

The response from the server.

Return type

xso.Request.

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.

async get_items_by_id(jid, node, ids)[source]¶

Request specific items by their IDs from a node.

Parameters

jid (aioxmpp.JID) – Address of the PubSub service.
node (str) – Name of the PubSub node to query.
ids (Iterable of str) – The item IDs to return.

Raises

aioxmpp.errors.XMPPError – as returned by the service

Returns

The response from the service

Return type

xso.Request

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:

async notify(jid, node)[source]¶

Notify all subscribers of a node without publishing an item.

Parameters

jid (aioxmpp.JID) – Address of the PubSub service.
node (str) – Name of the PubSub node to send a notify from.

Raises

aioxmpp.errors.XMPPError – as returned by the service

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

async publish(jid, node, payload, *, id_=None, publish_options=None)[source]¶

Publish an item to a node.

Parameters

jid (aioxmpp.JID) – Address of the PubSub service.
node (str) – Name of the PubSub node to publish to.
payload (aioxmpp.xso.XSO) – Registered payload to publish.
id (str or None.) – Item ID to use for the item.
publish_options (aioxmpp.forms.Data) – A data form with the options for the publish request

Raises

aioxmpp.errors.XMPPError – as returned by the service
RuntimeError – if publish_options is not None but the service does not support publish_options

Returns

The Item ID which was used to publish the item.

Return type

str or 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.

If publish_options is given, it is passed as <publish-options/> element to the server. This needs to be a data form which allows to define e.g. node configuration as a pre-condition to publishing. If the publish-options cannot be satisfied, the server will raise a aioxmpp.ErrorCondition.CONFLICT error.

If publish_options is given and the server does not announce the aioxmpp.pubsub.xso.Feature.PUBLISH_OPTIONS feature, RuntimeError is raised to prevent security issues (e.g. if the publish options attempt to assert a restrictive access model).

Return the ID of the item as published (or None if the server does not inform us; this is unfortunately common).

async retract(jid, node, id_, *, notify=False)[source]¶

Retract a previously published item from a node.

Parameters

jid (aioxmpp.JID) – Address of the PubSub service.
node (str) – Name of the PubSub node to send a notify from.
id (str) – The ID of the item to retract.
notify (bool) – Flag indicating whether subscribers shall be notified about the retraction.

Raises

aioxmpp.errors.XMPPError – as returned by the service

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:

async change_node_affiliations(jid, node, affiliations_to_set)[source]¶

Update the affiliations at a node.

Parameters

jid (aioxmpp.JID) – Address of the PubSub service.
node (str) – Name of the node to modify
affiliations_to_set (Iterable of tuples consisting of the JID to affiliate and the affiliation to use.) – The affiliations to set at the node.

Raises

aioxmpp.errors.XMPPError – as returned by the service

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.

async change_node_subscriptions(jid, node, subscriptions_to_set)[source]¶

Update the subscriptions at a node.

Parameters

jid (aioxmpp.JID) – Address of the PubSub service.
node (str) – Name of the node to modify
subscriptions_to_set (Iterable of tuples consisting of the JID to (un)subscribe and the subscription level to use.) – The subscriptions to set at the node.

Raises

aioxmpp.errors.XMPPError – as returned by the service

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.

async create(jid, node=None)[source]¶

Create a new node at a service.

Parameters

jid (aioxmpp.JID) – Address of the PubSub service.
node (str or None) – Name of the PubSub node to create.

Raises

aioxmpp.errors.XMPPError – as returned by the service

Returns

The name of the created node.

Return type

str

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.

async delete(jid, node, *, redirect_uri=None)[source]¶

Delete an existing node.

Parameters

jid (aioxmpp.JID) – Address of the PubSub service.
node (str or None) – Name of the PubSub node to delete.
redirect_uri (str or None) – A URI to send to subscribers to indicate a replacement for the deleted node.

Raises

aioxmpp.errors.XMPPError – as returned by the service

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

async get_nodes(jid, node=None)[source]¶

Request all nodes at a service or collection node.

Parameters

jid (aioxmpp.JID) – Address of the PubSub service.
node (str or None) – Name of the collection node to query

Raises

aioxmpp.errors.XMPPError – as returned by the service

Returns

The list of nodes at the service or collection node.

Return type

Sequence of tuples consisting of the node name and its description.

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 DiscoClient.get_items() directly.

Only nodes whose jid match the jid are returned.

async get_node_affiliations(jid, node)[source]¶

Return the affiliations of other jids at a node.

Parameters

jid (aioxmpp.JID) – Address of the PubSub service.
node (str) – Name of the node to query

Raises

aioxmpp.errors.XMPPError – as returned by the service

Returns

The response from the service.

Return type

xso.OwnerRequest

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

async get_node_config(jid, node=None)[source]¶

Request the configuration of a node.

Parameters

jid (aioxmpp.JID) – Address of the PubSub service.
node (str) – Name of the PubSub node to query.

Raises

aioxmpp.errors.XMPPError – as returned by the service

Returns

The configuration of the node.

Return type

Data

On success, the Data form is returned.

If an error occurs, the corresponding XMPPError is raised.

async get_node_subscriptions(jid, node)[source]¶

Return the subscriptions of other jids with a node.

Parameters

jid (aioxmpp.JID) – Address of the PubSub service.
node (str) – Name of the node to query

Raises

aioxmpp.errors.XMPPError – as returned by the service

Returns

The response from the service.

Return type

xso.OwnerRequest

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

async purge(jid, node)[source]¶

Delete all items from a node.

Parameters

jid – JID of the PubSub service
node (str) – Name of the PubSub node

Requires xso.Feature.PURGE.

async set_node_config(jid, config, node=None)[source]¶

Update the configuration of a node.

Parameters

jid (aioxmpp.JID) – Address of the PubSub service.
config (aioxmpp.forms.Data) – Configuration form
node (str) – Name of the PubSub node to query.

Raises

aioxmpp.errors.XMPPError – as returned by the service

Returns

The configuration of the node.

Return type

Data

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)[source]¶

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)[source]¶: 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)[source]¶

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)[source]¶

class aioxmpp.pubsub.xso.Affiliations(*args, **kwargs)[source]¶

class aioxmpp.pubsub.xso.Configure(*args, **kwargs)[source]¶

class aioxmpp.pubsub.xso.Create(*args, **kwargs)[source]¶

class aioxmpp.pubsub.xso.Default(*args, **kwargs)[source]¶

class aioxmpp.pubsub.xso.Item(*args, **kwargs)[source]¶

class aioxmpp.pubsub.xso.Items(*args, **kwargs)[source]¶

class aioxmpp.pubsub.xso.Options(*args, **kwargs)[source]¶

class aioxmpp.pubsub.xso.Publish(*args, **kwargs)[source]¶

class aioxmpp.pubsub.xso.Retract(*args, **kwargs)[source]¶

class aioxmpp.pubsub.xso.Subscribe(*args, **kwargs)[source]¶

class aioxmpp.pubsub.xso.SubscribeOptions(*args, **kwargs)[source]¶

class aioxmpp.pubsub.xso.Subscription(*args, **kwargs)[source]¶

class aioxmpp.pubsub.xso.Subscriptions(*args, **kwargs)[source]¶

class aioxmpp.pubsub.xso.Unsubscribe(*args, **kwargs)[source]¶

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)[source]¶

class aioxmpp.pubsub.xso.OwnerAffiliation(*args, **kwargs)[source]¶

class aioxmpp.pubsub.xso.OwnerAffiliations(*args, **kwargs)[source]¶

class aioxmpp.pubsub.xso.OwnerConfigure(*args, **kwargs)[source]¶

class aioxmpp.pubsub.xso.OwnerDefault(*args, **kwargs)[source]¶

class aioxmpp.pubsub.xso.OwnerDelete(*args, **kwargs)[source]¶

class aioxmpp.pubsub.xso.OwnerPurge(*args, **kwargs)[source]¶

class aioxmpp.pubsub.xso.OwnerRedirect(*args, **kwargs)[source]¶

class aioxmpp.pubsub.xso.OwnerSubscription(*args, **kwargs)[source]¶

class aioxmpp.pubsub.xso.OwnerSubscriptions(*args, **kwargs)[source]¶

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[source]¶

Forms¶

class aioxmpp.pubsub.NodeConfigForm(*args, **kwargs)[source]¶

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)

`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)

aioxmpp

Table of Contents

Navigation

Related Topics

pubsub — Publish-Subscribe support (XEP-0060)¶

Using Publish-Subscribe¶

XSOs¶

Registering payloads¶

Features¶

Generic namespace¶

Owner namespace¶

Application-condition error XSOs¶

Forms¶

`pubsub` — Publish-Subscribe support (XEP-0060)¶