| Name | cfgs JSON |
| Version |
0.13.0
JSON |
| download |
| home_page | |
| Summary | 🍇 XDG standard config files 🍇 |
| upload_time | 2023-10-05 14:15:56 |
| maintainer | |
| docs_url | None |
| author | Tom Ritchford |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
`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 <https://0x46.net/thoughts/2019/02/01/dotfile-madness/>`_.
Great was my embarrasment to discover that there was a
`neat little specification <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_
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 <https://raw.githubusercontent.com/timedata-org/cfgs/master/cfgs.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/my-project
app.xdg.XDG_CONFIG_DIRS
# /etc/xdg
with app.config.open() as f:
f.update(name='oliver', species='dog')
f['description'] = {'size': 'S', 'fur': 'brown'}
print(f.filename)
# /home/tom/.cache/my-project/my-project.json
# Later:
with app.config.open() as f:
print(f['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)
# 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 <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_
.. 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 <https://timedata-org.github.io/cfgs/cfgs.html>`_.
--------------------------------------
====== ======
|pic1| |pic2|
====== ======
.. |pic2| image::
https://img.shields.io/travis/timedata-org/cfgs/master.svg?style=flat
.. |pic1| image:: https://img.shields.io/pypi/pyversions/cfgs.svg?style=flat
Raw data
{
"_id": null,
"home_page": "",
"name": "cfgs",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Tom Ritchford",
"author_email": "tom@swirly.com",
"download_url": "https://files.pythonhosted.org/packages/0f/95/b7d0e411b1b64cfe18016616b5e9baf733071182c6d8ff6a7d4ed1138751/cfgs-0.13.0.tar.gz",
"platform": null,
"description": "`cfgs`\n-------------\n\nSimple, correct handling of config, data and cache files\n==================================================================\n\nLike everyone else, I wrote a lot of programs which saved config files\nas dotfiles in the user's home directory like ``~/.my-program-name`` and now\neveryone's home directory has dozens of these.\n\nThen I read\n`this article <https://0x46.net/thoughts/2019/02/01/dotfile-madness/>`_.\n\nGreat was my embarrasment to discover that there was a\n`neat little specification <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_\nfor data, config and cache directories in Linux that prevents this problem, and\nthat I was not using it:\n\nSo I implemented a small and simple Python API as a single file, ``cfgs.py``.\n\nIt works on all versions of Python from 2.7 to 3.7, has complete test coverage,\nand all the functionality is reachable from a single class, ``cfgs.App``\n\nHow it works in one sentence\n===========================================\n\nCreate a ``cfgs.App`` for your application, project, or script which\nhandles finding, reading and writing your data and config files, and\nmanaging your cache directories.\n\nHow to install\n=====================\n\nYou can either use pip:\n\n.. code-block:: bash\n\n pip install cfgs\n\nOr if you don't like dependencies (and who does?), you can drop the source file\n`cgfs.py <https://raw.githubusercontent.com/timedata-org/cfgs/master/cfgs.py>`_\nright into your project.\n\n\nUsage examples\n==================\n\n.. code-block:: python\n\n import cfgs\n app = cfgs.App('my-project')\n print(app.xdg.XDG_CACHE_HOME)\n # /home/tom/.cache/my-project\n\n app.xdg.XDG_CONFIG_DIRS\n # /etc/xdg\n\n with app.config.open() as f:\n f.update(name='oliver', species='dog')\n f['description'] = {'size': 'S', 'fur': 'brown'}\n print(f.filename)\n # /home/tom/.cache/my-project/my-project.json\n\n # Later:\n with app.config.open() as f:\n print(f['name'])\n # oliver\n\n print(f.as_dict())\n # {'name': 'oliver', 'species': 'dog',\n # 'description': {'size': 'S', 'fur': 'brown'}\n\n\nCache\n======\n\n.. code-block:: python\n\n import cfgs\n cache_size = 0x10000000\n app = cfgs.App('my-project')\n directory = app.cache.directory(cache_size=cache_size)\n # TODO: rewrite cache or add features.\n\n\nUsing ``cfgs`` In legacy code\n=============================\n\nIf you already have code to handle your config, data and cache files, then you\ncan just use ``cgfs`` to get the\n`XDG variables <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_\n\n.. code-block:: python\n\n from cfgs import XDG\n\n xdg = XDG()\n config_dir = xdg.XDG_CONFIG_HOME\n\n # Your code here - eg:\n my_config_file = os.path.join(config_dir, 'my-file.json')\n with open(my_config_file) as f:\n legacy_write_my_file(f)\n\n\n``cfgs`` automatically handles data and config files, and independently, cache\ndirectories.\n\n\nAPI Documentation\n======================\n\nAPI documentation is `here <https://timedata-org.github.io/cfgs/cfgs.html>`_.\n\n--------------------------------------\n\n====== ======\n|pic1| |pic2|\n====== ======\n\n\n.. |pic2| image::\n https://img.shields.io/travis/timedata-org/cfgs/master.svg?style=flat\n\n.. |pic1| image:: https://img.shields.io/pypi/pyversions/cfgs.svg?style=flat\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "\ud83c\udf47 XDG standard config files \ud83c\udf47",
"version": "0.13.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0fbb870a4df371ec417f05cb13304b14687eba0730de11921f8bf4b30a9f0a46",
"md5": "36591db72562b609d26336e944061b0d",
"sha256": "a3e80a31e32c2fae987cb3c38481bbbf4b276bc517e8862f87e9ff174620fa09"
},
"downloads": -1,
"filename": "cfgs-0.13.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "36591db72562b609d26336e944061b0d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7767,
"upload_time": "2023-10-05T14:14:42",
"upload_time_iso_8601": "2023-10-05T14:14:42.310907Z",
"url": "https://files.pythonhosted.org/packages/0f/bb/870a4df371ec417f05cb13304b14687eba0730de11921f8bf4b30a9f0a46/cfgs-0.13.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0f95b7d0e411b1b64cfe18016616b5e9baf733071182c6d8ff6a7d4ed1138751",
"md5": "771312d359ada9f67cbe6940112ea003",
"sha256": "cef47e67f0512783ee83e24cc2f39e5b23b5d4ca0c32bbd721bd64f48636667e"
},
"downloads": -1,
"filename": "cfgs-0.13.0.tar.gz",
"has_sig": false,
"md5_digest": "771312d359ada9f67cbe6940112ea003",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 7482,
"upload_time": "2023-10-05T14:15:56",
"upload_time_iso_8601": "2023-10-05T14:15:56.443459Z",
"url": "https://files.pythonhosted.org/packages/0f/95/b7d0e411b1b64cfe18016616b5e9baf733071182c6d8ff6a7d4ed1138751/cfgs-0.13.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-05 14:15:56",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "cfgs"
}
