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 isTrue
, 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.
- ensure_not_locked() None [source]¶
If collection is locked, raises
LockedException
.
- 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.