The secretstorage.collection module

Collection is a place where secret items are stored. Normally, only the default collection should be used (usually named “login”), but this module allows to use any registered collection.

Collections are usually automatically unlocked when user logs in, but collections can also be locked and unlocked using Collection.lock() and Collection.unlock() methods (unlocking requires showing the unlocking prompt to user and can be synchronous or asynchronous). Creating new items and editing existing ones is possible only in unlocked collection.

class secretstorage.collection.Collection(bus, collection_path='/org/freedesktop/secrets/aliases/default', session=None)

Represents a collection.

create_item(label, attributes, secret, replace=False, content_type='text/plain')

Creates a new Item with given label (unicode string), attributes (dictionary) and secret (bytestring). If replace is True, replaces the existing item with the same attributes. If content_type is given, also sets the content type of the secret (text/plain by default). Returns the created item.

delete()

Deletes the collection and all items inside it.

ensure_not_locked()

If collection is locked, raises LockedException.

get_all_items()

Returns a generator of all items in the collection.

get_label()

Returns the collection label.

is_locked()

Returns True if item is locked, otherwise False.

lock()

Locks the collection.

search_items(attributes)

Returns a generator of items with the given attributes. attributes should be a dictionary.

set_label(label)

Sets collection label to label.

unlock(callback=None)

Requests unlocking the collection. If callback is specified, calls it when unlocking is complete (see exec_prompt() description for details) and returns a boolean representing whether the operation was dismissed. Otherwise, uses asynchronous loop from GLib API.

secretstorage.collection.create_collection(bus, label, alias='', session=None)

Creates a new Collection with the given label and alias and returns it. This action requires prompting. If prompt is dismissed, raises ItemNotFoundException. This is asynchronous function, uses loop from GLib API.

secretstorage.collection.get_all_collections(bus)

Returns a generator of all available collections.

secretstorage.collection.get_collection_by_alias(bus, alias)

Returns the collection with alias alias. If there is no such collection, raises ItemNotFoundException.

secretstorage.collection.search_items(bus, attributes)

Returns a generator of items in all collections with the given attributes. attributes should be a dictionary.