# 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`.
### Self-Documenting Plaintext
Specify if/when you want to update stored plaintext file.
cfg = figtion.Config(..., promiscuous=True)
...
cfg.dump()
If `concise=True`, only modified values are stored in text file.
If `promiscuous=False` (default behavior), deprecated values are quietly removed.
Otherwise, serialized YAML will clarify default, modified, and deprecated values:
##############################
#### Modified ####
##############################
my server: www.newsite.web
##############################
#### Default ####
##############################
number of nodes: 5
##############################
#### Deprecated ####
##############################
fave cat: Zelda
### 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 - make default, modified, and unused properties explicit in plaintext
* 1.? - automatic/dynamic reloading of YAML files
* 1.? - support cascading configuration files
Raw data
{
"_id": null,
"home_page": "https://github.com/dactylroot/figtion",
"name": "figtion",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": null,
"keywords": "configuration secret raspberry pi embedded iot",
"author": "Cory Root",
"author_email": "dactylroot@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/cb/3b/1df9a21810c38dfe4db6bb21909ca395a16584be4bb84177358527878c4f/figtion-1.1.1.tar.gz",
"platform": null,
"description": "# figtion\n\n .---.\n .-. |~~~|\n |~| |~~~|--.\n .---!-| .--| C |--|\n |===|*|--|%%| f | |\n | |*|__| | g | |\n |===|*|==| | | |\n | |_|__| |~~~|__|\n |===|~|--|%%|~~~|--|\n `---^-^--^--^---`--' hjw\n\n\nA simple configuration interface with plaintext and encrypted file support.\n\n## Benefits\n\n * seemless Python `dict` interface\n * unified config definition and defaults\n * YAML text file source for file-system input & serialization\n * nested entries supported\n * simple precedence\n * `defaults` **keys** define config **keys**\n * YAML **values** override `defaults` **values**\n * secrets support\n * secrets saved to private YAML file\n * secrets encrypted at rest via environment variable\n * update & mask from public YAML file\n\n## Examples\n\n### Config Definition and Defaults\n\n import figtion\n\n defaults = {'my server' : 'www.bestsite.web'\n ,'number of nodes' : 5\n ,'password' : 'huduyutakeme4'\n ,'nested stuff' : {'breakfast' : 'coffee'}\n ,'listed stuff' : ['a','b','c']}\n\n cfg = figtion.Config(defaults=defaults,filepath='./conf.yml')\n\n print(cfg['my server']) \n\nThis will print either '[_www.bestsite.web_](.)' or the value of 'my server' in `./conf.yml` if it is something else.\n\n*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`.\n\n### Self-Documenting Plaintext\n\nSpecify if/when you want to update stored plaintext file.\n\n cfg = figtion.Config(..., promiscuous=True)\n ...\n cfg.dump()\n\nIf `concise=True`, only modified values are stored in text file.\nIf `promiscuous=False` (default behavior), deprecated values are quietly removed.\nOtherwise, serialized YAML will clarify default, modified, and deprecated values:\n \n\t##############################\n\t#### Modified ####\n\t##############################\n\tmy server: www.newsite.web\n\n\n\t##############################\n\t#### Default ####\n\t##############################\n\tnumber of nodes: 5\n\n\n\t##############################\n\t#### Deprecated ####\n\t##############################\n\tfave cat: Zelda\n\n\n### Config Secrets\n\nWhen you want a public config file and a separate secret one.\nTo keep secret encrypted \"at rest\", set a secret key environment variable *FIGKEY*.\n\n os.environ[\"FIGKEY\"] = \"seepost-itnote\"\n\n cfg = figtion.Config(defaults=defaults,filepath='./conf.yml',secretpath='./creds.yml')\n cfg.mask('password')\n\n print(cfg['password'])\n\nThis 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.\nThe dictionary object returned for `cfg` contains the true value.\n\nIf you want everything treated as secret, provide a `secretpath` and omit `filepath`:\n\n cfg = figtion.Config(secretpath='./creds.yml')\n\nIn this case, no call to `mask` is needed and everything is encrypted at rest.\n\n#### Encryption Details\n\nThis 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.\n\n## Roadmap\n\n * 0.9 - secrets store in separate location\n * 1.0 - secrets store in encrypted location\n * 1.1 - make default, modified, and unused properties explicit in plaintext\n * 1.? - automatic/dynamic reloading of YAML files\n * 1.? - support cascading configuration files\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple configuration interface with plaintext and encrypted file support.",
"version": "1.1.1",
"project_urls": {
"Download": "https://github.com/dactylroot/figtion/archive/1.1.1.tar.gz",
"Homepage": "https://github.com/dactylroot/figtion"
},
"split_keywords": [
"configuration",
"secret",
"raspberry",
"pi",
"embedded",
"iot"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d821016de1e0799cfa68b99b0ed061258a5d925ac03b351fde4cf3c0fad265f6",
"md5": "a1ff9a7cc939fe3aed1d33144ba28346",
"sha256": "e44bb230307b953d3b3cf5a72e55c9b1ed5a91ad1ea456459238dc0cb6feab08"
},
"downloads": -1,
"filename": "figtion-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a1ff9a7cc939fe3aed1d33144ba28346",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 8106,
"upload_time": "2024-08-13T20:26:52",
"upload_time_iso_8601": "2024-08-13T20:26:52.460523Z",
"url": "https://files.pythonhosted.org/packages/d8/21/016de1e0799cfa68b99b0ed061258a5d925ac03b351fde4cf3c0fad265f6/figtion-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cb3b1df9a21810c38dfe4db6bb21909ca395a16584be4bb84177358527878c4f",
"md5": "4466095329599edb32bda1780ec929eb",
"sha256": "42698a96d1e0078a67033499fa4d1f9f2fbcf6292998a26d48a66d7c105893f0"
},
"downloads": -1,
"filename": "figtion-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "4466095329599edb32bda1780ec929eb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 7433,
"upload_time": "2024-08-13T20:26:53",
"upload_time_iso_8601": "2024-08-13T20:26:53.454042Z",
"url": "https://files.pythonhosted.org/packages/cb/3b/1df9a21810c38dfe4db6bb21909ca395a16584be4bb84177358527878c4f/figtion-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-13 20:26:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dactylroot",
"github_project": "figtion",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "figtion"
}
JSON
