yini-parser 0.2.0b1

Official Python parser for YINI, an INI-inspired, indentation-insensitive configuration format with clear nested sections and explicit structure.

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.

Status: Beta.
This parser is intended for early testing and integration. The public API and edge-case behavior may still change before 1.0.0.

---

Installation

Install from PyPI:

pip install yini-parser

The package name on PyPI is:

yini-parser

The Python import name is:

import yini_parser

---

Copy-paste test

Test 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}}}

---

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

Parse a YINI file:

from yini_parser import load

data = load("sample/basic.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.

See the YINI specification and documentation.

---

Examples

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.

• 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 and parser are still beta-stage and best suited for testing, experiments, and early integration feedback.

---

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.

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.

---

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.
• 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 yini-test-suite v0.3.0, the external YINI conformance test suite, with all TypeScript parser cases passing.

---

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