maestral.keyring
================

.. py:module:: maestral.keyring

.. autoapi-nested-parse::

   This module is responsible for authorization and token store in the system keyring.





Module Contents
---------------

.. py:class:: CredentialStorage(config_name)

   Provides a threadsafe interface to store credentials in a system keyring

   CredentialStorage provides token store in the preferred system keyring. Supported
   keyring backends are, in order of preference:

       * macOS Keychain
       * Any keyring implementing the SecretService Dbus specification
       * KWallet
       * Plain text storage

   .. note:: Once the token has been stored with a keyring backend, that backend will
       be saved in the config file and remembered until deleting the credentials.

   .. warning:: Unlike macOS Keychain, Gnome Keyring and KWallet do not support
       app-specific access to passwords. If the user unlocks those keyrings, we and any
       other application in the same user session get access to *all* saved passwords.

   :param config_name: Name of maestral config.


   .. py:property:: keyring
      :type: keyring.backend.KeyringBackend | None

      The keyring backend currently being used to store auth tokens. Will be None if
      we are not linked.


   .. py:method:: set_keyring_backend(ring)

      Enforce usage of a particular keyring backend. If not called, the best backend
      will be selected depending on the platform. Do not change backends after saving
      credentials.

      :param ring: Keyring backend to use.



   .. py:property:: loaded
      :type: bool

      Whether we have already loaded the credentials. This will be true after
      calling :meth:`load_creds` or accessing the any of the auth credentials through
      instance properties.


   .. py:property:: token
      :type: str | None

      The saved token (read only). This call will block until the keyring is
      unlocked.


   .. py:property:: account_id
      :type: str | None

      The saved account id (read only).


   .. py:method:: load_creds()

      Loads auth token from system keyring. This will be called automatically when
      accessing the :attr:`token` property. This call will block until the keyring is
      unlocked or unlocking is declined by the user.

      :raises KeyringAccessError: if the system keyring is locked or otherwise cannot
          be accessed (for example if the app bundle signature has been invalidated).



   .. py:method:: save_creds(account_id, token)

      Saves the auth token to system keyring. Falls back to plain text storage if the
      user denies access to keyring.

      :param account_id: The account ID.
      :param token: The access token.



   .. py:method:: delete_creds()

      Deletes auth token from system keyring.

      :raises KeyringAccessError: if the system keyring is locked or otherwise cannot
          be accessed (for example if the app bundle signature has been invalidated).