keyrings.envvars 2.0.0
keyring backend plugin to retrieve credentials from environment variables.
License: MIT
Requires Python: >=3.9.0

keyrings.envvars
================

|PyPI| |Status| |Python Version| |License|

|PyPI Downloads|

|pre-commit| |Ruff| |Poetry|

.. |PyPI| image:: https://img.shields.io/pypi/v/keyrings.envvars
   :target: https://pypi.org/project/keyrings.envvars/
   :alt: PyPI
.. |Status| image:: https://img.shields.io/pypi/status/keyrings.envvars
   :target: https://pypi.org/project/keyrings.envvars/
   :alt: Status
.. |Python Version| image:: https://img.shields.io/pypi/pyversions/keyrings.envvars
   :target: https://pypi.org/project/keyrings.envvars
   :alt: Python Version
.. |PyPI Downloads| image:: https://img.shields.io/pypi/dm/keyrings.envvars
   :alt: PyPI - Downloads
.. |License| image:: https://img.shields.io/pypi/l/keyrings.envvars
   :target: https://opensource.org/licenses/MIT
   :alt: License
.. |pre-commit| image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white
   :target: https://github.com/pre-commit/pre-commit
   :alt: pre-commit
.. |Ruff| image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
    :target: https://github.com/astral-sh/ruff
    :alt: Ruff
.. |Poetry| image:: https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json
   :target: https://python-poetry.org/
   :alt: Poetry


*keyrings.envvars* is a keyring backend plugin for the keyring_ utility that provides credentials via environment variables.


Requirements
------------

* keyring >= 23.4.0
* Python >= 3.9


Installation
------------

You can install *keyrings.envvars* via pip_ from PyPI_:

.. code:: console

   $ pip install keyrings.envvars


Usage
-----

*keyrings.envvars* uses the following format for environment variables:

.. code:: console

   KEYRING_SERVICE_NAME_<n>=<service>
   KEYRING_SERVICE_USERNAME_<n>=<username>
   KEYRING_SERVICE_PASSWORD_<n>=<password>

Example for usage with pip credentials:

.. code:: console

   KEYRING_SERVICE_NAME_0=private-pypi-index.example.com
   KEYRING_SERVICE_USERNAME_0=testusername
   KEYRING_SERVICE_PASSWORD_0=testpassword
   KEYRING_SERVICE_NAME_1=another-private-pypi-index.example.com
   KEYRING_SERVICE_USERNAME_1=testusername
   KEYRING_SERVICE_PASSWORD_1=testpassword

This can be used along with a requirements.txt containing appropriate ``--extra-index-url`` flags to avoid storing
credentials in plain-text:

.. code::

   --extra-index-url https://private-pypi-index.example.com/simple

   private-package==1.2.3


Note: Defining multiple identical credentials (service name and username)
will result in the last defined password being returned as the environment
variables are sorted by the keyring backend.

.. code:: console

   export KEYRING_SERVICE_NAME_0=https://private-pypi-index.example.com
   export KEYRING_SERVICE_USERNAME_0=testusername
   export KEYRING_SERVICE_PASSWORD_0=testpassword
   export KEYRING_SERVICE_NAME_1=https://private-pypi-index.example.com
   export KEYRING_SERVICE_USERNAME_1=testusername
   export KEYRING_SERVICE_PASSWORD_1=testpassword_1
   keyring get https://private-pypi-index.example.com testusername
   testpassword_1

If there are multiple credentials defined for a service and no username is given when searching then ``None`` will be returned.
For example, given the definitions above:

.. code:: pycon

   >>> import keyring
   >>> cred = keyring.get_credential('https://private-pypi-index.example.com', None)
   >>> print(cred)
   None

Contributing
------------

Contributions including suggestions, pull requests, etc. are very welcome.
*keyrings.envvars* uses `Conventional Commits`_ format for commit messages.

Please run `nox`_ before committing any changes.
Running `pre-commit`_ with the ``pre-commit`` and ``commit-msg`` hooks enabled is also requested to ensure
linting checks are done correctly on code, configuration, and commit messages.

Please note that contributions created partially or entirely with AI/LLM will be rejected.


License
-------

Distributed under the terms of the `MIT license`_,
*keyrings.envvars* is free and open source software.


Issues
------

If you encounter any problems,
please `file an issue`_ along with a detailed description.

Please read https://www.chiark.greenend.org.uk/~sgtatham/bugs.html before you file an issue.


Credits
-------

This project was generated from `@cjolowicz`_'s `Hypermodern Python Cookiecutter`_ template.

.. _@cjolowicz: https://github.com/cjolowicz
.. _MIT license: https://opensource.org/licenses/MIT
.. _PyPI: https://pypi.org/
.. _Hypermodern Python Cookiecutter: https://github.com/cjolowicz/cookiecutter-hypermodern-python
.. _file an issue: https://codeberg.org/wwuck/keyrings.envvars/issues
.. _pip: https://pip.pypa.io/
.. _keyring: https://pypi.org/project/keyring/
.. _Conventional Commits: https://www.conventionalcommits.org/
.. _nox: https://nox.thea.codes
.. _pre-commit: https://pre-commit.com/