masq/i3pystatus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve keyring documentation

Browse Source
This commit is contained in:
Erik Johnson 2016-09-25 14:54:16 -05:00
parent ac961dbd33
commit 394eaf52ee
1 changed files with 70 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
docs/configuration.rst
View File

@ -536,33 +536,83 @@ service that is not traditionally required for web browsing:
Credentials Credentials
----------- -----------
Settings that require credentials can utilize the keyring module to For modules which require credentials, i3pystatus supports credential
keep sensitive information out of config files. To take advantage of management using the keyring_ module from PyPI.
this feature, simply use the ``i3pystatus-setting-util`` script
installed along i3pystatus to set the credentials for a module. Once .. important::
this is done you can add the module to your config without specifying Many distributions have keyring_ pre-packaged, available as
the credentials, e.g.: ``python-keyring``. Unless you have KWallet_ or SecretService_ available,
you will also most likely need to install keyrings.alt_, which contains
additional keyring backends for use by the keyring_ module.
Both i3pystatus and ``i3pystatus-setting-util`` will abort with a
RuntimeError_ if keyring_ isinstalled but a usable keyring backend is not
present, so it is a good idea to install both if you plan to use a module
which supports credential handling.
To store credentials in a keyring, use the ``i3pystatus-setting-util`` script
installed along i3pystatus.
.. note::
``i3pystatus-setting-util`` will store credentials using the default
keyring backend. The method for determining which backend is the default
can be found :ref:`below <default-keyring-backend>`. If, for some reason,
it is necessary to use a keyring other than the default, then you will need
to override the default in your keyringrc.cfg_ for
``i3pystatus-setting-util`` to successfully use it.
Once you have successfully set up credentials, you can add the module to your
config file without specifying the credentials in the registration, e.g.:
.. code:: python .. code:: python
# Use the default keyring to retrieve credentials. # Use the default keyring to retrieve credentials
# To determine which backend is the default on your system, run
# python -c 'import keyring; print(keyring.get_keyring())'
status.register('github') status.register('github')
If you don't want to use the default you can set a specific keyring like so: i3pystatus will locate and set the credentials during the module loading
process. Currently supported credentials are ``password``, ``email`` and
``username``.
.. code:: python .. _default-keyring-backend:
# Requires the keyrings.alt package .. note::
from keyrings.alt.file import PlaintextKeyring To determine which backend is the default on your system, run the
status.register('github', keyring_backend=PlaintextKeyring()) following:
i3pystatus will locate and set the credentials during the module .. code-block:: bash
loading process. Currently supported credentials are "password",
"email" and "username".
.. note:: Credential handling requires the PyPI package python -c 'import keyring; print(keyring.get_keyring())'
``keyring``. Many distributions have it pre-packaged available as
``python-keyring``.
If this command returns a ``keyring.backends.fail.Keyring`` object, none of
the keyrings supported out-of-the box by the keyring_ module are available,
and you will need to install the keyrings.alt_ Python module. keyrings.alt_
provides an encrypted keyring which will be seen as the default if both
keyrings.alt_ and keyring_ are installed, and none of the keyrings
supported by keyring_ are present:
.. code-block:: bash
$ python -c 'import keyring; print(keyring.get_keyring())'
<EncryptedKeyring at /home/username/.local/share/python_keyring/crypted_pass.cfg>
If the keyring backend you used to store credentials using
``i3pystatus-setting-util`` is not the default, then you can change which
keyring backend i3pystatus will use in one of two ways:
#. Override the default in your keyringrc.cfg_
#. Import and instantiate a keyring backend class, and pass it as the
``keyring_backend`` parameter when registering the module:
.. code:: python
# Requires the keyrings.alt package
from keyrings.alt.file import PlaintextKeyring
status.register('github', keyring_backend=PlaintextKeyring())
.. _KWallet: http://www.kde.org/
.. _SecretService: https://specifications.freedesktop.org/secret-service/re01.html
.. _RuntimeError: https://docs.python.org/3/library/exceptions.html#RuntimeError
.. _keyring: https://pypi.python.org/pypi/keyring
.. _keyrings.alt: https://pypi.python.org/pypi/keyrings.alt
.. _keyringrc.cfg: http://pythonhosted.org/keyring/#customize-your-keyring-by-config-file