nette-neon 1.0.0__py3-none-any.whl

neon/__init__.py

@@ -0,0 +1,83 @@
+"""NEON parser, encoder and lossless editor."""
+
+import sys
+
+from .builder import Builder, Place
+from .dumper import dump
+from .encoder import BlockFilter, encode
+from .errors import NeonError
+from .facade import decode, decode_file, parse_file
+from .layout import Layout
+from .lexer import decode_utf8, tokenize
+from .nodes import (
+    ArrayItemNode,
+    ArrayNode,
+    BlockArrayNode,
+    CommentPolicy,
+    DocumentNode,
+    EntityChainNode,
+    EntityNode,
+    InlineArrayNode,
+    ItemIndex,
+    LiteralNode,
+    Node,
+    PathSegment,
+    StringNode,
+    ValueNode,
+)
+from .parser import parse
+from .position import Position
+from .printer import locate_all, print_node, print_text
+from .scanner import TokenKind, TriviaKind
+from .token import Token, Trivia
+from .traverser import TraverseAction, Traverser, Visitor, VisitResult
+from .values import CHAIN, MAX_DEPTH, Date, Entity, Value
+
+# arrays nest 500 levels deep, and walking such a tree takes more frames than the default
+sys.setrecursionlimit(max(sys.getrecursionlimit(), MAX_DEPTH * 20))
+
+__all__ = [
+    "CHAIN",
+    "ArrayItemNode",
+    "ArrayNode",
+    "BlockArrayNode",
+    "BlockFilter",
+    "Builder",
+    "CommentPolicy",
+    "Date",
+    "DocumentNode",
+    "Entity",
+    "EntityChainNode",
+    "EntityNode",
+    "InlineArrayNode",
+    "ItemIndex",
+    "Layout",
+    "LiteralNode",
+    "NeonError",
+    "Node",
+    "PathSegment",
+    "Place",
+    "Position",
+    "StringNode",
+    "Token",
+    "TokenKind",
+    "TraverseAction",
+    "Traverser",
+    "Trivia",
+    "TriviaKind",
+    "Value",
+    "ValueNode",
+    "VisitResult",
+    "Visitor",
+    "decode",
+    "decode_file",
+    "decode_utf8",
+    "dump",
+    "encode",
+    "locate_all",
+    "parse",
+    "parse_file",
+    "print_node",
+    "print_text",
+    "tokenize",
+]

neon/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .lint import main
+
+sys.exit(main())

neon/_journal.py

