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 blocks until user accepts or declines it). Creating new items and editing existing ones is possible only in unlocked collections.

class secretstorage.collection.Collection(connection: DBusConnection, collection_path: str = '/org/freedesktop/secrets/aliases/default', session: Session | None = None)[source]

Represents a collection.

create_item(label: str, attributes: dict[str, str], secret: bytes, replace: bool = False, content_type: str = 'text/plain') Item[source]

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() None[source]

Deletes the collection and all items inside it.

ensure_not_locked() None[source]

If collection is locked, raises LockedException.

get_all_items() Iterator[Item][source]

Returns a generator of all items in the collection.

get_label() str[source]

Returns the collection label.

is_locked() bool[source]

Returns True if item is locked, otherwise False.

lock() None[source]

Locks the collection.

search_items(attributes: dict[str, str]) Iterator[Item][source]

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

set_label(label: str) None[source]

Sets collection label to label.

unlock() bool[source]

Requests unlocking the collection.

Returns a boolean representing whether the prompt has been dismissed; that means False on successful unlocking and True if it has been dismissed.

Changed in version 3.0: No longer accepts the callback argument.

secretstorage.collection.create_collection(connection: DBusConnection, label: str, alias: str = '', session: Session | None = None) Collection[source]

Creates a new Collection with the given label and alias and returns it. This action requires prompting.

Raises:

PromptDismissedException if the prompt is dismissed.

secretstorage.collection.get_all_collections(connection: DBusConnection) Iterator[Collection][source]

Returns a generator of all available collections.

secretstorage.collection.get_any_collection(connection: DBusConnection) Collection[source]

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(connection: DBusConnection, alias: str) Collection[source]

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

secretstorage.collection.get_default_collection(connection: DBusConnection, session: Session | None = None) Collection[source]

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

secretstorage.collection.search_items(connection: DBusConnection, attributes: dict[str, str]) Iterator[Item][source]

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