Skip to main content

A simple configuration interface with plaintext and encrypted file support.

Project description


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

A simple configuration interface with plaintext and encrypted file support.


  • 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


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')


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 for encryption. The encryption key provided by the FIGKEY environment variable is truncated to a 32-byte string.


  • 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

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

figtion-1.0.5.tar.gz (5.9 kB view hashes)

Uploaded source

Built Distribution

figtion-1.0.5-py3-none-any.whl (7.3 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page