# 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(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() → 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.

    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

  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.