yini-parser-python

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.

Project links

• YINI homepage
• YINI specification
• GitHub repository
• Bug reports and issues

Installation

Install from PyPI:

pip install yini-parser

The package name on PyPI is:

yini-parser

The Python import name is:

import yini_parser

Quick Start

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 = off

Conceptually, that parses to JSON-shaped data like this:

{
  "App": {
    "name": "Demo App",
    "version": 1.2,
    "features": ["search", "logs"],
    "debug": false,
    "pageSize": 25,
    "Server": {
      "host": "localhost",
      "port": 8080,
      "useTLS": false
    }
  }
}

Save the preceding configuration as config.yini, then parse it:

from yini_parser import load

data = load("config.yini")

print(data["App"]["name"])  # Demo App
print(data["App"]["Server"]["port"])  # 8080

Parse a YINI string:

from yini_parser import loads

data = loads("""
^ App
name = "Demo App"
version = 1.2
debug = false
""")

print(data["App"]["name"])  # Demo App

Use load(...) to parse a file and loads(...) to parse a string.

By default, both functions use lenient parsing. To validate a strict document, pass strict=True; strict documents require one top-level section and a final /END.

Inside backticked keys and section names, write \\ for one literal backslash.

See the YINI specification and documentation.

Examples

This repository includes small runnable examples in examples/.

Each Python script reads a .yini file from the same directory, so you can compare the configuration input with the code that loads it.

After cloning this repository, install the package locally:

python -m pip install -e .

If you use Task, the equivalent command is:

task install

Then run the examples from the repository root:

python examples/example1.py
python examples/example2.py
python examples/example3.py

What they show:

• examples/example1.py reads examples/basic.yini and prints basic app settings.
• examples/example2.py reads examples/nested.yini and shows nested sections as nested Python dictionaries.
• examples/example3.py reads examples/application.yini, validates required fields, and prints a small configuration report.

More YINI syntax examples are available on the YINI examples page.

Runnable example projects are available in the YINI demo apps repository:

• Python basic demo
• Python medium demo

Why YINI?

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:

YINI

^ Application
name = 'demo'
environment = 'dev'

^^ Server
host = 'localhost'
ports = [8080, 8081]

^^^ TLS
enabled = true
mode = 'optional'

• Application contains the top-level application settings.
• Server is nested under Application.
• TLS is nested under Server.
• The section markers ^ make the nesting explicit. Indentation is optional and not required for structure.
• Strings can use either ' or ".

JSON

{
  "Application": {
    "name": "demo",
    "environment": "dev",
    "Server": {
      "host": "localhost",
      "ports": [8080, 8081],
      "TLS": {
        "enabled": true,
        "mode": "optional"
      }
    }
  }
}

YAML

Application:
  name: demo
  environment: dev
  Server:
    host: localhost
    ports:
      - 8080
      - 8081
    TLS:
      enabled: true
      mode: optional

TOML

[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 specification and this parser are release candidates. Pin their versions and test against your application's requirements before using them in production.

Parser implementation

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.

ANTLR is a parser-generator tool: it turns the YINI grammar into Python code that can read and validate YINI files.

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.

Feedback and bug reports

If you find a problem, please open an issue on GitHub:

• Report a bug or issue

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-parser version.
• The Python version used.

Development

For local development:

python -m pip install -e ".[dev]"

or, if using the project Taskfile:

task install-dev

Generate the ANTLR parser sources:

task antlr

Run the full project check:

task check

This runs:

• The test suite with warnings treated as errors,
• Ruff lint checks,
• Ruff formatting checks,
• mypy type checking.

Tests

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.
• Backticked keys and section names, including escaped backslashes.
• Strict and lenient parser behavior.
• @yini strict and @yini lenient mode 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 error

or, if using the project Taskfile:

task test

Run the full project check with:

task check

🧪 Testing and Stability

This parser is covered by smoke, integration, and regression tests.

It has also been run against the shared external yini-test-suite conformance suite for YINI Specification 1.0.0 RC 6.

The CI conformance workflow runs the smoke and golden suites in both lenient and strict modes against a pinned release of yini-test-suite.

Links

• YINI specification
• YINI homepage
• YINI-lang on GitHub
• yini-parser on PyPI

^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.

yini-lang.org · YINI-lang on GitHub