iniconfig

Warnings

• breaking v2.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.
• breaking Duplicate 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.
• gotcha Inline 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().
• gotcha ini['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.
• gotcha iniconfig 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.
• deprecated The 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(...)`.
• gotcha IniConfig 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)`.

Install

• pip install iniconfig pip

Imports

• IniConfig

  import iniconfig
  ini = iniconfig.IniConfig('example.ini')

  Top-level module import; IniConfig is the only public class. Also available as `from iniconfig import IniConfig`.
• IniConfig (from string)

  import iniconfig
  ini = iniconfig.IniConfig(path=None, data='[s]\nk=v\n')

  Pass raw INI text via the `data` keyword argument; path is required positionally but ignored when data is provided — pass a sentinel or empty string.
• IniConfig.parse (2.3+)

  from iniconfig import IniConfig
  result = IniConfig.parse('[s]\nk=v # comment\n')

  IniConfig.parse() was added in 2.3.0 and strips inline comments and handles Unicode whitespace. IniConfig() itself still does NOT strip inline comments.
• ParseError

  from iniconfig import ParseError

  Raised on malformed INI input (duplicate sections, bad syntax). Must be imported explicitly.

Quickstart

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}")