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)¶
Supports retrieval and storage of bookmarks on the server. It currently only supports Private XML Storage as backend.
- coroutine get_bookmarks()¶
Get the stored bookmarks from the server.
Returns: the bookmarks as a Storage object
- coroutine set_bookmarks(bookmarks)¶
Set the bookmarks stored on the server.
Note
The bookmark protocol is prone to race conditions if several clients access it concurrently. Be careful to use a get-modify-set pattern.
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¶
The following XSOs are used to represent an manipulate bookmark lists.
- class aioxmpp.bookmarks.Storage(*args, **kwargs)¶
The container for storing bookmarks.
- bookmarks¶
A XSOList of bookmarks.
- class aioxmpp.bookmarks.Conference(name, jid, *, autojoin=False, nick=None, password=None)¶
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.
Notes on usage¶
It is important to use this class carefully to prevent race conditions with other clients modifying the bookmark data (unfortunately, this is not entirely preventable due to the design of the bookmark protocol).
The recommended practice is to modify the bookmarks in a get, modify, set fashion, where the modify step should be as short as possible (that is, should not depend on user input).
The individual bookmark classes support comparison by value. This allows useful manipulation of the bookmark list in agreement with the get-modify-set pattern. Where we reference the objects to operate on by with the value retrieved in an earlier get.
Removal:
storage = bookmark_client.get_bookmarks()
storage.bookmarks.remove(old_bookmark)
bookmark_client.set_bookmarks(storage)
Modifying:
storage = bookmark_client.get_bookmarks()
i = storage.bookmarks.index(old_bookmark)
storage.bookmarks[i].name = "New Shiny Name"
storage.bookmarks[i].nick = "new_nick"
bookmark_client.set_bookmarks(storage)
Adding:
storage = bookmark_client.get_bookmarks()
storage.bookmarks.append(new_bookmark)
bookmark_client.set_bookmarks(storage)