iniconfig

library2.3.0pypypi✓ verified 50d ago

iniconfig is a minimal, read-only INI-file parser maintained under the pytest-dev umbrella. It preserves section and key order, supports multi-line values, strips `#` comments from structure (not inline values in <2.3), raises `ParseError` with accurate line numbers, and rejects duplicate section names. Current stable version is 2.3.0, released 2024. Release cadence is irregular but healthy, driven by pytest ecosystem needs.

serialization testing

pip install iniconfig

github ↗package ↗

Install & Compatibility

Where this runs

tested against v2.3.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.925 runs

installs and imports cleanly · install 0.0s · import 0.012s · 17.8MB

glibc

py 3.10–3.925 runs

installs and imports cleanly · install 1.5s · import 0.011s · 18MB

16MB installed

● package 16MB

Code

Verified usage

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

IniConfig

✓ from iniconfig import IniConfig

✗ import iniconfig

Parse an INI config from a string, access values, use .get() for safe access with a default and optional converter.

import iniconfig INI_TEXT = """ [database] host = localhost port = 5432 names = foo,bar [app] debug = true """ # Parse from a string (no file needed) ini = iniconfig.IniConfig("-", data=INI_TEXT) # Direct access — raises KeyError if key/section missing host = ini["database"]["host"] # 'localhost' # Safe access with default + optional converter port = ini.get("database", "port", 5432, int) # 5432 (int) names = ini.get("database", "names", [], lambda x: x.split(",")) # ['foo', 'bar'] missing = ini.get("database", "user", "root") # 'root' # Membership check assert "database" in ini assert "ghost" not in ini # Iterate sections for section in ini: print(section.name, list(section.items())) # Catch parse errors try: bad = iniconfig.IniConfig("-", data="[dup]\n[dup]\n") except iniconfig.ParseError as exc: print(f"Parse failed: {exc}")

Debug

Known issues

breakingv2.0.0 dropped Python 2 and older Python 3 (< 3.7) support and changed the packaging. The API surface stayed compatible, but pip will refuse to install 2.x on Python < 3.10 (requires_python >=3.10 as of 2.3.0).

fix

Use iniconfig==1.1.1 for Python < 3.10 environments, or upgrade the interpreter.

affects: <2.0.0

breakingDuplicate section names raise ParseError. Unlike stdlib configparser, iniconfig does NOT merge duplicates — the second occurrence is an error, not a silent override.

fix

Ensure each section name appears exactly once in the INI source before parsing.

affects: all

gotchaInline comments (e.g. `key = value # comment`) are NOT stripped by IniConfig() — the raw string including `# comment` is returned as the value. This differed silently from the README example in versions 2.0–2.2.

fix

Use IniConfig.parse() (added in 2.3.0) which does strip inline comments, or strip manually: value.split('#')[0].strip().

affects: 1.x – 2.2.x

gotchaini['section']['key'] raises KeyError — not returning None — when the section or key is absent. There is no .get() short-circuit on the section-level dict.

fix

Use ini.get(section, key, default) instead of direct bracket access for any optional key.

affects: all

gotchainiconfig is READ-ONLY. There is no write-back, set(), or save() method. Attempts to assign to ini['section']['key'] will raise TypeError or silently do nothing depending on the internal namedtuple/mapping type.

fix

Use stdlib configparser or a different library (e.g. configupdater) if you need to write or round-trip INI files.

affects: all

deprecatedThe old py.iniconfig path (from the `py` / pylib package) was the predecessor of this standalone package. Any code doing `import py; py.iniconfig.IniConfig(...)` is using a long-deprecated shim.

fix

Replace `py.iniconfig` with `import iniconfig` and `iniconfig.IniConfig(...)`.

affects: py<2.0

gotchaIniConfig constructor requires a path as its first positional argument even when parsing from a string via the `data=` kwarg. Passing `None` raises TypeError; pass a placeholder string like '-' or '<string>' instead.

fix

Always supply a non-None path: `IniConfig('-', data=my_string)`.

affects: all

Upgrade

Version history

2.3.0latest on PyPI

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

seranking-bot

ahrefsbot

Resources

githubhttps://github.com/pytest-dev/iniconfig ↗

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