@@ -0,0 +1,40 @@
+from collections.abc import Callable
+from contextvars import ContextVar, Token
+from types import TracebackType
+
+type _Entries = list[Callable[[], None]]
+
+# per thread and per asyncio task, so that an edit never records into a journal of another
+_journal: ContextVar[_Entries | None] = ContextVar("journal", default=None)
+
+
+def record(undo: Callable[[], None]) -> None:
+    """Notes how to undo a write of the tree, while an atomic() operation runs."""
+    entries = _journal.get()
+    if entries is not None:
+        entries.append(undo)
+
+
+class atomic:
+    """Runs an operation; if it raises, every write it made is undone."""
+
+    __slots__ = ("_token",)
+
+    def __enter__(self) -> None:
+        self._token: Token[_Entries | None] | None = None
+        if _journal.get() is None:
+            self._token = _journal.set([])
+
+    def __exit__(
+        self,
+        kind: type[BaseException] | None,
+        error: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        if self._token is None:
+            return
+        entries = _journal.get()
+        _journal.reset(self._token)
+        if error is not None and entries:
+            for undo in reversed(entries):
+                undo()

neon/builder.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from .encoder import Encoder, encode
+from .errors import NeonError
+from .nodes import ArrayItemNode, ArrayNode, ValueNode
+from .parser import parse
+from .values import is_integer_key
+
+
+@dataclass(frozen=True, slots=True)
+class Place:
+    """Where a built node will stand."""
+
+    block: bool
+    """Write arrays as blocks."""
+    indent: str
+    """Indentation of the line of the item that will hold the value."""
+    unit: str
+    """Indentation unit of nested blocks."""
+    eol: str
+    """Line ending of the document."""
+    double_quoted: bool = False
+    """Write multiline strings in \"\"\", because ''' would close an earlier string."""
+
+
+class Builder:
+    """
+    Makes nodes from values of the host. The text is what encode() writes, so new
+    values look the same as encoded ones; it is parsed, so the nodes are valid by
+    construction.
+    """
+
+    @staticmethod
+    def value(value: object, place: Place) -> ValueNode:
+        """A value as a node, without edge trivia; a non-empty array is a block if allowed."""
+        block = place.block and _has_items(value)
+        text = Encoder(block, place.unit, place.double_quoted).encode(value)
+        if block:
+            text = _indent(text.rstrip("\n"), place.indent + place.unit, first=True)
+        else:
+            text = _indent(text, place.indent, first=False)
+        node = Builder.parse(text.replace("\n", place.eol))
+        if not block:
+            node.get_first_token()._set_leading(())
+        node.get_last_token()._set_trailing(())
+        return node
+
+    @staticmethod
+    def block_item(key: str | None, value: object, place: Place) -> ArrayItemNode:
+        """An item of a block, `key: value` or `- value`, with its indentation and line ending."""
+        head = "-" if key is None else Builder.key_text(key) + ":"
+        if value is None and key is not None:
+            text = head
+        elif _has_items(value):
+            body = Encoder(True, place.unit, place.double_quoted).encode(value)
+            text = head + "\n" + _indent(body.rstrip("\n"), place.unit, first=True)
+        else:
+            encoded = Encoder(False, place.unit, place.double_quoted).encode(value)
+            text = head + " " + encoded
+        text = _indent(text, place.indent, first=True).replace("\n", place.eol)
+        block = Builder.parse(text + place.eol)
+        assert isinstance(block, ArrayNode)
+        item = block.items[0]
+        block._set_items(())
+        return item
+
+    @staticmethod
+    def parse(text: str) -> ValueNode:
+        """The value of a document made of the text, detached, its tokens without an origin."""
+        document = parse(text)
+        node = document.value
+        assert node
+        document._set_value(None)
+        for token in node.get_tokens():
+            token._forget_origin()
+        return node
+
+    @staticmethod
+    def key_text(key: str) -> str:
+        """The text of a key: an integer key as digits, anything else as a string."""
+        if "\n" in key:
+            raise NeonError("A key cannot contain a line break.")
+        return key if is_integer_key(key) else encode(key)
+
+
+def _has_items(value: object) -> bool:
+    """A non-empty list, tuple or mapping."""
+    return isinstance(value, list | tuple | Mapping) and len(value) > 0
+
+
+def _indent(text: str, prefix: str, *, first: bool) -> str:
+    """Prefixes non-empty lines; the first one only if asked."""
+    return "\n".join(
+        prefix + line if line and (i or first) else line
+        for i, line in enumerate(text.split("\n"))
+    )

neon/dumper.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from .nodes import Node
+from .token import Token, Trivia
+
+_SLOTS = {
+    "DocumentNode": (("value", "value"), ("endOfFile", "end_of_file")),
+    "BlockArrayNode": (("items", "items"),),
+    "InlineArrayNode": (
+        ("openBracket", "open_bracket"),
+        ("items", "items"),
+        ("closeBracket", "close_bracket"),
+    ),
+    "ArrayItemNode": (
+        ("bullet", "bullet"),
+        ("key", "key"),
+        ("colon", "colon"),
+        ("value", "value"),
+        ("separator", "separator"),
+    ),
+    "EntityNode": (("value", "value"), ("attributes", "attributes")),
+    "EntityChainNode": (("entities", "entities"),),
+    "StringNode": (("token", "token"),),
+    "LiteralNode": (("token", "token"),),
+}
+
+_SHORT_ESCAPES = {"\b": "\\b", "\f": "\\f", "\n": "\\n", "\r": "\\r", "\t": "\\t"}
+
+
+def dump(node: Node) -> str:
+    """Text form of the tree, as in the conformance corpus."""
+    lines: list[str] = []
+
+    def write(node: Node, prefix: str, depth: int) -> None:
+        indent = "\t" * depth
+        name = type(node).__name__
+        lines.append(indent + prefix + name)
+        for slot, attribute in _SLOTS[name]:
+            value = getattr(node, attribute)
+            if value is None:
+                continue
+            if isinstance(value, tuple):
+                if not value:
+                    lines.append(f"{indent}\t{slot}: []")
+                    continue
+                lines.append(f"{indent}\t{slot}:")
+                for item in value:
+                    write(item, "- ", depth + 2)
+            elif isinstance(value, Node):
+                write(value, slot + ": ", depth + 1)
+            else:
+                lines.append(f"{indent}\t{slot}: {dump_token(value)}")
+
+    write(node, "", 0)
+    return "\n".join(lines) + "\n"
+
+
+def dump_token(token: Token) -> str:
+    res = f"{token.kind} {_dump_text(token.text)}"
+    if token.leading_trivia:
+        res += " <" + _dump_trivia(token.leading_trivia)
+    if token.trailing_trivia:
+        res += " >" + _dump_trivia(token.trailing_trivia)
+    return res
+
+
+def _dump_trivia(trivia: Sequence[Trivia]) -> str:
+    return "[" + ", ".join(f"{t.kind} {_dump_text(t.text)}" for t in trivia) + "]"
+
+
+def _dump_text(text: str) -> str:
+    """JSON string escaping only quotes, backslashes and control characters."""
+    res = ['"']
+    for c in text:
+        if c in _SHORT_ESCAPES:
+            res.append(_SHORT_ESCAPES[c])
+        elif c in '"\\':
+            res.append("\\" + c)
+        elif c < " ":
+            res.append(f"\\u{ord(c):04x}")
+        else:
+            res.append(c)
+    res.append('"')
+    return "".join(res)