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.
- 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:
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)
-
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.
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
¶
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
fieldpubsub#access_model
Who may subscribe and retrieve items
-
body_xslt
¶ text-single
fieldpubsub#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
fieldpubsub#children_association_policy
Who may associate leaf nodes with a collection
-
children_association_whitelist
¶ jid-multi
fieldpubsub#children_association_whitelist
The list of JIDs that may associate leaf nodes with a collection
-
children
¶ text-multi
fieldpubsub#children
The child nodes (leaf or collection) associated with a collection
-
children_max
¶ text-single
fieldpubsub#children_max
The maximum number of child nodes that can be associated with a collection
-
collection
¶ text-multi
fieldpubsub#collection
The collection(s) with which a node is affiliated
-
contact
¶ jid-multi
fieldpubsub#contact
The JIDs of those to contact with questions
-
dataform_xslt
¶ text-single
fieldpubsub#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
fieldpubsub#deliver_notifications
Whether to deliver event notifications
-
deliver_payloads
¶ boolean
fieldpubsub#deliver_payloads
Whether to deliver payloads with event notifications; applies only to leaf nodes
-
description
¶ text-single
fieldpubsub#description
A description of the node
-
item_expire
¶ text-single
fieldpubsub#item_expire
Number of seconds after which to automatically purge items
-
itemreply
¶ list-single
fieldpubsub#itemreply
Whether owners or publisher should receive replies to items
-
language
¶ list-single
fieldpubsub#language
The default language of the node
-
max_items
¶ text-single
fieldpubsub#max_items
The maximum number of items to persist
-
max_payload_size
¶ text-single
fieldpubsub#max_payload_size
The maximum payload size in bytes
-
node_type
¶ list-single
fieldpubsub#node_type
Whether the node is a leaf (default) or a collection
-
notification_type
¶ list-single
fieldpubsub#notification_type
Specify the delivery style for notifications
-
notify_config
¶ boolean
fieldpubsub#notify_config
Whether to notify subscribers when the node configuration changes
-
notify_delete
¶ boolean
fieldpubsub#notify_delete
Whether to notify subscribers when the node is deleted
-
notify_retract
¶ boolean
fieldpubsub#notify_retract
Whether to notify subscribers when items are removed from the node
-
notify_sub
¶ boolean
fieldpubsub#notify_sub
Whether to notify owners about new subscribers and unsubscribes
-
persist_items
¶ boolean
fieldpubsub#persist_items
Whether to persist items to storage
-
presence_based_delivery
¶ boolean
fieldpubsub#presence_based_delivery
Whether to deliver notifications to available users only
-
publish_model
¶ list-single
fieldpubsub#publish_model
The publisher model
-
purge_offline
¶ boolean
fieldpubsub#purge_offline
Whether to purge all items when the relevant publisher goes offline
-
roster_groups_allowed
¶ list-multi
fieldpubsub#roster_groups_allowed
The roster group(s) allowed to subscribe and retrieve items
-
send_last_published_item
¶ list-single
fieldpubsub#send_last_published_item
When to send the last published item
-
tempsub
¶ boolean
fieldpubsub#tempsub
Whether to make all subscriptions temporary, based on subscriber presence
-
subscribe
¶ boolean
fieldpubsub#subscribe
Whether to allow subscriptions
-
title
¶ text-single
fieldpubsub#title
A friendly name for the node
-
type
¶ text-single
fieldpubsub#type
The type of node data, usually specified by the namespace of the payload (if any)
-