yapyon 0.1.0__py3-none-any.whl

yapyon/__init__.py

@@ -0,0 +1,58 @@
+"""yapyon — YAMLちゃうで。やぴょんやぴょん。
+
+Python-style typed literals with YAML-like block structure.
+Home: https://github.com/doctorjei/yapyon
+
+    >>> import yapyon
+    >>> yapyon.loads('name: "gw"\\nbanner: y"{name} v1"\\n')
+    {'name': 'gw', 'banner': 'gw v1'}
+
+**Conformance (SPEC §12.5): this implementation provides the full form**,
+and therefore also loads yapyon records — `loads_record`, `load_record` and
+`is_record` are the record surface.
+
+**Identifier tables (GRAMMAR §G4.1): pinned to Unicode 14.0.0.** yapyon
+ships its own table rather than asking `str.isidentifier()`, whose answer
+depends on the interpreter, so a key means the same thing on every install.
+`UNICODE_VERSION` is that pinned version.
+"""
+
+from ._xid import UNICODE_VERSION as _XID_UNICODE_VERSION
+from .lexer import Lexer, Token, tokenize, AkanError, Yakamashiwa
+from .parser import (Mapping, MultiMap, Node, Pair, Parser, Scalar, Sequence,
+                     ResolvedTemplate, YString, dump, parse,
+                     parse_tokens)
+from .resolver import Resolver, resolve
+from .multimap import Entry, KeyView, OrderedMultimap
+from .template import Hole, Template
+from .loader import build, is_record, load, load_record, loads, loads_record
+from .emitter import emit
+
+__version__ = "0.1.0"
+
+#: GRAMMAR §G4.1 asks every implementation to document where its identifier
+#: tables come from. yapyon's are generated from this Unicode version by
+#: tools/gen_xid_table.py, and do not vary with the interpreter.
+UNICODE_VERSION = _XID_UNICODE_VERSION
+
+__all__ = [
+    # what this install's identifier tables are (GRAMMAR §G4.1)
+    "UNICODE_VERSION",
+    # the everyday API
+    "load", "loads", "build", "Template", "Hole", "OrderedMultimap",
+    # records — the fixed, literal-only form
+    "load_record", "loads_record", "is_record",
+    # a record AST back to canonical yapyon source (python -m yapyon.record)
+    "emit",
+    # diagnostics
+    "AkanError", "Yakamashiwa",
+    # the stages, for tools that want them
+    "Lexer", "Token", "tokenize",
+    "Parser", "parse", "parse_tokens", "dump",
+    "Resolver", "resolve",
+    # AST
+    "Node", "Scalar", "YString", "ResolvedTemplate", "Pair", "Mapping",
+    "Sequence", "MultiMap",
+    # multimap internals
+    "Entry", "KeyView",
+]

yapyon/__main__.py

@@ -0,0 +1,39 @@
+"""`python -m yapyon <stage> [FILE]` — the stages, from the command line.
+
+    python -m yapyon lexer  FILE    # token dump
+    python -m yapyon parser FILE    # AST dump
+    python -m yapyon record FILE    # a record, normalized back to yapyon
+
+Prefer this spelling over `python -m yapyon.lexer`. Both work, but the
+per-module form re-executes a module the package has already imported, which
+makes CPython print a `RuntimeWarning` onto the very stream the diagnostics
+use — and, before this indirection existed, gave the stage a second copy of
+`AkanError` that `_cli` could not catch.
+
+Diagnostics go to stderr, output to stdout, and a shiran does not change the
+exit status; `_cli` holds those rules.
+"""
+
+from __future__ import annotations
+
+import sys
+
+STAGES = ("lexer", "parser", "record")
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 2 or argv[1] in ("-h", "--help"):
+        print(__doc__.strip(), file=sys.stderr)
+        return 0 if len(argv) > 1 else 2
+    stage, rest = argv[1], argv[2:]
+    if stage not in STAGES:
+        print(f"akan: no such stage {stage!r}; try one of "
+              f"{', '.join(STAGES)}", file=sys.stderr)
+        return 2
+    from importlib import import_module
+    module = import_module(f".{stage}", __package__)
+    return module.main([f"yapyon {stage}", *rest])
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

yapyon/_cli.py

@@ -0,0 +1,46 @@
+"""Shared plumbing for the `python -m yapyon.*` entry points.
+
+Three rules live here, once, because four copies of them would drift:
+
+* **Shirans go to stderr and are shown by default.** The library keeps them
+  behind `warn=` — a caller may not want them — but a person at a terminal
+  asked to see what the tool thinks, so a CLI that swallowed them would be
+  hiding the only warning rung the format has.
+* **A shiran never changes the exit status.** It is legal-but-suspicious, not
+  an error; a pipeline consuming stdout must not break because of one.
+* **Diagnostics never go to stdout.** `python -m yapyon.record` writes yapyon
+  there and its output is meant to be redirected, so an akan or a shiran on
+  stdout would corrupt the file it is being written into.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from .lexer import AkanError
+
+
+def source_from(argv: list[str]) -> tuple[str, str | None]:
+    """The file named on the command line, or stdin. The name is returned so
+    diagnostics can carry it — `f.ypy:3:9` rather than `line 3, col 9`."""
+    name = argv[1] if len(argv) > 1 else None
+    text = open(name, encoding="utf-8").read() if name else sys.stdin.read()
+    return text, name
+
+
+def run(argv: list[str], work) -> int:
+    """`work(text, source) -> (stdout_text, warnings)`, wrapped in the rules.
+
+    Warnings are written before the output: they are diagnostics *about* the
+    input, and on a terminal a long dump would otherwise scroll them away.
+    """
+    text, name = source_from(argv)
+    try:
+        out, warnings = work(text, name)
+    except AkanError as exc:
+        print(exc, file=sys.stderr)
+        return 1
+    for warning in warnings:
+        print(warning, file=sys.stderr)
+    sys.stdout.write(out)
+    return 0