The official Python parser for YINI (by the YINI-lang project) — a human-readable, INI-inspired, indentation-insensitive configuration format with clear nested sections, explicit structure, comments, and predictable parsing.
Status: Alpha.
This parser is intended for early testing and integration. The public API and edge-case behavior may still change before1.0.0.
Install from PyPI:
pip install yini-parserThe package name on PyPI is:
yini-parser
The Python import name is:
import yini_parserTest the package in under one minute.
Parse a YINI string:
from yini_parser import loads
data = loads("""
^ Application
name = "demo"
^^ Server
port = 8080
""")
print(data)Expected output:
{'Application': {'name': 'demo', 'Server': {'port': 8080}}}Example lenient-mode (default) YINI file:
// A small, practical YINI config.
// The App section starts here.
^ App
name = "Demo App"
version = 1.2
features = ["search", "logs"]
debug = false // off/no would work too.
pageSize = 25
// Nested under App. Indentation is optional and used for readability.
^^ Server
host = "localhost"
port = 8080 # YINI also supports # comments.
useTLS = offParse a YINI file:
from yini_parser import load
data = load("sample/basic.yini")
print(data["App"]["name"]) # Demo App
print(data["App"]["Server"]["port"]) # 8080Parse a YINI string:
from yini_parser import loads
data = loads("""
^ App
name = "Demo App"
version = 1.2
debug = false
""")
print(data["App"]["name"]) # Demo AppUse load(...) to parse a file and loads(...) to parse a string.
See the YINI specification and documentation.
Runnable example projects are available in the YINI demo apps repository.
The Python examples show how to install yini-parser, load .yini files, and access parsed configuration data in small practical scripts.
YINI is intended for configuration files where human readability, explicit structure, and predictable parsing are more important than minimal syntax or maximum flexibility.
Compared with common configuration formats:
- INI: YINI supports clearer nested sections and typed values.
- JSON: YINI supports comments and is easier to edit by hand.
- YAML: YINI does not use indentation to define structure.
- TOML: YINI uses explicit section markers for hierarchy instead of dotted table names.
The same small configuration can be written in several formats:
^ Application
name = 'demo'
environment = 'dev'
^^ Server
host = 'localhost'
ports = [8080, 8081]
^^^ TLS
enabled = true
mode = 'optional'Applicationcontains the top-level application settings.Serveris nested underApplication.TLSis nested underServer.- The section markers
^make the nesting explicit. Indentation is optional and not required for structure. - Strings can use either
'or".
{
"Application": {
"name": "demo",
"environment": "dev",
"Server": {
"host": "localhost",
"ports": [8080, 8081],
"TLS": {
"enabled": true,
"mode": "optional"
}
}
}
}Application:
name: demo
environment: dev
Server:
host: localhost
ports:
- 8080
- 8081
TLS:
enabled: true
mode: optional[Application]
name = "demo"
environment = "dev"
[Application.Server]
host = "localhost"
ports = [8080, 8081]
[Application.Server.TLS]
enabled = true
mode = "optional"YINI may not be the right choice when you need mature ecosystem support, existing schema tooling, or maximum compatibility with infrastructure that already expects JSON, YAML, or TOML. The format and parser are still alpha-stage and best suited for testing, experiments, and early integration feedback.
yini-parser uses Python parser code generated by ANTLR.
The generated Python parser files are included in the package. Users do not need Java or the ANTLR generator tool to install or use yini-parser.
The package depends on antlr4-python3-runtime because the generated lexer and parser use the ANTLR Python runtime while parsing.
The ANTLR generator JAR is only needed by maintainers when regenerating parser sources from the grammar, and it is not included in the published Python package.
If you find a problem, please open an issue on GitHub:
When reporting parser behavior, it is helpful to include:
- The YINI input that caused the issue.
- The expected result.
- The actual result or error message.
- The installed
yini-parserversion. - The Python version used.
For local development:
python -m pip install -e ".[dev]"or, if using the project Taskfile:
task install-devGenerate the ANTLR parser sources:
task antlrRun the full project check:
task checkThis runs:
- The test suite with warnings treated as errors,
- Ruff lint checks,
- Ruff formatting checks,
- mypy type checking.
The tests/ directory contains a focused implementation-local test suite, including tests for:
- The public loading API.
- Values, numbers, strings, lists, and inline objects, including lenient
=separators and strict:enforcement. - Sections, nested sections, section depth, and section marker separators.
- Strict and lenient parser behavior.
@yini strictand@yini lenientmode declarations.- Duplicate keys, repeated sections, and key/section collisions.
- String concatenation.
- Comments, ignored lines, smoke fixtures, and warning/error behavior.
Run the test suite with:
python -m pytest -v -W erroror, if using the project Taskfile:
task testRun the full project check with:
task check^YINI ≡
YINI is a human-readable, INI-inspired, indentation-insensitive configuration format with clear nested sections, explicit structure, and predictable parsing.
It has a formal specification and a defined grammar.