Metadata-Version: 2.1
Name: figtion
Version: 1.0.5
Summary: A simple configuration interface with plaintext and encrypted file support.
Home-page: https://github.com/dactylroot/figtion
Author: Cory Root
Author-email: dactylroot@gmail.com
License: MIT
Download-URL: https://github.com/dactylroot/figtion/archive/1.0.5.tar.gz
Keywords: configuration secret
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.5
Description-Content-Type: text/markdown
License-File: LICENSE

# figtion

                .---.
        .-.     |~~~|
        |~|     |~~~|--.
    .---!-|  .--| C |--|
    |===|*|--|%%| f |  |
    |   |*|__|  | g |  |
    |===|*|==|  |   |  |
    |   |_|__|  |~~~|__|
    |===|~|--|%%|~~~|--|
    `---^-^--^--^---`--' hjw


A simple configuration interface with plaintext and encrypted file support.

## Benefits

  * seemless Python `dict` interface
    * unified config definition and defaults
  * YAML text file source for file-system input & serialization
    * nested entries supported
  * simple precedence
    * `defaults` **keys** define config **keys**
    * YAML **values** override `defaults` **values**
  * secrets support
    * secrets saved to private YAML file
    * secrets encrypted at rest via environment variable
    * update & mask from public YAML file

## Examples

### Config Definition and Defaults

    import figtion

    defaults = {'my server'       : 'www.bestsite.web'
               ,'number of nodes' : 5
               ,'password'        : 'huduyutakeme4'
               ,'nested stuff'    : {'breakfast' : 'coffee'}
               ,'listed stuff'    : ['a','b','c']}

    cfg = figtion.Config(defaults=defaults,filepath='./conf.yml')

    print(cfg['my server'])  

This will print either '[_www.bestsite.web_](.)' or the value of 'my server' in `./conf.yml` if it is something else.

*defaults* strictly defines the schema. Only keys present in *defaults* from a serial file will be retained. If you want to risk unspecified input keys and load everything from the YAML file, you can either omit the *defaults* parameter or set `promiscuous=True` when constructing `Config`.

### Config Secrets

When you want a public config file and a separate secret one.
To keep secret encrypted "at rest", set a secret key environment variable *FIGKEY*.

    os.environ["FIGKEY"] = "seepost-itnote"

    cfg = figtion.Config(defaults=defaults,filepath='./conf.yml',secretpath='./creds.yml')
    cfg.mask('password')

    print(cfg['password'])

This will print the value of `'password'`, which is stored in `./creds.yml` and not `./conf.yml`. If the value of `'password'` is changed in either YAML file, the password will be updated in `./creds.yml` and masked from `./conf.yml` the next time the class is loaded in Python. If a secret key is present via environment variable *FIGKEY*, the values in `./creds.yml` will be encrypted using that key.
The dictionary object returned for `cfg` contains the true value.

If you want everything treated as secret, provide a `secretpath` and omit `filepath`:

    cfg = figtion.Config(secretpath='./creds.yml')

In this case, no call to `mask` is needed and everything is encrypted at rest.

#### Encryption Details

This uses the *pynacl* bindings to the *libsodium* library, which uses [the XSalsa20 algorithm](https://libsodium.gitbook.io/doc/advanced/stream_ciphers/xsalsa20) for encryption. The encryption key provided by the *FIGKEY* environment variable is truncated to a 32-byte string.

## Roadmap

  * 0.9 - secrets store in separate location
  * 1.0 - secrets store in encrypted location
  * 1.1 - defaults explicitly separate from custom configs
  * 1.2 - automatic/dynamic reloading of YAML files


