imperfect

library0.4.0pypypi✓ verified 84d ago

Imperfect is a Python library (version 0.4.0) designed for editing `configparser`-compatible INI files while preserving comments and whitespace. It operates by parsing configuration files into a Concrete Syntax Tree (CST) of nodes, allowing programmatic modifications that maintain the original file's structural integrity. The library is under active development with irregular releases.

serialization

pip install imperfect

github ↗package ↗

INSTALL

IMPORT

SIG · IMPERFECT

imperfect

serializationpythonv0.4.0

Install

1.8s avg

Import

44ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.4.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.048s · 18MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.8s · import 0.041s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ConfigFile

✓ from imperfect import ConfigFile

parse_string

✓ from imperfect import parse_string

This quickstart demonstrates how to parse an existing INI-style configuration string using `imperfect.parse_string`, modify a value using `set_value`, and then retrieve the modified content, showcasing the preservation of comments and whitespace.

import imperfect import io # Simulate an existing config file content initial_config_content = ''' [metadata] # the package name name = imperfect # slurp the readme long_description = file: README.md [options] packages = imperfect ''' # Parse the string content into an imperfect.ConfigFile object conf: imperfect.ConfigFile = imperfect.parse_string(initial_config_content) # Set a new value, it will be added at the end of the section by default conf.set_value("metadata", "long_description_content_type", "text/markdown") # Print the modified content, preserving comments and whitespace print(conf.text)

Debug

Known issues

gotchaImperfect aims for compatibility with `configparser.RawConfigParser`, which includes replicating some of its longstanding 'odd behaviors' or bugs. Developers should be aware that certain quirks of `configparser` might be preserved rather than 'fixed'.

fix

Consult `configparser` documentation for detailed behavior, especially regarding edge cases, and test `imperfect`'s behavior thoroughly for critical parsing scenarios.

affects: All versions

gotchaWhile `imperfect` is designed to preserve whitespace and comments, precise control over their exact placement when inserting or deleting entries can be complex. Direct manipulation of `ConfigEntry` objects might be required for fine-grained control.

fix

For complex structural edits involving comments or specific whitespace, inspect and manipulate `ConfigEntry` objects directly rather than relying solely on high-level `set_value` methods. Review the output (`conf.text`) carefully after modifications.

affects: All versions

gotchaVersion 0.4.0 introduced support for parsing unnamed sections. If previous application logic relied on older `imperfect` versions to reject (or not parse) configuration files containing unnamed sections, this change could alter behavior. Such files will now be processed.

fix

Review any code that processes user-provided or external configuration files to ensure compatibility with the new unnamed section parsing behavior. Implement explicit validation if unnamed sections are still undesirable for your application.

affects: 0.4.0 and later

Errors

Common errors & fixes

KeyError: 'section_name' or unexpected behavior with casing of section/option names.

`imperfect` aims for `RawConfigParser` compatibility, which defaults to case-sensitive section and option names. If you are accustomed to `configparser.ConfigParser` (which is case-insensitive by default), this can lead to lookup failures or incorrect behavior.

fix

Always refer to section and option names with their exact casing as present in the INI file. If migrating from `configparser.ConfigParser` where `optionxform = str` was not explicitly set, be mindful of casing.

Modified configuration file loses comments, custom spacing, or has unexpected formatting after writing back.

Attempting to manipulate the configuration content as a plain string, or mixing `imperfect`'s CST-based editing with direct string operations or standard `configparser` methods that do not preserve comments and whitespace.

fix

Ensure all modifications are performed using the `imperfect.ConfigFile` object's methods (e.g., `set_value`, direct manipulation of `ConfigEntry` objects within sections). Always use `conf.text` or `conf.build(file_object)` to retrieve or write the modified content to ensure CST-based preservation.

Upgrade

Version history

0.4.0latest on PyPI · released Apr 24, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/advice-animal/imperfect ↗

packagehttps://pypi.org/project/imperfect/ ↗