cfgs 0.14.0

🍇 XDG standard config files 🍇

Simple, correct handling of config, data and cache files

Like everyone else, I wrote a lot of programs which saved config files as dotfiles in the user’s home directory like ~/.my-program-name and now everyone’s home directory has dozens of these.

Then I read this article.

Great was my embarrasment to discover that there was a neat little specification for data, config and cache directories in Linux that prevents this problem, and that I was not using it:

So I implemented a small and simple Python API as a single file, cfgs.py.

It works on all versions of Python from 2.7 to 3.7, has complete test coverage, and all the functionality is reachable from a single class, cfgs.App

How it works in one sentence

Create a cfgs.App for your application, project, or script which handles finding, reading and writing your data and config files, and managing your cache directories.

How to install

You can either use pip:

pip install cfgs

Or if you don’t like dependencies (and who does?), you can drop the source file cgfs.py right into your project.

Usage examples

import cfgs
app = cfgs.App('my-project')
print(app.xdg.XDG_CACHE_HOME)
#   /home/tom/.cache

app.xdg.XDG_CONFIG_DIRS
#   /etc/xdg

with app.config.open() as f:
    f.contents.update(name='oliver', species='dog')
    f.contents['description'] = {'size': 'S', 'fur': 'brown'}
    print(f.filename)
#    /home/tom/.config/my-project/my-project.json

# Later:
with app.config.open() as f:
    print(f.contents['name'])
#    oliver

    print(f.as_dict())
#     {'name': 'oliver', 'species': 'dog',
#      'description': {'size': 'S', 'fur': 'brown'}

Cache

import cfgs
cache_size = 0x10000000
app = cfgs.App('my-project')
directory = app.cache.directory(cache_size=cache_size)

with directory.open('cache') as f:
    f.write('cache data')

# TODO: rewrite cache or add features.

Using cfgs In legacy code

If you already have code to handle your config, data and cache files, then you can just use cgfs to get the XDG variables

from cfgs import XDG

xdg = XDG()
config_dir = xdg.XDG_CONFIG_HOME

# Your code here - eg:
my_config_file = os.path.join(config_dir, 'my-file.json')
with open(my_config_file) as f:
    legacy_write_my_file(f)

cfgs automatically handles data and config files, and independently, cache directories.

API Documentation

API documentation is here.

---