jpcl 1.1.1__py3-none-any.whl

jpcl/__init__.py

@@ -0,0 +1,62 @@
+"""jpcl -- a hybrid JSON/TOML configuration language.
+
+``.jp`` files use TOML-style ``[SECTION]`` headers at the top level and
+JSON-style ``{...}`` / ``[...]`` structures inside them, with unquoted keys and
+``#`` comments::
+
+    [SERVER_ID]
+    config: {
+      disabled_channels:,
+      disabled_users: [9892, 82082, 8209]
+    }
+
+Typical use::
+
+    import jpcl
+
+    data = jpcl.load("data/servers.jp")          # -> dict
+    jpcl.dump(data, "data/servers.jp")           # formatted, atomic write
+
+    cfg = jpcl.JPConfig.load("data/servers.jp")  # dict-like, dotted paths
+    cfg.set_path("SERVER_ID.prefix", "!")
+    cfg.save()
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _installed_version
+
+from .errors import JPDecodeError, JPEncodeError, JPError
+from .jp_config import (
+    ENCODING,
+    SUFFIX,
+    JPConfig,
+    dump,
+    dumps,
+    load,
+    load_dir,
+    loads,
+)
+
+try:
+    #: Taken from the installed distribution metadata, so ``pyproject.toml`` is
+    #: the only place a release version has to be bumped.
+    __version__ = _installed_version("jpcl")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "JPConfig",
+    "JPDecodeError",
+    "JPEncodeError",
+    "JPError",
+    "ENCODING",
+    "SUFFIX",
+    "dump",
+    "dumps",
+    "load",
+    "load_dir",
+    "loads",
+    "__version__",
+]

jpcl/__main__.py

@@ -0,0 +1,8 @@
+"""Allow ``python -m jpcl`` to run the command line interface."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

jpcl/cli.py

