nyx-lang 0.1.5

Python parser and converter for the Nyx 0.1.2 data serialization language

nyx-lang

A small, dependency-free Python parser and converter for the Nyx 0.1.2 data serialization language.

Nyx is a flat, context-stateful format built around boxes, items, sub-items, pieces, and tape seals. It maps cleanly to JSON while keeping authoring readable for nested personal data.

Installation

pip install nyx-lang

Quick Start

import nyx_lang

source = """
^nyx=0.1.2
box: "Inventory"
sub-box: "Electronics"

item: "Console"
sub-item: "manufacturer"
sub-item: "Nintendo"
tape
sub-item: "controllers"
piece: "Pro Controller"
piece: "Joy-Con"
"""

data = nyx_lang.parse(source)
print(nyx_lang.to_json(data))

Output:

{
  "Inventory": {
    "Electronics": {
      "Console": {
        "manufacturer": "Nintendo",
        "controllers": [
          "Pro Controller",
          "Joy-Con"
        ]
      }
    }
  }
}

Command Line

The package installs a nyx command. You can also run it as a module with python -m nyx_lang.

# Nyx -> JSON
nyx to-json input.nyx --output output.json
python -m nyx_lang to-json input.nyx --output output.json

# JSON -> Nyx
nyx to-nyx input.json --output output.nyx
python -m nyx_lang to-nyx input.json --output output.nyx

# Print parsed JSON to the terminal
nyx parse input.nyx

# Validate a Nyx document
nyx validate input.nyx

On Windows, prefer --output over shell redirection so files are written as UTF-8.

API

nyx_lang.parse(source, *, strict=True) -> dict

Parse a Nyx document string into a Python dictionary.

from nyx_lang import parse

data = parse('^nyx=0.1.2\nbox: "Settings"\nitem: "theme"\nsub-item: "dark"')
assert data == {"Settings": {"theme": "dark"}}

strict=True raises NyxSyntaxError for unsupported versions. Version 0.1 documents are accepted for compatibility with earlier package builds.

nyx_lang.to_json(data, *, indent=2, **kwargs) -> str

Serialize parsed Nyx data to JSON. Extra keyword arguments are passed to json.dumps.

from nyx_lang import to_json

print(to_json({"Settings": {"theme": "dark"}}, indent=2))

nyx_lang.to_nyx(data) -> str

Serialize a Python dictionary to a Nyx 0.1.2 document.

from nyx_lang import to_nyx

print(to_nyx({"Settings": {"theme": "dark"}}))

Nyx Primer

Every document starts with a version header:

^nyx=0.1.2

Core statements:

Keyword	Effect
box: "Name"	Open a root container.
sub-box: "Name"	Open a nested container inside the active box.
sub-box: ""	Open the next anonymous array-object slot.
item: "Name"	Create an item in the active box.
sub-item: "key"	Add a child key under the active item.
piece: value	Append a scalar element to the active item list.
tape	Seal the current context and step up one level.

Primitive values:

sub-item: "string"
sub-item: 42
sub-item: 3.14
sub-item: true
sub-item: false
sub-item: null

A sub-item with exactly one scalar child collapses to a key-value pair:

sub-item: "temperature"
sub-item: -4.5

Result:

{ "temperature": -4.5 }

Flat arrays use piece:

item: "controllers"
piece: "Pro Controller"
piece: "Joy-Con"

Arrays of objects use anonymous sub-boxes:

box: "tabs"
sub-box: ""
item: "pageTitle"
sub-item: "Home"
tape
tape
sub-box: ""
item: "pageTitle"
sub-item: "Settings"

Result:

{
  "tabs": [
    { "pageTitle": "Home" },
    { "pageTitle": "Settings" }
  ]
}

Exceptions

Exception	When raised
NyxSyntaxError	Invalid syntax, invalid keyword, missing header, wrong context, or mixed item/list usage.
NyxVersionWarning	Unsupported version in lenient mode.

Development

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

Build artifacts are written to dist/.

Publishing Checklist

1. Confirm pyproject.toml has the intended version.
2. Run python -m pytest.
3. Run python -m build.
4. Inspect the wheel and source distribution in dist/.
5. Upload to TestPyPI first:

python -m twine upload --repository testpypi dist/*

6. Upload to PyPI:

python -m twine upload dist/*

License

Proprietary. See LICENSE for details.