CFG-RW

CFG-RW is a Python library for reading and writing properties in configuration files.

Installation

pip3 install cfgrw

Usage

Configuration file

CFG-RW can read configuration properties from YAML, JSON, INI, and XML files.

Create a configuration file, e.g. cfgrw.yaml:

---
handlers: "stream,file"
datefmt: "%Y-%m-%d %H:%M:%S"
filename: "stage/test-integration/test-yaml-conf.log"
filemode: "w"
format: "%(levelname)s %(message)s"
level: "info"

Create CFGRW object with specific conf_file, and read the values of the configuration properties:

from cfgrw import CFGRW

cfgrw = CFGRW(conf_file='path/to/cfgrw.yaml')
values = cfgrw.read(['handlers', 'filemode', 'level'])
print(values['handlers']) # will print stream,file
print(values['filemode']) # will print w
print(values['level']) # will print info

Environment variables

CFG-RW can also read configuration properties from environment variables with a given prefix.

For example, here are the environment variables with prefix CFGRW_ :

export CFGRW_HANDLERS="stream,file"
export CFGRW_DATEFMT="%Y-%m-%d %H:%M:%S"
export CFGRW_FILENAME="stage/test-integration/test-yaml-conf.log"
export CFGRW_FILEMODE="w"
export CFGRW_FORMAT="%(levelname)s %(message)s"
export CFGRW_LEVEL="info"

Create CFGRW object without conf_file, and read the value of the configuration properties with specified prefix:

cfgrw = CFGRW()
values = cfgrw.read(['handlers', 'filemode', 'level'], { 'prefix': 'CFGRW_' })
print(values['handlers']) # will print stream,file
print(values['filemode']) # will print w
print(values['level']) # will print info

Configuration file with environment variable fallback

If a property is not found in the configuration file, CFG-RW will fall back to reading it from an environment variable. This requires a prefix to be passed in the options.

For example, given a configuration file cfgrw.yaml that only contains handlers and level:

---
handlers: "stream,file"
level: "info"

and the following environment variable for the missing filemode property:

export CFGRW_FILEMODE="w"

CFG-RW will read handlers and level from the file, then fall back to the environment variable for filemode:

from cfgrw import CFGRW

cfgrw = CFGRW(conf_file='path/to/cfgrw.yaml')
values = cfgrw.read(['handlers', 'filemode', 'level'], { 'prefix': 'CFGRW_' })
print(values['handlers']) # will print stream,file
print(values['filemode']) # will print w (from environment variable)
print(values['level'])    # will print info

If a property is missing from both the configuration file and the environment variables, it will simply be absent from the returned values dict — no error is raised.

Configuration file with Jinja template

CFG-RW can read configuration properties with YAML, JSON, INI, and XML within a Jinja template. You just need to add a .j2 to the configuration file name.

Create a configuration Jinja template, e.g. cfgrw.yaml.j2:

---
handlers: "{{ env.FOOBAR_HANDLERS }}"
datefmt: "%Y-%m-%d %H:%M:%S"
filename: "stage/test-integration/test-yaml-conf.log"
filemode: "{{ env.FOOBAR_FILEMODE }}"
format: "%(levelname)s %(message)s"
level: "{{ env.FOOBAR_LEVEL }}"

and the following environment variables:

export FOOBAR_HANDLERS="stream,file"
export FOOBAR_FILEMODE="w"
export FOOBAR_LEVEL="info"

Create CFGRW object with specific conf_file, and read the values of the configuration properties:

from cfgrw import CFGRW

cfgrw = CFGRW(conf_file='path/to/cfgrw.yaml.j2')
values = cfgrw.read(['handlers', 'level', 'level'])
print(values['handlers']) # will print stream,file
print(values['filemode']) # will print w
print(values['level']) # will print info

Configuration

CFG-RW automatically loads the configuration file based on the extension.

Format	Extension
INI	.ini
JSON	.json
XML	.xml
YAML	.yaml or .yml
Jinja	.ini.j2 or .json.j2 or .xml.j2 or .yaml.j2 or .yml.j2

Colophon

Developer's Guide

Build reports:

• Lint report
• Code complexity report
• Unit tests report
• Test coverage report
• Integration tests report
• API Documentation