https://github.com/rec/cfgs
🍇 XDG standard config files 🍇
https://github.com/rec/cfgs
configuration configuration-files python
Last synced: about 1 year ago
JSON representation
🍇 XDG standard config files 🍇
- Host: GitHub
- URL: https://github.com/rec/cfgs
- Owner: rec
- License: mit
- Created: 2019-02-03T14:17:05.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2024-06-14T10:39:02.000Z (about 2 years ago)
- Last Synced: 2025-02-13T18:53:00.777Z (over 1 year ago)
- Topics: configuration, configuration-files, python
- Language: Python
- Homepage:
- Size: 130 KB
- Stars: 2
- Watchers: 3
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGELIST.md
- Funding: FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
`cfgs`
-------------
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:
.. code-block:: bash
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
==================
.. code-block:: python
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
======
.. code-block:: python
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 `_
.. code-block:: python
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 `_.
--------------------------------------
====== ======
|pic1| |pic2|
====== ======
.. |pic2| image::
https://img.shields.io/travis/rec/cfgs/master.svg?style=flat
.. |pic1| image:: https://img.shields.io/pypi/pyversions/cfgs.svg?style=flat