mojo-ini 🔥

January 27, 2026 · View on GitHub

INI file parser and writer for Mojo - Python configparser compatible

Parse and write INI configuration files in native Mojo with zero Python dependencies. Compatible with Python's configparser module for drop-in replacement in Mojo projects.

Features

✅ Python configparser Compatible - Drop-in replacement for Python's standard library
✅ Parser & Writer - Both read and write INI files
✅ Classic INI Support - Standard key = value syntax with [sections]
✅ Extended Features - Multiline values, inline comments, value interpolation
✅ Multiple Dialects - configparser (default) and classic INI modes
✅ Comprehensive Tests - Full test coverage
✅ Zero Dependencies - Pure Mojo implementation

Status: ✅ v0.2.0 Released - Production ready with comprehensive testing and benchmarks

Quick Start

Parsing INI Files:

from ini import parse

var config = parse("""
[Database]
host = localhost
port = 5432
user = admin

[Server]
debug = true
timeout = 30
""")

# Access values
print(config["Database"]["host"])    # localhost
print(config["Database"]["port"])    # 5432
print(config["Server"]["debug"])     # true

Writing INI Files:

from ini import to_ini

var data = Dict[String, Dict[String, String]]()
data["App"] = Dict[String, String]()
data["App"]["name"] = "MyApp"
data["App"]["version"] = "1.0"

var ini_text = to_ini(data)
print(ini_text)
# Output:
# [App]
# name = MyApp
# version = 1.0

See examples/read_example.mojo and examples/write_example.mojo for complete working examples.

Installation

Option 1: Magic Package Manager (Recommended)

magic add mojo-ini

Option 2: Git Submodule

git submodule add https://github.com/databooth/mojo-ini vendor/mojo-ini

Then in your Mojo code:

mojo -I vendor/mojo-ini/src your_app.mojo

Option 3: Direct Copy

cp -r mojo-ini/src/ini your-project/lib/ini

Usage

Basic Parsing

from ini import parse

var config = parse("""
[DEFAULT]
base_url = https://example.com

[API]
endpoint = /api/v1
timeout = 30
""")

print(config["API"]["endpoint"])  # /api/v1
print(config["API"]["timeout"])   # 30

File I/O

from ini import parse_file, write_file

# Read from file
var config = parse_file("config.ini")

# Modify
config["Server"]["port"] = "8080"

# Write back
write_file("config.ini", config)

See examples/file_io_example.mojo for a complete example.

Multiline Values

Indented lines are treated as continuations (Python configparser behavior):

from ini import parse

var config = parse("""
[Database]
connection_string = postgresql://host:5432/db
    ?sslmode=require
    &timeout=10
""")

# Result: connection_string contains all three lines with newlines
print(config["Database"]["connection_string"])
# postgresql://host:5432/db
# ?sslmode=require
# &timeout=10

Important: Lines starting with whitespace are ALWAYS treated as continuations, not as new keys. This matches Python configparser behavior.

Python configparser Compatibility

⚠️ Coming in v0.3.0 - ConfigParser API with type converters planned for future release.

For now, all values are strings. Manual conversion:

from ini import parse

var config = parse("...")

# Manual type conversion
var port = int(config["Server"]["port"])                    # Int
var debug = config["Server"]["debug"] == "true"            # Bool
var timeout = float64(config["API"]["timeout"])            # Float64

Supported INI Features

Classic INI (Default)

[section] headers
key = value pairs
# comments and ; comments
Multiline values (indented continuation)
Inline comments

Extended (configparser mode)

[DEFAULT] section for shared values
Value interpolation: %(var)s references
Type conversion helpers (getint, getboolean, etc.)
Case-insensitive section/key names (optional)

Known Limitations

Indented Keys Not Supported

By design, keys with leading whitespace are treated as multiline value continuations:

# ❌ This does NOT create a key named "indented_key"
[Section]
key1 = value1
  indented_key = value2  # This becomes part of key1's value!

This matches Python configparser behavior. If you need indented keys, consider:

TOML: Native support for nested tables (mojo-toml)
YAML: Indentation-based structure
Remove indentation: Keep all keys at column 0

Tab-Indented Keys (Git Config Style)

Git config files use tabs before keys, which mojo-ini treats as continuations. To use Git configs:

# Convert tabs to standard format
sed 's/^\t//' .git/config > config.ini

Or manually remove leading tabs from keys.

Python Compatibility

mojo-ini aims for high compatibility with Python's configparser:

Feature	Python configparser	mojo-ini v0.2
Basic key=value	✅	✅
[Sections]	✅	✅
[DEFAULT]	✅	🚧 Planned
Multiline values	✅	✅
Inline comments	✅	✅
Value interpolation	✅	🚧 Planned
	Type converters	✅
Case insensitive	✅	🚧 Planned

Development

Setup

# Install pixi (if not already installed)
curl -fsSL https://pixi.sh/install.sh | bash

# Install dependencies
pixi install

# Verify Mojo version
pixi run mojo-version

Testing

# Run all tests
pixi run test-all

# Run individual test suites
pixi run test-lexer
pixi run test-parser
pixi run test-writer
pixi run test-configparser

# Build package
pixi run build-package

Benchmarks

# Benchmark mojo-ini performance
pixi run benchmark-mojo

# Compare with Python configparser
pixi run benchmark-python

Roadmap

See ROADMAP.md for detailed development timeline.

v0.2.0 (Released: 2026-01-13) ✅

✅ Basic INI parsing (sections, key=value)
✅ INI writer
✅ Comments support (# and ;)
✅ Multiline values
✅ Comprehensive test suite (46 tests)
✅ Performance benchmarks with statistical reporting
✅ File I/O helpers (parse_file, write_file)

v0.3.0 (Target: Q2 2026)

🚧 [DEFAULT] section support
🚧 Value interpolation %(var)s
🚧 configparser API compatibility
🚧 Type converters (getint, getboolean, etc.)

v0.4.0 (Target: Q3 2026)

🚧 Case-insensitive mode
🚧 Git config format support
🚧 Advanced interpolation

Documentation

CHANGELOG.md - Version history and changes
docs/planning/ - Technical documentation and design docs
examples/ - Usage examples

mojo-toml - TOML 1.0 parser/writer for modern configs
mojo-dotenv - Environment variable management

Together these provide comprehensive configuration file support for Mojo! 🎯

Contributing

Contributions welcome! Please:

Follow existing code style (see mojo-toml for reference)
Add tests for new features
Update documentation
Use Australian English for docs, US spelling for code

License

Apache 2.0 License - see LICENSE file for details

Made with 🔥 by DataBooth