# 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.