python-iniparse

iniparse is a Python library for reading and writing INI configuration files that behaves as a near drop-in replacement for the standard library’s ConfigParser, RawConfigParser, and SafeConfigParser. Unlike the stdlib parser, it preserves the original structure of a file — section and option order, indentation, comments, and blank lines — so a config file edited by a program still looks handwritten afterward.

Values can be accessed with either container syntax (cfg[‘section’][‘option’]) or dotted attribute syntax (cfg.section.option), and the library ships a ConfigNamespace abstraction for building custom hierarchical configuration objects independent of INI files. This candlepin/python-iniparse fork keeps a project born inside Red Hat’s tooling ecosystem (originally packaged with patches from Fedora) alive with ongoing compatibility fixes for current Python versions.

What You Get

• A ConfigParser-compatible API (RawConfigParser, ConfigParser, SafeConfigParser) that’s a near drop-in swap for the standard library
• A structure-preserving INIConfig object that keeps comments, blank lines, and section/option order intact across edits
• Dotted and dict-style attribute access to config values via cfg.section.option or cfg[‘section’][‘option’]
• A tidy() utility for cleaning up excess blank lines in a config after programmatic edits
• ConfigNamespace/BasicConfig base classes for building your own hierarchical, dotted-access config objects unrelated to INI files

Common Use Cases

• Editing an existing INI config file from a script or CLI tool without clobbering the user’s comments and formatting
• Migrating an existing ConfigParser-based codebase to preserve file structure with minimal code changes
• Building admin tools that read and rewrite service configuration files (e.g. system daemons, package managers) in place
• Layering structured, dotted-access config objects on top of arbitrary key/value data in Python applications

Under The Hood

Architecture iniparse separates a low-level line-oriented parser (ini.py) from a high-level namespace abstraction (config.py) and a compatibility shim (compat.py) that adapts INIConfig to stdlib ConfigParser semantics. ini.py models a file as a sequence of typed LineType objects (SectionLine, OptionLine, and related line types) held in LineContainer instances, so reading and writing back a file only rewrites the lines that actually changed rather than fully re-serializing the document — a design built specifically to make round-trip edits non-destructive. config.py’s ConfigNamespace/Undefined pair implements the dotted-access behavior, with getattr/setattr delegating to _getitem/setitem and Undefined lazily materializing intermediate namespaces on assignment (so cfg.a.b.c = 1 auto-creates a and b). compat.py’s RawConfigParser wraps an INIConfig instance and re-implements each stdlib ConfigParser method against it, translating the flat dict-of-dicts model callers expect onto the namespace model underneath. It’s a small, cleanly layered codebase — four core modules, no runtime dependencies — where the main integration seam is the ConfigParser-compatibility layer versus using INIConfig directly, and any change to the LineType hierarchy would ripple to every consumer relying on line-level identity being preserved.

Tech Stack Pure Python standard library only — setup.py declares no install_requires, and the project supports Python 3.5 through 3.13 per its classifiers and tox.ini matrix. It uses re for line parsing, typing throughout for annotations, and vendors its own exception classes (DuplicateSectionError, NoSectionError, etc.) in iniparse/configparser.py rather than importing the stdlib module of the same name. Packaging is plain setuptools (setup.py, no pyproject.toml), tests run via tox across the full interpreter matrix, and GitHub Actions CI runs pytest inside Fedora and CentOS Stream containers — reflecting the project’s Red Hat/Fedora packaging heritage, which also shows up in the checked-in .packit.yaml and python-iniparse.spec RPM spec file.

Code Quality Tests are unittest-based (test_compat.py, test_ini.py, test_misc.py, test_multiprocessing.py, test_fuzz.py, test_unicode.py, test_tidy.py) plus doctest suites embedded directly in the ini.py and config.py docstrings, aggregated by a custom load_tests() in runtests.py — a comprehensive setup with dedicated fuzz and unicode coverage. Error handling uses a small hierarchy of custom exceptions mirroring the stdlib’s own names (ParsingError, MissingSectionHeaderError, DuplicateSectionError, NoSectionError, NoOptionError, InterpolationError variants) for drop-in compatibility, rather than swallowing failures. Naming follows PEP 8 and deliberately mirrors stdlib ConfigParser conventions. Type hints are present throughout the core modules (config.py, ini.py, compat.py all import from typing), though there’s no checked-in mypy configuration or lint/formatter config file. CI runs pytest across multiple OS containers on a monthly schedule plus every pull request, and a separate docstring-validation workflow checks test docstrings against Red Hat’s internal Polarion metadata format.

API Design iniparse’s core differentiator versus the stdlib configparser is the structure-preservation model itself — most INI parsers either discard the original file representation entirely or don’t attempt round-trip fidelity; iniparse’s line-object model is a deliberate design for making arbitrary programmatic edits non-destructive. Developer experience benefits from offering three access styles at once — dict-style, dotted-attribute style via ConfigNamespace, and the stdlib-compatible get/set method style via compat.py — so migrating from ConfigParser is close to zero-effort while still giving new code a more ergonomic option. Documentation leans heavily on runnable doctest examples embedded in the source rather than prose docs or a dedicated docs site, so discoverability depends on reading the README and docstrings directly. As a narrowly-scoped compatibility and utility library rather than a novel algorithm, it doesn’t break new ground beyond the structure-preservation idea, which remains a useful but still uncommon technique among INI parsers.