click-keyring 0.2.1
A click option decorator to store and retrieve credentials using keyring.
License: MIT
Requires Python: >=3.6

# click-keyring

**click-keyring** provides a customized [click](https://click.palletsprojects.com) password option decorator to store and retrieve credentials using [keyring](https://keyring.readthedocs.io/en/latest/).

When a command is decorated with `click-keyring`:
* `click-keyring` generates a keyring service name using the command name by default (this can be customized).
* `click-keyring` uses the service name to look up an existing password using keyring.
* If an existing password is found, it is used as the param value.
* If not found, the user is prompted to enter a password.
* The new password is then saved to the keyring backend.

## Installation
```bash
pip install click-keyring
```

## Example
See the examples folder for additional examples.

```python
import click
from click_keyring import keyring_option


@keyring_option('-p', '--password')
@click.option('-u', '--username', prompt='Username')
@click.command()
def simple_cmd(username, password):
    """
    Example of click_keyring using defaults.

    The password will be saved to keyring with service name
    matching the click command name (in this case "simple_cmd").

    This can be overridden by setting `prefix` and/or `keyring_option`
     on the decorator.
    """
    click.echo()
    click.echo('** Command Params. User: {}, Password: {}'.format(username, password))


if __name__ == '__main__':
    simple_cmd()
```

When executed the first time, both username and password will be prompted.

```bash
~/g/c/examples python ./simple.py
Username: testuser
Password:

** Command Params. User: testuser, Password: testpw
~/g/c/examples
```

Subsequent executions using the same username will retrieve the password from the keyring backend.

```bash
~/g/c/examples python ./simple.py
Username: testuser

** Command Params. User: testuser, Password: testpw
~/g/c/examples
```

## Service Names
By default, the value of the `click.Command.name` attribute is used as the service name.  
The name is based on the function name or, if provided, the name argument on the `@click.command` decorator.

```python
@keyring_option('-p', '--password')
@click.option('-u', '--username', prompt='Username')
@click.command()
def simple_cmd(username, password):
    # service name will be the value of `simple_cmd.name`
    # This will likely be "simple-cmd" as click replaces underscores with hyphens.
    pass
```

A custom service name can be specified using the `prefix` argument.

```python
@keyring_option('-p', '--password', prefix='customnservice')
@click.option('-u', '--username', prompt='Username')
@click.command()
def simple_cmd(username, password):
    # service name will be "customnservice"
    pass
```

Other options on the command can be included in the service name using the `other_options` argument. 
This is an iterable of option names.  The values provided for those options is appended to the service name. 

```python
@keyring_option('-p', '--password', prefix='customnservice', other_options=('hostname',))
@click.option('-n', '--hostname')
@click.option('-u', '--username', prompt='Username')
@click.command()
def simple_cmd(username, hostname, password):
    # service name will be "customnservice_[value provided for hostname]"
    pass
```