ConfigUpdater

3.2 · active · verified Thu Apr 09

ConfigUpdater is a Python library designed to update INI configuration files while preserving their original formatting, comments, and structure. It offers complementary functionality to Python's standard `ConfigParser`, which primarily focuses on reading and writing new files. The library aims for minimal, targeted changes, ensuring that the ordering of sections and key-value pairs, as well as their original casing, remain intact. The current version is 3.2, and it is actively maintained as part of the PyScaffold project.

Warnings

gotcha Shallow copies of configuration blocks (sections, options, comments) are highly discouraged. Each block maintains a reference to its container, and using shallow copies for modifications can lead to unreliable and unexpected results.
Fix: Always use `copy.deepcopy()` from the standard library if you need to duplicate a configuration block and modify the copy independently.
gotcha ConfigUpdater does *not* implement all features found in Python's standard `ConfigParser`. Specifically, it does not support value interpolation, propagation of parameters from the default section, value conversions, passing key/value pairs with default arguments, or a non-strict mode allowing duplicate sections and keys. Its focus is solely on minimal invasive updates.
Fix: Be aware of the distinct functionality. If you require these `ConfigParser` features, process your configuration with `ConfigParser` first, then use `ConfigUpdater` for targeted structural or value changes, or handle interpolation/conversion manually.
gotcha Direct assignment to an option's `.value` property (`updater['section']['key'].value = 'multi\nline'`) will fail if the value contains multiple lines. Multi-line values are explicitly disallowed for direct assignment.
Fix: For setting multi-line values, use the `set_values()` or `append()` methods provided by `ConfigUpdater` to handle them correctly.

Install

pip install configupdater Install with pip

Imports

ConfigUpdater
```
from configupdater import ConfigUpdater
```

Quickstart

This quickstart demonstrates how to read an INI file, modify an existing option, add new options (with and without comments), remove an option, and write the updated configuration back to the original file.

import os
from configupdater import ConfigUpdater

# Create a dummy config file for demonstration
config_content = '''
[metadata]
author = Ada Lovelace
summary = The Analytical Engine
version = 1.0

[options]
verbose = yes
path = /tmp/data
'''

config_file_path = "example.ini"
with open(config_file_path, "w") as f:
    f.write(config_content)

updater = ConfigUpdater()
updater.read(config_file_path)

# Change an existing value
updater["metadata"]["author"].value = "Grace Hopper"

# Add a new option
updater["metadata"]["license"] = "MIT"

# Add a new option with a comment before it
(updater["options"]["path"].add_before
 .comment("  # Path to store temporary files")
 .option("temp_dir", "/var/temp"))

# Remove an option
del updater["metadata"]["version"]

# Print the current state (optional)
# print(updater)

# Write the changes back to the original file
updater.update_file()

print(f"Updated configuration written to {config_file_path}")
with open(config_file_path, 'r') as f:
    print(f.read())

# Clean up the dummy file
os.remove(config_file_path)

view raw JSON →