nette-neon 1.0.0__tar.gz

nette_neon-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__
+.venv
+.pytest_cache
+.ruff_cache
+dist
+tests/neon-spec

nette_neon-1.0.0/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.5
+Name: nette-neon
+Version: 1.0.0
+Summary: NEON parser, encoder and lossless editor: change a value in a config file and keep its comments and formatting.
+Project-URL: Homepage, https://neon.nette.org
+Project-URL: Repository, https://github.com/nette/neon-py
+Author: David Grudl
+License-Expression: MIT
+License-File: license.md
+Keywords: config,cst,format-preserving,neon,nette,parser,round-trip
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+NEON for Python
+===============
+
+[![PyPI](https://img.shields.io/pypi/v/nette-neon.svg)](https://pypi.org/project/nette-neon/)
+[![Tests](https://github.com/nette/neon-py/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/nette/neon-py/actions)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/nette/neon-py/blob/master/license.md)
+
+ <!---->
+
+<h3>
+
+✅ A NEON parser that keeps [every comment and space](#the-tree-nodes-slots-tokens-trivia)<br>
+✅ [Edit a configuration file](#format-preserving-editing) and the diff is only your change<br>
+✅ [`neon-lint`](#for-editors-and-ai-agents) for editors, CI and AI agents<br>
+✅ [No dependencies](#installation), fully typed, Python 3.13+
+
+</h3>
+
+ <!---->
+
+**NEON parser, encoder and lossless editor for Python.** NEON is the human-friendly
+configuration format of the Nette framework, a YAML alternative with entities, and the format of
+`phpstan.neon`. This library parses it into a concrete syntax tree in which every character of
+the file has its place, so printing the tree gives the file back byte for byte:
+
+```python
+doc = parse(text)
+doc.print() == text   # True, for any input NEON accepts
+```
+
+That is what makes editing safe. Change a value, add a key, remove an item, and the rest of the
+file stays as its author wrote it:
+
+```python
+doc.set_value(["database", "host"], "db.example.com")
+```
+
+```
+- 	host: localhost   # the server
++ 	host: db.example.com   # the server
+```
+
+On that you build scripts that bump a setting in every `phpstan.neon` of a monorepo, installers
+that register an extension in `config.neon`, migrations that rename a service, and tools that
+read the configuration of a PHP project without running PHP.
+
+The library comes from David Grudl, the author of [Nette](https://nette.org),
+[Latte](https://latte.nette.org) and [Tracy](https://tracy.nette.org). NEON has been the
+configuration format of Nette since 2011, read by every Nette application, and this
+implementation follows the same specification as [nette/neon](https://github.com/nette/neon) for
+PHP and [@nette/neon](https://github.com/nette/neon-js) for JavaScript.
+
+ <!---->
+
+NEON in one minute
+==================
+
+```neon
+# mappings and sequences, indented by tabs or spaces
+database:
+	host: localhost
+	port: 3306
+
+roles: [guest, member, admin]   # inline arrays
+
+# entities: a value with attributes, the way Nette writes services
+mailer: App\Mailer(@smtp, timeout: 30)
+
+note: '''
+	multiline strings
+	without escaping
+'''
+```
+
+JSON is a subset of NEON, except for a colon at the start of a line glued to its value
+(`"a"` + new line + `:1`), which NEON reads as a literal. The format is described at
+[ne-on.org](https://ne-on.org) and in the [manual](https://doc.nette.org/en/neon/format).
+
+▶ Runnable examples: [examples/edge-cases](examples/edge-cases/)
+
+ <!---->
+
+Format-preserving editing
+=========================
+
+Most YAML libraries for Python, like PyYAML, drop comments and formatting when they write a
+file. Here keeping them is an invariant, not an effort: every edit changes the tokens it edits,
+and the four guarantees of the specification (the file reads back as the same tree, with the
+expected value, with the change only where it was made) are checked after every operation of a
+large corpus of edits.
+
+```python
+from neon import CommentPolicy, parse
+
+doc = parse(text)
+doc.set_value(["database", "port"], 3307)          # 0x0CEA stays hexadecimal: 0x0CEB
+doc.set_value(["database", "debug"], False)        # yes becomes no, not false
+doc.set_value(["timeout"], 30)                     # the same value: no change at all
+doc.set_value(["parameters", "admin"], "a@b.cz")   # a new key, indented like its siblings
+doc.add_item(["services"], "App\\OrderFacade")     # a new item of a list
+doc.remove_item(["database", "driver"])            # with the comment that describes it
+doc.remove_item(["mail"], comments=CommentPolicy.MOVE_TO_NEXT_TOKEN)
+```
+
+A missing key in the middle of a path is an error, so a typo does not create a new section.
+Removing the last item of a collection leaves it empty (`services: []`), because in a
+configuration empty and missing often mean different things; an item marked `nullable` loses its
+value instead. A refused edit changes nothing at all.
+
+▶ Runnable examples: [examples/editing](examples/editing/), [examples/config-editor](examples/config-editor/)
+
+ <!---->
+
+Installation
+============
+
+```shell
+uv add nette-neon        # or: pip install nette-neon
+```
+
+The package is imported as `neon`. Python 3.13 or newer, fully typed (`py.typed`), no
+dependencies.
+
+ <!---->
+
+The tree: nodes, slots, tokens, trivia
+======================================
+
+```python
+item = doc.find_item(["database", "user"])
+item.get_value()                    # 'root'
+item.get_trailing_comments()        # the comment on its line
+item.value.get_first_token().text   # the text exactly as written
+item.get_position()                 # Position(line, column, offset), from the current tree
+```
+
+Eight node classes (`DocumentNode`, `BlockArrayNode`, `InlineArrayNode`, `ArrayItemNode`,
+`EntityNode`, `EntityChainNode`, `StringNode`, `LiteralNode`) with named slots, tokens with their
+trivia (whitespace, line endings, comments), `find()`, `find_ancestor()`, siblings, and
+`Traverser` for a walk with replacements.
+
+▶ Runnable examples: [examples/tree](examples/tree/)
+
+ <!---->
+
+Decoding and encoding
+=====================
+
+```python
+from neon import decode, decode_file, encode
+
+decode("a: [1, 2]")                  # {'a': [1, 2]}
+decode_file("phpstan.neon")          # the value of a file
+encode({"a": [1, 2]})                # '{a: [1, 2]}'
+encode({"a": [1, 2]}, True)          # 'a:\n\t- 1\n\t- 2\n\n'
+encode({"a": [1, 2]}, lambda _, path: not path)        # 'a: [1, 2]\n', one level of blocks
+encode(config, lambda value, _: not isinstance(value, list))   # lists on one line
+```
+
+| NEON | Python |
+|---|---|
+| `null`, `true`, `yes` ... | `None`, `bool` |
+| integer | `int`, of any size |
+| float | `float` |
+| string | `str` |
+| date | `Date` (components and offset as written; `to_datetime()` for a `datetime`) |
+| entity, chain | `Entity` |
+| list | `list` |
+| map | `dict` with string keys, in the order of the file |
+
+The mapping is one-to-one: `1.0` stays a float, a big integer stays exact, `{}` is a `dict` and
+`[]` a `list`, and a key keeps its place. `encode()` takes `datetime` and `date` as well.
+`decode()` is typed as `json.loads()` is, `Any`; `to_value()` of the tree returns the exact
+union `neon.Value`.
+
+▶ Runnable examples: [examples/parsing](examples/parsing/), [examples/encoding](examples/encoding/)
+
+ <!---->
+
+One format, one specification
+=============================
+
+The format, the value model, the tree and the semantics of editing are written down in a
+language-neutral [specification](https://github.com/nette/neon-specification) with a conformance
+corpus, and every implementation runs that corpus in its tests. The values and the error messages
+were checked against nette/neon for PHP over 30,000 real-world files and 100,000 generated ones.
+The corpus is public; if you write an implementation of NEON for another language, use it.
+
+ <!---->
+
+For editors and AI agents
+=========================
+
+```shell
+neon-lint config/
+```
+
+```
+config/local.neon:3:2: Duplicated key 'user'
+```
+
+One line per finding, the exit code as the verdict, `--json` for tools; the same command, output
+and exit codes as `neon-lint` of the other implementations. Without installing anything:
+`uvx --from nette-neon neon-lint config/`.
+
+For **AI agents**, run it after every edit of a `.neon` file and hand a finding back as an error,
+so the agent fixes the file before it goes on. See [docs/skills/agents.md](docs/skills/agents.md).
+
+▶ Runnable examples: [examples/linting](examples/linting/)
+
+ <!---->
+
+Limits
+======
+
+- No formatter: the library keeps your formatting, it does not impose one.
+- No schema or validation of values.
+- No error recovery: an invalid file is reported, not partially parsed.
+- Positions are computed on request, from the current tree.
+
+ <!---->
+
+Documentation and credits
+=========================
+
+The [examples](examples/) are the documentation of the API, each chapter with the real output of
+its programs. The format itself is documented in the [Nette manual](https://doc.nette.org/en/neon).
+
+Released under the [MIT license](license.md).

nette_neon-1.0.0/docs/internals.md

@@ -0,0 +1,89 @@
+# Internals
+
+How `nette-neon` works where it is not obvious from the code. The format, the tree and the
+semantics of editing are defined by the specification (`tests/neon-spec/spec/`); the
+implementation is a port of `@nette/neon` for JavaScript, module by module, so the two can be
+read side by side. This document covers what is specific to this implementation.
+
+
+## Map
+
+| module | role |
+|---|---|
+| `scanner.py` | the hand-written scanner of grammar.md §1, `TokenKind`, `TriviaKind` |
+| `lexer.py` | tokens with trivia attached by the convention; `decode_utf8()`; `quote()` of messages |
+| `token.py` | `Token`, `Trivia`, the setters that keep trivia canonical, neighbours of a token |
+| `parser.py` | the parser of nette/neon 3.x ported onto tokens |
+| `nodes.py` | node classes, slots, queries, the facade methods of editing |
+| `values.py` | evaluation of literals and strings, canonical keys, `Date`, `Entity`, equality |
+| `encoder.py` | `encode()`, the one source of how a value is written |
+| `builder.py` | nodes from host values: encode, then parse |
+| `editing.py` | every mutation (mutations.md) |
+| `layout.py` | indentation unit, indentation of an item, line ending |
+| `_journal.py` | `atomic()` and `record()`, the undo of a refused edit, per thread and task |
+| `facade.py` | `decode()`, `decode_file()`, `parse_file()` |
+| `printer.py`, `dumper.py`, `traverser.py`, `lint.py` | as named |
+
+
+## Parsing
+
+- **The parser is the algorithm of 3.x**, kept parallel to `parser.ts` and to
+  `Nette\Neon\Parser`: the error messages and positions come from the order in which it looks
+  at tokens. Line endings are trivia, but the stream presents a line break before a token as
+  the pseudo-kind `Newline`, consumed once per gap.
+- **In an inline array, a value on the line after a key is the value of that key**, unlike in
+  3.x (specification 1.1). It is read once; when a colon follows it, it is handed over as the key
+  of the next item instead of being parsed again.
+- **The block on the line of a dash does not backtrack**: its indentation is a `_PendingIndent`
+  decided on the line where the block first compares it.
+- **Positions are code points, which is what a Python `str` is indexed by**, so an offset is an
+  index into the string and `Cursor` only counts lines.
+- **Integers have any size.** `int()` and `str()` refuse more than 4300 digits, so beyond about
+  4000 digits `values.py` converts through `Decimal`, which has no such limit.
+- **Arrays nest at most 500 levels** (`MAX_DEPTH`), and walking such a tree recursively
+  (`to_value()`, `get_tokens()`, `dump()`, the parser itself) takes several frames a level,
+  more than the default recursion limit of 1000. Importing the package raises the limit to at
+  least 10,000 frames; since Python 3.12 that costs no C stack.
+
+
+## The tree
+
+- Slots are private attributes behind read-only properties; a slot is written through
+  `_adopt()`, which refuses a node with a parent or one that would become its own ancestor. The
+  raw writes of the editing code are `_set_slots()`, `_set_items()`, `_set_value()`,
+  `_set_entities()`, `_set_leading()` and `_set_trailing()`; the public setters
+  (`item.value = node`, `document.value = node`, the trivia setters of a token) are editing
+  operations or check the neighbours.
+- Lists are tuples, so `items`, `entities` and the trivia of a token can be returned without a
+  copy and cannot be changed from outside. Identity matters: `Trivia` is a frozen dataclass and
+  two trivia with the same text are equal, so the code that looks for one (`replace_trivia()`,
+  the snapshots of the tests) compares with `is`.
+- `nodes.py` imports `editing.py` inside its methods, and `token.py` imports `nodes.py` inside
+  its functions, because each needs the other; keep the imports there.
+- `TokenKind` is a `StrEnum` whose values are the names of the specification, so the dump
+  prints them as they are and `token.is_(":")` (a text) is told from
+  `token.is_(TokenKind.COLON)` (a kind) by the type.
+
+
+## Editing
+
+- **A refused edit changes nothing.** The checks that can run first do so, and every public
+  mutation runs in `with atomic():`, which collects how to undo each raw write (`record()`) and
+  replays them in reverse when the block raises. A new mutation must run in `atomic()`, and a
+  new private attribute that an edit writes must `record()` its old value.
+- The rest follows `editing.ts` function by function: `replace_node()` and `detach_node()` decide
+  by the slot, writing an equal value is a no-op by `values_equal()`, new text comes from
+  `encode()` through `Builder`, and every operation that changes an array ends with
+  `_keep_keys()` and `_guard_grammar()`.
+- A Python `dict` keeps its order, so a host map is compared with the tree in order, and the
+  key of a `dict` may be a `str` or an `int` (never a `bool`).
+
+
+## Tests
+
+- `tests/test_corpus.py` and `tests/test_mutations.py` run every category of the corpus,
+  loaded by the strict validator of `tests/corpus.py`; `tests/test_mutation_fuzz.py` edits the
+  documents of the corpus at random against an independent model.
+- `tests/differential.py` compares with nette/neon 3.4 over the output of
+  `php-oracle.php outcomes` or `fuzz.php` from the specification repository.
+- `examples/verify.py` runs the examples and compares their output with the readmes.

nette_neon-1.0.0/docs/skills/agents.md

@@ -0,0 +1,65 @@
+# NEON for AI agents
+
+An agent that edits configuration files should learn about a broken file the moment it breaks
+it, not when the application fails to start. This guide sets that up with `neon-lint`, and shows
+how an agent should edit NEON from a Python script when it has to.
+
+`neon-lint` has the same output and exit codes in every implementation of NEON. In a Python
+project, use this one; in any other, the JavaScript package `@nette/neon` has a ready hook for
+Claude Code in its guide.
+
+
+## 1. Run the linter
+
+```shell
+uv add --dev nette-neon
+uv run neon-lint config/
+```
+
+or without installing anything, `uvx --from nette-neon neon-lint config/` (it needs the
+network the first time, so a hook should call the installed one).
+
+The output is one line per finding, `<path>:<line>:<column>: <message>`, and the exit code is the
+verdict: 0 valid, 1 a finding, 2 a wrong invocation or a failure of the linter itself.
+
+
+## 2. After every edit
+
+A hook of the agent runs `neon-lint <file>` after each edit of a `.neon` file and hands the
+output back to the agent when the exit code is 1, so it fixes the file before it goes on. Treat
+any other non-zero code as a failure of the check, shown to the user, so that an unchecked file
+never passes for a valid one. Where the agent has no hooks, put the rule into the instructions of
+the project:
+
+```markdown
+## NEON files
+
+- After every change of a `.neon` file, run `uv run neon-lint <file>`; exit code 0 is the only
+  acceptable result. The message says the line and the column.
+- Indentation is structure: a tab, or the spaces the file already uses. Never mix them in one block.
+```
+
+
+## 3. Editing NEON from a program
+
+When an agent writes a script that changes configuration, it should edit the tree, not the text
+with regular expressions. The tree keeps comments, blank lines, indentation and the style of
+values, and every edit leaves a valid file:
+
+```python
+from pathlib import Path
+
+from neon import parse_file
+
+path = Path("config/common.neon")
+doc = parse_file(path)
+doc.set_value(["database", "host"], "db.example.com")
+doc.set_value(["extensions", "my"], "App\\DI\\MyExtension")
+doc.remove_item(["parameters", "legacyOption"])
+path.write_text(doc.print(), encoding="utf-8", newline="")
+```
+
+`set_value()` on a path whose last key is missing adds it, a missing key in the middle of the path
+is an error (a typo does not create a section), and writing a value that is already there changes
+nothing. Write the file with `newline=""`, so that Python does not translate its line endings.
+See `examples/editing` for what each operation does to the text.

nette_neon-1.0.0/examples/config-editor/editor.py

@@ -0,0 +1,69 @@
+"""
+The core of a configuration editor: list the options of a file as the fields of a form,
+apply what the user changed, and save a file whose diff is exactly those changes.
+
+Usage: uv run python examples/config-editor/editor.py
+"""
+
+from collections.abc import Iterator
+from difflib import ndiff
+from textwrap import dedent
+
+from neon import ArrayNode, Node, PathSegment, parse
+
+file = dedent("""\
+    # Application settings
+    # (edited by hand and by the admin panel)
+
+    mail:
+    \thost: smtp.example.com   # outgoing server
+    \tport: 587
+    \tsecure: yes
+
+    cache:
+    \tenabled: true
+    \tttl: 3600   # seconds
+    \tpaths: [temp/cache]
+""")
+
+doc = parse(file)
+
+
+# 1. the fields of the form: every scalar with its path, its type and its comment
+def fields(node: Node | None, path: list[PathSegment]) -> Iterator[tuple]:
+    if not isinstance(node, ArrayNode):
+        return
+    for i, item in enumerate(node.items):
+        key = item.get_key_value()
+        item_path = [*path, i if key is None else key]
+        if isinstance(item.value, ArrayNode):
+            yield from fields(item.value, item_path)
+        else:
+            comment = " ".join(
+                c.get_comment_text() for c in item.get_trailing_comments()
+            )
+            yield item_path, item.get_value(), comment
+
+
+for path, value, comment in fields(doc.value, []):
+    key = ".".join(map(str, path))
+    print(f"{key:<14} {type(value).__name__:<8} {value!s:<18} {comment}".rstrip())
+
+# 2. what the user submitted: all fields, most of them unchanged
+submitted = {
+    "mail.host": "smtp.example.com",
+    "mail.port": 465,
+    "mail.secure": True,
+    "cache.enabled": False,
+    "cache.ttl": 3600,
+    "cache.paths.0": "temp/cache",
+}
+
+for key, value in submitted.items():
+    doc.set_value([int(s) if s.isdigit() else s for s in key.split(".")], value)
+
+# 3. save: only what changed is in the diff
+print()
+for line in ndiff(file.splitlines(), doc.print().splitlines()):
+    if line[0] in "-+":
+        print(line)

nette_neon-1.0.0/examples/config-editor/readme.md

@@ -0,0 +1,36 @@
+# A configuration editor: a form over a NEON file
+
+Use case number one: an admin panel shows the options of `config.neon` as the fields of a form,
+the user changes two of them and saves, and the file keeps its comments, its blank lines and
+everything the user did not touch.
+
+**You will learn:**
+
+- how to list the options of a file with their paths, types and comments
+- why saving all fields of a form changes only those the user changed
+
+```shell
+uv run python examples/config-editor/editor.py
+```
+
+## Load, edit, save (editor.py)
+
+```
+mail.host      str      smtp.example.com   outgoing server
+mail.port      int      587
+mail.secure    bool     True
+cache.enabled  bool     True
+cache.ttl      int      3600               seconds
+cache.paths.0  str      temp/cache
+
+- 	port: 587
++ 	port: 465
+- 	enabled: true
++ 	enabled: false
+```
+
+The fields come from the tree, not from the value: the tree knows the comment that explains an
+option and could tell the type a schema would expect. The form submits every field, and every
+one is written with `set_value()`; four of them carry the value they already had, and writing an
+equal value changes nothing, so the diff holds the two changes and nothing else. `secure: yes`
+stays `yes`, though the form sent `True`.

nette_neon-1.0.0/examples/edge-cases/edges.py

@@ -0,0 +1,40 @@
+"""
+The corners of the format that a tool meets in real files, and what the library does.
+
+Usage: uv run python examples/edge-cases/edges.py
+"""
+
+import json
+
+from neon import NeonError, decode, encode, parse
+
+
+def show(label: str, text: str) -> None:
+    try:
+        print(f"{label:<26}", json.dumps(decode(text)))
+    except NeonError as e:
+        print(f"{label:<26}", e)
+
+
+show("BOM and CRLF", "\ufeffa: 1\r\nb: 2\r\n")
+show("dash subblock", "list:\n- a\n- b\nnext: 1")
+show("block on a dash, tab", "- a: 1\n\tb: 2")
+show("block on a dash, 2 spaces", "- a: 1\n  b: 2")
+show("block on a dash, 4 spaces", "- a: 1\n    b: 2")
+show("value on the next line", "a:\n\tx")
+show("multiline indentation", "a: '''\n\t\tdeeper\n\tshallower\n'''")
+show("words that are not bool", "[on, off, tRuE]")
+show("implicit keys", "{5: a, b}")
+
+# edits keep what is not edited, the missing final line ending included
+doc = parse("a: 1\r\nb: 2")
+doc.set_value(["c"], 3)
+print("\nadd to CRLF without EOL  ", json.dumps(doc.print()))
+
+# a value whose first line starts with spaces is written so that it reads back the same
+value = "  indented first line\nsecond"
+print(
+    "encode leading spaces    ",
+    json.dumps(encode(value)),
+    decode(encode(value)) == value,
+)

nette_neon-1.0.0/examples/edge-cases/readme.md

@@ -0,0 +1,44 @@
+# Edge cases: the corners real files have
+
+NEON has a few rules that surprise a newcomer, and a tool that reads and writes configuration
+files meets all of them sooner or later. They are the rules of nette/neon, which every Nette
+application has read since 2011; this library keeps them, so a file means the same in PHP and here.
+
+**You will learn:**
+
+- how a byte order mark, CRLF and a missing final line ending are kept
+- the dash subblock, a block opened on the line of a dash, and a value on the next line
+- how the indentation of a multiline string is found
+- which words are not booleans, and how implicit keys count
+
+```shell
+uv run python examples/edge-cases/edges.py
+```
+
+## The rules (edges.py)
+
+```
+BOM and CRLF               {"a": 1, "b": 2}
+dash subblock              {"list": ["a", "b"], "next": 1}
+block on a dash, tab       [{"a": 1, "b": 2}]
+block on a dash, 2 spaces  [{"a": 1, "b": 2}]
+block on a dash, 4 spaces  Bad indentation on line 2 at column 5
+value on the next line     {"a": "x"}
+multiline indentation      {"a": "deeper\n\tshallower"}
+words that are not bool    ["on", "off", "tRuE"]
+implicit keys              {"5": "a", "6": "b"}
+
+add to CRLF without EOL   "a: 1\r\nb: 2\r\nc: 3"
+encode leading spaces     "\"\"\"\n\t\\u0020\\u0020indented first line\n\tsecond\n\"\"\"" True
+```
+
+A **dash subblock** is a list written at the same indentation as its key; it ends at the first
+item with a key. A **block opened on the line of a dash** (`- a: 1`) continues on the next line
+indented by a tab or by two spaces, nothing else, which is why four spaces are an error. The
+**indentation of a multiline string** is that of its first line; a line indented less keeps its
+whitespace. `on`, `off` and odd spellings like `tRuE` are strings, though the encoder quotes them.
+An item without a key gets **one more than the greatest integer key** before it.
+
+Edits keep the line endings of the file and its missing final line ending. And the encoder writes
+a string whose first line starts with spaces in `"""` with escapes, because in `'''` those spaces
+would be read as indentation.

nette_neon-1.0.0/examples/editing/adding.py

@@ -0,0 +1,41 @@
+"""
+Adding items: a new key gets the indentation of its siblings, a list item its dash, a
+missing section is created under the key that exists, and a typo in a path fails instead
+of adding a key.
+
+Usage: uv run python examples/editing/adding.py
+"""
+
+from difflib import ndiff
+from textwrap import dedent
+
+from neon import NeonError, parse
+
+text = dedent("""\
+    parameters:
+        mail: info@example.com
+
+    services:
+    \t- App\\Model\\UserFacade
+
+    extensions:
+""")
+
+doc = parse(text)
+doc.set_value(["parameters", "admin"], "admin@example.com")
+doc.add_item(["services"], "App\\Model\\OrderFacade")
+doc.set_value(["extensions", "console"], "Contributte\\Console\\DI\\ConsoleExtension")
+
+for line in ndiff(text.splitlines(), doc.print().splitlines()):
+    if line[0] in "-+":
+        print(line)
+
+print()
+try:
+    doc.set_value(["parametres", "admin"], "x")
+except NeonError as e:
+    print(e)
+try:
+    doc.set_value(["parameters", "amdin"], "x", create=False)
+except NeonError as e:
+    print(e)

nette_neon-1.0.0/examples/editing/inline.py

@@ -0,0 +1,33 @@
+"""
+Inline arrays: an item is added with the separator its neighbours use, on its own line in
+an array that spans lines, and the trailing comma stays where it was.
+
+Usage: uv run python examples/editing/inline.py
+"""
+
+from difflib import ndiff
+from textwrap import dedent
+
+from neon import parse
+
+text = dedent("""\
+    roles: [guest, member]
+    hosts: [
+    \talpha,
+    \tbeta,
+    ]
+    limits: {cpu: 2, memory: 512}
+    empty: []
+""")
+
+doc = parse(text)
+doc.add_item(["roles"], "admin")
+doc.add_item(["roles"], "root", position=0)
+doc.add_item(["hosts"], "gamma")
+doc.set_value(["limits", "disk"], 100)
+doc.remove_item(["limits", "cpu"])
+doc.add_item(["empty"], "first")
+
+for line in ndiff(text.splitlines(), doc.print().splitlines()):
+    if line[0] in "-+":
+        print(line)