Biconfigs

📄⇄🛠 Two way configurations mapping helper for Python.

Get Started

from biconfigs import Biconfigs
configs = Biconfigs('configs.json')

# Simply change the dict, and it will automatically save the changes to file.
configs['options'] = {'debug': True,
                      'username': 'Anthony',
                      'list': [] }

# Access with simple 'x.y.z' style
configs.options.list.append('example')

Content of file configs.json after execution:

{
  "options": {
    "debug": true,
    "list": [
      "example"
    ],
    "username": "Anthony"
  }
}

* Biconfigs also supports CSON and YAML file formats.

Install

pip install biconfigs

Dependencies

No dependencies required 🎉

Tested on Python 2.6, 2.7, 3.3, 3.4, 3.5, pypy, pypy3

Documentation

When to save

• Saving when: Item create, item delete, list reorder, value change, setdefault, etc.

# All the following single statement will cause saving
configs['item'] = 'value'
configs['options'] = {}
configs.options['list'] = []
configs.options.list.append('example')
configs.options['list'] = []
configs.options.clear()
value2 = configs.setdefault('item2', 45)

• Not saving when: Item access, assignment but not changed, etc.

# All the following single statement will NOT cause saving
value = configs.item
configs['item'] = 'value' # The value of 'item' is not changed
value3 = configs.get('item_not_exists', 'default_value')

Non-blocking saving

By default, Biconfigs use asynchronous saving. You can disable the feature by setting async_write to False

# set "async_write=False" if your want to use synchronous saving
# to ensure your data saved to file in time,
# WARNING: In sync mode, your changes will block the incoming statement
# until the file correctly saved.
configs = Biconfigs('configs.json', async_write=False)

configs['item'] = 'value' # Blocking
# Configure file saved already

# Your code...

High frequency update

Normally, Biconfigs will write the changes to file immediately. But sometime you may want to update values frequently, which will result in a IO bottleneck. So you can use with statement to prevent auto saving for a while.

with configs:
  for i in range(1000):
    configs['some_key'] = i
# This statement will execute saving process only one time when exiting "with" scope

Reload from file

Simply use reload function to reload from file. Note: reload will discard all present data in Biconfigs-object and loads new ones from file)

configs.reload()

Parsers

Biconfigs use Prettified Json as default parser. You may want to set parser='json' to save as compacted json file.

configs = Biconfigs('configs.json', parser='json')
configs['item'] = 'value'
configs['debug'] = False

configs.json:

{"debug": false, "item": "value"}

Available Parsers

• json: Compact JSON format
• pretty-json: Prettified JSON
• cson: CSON format, refer to CSON
• yaml: YAML format, refer to YAML

CSON

Biconfigs supports CSON by avakar/pycson

from biconfigs import Biconfigs
from biconfigs import parser_cson

configs = Biconfigs('configs.cson', parser='cson')
# Then use biconfigs as you normally would...

Extra requirements

To use CSON, you need to install extra requirement

pip install biconfigs[cson]

Or install cson manually:

pip install cson

CSON problems

Please check avakar/pycson: The Language

YAML

Biconfigs supports YAML by PyYAML

from biconfigs import Biconfigs
from biconfigs import parser_yaml

configs = Biconfigs('configs.yml', parser='yaml')
# Then use biconfigs as you normally would...

Extra requirements

To use YAML, you need to install extra requirement

pip install biconfigs[yaml]

Or install PyYAML manually:

pip install PyYAML

License

MIT