{"id":23344389,"url":"https://github.com/rec/cfgs","last_synced_at":"2025-04-07T16:46:40.414Z","repository":{"id":62561503,"uuid":"168952823","full_name":"rec/cfgs","owner":"rec","description":"🍇 XDG standard config files 🍇","archived":false,"fork":false,"pushed_at":"2024-06-14T10:39:02.000Z","size":133,"stargazers_count":2,"open_issues_count":4,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-02-13T18:53:00.777Z","etag":null,"topics":["configuration","configuration-files","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rec.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELIST.md","contributing":null,"funding":"FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"rec"}},"created_at":"2019-02-03T14:17:05.000Z","updated_at":"2024-06-14T10:39:06.000Z","dependencies_parsed_at":"2024-02-14T15:47:19.281Z","dependency_job_id":"166aec78-0df9-4e96-ad32-bdbd14ffa353","html_url":"https://github.com/rec/cfgs","commit_stats":null,"previous_names":["timedata-org/cfgs"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rec%2Fcfgs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rec%2Fcfgs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rec%2Fcfgs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rec%2Fcfgs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rec","download_url":"https://codeload.github.com/rec/cfgs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247693293,"owners_count":20980637,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["configuration","configuration-files","python"],"created_at":"2024-12-21T06:26:30.645Z","updated_at":"2025-04-07T16:46:40.389Z","avatar_url":"https://github.com/rec.png","language":"Python","funding_links":["https://github.com/sponsors/rec"],"categories":[],"sub_categories":[],"readme":"`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 \u003chttps://0x46.net/thoughts/2019/02/01/dotfile-madness/\u003e`_.\n\nGreat was my embarrasment to discover that there was a\n`neat little specification \u003chttps://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html\u003e`_\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 \u003chttps://raw.githubusercontent.com/rec/cfgs/master/cfgs.py\u003e`_\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\n\n    app.xdg.XDG_CONFIG_DIRS\n    #   /etc/xdg\n\n    with app.config.open() as f:\n        f.contents.update(name='oliver', species='dog')\n        f.contents['description'] = {'size': 'S', 'fur': 'brown'}\n        print(f.filename)\n    #    /home/tom/.config/my-project/my-project.json\n\n    # Later:\n    with app.config.open() as f:\n        print(f.contents['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\n    with directory.open('cache') as f:\n        f.write('cache data')\n\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 \u003chttps://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html\u003e`_\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 \u003chttps://rec.github.io/cfgs/cfgs.html\u003e`_.\n\n--------------------------------------\n\n====== ======\n|pic1| |pic2|\n====== ======\n\n\n.. |pic2| image::\n          https://img.shields.io/travis/rec/cfgs/master.svg?style=flat\n\n.. |pic1| image:: https://img.shields.io/pypi/pyversions/cfgs.svg?style=flat\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frec%2Fcfgs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frec%2Fcfgs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frec%2Fcfgs/lists"}