@@ -0,0 +1,183 @@
+"""Command line interface: ``jpcl <command> [files]``.
+
+Commands:
+    check      Validate ``.jp`` files and report the first error in each.
+    fmt        Reformat files to canonical style (``-w`` to rewrite in place).
+    get        Print one dotted-path value as JSON.
+    to-json    Convert ``.jp`` to JSON.
+    from-json  Convert JSON to ``.jp``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from . import __version__, jp_config
+from .errors import JPError
+
+_MISSING = object()
+
+
+def _read(path: str) -> dict:
+    """Load a ``.jp`` file, or stdin when *path* is ``-``."""
+    if path == "-":
+        return jp_config.loads(sys.stdin.read(), filename="<stdin>")
+    return jp_config.load(path)
+
+
+def _write_options(args: argparse.Namespace) -> dict:
+    return {
+        "indent": args.indent,
+        "width": args.width,
+        "sort_keys": args.sort_keys,
+    }
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    failures = 0
+    for path in args.files:
+        try:
+            _read(path)
+        except (JPError, OSError) as exc:
+            failures += 1
+            print(exc, file=sys.stderr)
+        else:
+            if not args.quiet:
+                print(f"ok  {path}")
+    return 1 if failures else 0
+
+
+def _cmd_fmt(args: argparse.Namespace) -> int:
+    failures = 0
+    for path in args.files:
+        try:
+            data = _read(path)
+            text = jp_config.dumps(data, **_write_options(args))
+        except (JPError, OSError) as exc:
+            failures += 1
+            print(exc, file=sys.stderr)
+            continue
+        if args.write and path != "-":
+            target = Path(path)
+            if target.read_text(encoding=jp_config.ENCODING) == text:
+                continue
+            jp_config.dump(data, target, **_write_options(args))
+            print(f"reformatted {path}", file=sys.stderr)
+        else:
+            sys.stdout.write(text)
+    return 1 if failures else 0
+
+
+def _cmd_get(args: argparse.Namespace) -> int:
+    try:
+        config = jp_config.JPConfig(_read(args.file))
+    except (JPError, OSError) as exc:
+        print(exc, file=sys.stderr)
+        return 1
+    value = config.get_path(args.path, _MISSING)
+    if value is _MISSING:
+        print(f"no such path: {args.path}", file=sys.stderr)
+        return 1
+    if isinstance(value, str) and args.raw:
+        print(value)
+    else:
+        print(json.dumps(value, indent=2, ensure_ascii=False))
+    return 0
+
+
+def _cmd_to_json(args: argparse.Namespace) -> int:
+    try:
+        data = _read(args.file)
+    except (JPError, OSError) as exc:
+        print(exc, file=sys.stderr)
+        return 1
+    text = json.dumps(data, indent=args.indent, ensure_ascii=False) + "\n"
+    if args.output:
+        Path(args.output).write_text(text, encoding="utf-8", newline="\n")
+    else:
+        sys.stdout.write(text)
+    return 0
+
+
+def _cmd_from_json(args: argparse.Namespace) -> int:
+    try:
+        raw = sys.stdin.read() if args.file == "-" else Path(args.file).read_text(
+            encoding="utf-8"
+        )
+        data = json.loads(raw)
+        text = jp_config.dumps(data, **_write_options(args))
+    except (JPError, OSError, ValueError) as exc:
+        print(exc, file=sys.stderr)
+        return 1
+    if args.output:
+        Path(args.output).write_text(text, encoding="utf-8", newline="\n")
+    else:
+        sys.stdout.write(text)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the argument parser for the ``jpcl`` command."""
+    parser = argparse.ArgumentParser(
+        prog="jpcl", description="Work with .jp configuration files."
+    )
+    parser.add_argument("--version", action="version", version=f"jpcl {__version__}")
+    subcommands = parser.add_subparsers(dest="command", required=True)
+
+    def add_format_flags(sub: argparse.ArgumentParser) -> None:
+        sub.add_argument("--indent", type=int, default=2, help="spaces per level")
+        sub.add_argument(
+            "--width", type=int, default=88, help="column budget for inline arrays"
+        )
+        sub.add_argument(
+            "--sort-keys", action="store_true", help="sort keys alphabetically"
+        )
+
+    check = subcommands.add_parser("check", help="validate .jp files")
+    check.add_argument("files", nargs="+")
+    check.add_argument("-q", "--quiet", action="store_true", help="only report errors")
+    check.set_defaults(func=_cmd_check)
+
+    fmt = subcommands.add_parser("fmt", help="reformat .jp files")
+    fmt.add_argument("files", nargs="+")
+    fmt.add_argument(
+        "-w", "--write", action="store_true", help="rewrite files in place"
+    )
+    add_format_flags(fmt)
+    fmt.set_defaults(func=_cmd_fmt)
+
+    get = subcommands.add_parser("get", help="print one value by dotted path")
+    get.add_argument("file")
+    get.add_argument("path", help="e.g. SERVER_ID.config.disabled_users")
+    get.add_argument(
+        "-r", "--raw", action="store_true", help="print strings unquoted"
+    )
+    get.set_defaults(func=_cmd_get)
+
+    to_json = subcommands.add_parser("to-json", help="convert .jp to JSON")
+    to_json.add_argument("file")
+    to_json.add_argument("-o", "--output")
+    to_json.add_argument("--indent", type=int, default=2)
+    to_json.set_defaults(func=_cmd_to_json)
+
+    from_json = subcommands.add_parser("from-json", help="convert JSON to .jp")
+    from_json.add_argument("file")
+    from_json.add_argument("-o", "--output")
+    add_format_flags(from_json)
+    from_json.set_defaults(func=_cmd_from_json)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Entry point for the ``jpcl`` console script."""
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

jpcl/errors.py

@@ -0,0 +1,73 @@
+"""Exception hierarchy for the ``.jp`` (JSOML) configuration format.
+
+All errors raised by this package derive from :class:`JPError`, so callers can
+catch everything with a single ``except JPError``.  The decode error also
+derives from :class:`ValueError` and the encode error from :class:`TypeError`,
+which keeps the module drop-in compatible with code written against
+:mod:`json`.
+"""
+
+from __future__ import annotations
+
+__all__ = ["JPError", "JPDecodeError", "JPEncodeError"]
+
+
+def _line_col(doc: str, pos: int) -> tuple[int, int]:
+    """Return the 1-based ``(line, column)`` of *pos* inside *doc*."""
+    line = doc.count("\n", 0, pos) + 1
+    col = pos - doc.rfind("\n", 0, pos)
+    return line, col
+
+
+class JPError(Exception):
+    """Base class for every error raised by :mod:`jsoml`."""
+
+
+class JPEncodeError(JPError, TypeError):
+    """Raised when a Python object cannot be serialised to ``.jp``."""
+
+
+class JPDecodeError(JPError, ValueError):
+    """Raised when a ``.jp`` document is malformed.
+
+    The rendered message points at the exact offending character, for example::
+
+        servers.jp:4:3: expected ':' after key 'prefix'
+            prefix "!"
+              ^
+
+    Attributes:
+        raw_message: The message without the location prefix or source excerpt.
+        doc: The full source text that was being parsed.
+        pos: Zero-based character offset of the error inside ``doc``.
+        line: One-based line number of the error.
+        col: One-based column number of the error.
+        filename: Name of the file the text came from, if known.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        doc: str = "",
+        pos: int = 0,
+        *,
+        filename: str | None = None,
+    ) -> None:
+        self.raw_message = message
+        self.doc = doc
+        self.pos = max(0, min(pos, len(doc)))
+        self.filename = filename
+        self.line, self.col = _line_col(doc, self.pos)
+        super().__init__(self._render())
+
+    def _render(self) -> str:
+        location = f"{self.filename or '<string>'}:{self.line}:{self.col}"
+        parts = [f"{location}: {self.raw_message}"]
+        lines = self.doc.splitlines()
+        if 0 < self.line <= len(lines):
+            source = lines[self.line - 1].rstrip("\r")
+            # Keep tabs in the caret prefix so the marker stays aligned.
+            prefix = "".join(c if c == "\t" else " " for c in source[: self.col - 1])
+            parts.append(f"    {source}")
+            parts.append(f"    {prefix}^")
+        return "\n".join(parts)