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)

Represents a collection.

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

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

Deletes the collection and all items inside it.

ensure_not_locked() → None

If collection is locked, raises LockedException.

get_all_items() → Iterator[Item]

Returns a generator of all items in the collection.

get_label() → str

Returns the collection label.

is_locked() → bool

Returns True if item is locked, otherwise False.

lock() → None

Locks the collection.

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

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

set_label(label: str) → None

Sets collection label to label.

unlock(timeout: float | None = None) → bool

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.

Raises:

TimeoutError if timeout (in seconds) passed and the prompt was neither accepted nor dismissed.

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

Changed in version 3.5: Added timeout argument.

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

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]

Returns a generator of all available collections.

secretstorage.collection.get_any_collection(connection: DBusConnection) → Collection

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

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

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

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

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