The secretstorage.collection module

Collection is a place where secret items are stored. Normally, only the default collection should be used, but this module allows to use any registered collection. Use get_default_collection() to get the default collection (and create it, if necessary).

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 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 synchronous function, uses loop from GLib API.

secretstorage.collection.get_all_collections(bus)

Returns a generator of all available collections.

secretstorage.collection.get_any_collection(bus)

Returns any collection, in the following order of preference:

• The default collection;
• The “session” collection (usually temporary);
• The first collection in the collections list.

secretstorage.collection.get_collection_by_alias(bus, alias)

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

secretstorage.collection.get_default_collection(bus, session=None)

Returns the default collection. If it doesn’t exist, creates it.

secretstorage.collection.search_items(bus, attributes)

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