bookmarks – Bookmark support (XEP-0048)

This module provides support for storing and retrieving bookmarks on the server as per Bookmarks.

Service

class aioxmpp.BookmarkClient(client, **kwargs)[source]

Supports retrieval and storage of bookmarks on the server. It currently only supports Private XML Storage as backend.

There is the general rule never to modify the bookmark instances retrieved from this class (either by get_bookmarks() or as an argument to one of the signals). If you need to modify a bookmark for use with update_bookmark() use copy.copy() to create a copy.

The following methods change the bookmark list in a get-modify-set pattern, to mitigate the danger of race conditions and should be used in most circumstances:

The following signals are provided that allow tracking the changes to the bookmark list:

signal on_bookmark_added(added_bookmark)

Fires when a new bookmark is added.

signal on_bookmark_removed(removed_bookmark)

Fires when a bookmark is removed.

signal on_bookmark_changed(old_bookmark, new_bookmark)

Fires when a bookmark is changed.

Note

A heuristic is used to determine the change of bookmarks and the reported changes may not directly reflect the used methods, but it will always be possible to construct the list of bookmarks from the events. For example, when using update_bookmark() to change the JID of a Conference bookmark a removed and a added signal will fire.

Note

The bookmark protocol is prone to race conditions if several clients access it concurrently. Be careful to use a get-modify-set pattern or the provided highlevel interface.

Note

Some other clients extend the bookmark format. For now those extensions are silently dropped by our XSOs, and therefore are lost, when changing the bookmarks with aioxmpp. This is considered a bug to be fixed in the future.

XSOs

All bookmark types must adhere to the following ABC:

class aioxmpp.bookmarks.Bookmark(*args, **kwargs)[source]

A bookmark XSO abstract base class.

Every XSO class registered as child of Storage must be a Bookmark subclass.

Bookmarks must provide the following interface:

primary

Return the primary category of the bookmark.

The internal structure of the category is opaque to the code using it; only equality and hashing must be provided and operate by value. It is recommended that this be either a single datum (e.g. a string or JID) or a tuple of data items.

Together with the type and secondary this must fully determine the value of the bookmark.

This is used in the computation of the change signals. Bookmarks with different type or primary keys cannot be identified as changed from/to one another.

secondary

Return the tuple of secondary categories of the bookmark.

Together with the type and primary they must fully determine the value of the bookmark.

This is used in the computation of the change signals. The categories in the tuple are ordered in decreasing precedence, when calculating which bookmarks have changed the ones which mismatch in the category with the lowest precedence are grouped together.

The length of the tuple must be the same for all bookmarks of a type.

name

The human-readable label or description of the bookmark.

Equality is defined in terms of those properties:

__eq__(other)[source]

Compare for equality by value and type.

The value of a bookmark must be fully determined by the values of the primary and secondary properties.

This is used for generating the bookmark list change signals and for the get-modify-set methods.

It is highly recommended not to redefine __eq__() in a subclass, if you do so make sure that the following axiom relating __eq__(), primary and secondary holds:

(type(a) == type(b) and
 a.primary == b.primary and
 a.secondary == b.secondary)

if and only if:

a == b

Otherwise the generation of bookmark change signals is not guaranteed to be correct.

The following XSOs are used to represent an manipulate bookmark lists.

class aioxmpp.bookmarks.Conference(*args, **kwargs)[source]

An bookmark for a groupchat.

name

The name of the bookmark.

jid

The jid under which the groupchat is accessible.

autojoin

Whether to join automatically, when the client starts.

nick

The nick to use in the groupchat.

password

The password used to access the groupchat.

class aioxmpp.bookmarks.URL(*args, **kwargs)[source]

An URL bookmark.

name

The name of the bookmark.

url

The URL the bookmark saves.

To register custom bookmark classes use:

aioxmpp.bookmarks.as_bookmark_class(xso_class)[source]

Decorator to register xso_class as a custom bookmark class.

This is necessary to store and retrieve such bookmarks. The registered class must be a subclass of the abstract base class Bookmark.

Raises

TypeError – if xso_class is not a subclass of Bookmark.

The following is used internally as the XSO container for bookmarks.

class aioxmpp.bookmarks.Storage(*args, **kwargs)[source]

The container for storing bookmarks.

bookmarks

A XSOList of bookmarks.

Notes on usage

It is highly recommended to interact with the bookmark client via the provided signals and the get-modify-set methods add_bookmark(), discard_bookmark() and update_bookmark(). Using set_bookmarks() directly is error prone and might cause data loss due to race conditions.