.. image:: https://api.cirrus-ci.com/github/pyscaffold/configupdater.svg?branch=main
:alt: Built Status
:target: https://cirrus-ci.com/github/pyscaffold/configupdater
.. image:: https://readthedocs.org/projects/pyscaffold/badge/?version=latest
:alt: ReadTheDocs
:target: https://configupdater.readthedocs.io/
.. image:: https://img.shields.io/coveralls/github/pyscaffold/configupdater/main.svg
:alt: Coveralls
:target: https://coveralls.io/r/pyscaffold/configupdater
.. image:: https://img.shields.io/pypi/v/configupdater.svg
:alt: PyPI-Server
:target: https://pypi.org/project/configupdater/
.. image:: https://img.shields.io/conda/vn/conda-forge/configupdater.svg
:alt: Conda-Forge
:target: https://anaconda.org/conda-forge/configupdater
.. image:: https://static.pepy.tech/badge/configupdater/month
:alt: Monthly Downloads
:target: https://pepy.tech/project/configupdater
.. image:: https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=ff69b4
:alt: Sponsor me
:target: https://github.com/sponsors/FlorianWilhelm
|
.. image:: https://configupdater.readthedocs.io/en/latest/_images/banner-640x323.png
:height: 323px
:width: 640px
:scale: 60 %
:alt: Config Updater
:align: center
|
The sole purpose of `ConfigUpdater`_ is to easily update an INI config file
with no changes to the original file except the intended ones. This means
comments, the ordering of sections and key/value-pairs as wells as their
cases are kept as in the original file. Thus ConfigUpdater provides
complementary functionality to Python's `ConfigParser`_ which is primarily
meant for reading config files and writing *new* ones.
Features
========
The key differences to `ConfigParser`_ are:
* minimal invasive changes in the update configuration file,
* proper handling of comments,
* only a single config file can be updated at a time,
* the original case of sections and keys are kept,
* control over the position of a new section/key
Following features are **deliberately not** implemented:
* interpolation of values,
* propagation of parameters from the default section,
* conversions of values,
* passing key/value-pairs with ``default`` argument,
* non-strict mode allowing duplicate sections and keys.
Usage
=====
First install the package with either::
pip install configupdater
or::
conda install -c conda-forge configupdater
Now we can simply do::
from configupdater import ConfigUpdater
updater = ConfigUpdater()
updater.read("setup.cfg")
which would read the file ``setup.cfg`` that is found in many projects.
To change the value of an existing key we can simply do::
updater["metadata"]["author"].value = "Alan Turing"
At any point we can print the current state of the configuration file with::
print(updater)
To update the read-in file just call ``updater.update_file()`` or ``updater.write(open('filename','w'))``
to write the changed configuration file to another destination. Before actually writing,
ConfigUpdater will automatically check that the updated configuration file is still valid by
parsing it with the help of ConfigParser.
Many of ConfigParser's methods still exists and it's best to look them up in the `module reference`_.
Let's look at some examples.
Adding and removing options
---------------------------
Let's say we have the following configuration in a string::
cfg = """
[metadata]
author = Ada Lovelace
summary = The Analytical Engine
"""
We can add an *license* option, i.e. a key/value pair, in the same way we would do with ConfigParser::
updater = ConfigUpdater()
updater.read_string(cfg)
updater["metadata"]["license"] = "MIT"
A simple ``print(updater)`` will give show you that the new option was appended to the end::
[metadata]
author = Ada Lovelace
summary = The Analytical Engine
license = MIT
Since the license is really important to us let's say we want to add it before the ``summary``
and even add a short comment before it::
updater = ConfigUpdater()
updater.read_string(cfg)
(updater["metadata"]["summary"].add_before
.comment("Ada would have loved MIT")
.option("license", "MIT"))
which would result in::
[metadata]
author = Ada Lovelace
# Ada would have loved MIT
license = MIT
summary = Analytical Engine calculating the Bernoulli numbers
Using ``add_after`` would give the same result and looks like::
updater = ConfigUpdater()
updater.read_string(cfg)
(updater["metadata"]["author"].add_after
.comment("Ada would have loved MIT")
.option("license", "MIT"))
Let's say we want to rename `summary` to the more common `description`::
updater = ConfigUpdater()
updater.read_string(cfg)
updater["metadata"]["summary"].key = "description"
If we wanted no summary at all, we could just do ``del updater["metadata"]["summary"]``.
Adding and removing sections
----------------------------
Adding and remove sections just works like adding and removing options but on a higher level.
Sticking to our *Ada Lovelace* example, let's say we want to add a section ``options`` just
before ``metadata`` with a comment and two new lines to separate it from ``metadata``::
updater = ConfigUpdater()
updater.read_string(cfg)
(updater["metadata"].add_before
.section("options")
.comment("Some specific project options")
.space(2))
As expected, this results in::
[options]
# Some specific project options
[metadata]
author = Ada Lovelace
summary = The Analytical Engine
We could now fill the new section with options like we learnt before. If we wanted to rename
an existing section we could do this with the help of the ``name`` attribute::
updater["metadata"].name = "MetaData"
Sometimes it might be useful to inject a new section not in a programmatic way but more declarative.
Let's assume we have thus defined our new section in a multi-line string::
sphinx_sect_str = """
[build_sphinx]
source_dir = docs
build_dir = docs/_build
"""
With the help of two ConfigUpdater objects we can easily inject this section into our example::
sphinx = ConfigUpdater()
sphinx.read_string(sphinx_sect_str)
sphinx_sect = sphinx["build_sphinx"]
updater = ConfigUpdater()
updater.read_string(cfg)
(updater["metadata"].add_after
.space()
.section(sphinx_sect.detach()))
The ``detach`` method will remove the ``build_sphinx`` section from the first object
and add it to the second object. This results in::
[metadata]
author = Ada Lovelace
summary = The Analytical Engine
[build_sphinx]
source_dir = docs
build_dir = docs/_build
Alternatively, if you want to preserve ``build_sphinx`` in both
``ConfigUpdater`` objects (i.e., prevent it from being removed from the first
while still adding a copy to the second), you call also rely on stdlib's
``copy.deepcopy`` function instead of ``detach``::
from copy import deepcopy
(updater["metadata"].add_after
.space()
.section(deepcopy(sphinx_sect)))
This technique can be used for all objects inside ConfigUpdater: sections,
options, comments and blank spaces.
Shallow copies are discouraged in the context of ConfigUpdater because each
configuration block keeps a reference to its container to allow easy document
editing. When doing editions (such as adding or changing options and comments)
based on a shallow copy, the results can be unreliable and unexpected.
For more examples on how the API of ConfigUpdater works it's best to take a look into the
`unit tests`_ and read the references.
Notes
=====
ConfigUpdater is mainly developed for `PyScaffold`_.
.. _ConfigParser: https://docs.python.org/3/library/configparser.html
.. _ConfigUpdater: https://configupdater.readthedocs.io/
.. _PyScaffold: https://pyscaffold.org/
.. _module reference: https://configupdater.readthedocs.io/en/latest/api.html#configupdater.configupdater.ConfigUpdater
.. _unit tests: https://github.com/pyscaffold/configupdater/blob/main/tests/test_configupdater.py
Raw data
{
"_id": null,
"home_page": "https://github.com/pyscaffold/configupdater",
"name": "ConfigUpdater",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Florian Wilhelm",
"author_email": "florian.wilhelm@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/2b/f4/603bd8a65e040b23d25b5843836297b0f4e430f509d8ed2ef8f072fb4127/ConfigUpdater-3.2.tar.gz",
"platform": "any",
"description": ".. image:: https://api.cirrus-ci.com/github/pyscaffold/configupdater.svg?branch=main\n :alt: Built Status\n :target: https://cirrus-ci.com/github/pyscaffold/configupdater\n.. image:: https://readthedocs.org/projects/pyscaffold/badge/?version=latest\n :alt: ReadTheDocs\n :target: https://configupdater.readthedocs.io/\n.. image:: https://img.shields.io/coveralls/github/pyscaffold/configupdater/main.svg\n :alt: Coveralls\n :target: https://coveralls.io/r/pyscaffold/configupdater\n.. image:: https://img.shields.io/pypi/v/configupdater.svg\n :alt: PyPI-Server\n :target: https://pypi.org/project/configupdater/\n.. image:: https://img.shields.io/conda/vn/conda-forge/configupdater.svg\n :alt: Conda-Forge\n :target: https://anaconda.org/conda-forge/configupdater\n.. image:: https://static.pepy.tech/badge/configupdater/month\n :alt: Monthly Downloads\n :target: https://pepy.tech/project/configupdater\n.. image:: https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=ff69b4\n :alt: Sponsor me\n :target: https://github.com/sponsors/FlorianWilhelm\n\n|\n\n.. image:: https://configupdater.readthedocs.io/en/latest/_images/banner-640x323.png\n :height: 323px\n :width: 640px\n :scale: 60 %\n :alt: Config Updater\n :align: center\n\n|\n\nThe sole purpose of `ConfigUpdater`_ is to easily update an INI config file\nwith no changes to the original file except the intended ones. This means\ncomments, the ordering of sections and key/value-pairs as wells as their\ncases are kept as in the original file. Thus ConfigUpdater provides\ncomplementary functionality to Python's `ConfigParser`_ which is primarily\nmeant for reading config files and writing *new* ones.\n\nFeatures\n========\n\nThe key differences to `ConfigParser`_ are:\n\n* minimal invasive changes in the update configuration file,\n* proper handling of comments,\n* only a single config file can be updated at a time,\n* the original case of sections and keys are kept,\n* control over the position of a new section/key\n\nFollowing features are **deliberately not** implemented:\n\n* interpolation of values,\n* propagation of parameters from the default section,\n* conversions of values,\n* passing key/value-pairs with ``default`` argument,\n* non-strict mode allowing duplicate sections and keys.\n\nUsage\n=====\n\nFirst install the package with either::\n\n pip install configupdater\n\nor::\n\n conda install -c conda-forge configupdater\n\nNow we can simply do::\n\n from configupdater import ConfigUpdater\n\n updater = ConfigUpdater()\n updater.read(\"setup.cfg\")\n\nwhich would read the file ``setup.cfg`` that is found in many projects.\n\nTo change the value of an existing key we can simply do::\n\n updater[\"metadata\"][\"author\"].value = \"Alan Turing\"\n\nAt any point we can print the current state of the configuration file with::\n\n print(updater)\n\nTo update the read-in file just call ``updater.update_file()`` or ``updater.write(open('filename','w'))``\nto write the changed configuration file to another destination. Before actually writing,\nConfigUpdater will automatically check that the updated configuration file is still valid by\nparsing it with the help of ConfigParser.\n\nMany of ConfigParser's methods still exists and it's best to look them up in the `module reference`_.\nLet's look at some examples.\n\nAdding and removing options\n---------------------------\n\nLet's say we have the following configuration in a string::\n\n cfg = \"\"\"\n [metadata]\n author = Ada Lovelace\n summary = The Analytical Engine\n \"\"\"\n\nWe can add an *license* option, i.e. a key/value pair, in the same way we would do with ConfigParser::\n\n updater = ConfigUpdater()\n updater.read_string(cfg)\n updater[\"metadata\"][\"license\"] = \"MIT\"\n\nA simple ``print(updater)`` will give show you that the new option was appended to the end::\n\n [metadata]\n author = Ada Lovelace\n summary = The Analytical Engine\n license = MIT\n\nSince the license is really important to us let's say we want to add it before the ``summary``\nand even add a short comment before it::\n\n updater = ConfigUpdater()\n updater.read_string(cfg)\n (updater[\"metadata\"][\"summary\"].add_before\n .comment(\"Ada would have loved MIT\")\n .option(\"license\", \"MIT\"))\n\nwhich would result in::\n\n [metadata]\n author = Ada Lovelace\n # Ada would have loved MIT\n license = MIT\n summary = Analytical Engine calculating the Bernoulli numbers\n\nUsing ``add_after`` would give the same result and looks like::\n\n updater = ConfigUpdater()\n updater.read_string(cfg)\n (updater[\"metadata\"][\"author\"].add_after\n .comment(\"Ada would have loved MIT\")\n .option(\"license\", \"MIT\"))\n\nLet's say we want to rename `summary` to the more common `description`::\n\n updater = ConfigUpdater()\n updater.read_string(cfg)\n updater[\"metadata\"][\"summary\"].key = \"description\"\n\nIf we wanted no summary at all, we could just do ``del updater[\"metadata\"][\"summary\"]``.\n\n\nAdding and removing sections\n----------------------------\n\nAdding and remove sections just works like adding and removing options but on a higher level.\nSticking to our *Ada Lovelace* example, let's say we want to add a section ``options`` just\nbefore ``metadata`` with a comment and two new lines to separate it from ``metadata``::\n\n updater = ConfigUpdater()\n updater.read_string(cfg)\n (updater[\"metadata\"].add_before\n .section(\"options\")\n .comment(\"Some specific project options\")\n .space(2))\n\nAs expected, this results in::\n\n [options]\n # Some specific project options\n\n\n [metadata]\n author = Ada Lovelace\n summary = The Analytical Engine\n\nWe could now fill the new section with options like we learnt before. If we wanted to rename\nan existing section we could do this with the help of the ``name`` attribute::\n\n updater[\"metadata\"].name = \"MetaData\"\n\nSometimes it might be useful to inject a new section not in a programmatic way but more declarative.\nLet's assume we have thus defined our new section in a multi-line string::\n\n sphinx_sect_str = \"\"\"\n [build_sphinx]\n source_dir = docs\n build_dir = docs/_build\n \"\"\"\n\nWith the help of two ConfigUpdater objects we can easily inject this section into our example::\n\n sphinx = ConfigUpdater()\n sphinx.read_string(sphinx_sect_str)\n sphinx_sect = sphinx[\"build_sphinx\"]\n\n updater = ConfigUpdater()\n updater.read_string(cfg)\n\n (updater[\"metadata\"].add_after\n .space()\n .section(sphinx_sect.detach()))\n\nThe ``detach`` method will remove the ``build_sphinx`` section from the first object\nand add it to the second object. This results in::\n\n [metadata]\n author = Ada Lovelace\n summary = The Analytical Engine\n\n [build_sphinx]\n source_dir = docs\n build_dir = docs/_build\n\nAlternatively, if you want to preserve ``build_sphinx`` in both\n``ConfigUpdater`` objects (i.e., prevent it from being removed from the first\nwhile still adding a copy to the second), you call also rely on stdlib's\n``copy.deepcopy`` function instead of ``detach``::\n\n from copy import deepcopy\n\n (updater[\"metadata\"].add_after\n .space()\n .section(deepcopy(sphinx_sect)))\n\nThis technique can be used for all objects inside ConfigUpdater: sections,\noptions, comments and blank spaces.\n\nShallow copies are discouraged in the context of ConfigUpdater because each\nconfiguration block keeps a reference to its container to allow easy document\nediting. When doing editions (such as adding or changing options and comments)\nbased on a shallow copy, the results can be unreliable and unexpected.\n\nFor more examples on how the API of ConfigUpdater works it's best to take a look into the\n`unit tests`_ and read the references.\n\n\nNotes\n=====\n\nConfigUpdater is mainly developed for `PyScaffold`_.\n\n.. _ConfigParser: https://docs.python.org/3/library/configparser.html\n.. _ConfigUpdater: https://configupdater.readthedocs.io/\n.. _PyScaffold: https://pyscaffold.org/\n.. _module reference: https://configupdater.readthedocs.io/en/latest/api.html#configupdater.configupdater.ConfigUpdater\n.. _unit tests: https://github.com/pyscaffold/configupdater/blob/main/tests/test_configupdater.py\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Parser like ConfigParser but for updating configuration files",
"version": "3.2",
"project_urls": {
"Changelog": "https://configupdater.readthedocs.io/en/latest/changelog.html",
"Conda-Forge": "https://anaconda.org/conda-forge/configupdater",
"Documentation": "https://configupdater.readthedocs.io/",
"Download": "https://pypi.org/project/configupdater/#files",
"Homepage": "https://github.com/pyscaffold/configupdater",
"Source": "https://github.com/pyscaffold/configupdater/",
"Tracker": "https://github.com/pyscaffold/configupdater/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e7f0b59cb7613d9d0f866b6ff247c5953ad78363c27ff5d684a2a98899ab8220",
"md5": "1394bce9dbb46ca8a6190475aaf62347",
"sha256": "0f65a041627d7693840b4dd743581db4c441c97195298a29d075f91b79539df2"
},
"downloads": -1,
"filename": "ConfigUpdater-3.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "1394bce9dbb46ca8a6190475aaf62347",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 34688,
"upload_time": "2023-11-27T17:16:43",
"upload_time_iso_8601": "2023-11-27T17:16:43.530484Z",
"url": "https://files.pythonhosted.org/packages/e7/f0/b59cb7613d9d0f866b6ff247c5953ad78363c27ff5d684a2a98899ab8220/ConfigUpdater-3.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2bf4603bd8a65e040b23d25b5843836297b0f4e430f509d8ed2ef8f072fb4127",
"md5": "3ceb028287e357e19aa98ce3d362eebb",
"sha256": "9fdac53831c1b062929bf398b649b87ca30e7f1a735f3fbf482072804106306b"
},
"downloads": -1,
"filename": "ConfigUpdater-3.2.tar.gz",
"has_sig": false,
"md5_digest": "3ceb028287e357e19aa98ce3d362eebb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 140603,
"upload_time": "2023-11-27T17:16:45",
"upload_time_iso_8601": "2023-11-27T17:16:45.434163Z",
"url": "https://files.pythonhosted.org/packages/2b/f4/603bd8a65e040b23d25b5843836297b0f4e430f509d8ed2ef8f072fb4127/ConfigUpdater-3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-27 17:16:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pyscaffold",
"github_project": "configupdater",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "configupdater"
}
JSON
