zig-hocon 0.4.0__py3-none-win_amd64.whl

zig_hocon/__init__.py

@@ -0,0 +1,39 @@
+"""HOCON for Python, read by zig-hocon.
+
+The parsing, the substitutions and every conversion are the Zig library's
+(libhocon, next to this file); this is a thin ctypes layer over its C API
+(c/hocon.h), shaped like pyhocon so moving over is a change of import::
+
+    from zig_hocon import ConfigFactory
+
+    conf = ConfigFactory.parse_file("deploy/prod/app.conf")
+    conf.get_int("db.pool")
+    conf.as_dict()
+
+The modules are pyhocon's: ``config_parser`` (ConfigFactory), ``config_tree``
+(ConfigTree), ``exceptions``; and ``units`` for durations and sizes.
+"""
+
+from .config_parser import KEEP, ConfigFactory
+from .config_tree import ConfigTree
+from .exceptions import (
+    ConfigException,
+    ConfigMissingException,
+    ConfigParseException,
+    ConfigSubstitutionException,
+    ConfigWrongTypeException,
+)
+from .units import parse_bytes, parse_duration
+
+__all__ = [
+    "KEEP",
+    "ConfigException",
+    "ConfigFactory",
+    "ConfigMissingException",
+    "ConfigParseException",
+    "ConfigSubstitutionException",
+    "ConfigTree",
+    "ConfigWrongTypeException",
+    "parse_bytes",
+    "parse_duration",
+]

zig_hocon/__main__.py

@@ -0,0 +1,36 @@
+"""``python -m zig_hocon [--hocon | --json] [--env=process|none|keep] <file.conf>``
+
+The file resolved, as the ``hocon`` CLI prints it: HOCON by default, or
+compact JSON; an error goes to stderr with exit 1. Through this package and
+libhocon, so the conformance suite can measure them
+(conformance/adapters/zig-hocon-python.sh).
+"""
+
+import argparse
+import os
+import sys
+
+from zig_hocon import KEEP, ConfigException, ConfigFactory
+
+parser = argparse.ArgumentParser(prog="python -m zig_hocon")
+output = parser.add_mutually_exclusive_group()
+output.add_argument("--hocon", action="store_true", help="print HOCON (the default)")
+output.add_argument("--json", action="store_true", help="print compact JSON")
+parser.add_argument("--env", choices=["process", "none", "keep"], default="process")
+parser.add_argument("file")
+args = parser.parse_args()
+
+try:
+    conf = ConfigFactory.parse_file(args.file, env={"process": os.environ, "none": None, "keep": KEEP}[args.env])
+    out = conf.to_json() + b"\n" if args.json else conf.to_hocon().encode("utf-8", "surrogatepass")
+except ConfigException as e:
+    sys.exit(f"error: {e}")
+
+# A closed stdout is None, a pipe whose reader has gone an OSError: the CLI's
+# error for both. Python flushes stdout once more at exit; devnull keeps that quiet.
+try:
+    sys.stdout.buffer.write(out)
+    sys.stdout.flush()
+except (OSError, AttributeError):
+    os.dup2(os.open(os.devnull, os.O_WRONLY), 1)
+    sys.exit(f"error: {args.file}: WriteFailed")

zig_hocon/_capi.py

@@ -0,0 +1,104 @@
+"""libhocon through ctypes: the library next to this file, the structs and
+codes of c/hocon.h, and the types of its functions. Kept to hocon.h by
+python/tests/test_capi.py."""
+
+import ctypes
+import os
+import sys
+from typing import Any
+
+# The codes of hocon.h.
+OK, PARSE, SUBSTITUTION, MISSING, WRONG_TYPE, IO, BAD_PATH, TOO_DEEP, OTHER = range(9)
+ENV_PROCESS, ENV_NONE, ENV_MAP, ENV_KEEP = range(4)
+
+
+class Options(ctypes.Structure):
+    """``hocon_options``."""
+
+    env: int
+    env_vars: "ctypes._Pointer[ctypes.c_char_p] | None"
+    resolve: bool
+    include_dir: bytes | None
+    _fields_ = [
+        ("env", ctypes.c_int),
+        ("env_vars", ctypes.POINTER(ctypes.c_char_p)),
+        ("resolve", ctypes.c_bool),
+        ("include_dir", ctypes.c_char_p),
+    ]
+
+
+class Error(ctypes.Structure):
+    """``hocon_error``."""
+
+    code: int
+    name: bytes | None
+    file: bytes | None
+    line: int
+    column: int
+    source_line: bytes | None
+    key_path: bytes | None
+    expected: bytes | None
+    _fields_ = [
+        ("code", ctypes.c_int),
+        ("name", ctypes.c_char_p),
+        ("file", ctypes.c_char_p),
+        ("line", ctypes.c_size_t),
+        ("column", ctypes.c_size_t),
+        ("source_line", ctypes.c_char_p),
+        ("key_path", ctypes.c_char_p),
+        ("expected", ctypes.c_char_p),
+    ]
+
+
+def _load() -> ctypes.CDLL:
+    name = {"darwin": "libhocon.dylib", "win32": "hocon.dll"}.get(sys.platform, "libhocon.so")
+    path = os.path.join(os.path.dirname(os.path.abspath(__file__)), name)
+    try:
+        return ctypes.CDLL(path)
+    except OSError as e:
+        raise ImportError(f"zig_hocon: cannot load {path} ({e}); `zig build python` puts it there") from e
+
+
+lib = _load()
+_doc, _path = ctypes.c_void_p, ctypes.c_char_p
+lib.hocon_parse_file.argtypes = [ctypes.c_char_p, ctypes.POINTER(Options), ctypes.POINTER(Error)]
+lib.hocon_parse_file.restype = _doc
+lib.hocon_parse_string.argtypes = [ctypes.c_char_p, ctypes.c_size_t, ctypes.POINTER(Options), ctypes.POINTER(Error)]
+lib.hocon_parse_string.restype = _doc
+# Each getter, and the types of its out parameters.
+_getters: list[tuple[str, list[Any]]] = [
+    ("int", [ctypes.c_int64]),
+    ("float", [ctypes.c_double]),
+    ("bool", [ctypes.c_bool]),
+    ("string", [ctypes.c_void_p, ctypes.c_size_t]),
+    ("duration_ns", [ctypes.c_int64]),
+    ("bytes", [ctypes.c_uint64]),
+    ("period", [ctypes.c_int32] * 3),
+]
+for _name, _out in _getters:
+    _getter = getattr(lib, "hocon_get_" + _name)
+    _getter.argtypes = [_doc, _path] + [ctypes.POINTER(t) for t in _out]
+    _getter.restype = ctypes.c_int
+lib.hocon_get_config.argtypes = [_doc, _path]
+lib.hocon_get_config.restype = ctypes.c_int
+# A void pointer, not c_char_p: ctypes would copy the text and lose the
+# pointer that hocon_free_string needs.
+for _writer in (lib.hocon_to_json, lib.hocon_to_hocon):
+    _writer.argtypes = [_doc, _path, ctypes.POINTER(ctypes.c_int)]
+    _writer.restype = ctypes.c_void_p
+lib.hocon_free_string.argtypes = [ctypes.c_void_p]
+lib.hocon_free_string.restype = None
+lib.hocon_error_free.argtypes = [ctypes.POINTER(Error)]
+lib.hocon_error_free.restype = None
+lib.hocon_free.argtypes = [_doc]
+lib.hocon_free.restype = None
+lib.hocon_last_error.argtypes = [_doc]
+lib.hocon_last_error.restype = ctypes.POINTER(Error)
+
+
+def c_string(data: bytes) -> bytes:
+    """``data`` for C, which ends a string at its first 0: with one inside, it
+    would be another path or name, so that is a ValueError, as for open()."""
+    if b"\0" in data:
+        raise ValueError("embedded null byte")
+    return data

zig_hocon/config_parser.py

@@ -0,0 +1,108 @@
+"""Reading a document, as pyhocon's ``ConfigFactory``: from a file or from
+text, with ``env`` and ``resolve`` saying how far it is worked out."""
+
+import ctypes
+import os
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any
+
+from . import _capi
+from ._capi import lib
+from .config_tree import ConfigTree, Doc
+from .exceptions import ConfigException, ConfigParseException, ConfigSubstitutionException, name_of, placed
+
+__all__ = ["KEEP", "ConfigFactory"]
+
+
+class _Keep:
+    def __repr__(self) -> str:
+        return "zig_hocon.KEEP"
+
+
+KEEP = _Keep()
+"""``env=KEEP``: a substitution the document cannot answer stays in it, for
+``to_hocon()`` to write out and the machine it runs on to resolve."""
+
+Path = str | bytes | os.PathLike[str] | os.PathLike[bytes]
+"""A file name, as open() takes it."""
+
+Env = Mapping[str, str | bytes] | Mapping[bytes, str | bytes] | _Keep | None
+"""Where ``${NAME}`` looks when NAME is not in the document (``ConfigFactory``)."""
+
+
+def _env_bytes(text: str | bytes, key: str | bytes) -> bytes:
+    # os.environ decodes what is not UTF-8 with surrogateescape; this gives the
+    # bytes back.
+    if isinstance(text, str):
+        return text.encode("utf-8", "surrogateescape")
+    if isinstance(text, bytes):
+        return text
+    raise TypeError(f"env {key!r}: expected str or bytes, not {type(text).__name__}")
+
+
+def _options(env: Env, resolve: bool, include_dir: Path | None = None) -> tuple[_capi.Options, object]:
+    """The options, and what has to live as long as they are used."""
+    opts = _capi.Options(resolve=bool(resolve))
+    entries = None
+    if env is KEEP:
+        opts.env = _capi.ENV_KEEP
+    elif env is None:
+        opts.env = _capi.ENV_NONE
+    elif isinstance(env, Mapping):
+        lines = []
+        for key, value in env.items():
+            k, v = _env_bytes(key, key), _env_bytes(value, key)
+            # No `${…}` can name it (Windows has `=C:=C:\` in its environment):
+            # skipped, as hocon.h skips it in `environ`.
+            if not k or b"=" in k:
+                continue
+            lines.append(_capi.c_string(k + b"=" + v))
+        entries = (ctypes.c_char_p * (len(lines) + 1))(*lines, None)
+        opts.env = _capi.ENV_MAP
+        opts.env_vars = ctypes.cast(entries, ctypes.POINTER(ctypes.c_char_p))
+    else:
+        raise TypeError(f"env: expected a mapping, None or KEEP, not {type(env).__name__}")
+    if include_dir is not None:
+        opts.include_dir = _capi.c_string(os.fsencode(include_dir))
+    return opts, entries
+
+
+def _parse(parse: Callable[..., int | None], args: Sequence[Any], env: Env, resolve: bool, include_dir: Path | None, given: str | None) -> ConfigTree:
+    opts, _entries = _options(env, resolve, include_dir)
+    err = _capi.Error()
+    handle = parse(*args, ctypes.byref(opts), ctypes.byref(err))
+    if handle:
+        return ConfigTree(Doc(handle), "")
+    try:
+        raise _parse_error(err, given)
+    finally:
+        lib.hocon_error_free(ctypes.byref(err))
+
+
+def _parse_error(err: _capi.Error, given: str | None) -> ConfigException:
+    """`app.conf:7:12: Unresolved`, the line, and a caret under the column."""
+    name = name_of(err)
+    cls = {_capi.PARSE: ConfigParseException, _capi.SUBSTITUTION: ConfigSubstitutionException}.get(err.code, ConfigException)
+    if not err.line:
+        # An empty file name is shown as '' so the message still names it.
+        return cls(f"{given or repr(given)}: {name}" if given is not None else name, name=name)
+    return placed(cls, err, name)
+
+
+class ConfigFactory:
+    """Reads a document. ``env`` is where ``${NAME}`` looks when NAME is not
+    in it: ``os.environ`` (the default, as pyhocon), any mapping of names to
+    values, ``None`` for nowhere, or ``KEEP`` to leave it in the document.
+    ``resolve=False`` reads it with every ``${…}`` as written."""
+
+    @staticmethod
+    def parse_file(path: Path, *, env: Env = os.environ, resolve: bool = True) -> ConfigTree:
+        """The file at ``path``; its includes are found next to it."""
+        return _parse(lib.hocon_parse_file, [_capi.c_string(os.fsencode(path))], env, resolve, None, os.fsdecode(path))
+
+    @staticmethod
+    def parse_string(content: str | bytes, *, basedir: Path | None = None, env: Env = os.environ, resolve: bool = True) -> ConfigTree:
+        """HOCON text; an include in it is found in ``basedir``, and without
+        one is an error."""
+        data = content.encode("utf-8", "surrogatepass") if isinstance(content, str) else bytes(content)
+        return _parse(lib.hocon_parse_string, [data, len(data)], env, resolve, basedir, None)

zig_hocon/config_tree.py

@@ -0,0 +1,248 @@
+"""A parsed document and the getters on it, as pyhocon's ``ConfigTree``."""
+
+import ctypes
+import datetime
+import json
+import threading
+from collections.abc import Callable, Sequence
+from typing import Any, TypeVar, overload
+
+from . import _capi
+from ._capi import lib
+from .exceptions import (
+    ConfigException,
+    ConfigMissingException,
+    ConfigSubstitutionException,
+    ConfigWrongTypeException,
+    name_of,
+    placed,
+)
+
+__all__ = ["ConfigTree"]
+
+_T = TypeVar("_T")
+
+
+class Doc:
+    """A parsed document, freed with the last ConfigTree that reads it.
+
+    hocon.h has one thread at a time on a document, and a call that fails
+    leaves why on it until the next one fails: a call and the reading of its
+    error hold ``lock``, so the trees of one document can be shared between
+    threads."""
+
+    def __init__(self, handle: int) -> None:
+        self.handle = handle
+        self.lock = threading.Lock()
+
+    # The function is bound now: at interpreter exit the module's globals may
+    # be gone before this runs.
+    def __del__(self, _free: Callable[[int], None] = lib.hocon_free) -> None:
+        _free(self.handle)
+
+
+class _NoDefault:
+    """What a getter's ``default`` is when none is given."""
+
+
+_NO_DEFAULT: Any = _NoDefault()
+
+# HOCON's whitespace, which a path may have around it: Python's own but U+0085,
+# and the BOM. Held to the library's by python/tests/test_capi.py.
+BLANK = "\t\n\v\f\r\x1c\x1d\x1e\x1f \xa0            

  　"
+
+
+def _path_bytes(full: str) -> bytes:
+    """A path for C."""
+    return _capi.c_string(full.encode("utf-8", "surrogatepass"))
+
+
+def _timedelta(ns: int) -> datetime.timedelta:
+    seconds, rest = divmod(ns, 1_000_000_000)
+    return datetime.timedelta(seconds=seconds, microseconds=rest / 1000)
+
+
+class ConfigTree:
+    """A document, or an object in one (``get_config``). A path is written as
+    in the file, ``db.host`` or ``a."b.c"``; ``""`` is this tree itself.
+    The values stay in the Zig library until a getter asks for one.
+
+    ``default``, when given, is what a getter gives where there is nothing,
+    or ``null``. The trees of one document can be read from many threads."""
+
+    def __init__(self, doc: Doc, prefix: str) -> None:
+        self._doc = doc
+        self._prefix = prefix
+
+    def _full(self, path: str) -> str:
+        """``path`` from the root. Whitespace around a path is no part of it,
+        and joined to the prefix it would be inside a key."""
+        if not self._prefix:
+            return path
+        if not path:
+            return self._prefix
+        return f"{self._prefix.strip(BLANK)}.{path.strip(BLANK)}"
+
+    def _get(self, getter: Callable[..., int], path: str, outs: Sequence[Any], what: str, default: Any) -> tuple[bool, Any]:
+        """Calls ``getter`` into ``outs``: (True, None) when it gives a value,
+        (False, default) when there is none and a default."""
+        full = self._full(path)
+        with self._doc.lock:
+            code = getter(self._doc.handle, _path_bytes(full), *[ctypes.byref(o) for o in outs])
+            error = self._error(code, full, what)
+        if error is None:
+            return True, None
+        # A path through a scalar or a list (`a.b` with `a = 5`) is the wrong
+        # type to a getter, WrongType, and has nothing at it: java's hasPath
+        # is false, pyhocon gives the default. A value that does not convert
+        # fails with an error of its own (TypeMismatch, InvalidCharacter…).
+        if default is not _NO_DEFAULT and (code == _capi.MISSING or error.name == "WrongType"):
+            return False, default
+        raise error
+
+    def _error(self, code: int, full: str, what: str) -> ConfigException | None:
+        """The exception for ``code``, which a call on ``full`` just returned;
+        None for none. Read before any other call on the document, which
+        would say why it failed instead."""
+        if code == _capi.OK:
+            return None
+        err = lib.hocon_last_error(self._doc.handle).contents
+        name = name_of(err)
+        shown = full or "the document"
+        # A value that does not convert, or a `${…}` that waits, where it is
+        # written: `app.conf:3:8: InvalidCharacter at db.pool: expected i64`.
+        if err.line and code in (_capi.WRONG_TYPE, _capi.SUBSTITUTION):
+            said = f"{name} at {shown}" + (f": expected {err.expected.decode()}" if err.expected else "")
+            cls = ConfigWrongTypeException if code == _capi.WRONG_TYPE else ConfigSubstitutionException
+            return placed(cls, err, said)
+        if code == _capi.MISSING:
+            return ConfigMissingException(f"No configuration setting found for key {full}", name=name)
+        if code == _capi.WRONG_TYPE:
+            return ConfigWrongTypeException(f"{shown} is not {what}", name=name)
+        if code == _capi.SUBSTITUTION:
+            return ConfigSubstitutionException(
+                f"{shown} is not resolved: it was read with resolve=False or env=KEEP, and a ${{…}} is still in it; "
+                "to_hocon() of the whole document writes it as it is",
+                name=name,
+            )
+        if code == _capi.BAD_PATH:
+            return ConfigException(f"not a path: {full!r}", name=name)
+        if code == _capi.TOO_DEEP:
+            return ConfigException(f"{shown} is more than 256 levels deep, deeper than JSON is written", name=name)
+        # ponytail: no test runs the library out of memory, nor gives it a NULL.
+        return ConfigException(f"{shown}: failed (out of memory?)", name=name)  # pragma: no cover
+
+    def _write(self, writer: Callable[..., int | None], what: str) -> bytes:
+        """This tree as ``writer`` writes it."""
+        code = ctypes.c_int()
+        with self._doc.lock:
+            ptr = writer(self._doc.handle, _path_bytes(self._prefix), ctypes.byref(code))
+            error = self._error(code.value, self._prefix, what)
+        if error is not None:
+            raise error
+        assert ptr is not None  # there whenever the code is OK
+        try:
+            return ctypes.string_at(ptr)
+        finally:
+            lib.hocon_free_string(ptr)
+
+    @overload
+    def get_string(self, path: str) -> str: ...
+    @overload
+    def get_string(self, path: str, default: _T) -> str | _T: ...
+    def get_string(self, path: str, default: Any = _NO_DEFAULT) -> Any:
+        """Text, also of a number or a boolean as written (``1e3``, ``yes``)."""
+        ptr, size = ctypes.c_void_p(), ctypes.c_size_t()
+        found, value = self._get(lib.hocon_get_string, path, [ptr, size], "a string", default)
+        if not found:
+            return value
+        return ctypes.string_at(ptr, size.value).decode("utf-8", "surrogatepass") if size.value else ""
+
+    @overload
+    def get_int(self, path: str) -> int: ...
+    @overload
+    def get_int(self, path: str, default: _T) -> int | _T: ...
+    def get_int(self, path: str, default: Any = _NO_DEFAULT) -> Any:
+        """A whole number, also from text (``"5"``); ``1.5`` is none."""
+        out = ctypes.c_int64()
+        found, value = self._get(lib.hocon_get_int, path, [out], "an int", default)
+        return out.value if found else value
+
+    @overload
+    def get_float(self, path: str) -> float: ...
+    @overload
+    def get_float(self, path: str, default: _T) -> float | _T: ...
+    def get_float(self, path: str, default: Any = _NO_DEFAULT) -> Any:
+        out = ctypes.c_double()
+        found, value = self._get(lib.hocon_get_float, path, [out], "a float", default)
+        return out.value if found else value
+
+    @overload
+    def get_bool(self, path: str) -> bool: ...
+    @overload
+    def get_bool(self, path: str, default: _T) -> bool | _T: ...
+    def get_bool(self, path: str, default: Any = _NO_DEFAULT) -> Any:
+        """``true``/``yes``/``on`` and ``false``/``no``/``off``."""
+        out = ctypes.c_bool()
+        found, value = self._get(lib.hocon_get_bool, path, [out], "a bool", default)
+        return out.value if found else value
+
+    @overload
+    def get_duration(self, path: str) -> datetime.timedelta: ...
+    @overload
+    def get_duration(self, path: str, default: _T) -> datetime.timedelta | _T: ...
+    def get_duration(self, path: str, default: Any = _NO_DEFAULT) -> Any:
+        """``30s``, ``2 minutes``; a number alone is milliseconds. A timedelta,
+        to the nearest microsecond."""
+        out = ctypes.c_int64()
+        found, value = self._get(lib.hocon_get_duration_ns, path, [out], "a duration", default)
+        return _timedelta(out.value) if found else value
+
+    @overload
+    def get_bytes(self, path: str) -> int: ...
+    @overload
+    def get_bytes(self, path: str, default: _T) -> int | _T: ...
+    def get_bytes(self, path: str, default: Any = _NO_DEFAULT) -> Any:
+        """``512MB``, ``1.5 GiB``; a number alone is bytes."""
+        out = ctypes.c_uint64()
+        found, value = self._get(lib.hocon_get_bytes, path, [out], "a size in bytes", default)
+        return out.value if found else value
+
+    @overload
+    def get_period(self, path: str) -> dict[str, int]: ...
+    @overload
+    def get_period(self, path: str, default: _T) -> dict[str, int] | _T: ...
+    def get_period(self, path: str, default: Any = _NO_DEFAULT) -> Any:
+        """``3mo``, ``2w``, ``1y``; a number alone is days. A dict of
+        ``years``, ``months`` and ``days`` (weeks are days): months and years
+        have no fixed length, and the standard library has no calendar period."""
+        years, months, days = ctypes.c_int32(), ctypes.c_int32(), ctypes.c_int32()
+        found, value = self._get(lib.hocon_get_period, path, [years, months, days], "a period", default)
+        return {"years": years.value, "months": months.value, "days": days.value} if found else value
+
+    @overload
+    def get_config(self, path: str) -> "ConfigTree": ...
+    @overload
+    def get_config(self, path: str, default: _T) -> "ConfigTree | _T": ...
+    def get_config(self, path: str, default: Any = _NO_DEFAULT) -> Any:
+        """The object at ``path``, as a ConfigTree of its own."""
+        found, value = self._get(lib.hocon_get_config, path, [], "an object", default)
+        return ConfigTree(self._doc, self._full(path)) if found else value
+
+    def to_json(self) -> bytes:
+        """Compact JSON, as bytes: ``msgspec.json.decode`` takes them as they
+        are. Durations and sizes are the text they are written as, ``"30s"``."""
+        return self._write(lib.hocon_to_json, "JSON")
+
+    def as_dict(self) -> dict[str, Any]:
+        """The tree as dicts, lists and scalars, by way of JSON."""
+        tree: dict[str, Any] = json.loads(self.to_json())
+        return tree
+
+    def to_hocon(self) -> str:
+        """The tree as HOCON text. Read with ``env=KEEP`` that is everything
+        resolved but the variables, one file to deploy; with
+        ``resolve=False`` it is the document as written. A subtree with a
+        ``${…}`` still in it is a ConfigSubstitutionException: the ``${…}``
+        is the root's, and the subtree's text alone would read it wrong."""
+        return self._write(lib.hocon_to_hocon, "HOCON").decode("utf-8", "surrogatepass")

zig_hocon/exceptions.py

@@ -0,0 +1,81 @@
+"""What the library refuses, as pyhocon names it (``pyhocon.exceptions``)."""
+
+import os
+from typing import TypeVar
+
+from ._capi import Error
+
+__all__ = [
+    "ConfigException",
+    "ConfigMissingException",
+    "ConfigParseException",
+    "ConfigSubstitutionException",
+    "ConfigWrongTypeException",
+]
+
+
+class ConfigException(Exception):
+    """Anything the library refuses. ``name`` is the error's own name
+    (``Unresolved``, ``UnexpectedToken``); an error in a file also has
+    ``file``, ``line``, ``column`` (1-based, in characters) and
+    ``source_line``, and its message shows the line with a caret under the
+    column."""
+
+    def __init__(
+        self,
+        message: str,
+        name: str | None = None,
+        file: str | None = None,
+        line: int | None = None,
+        column: int | None = None,
+        source_line: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.name = name
+        self.file = file
+        self.line = line
+        self.column = column
+        self.source_line = source_line
+
+    # KeyError, a base of ConfigMissingException, would print the message quoted.
+    def __str__(self) -> str:
+        return str(self.args[0])
+
+
+class ConfigParseException(ConfigException):
+    """The text is not valid HOCON, or an include failed."""
+
+
+class ConfigSubstitutionException(ConfigException):
+    """A ``${…}`` with no value or in a cycle; or one that is still there,
+    read with ``resolve=False`` or ``env=KEEP``, where a value is needed."""
+
+
+class ConfigMissingException(ConfigException, KeyError):
+    """Nothing at the path, or ``null`` there."""
+
+
+class ConfigWrongTypeException(ConfigException, ValueError):
+    """The value is there and is not what was asked for. A ValueError too, so
+    pydantic and msgspec report it as a validation error."""
+
+
+_E = TypeVar("_E", bound=ConfigException)
+
+
+def name_of(err: Error) -> str:
+    """The error's name; static in the library, there whenever it failed."""
+    return (err.name or b"").decode()
+
+
+def placed(cls: type[_E], err: Error, said: str) -> _E:
+    """``cls`` for an error with a place: `app.conf:7:12: <said>`, the line,
+    and a caret under the column."""
+    file = os.fsdecode(err.file or b"")
+    source_line = (err.source_line or b"").decode("utf-8", "replace")
+    # As the CLI prints it: a tab or a control character would move the text
+    # and leave the caret behind, so each is one space.
+    shown = "".join(" " if c < " " or c == "\x7f" else c for c in source_line)
+    where = f"{file}:" if file else ""
+    message = f"{where}{err.line}:{err.column}: {said}\n{shown}\n{' ' * (err.column - 1)}^"
+    return cls(message, name=name_of(err), file=file, line=err.line, column=err.column, source_line=source_line)

zig_hocon/units.py

@@ -0,0 +1,37 @@
+"""Durations and sizes in a program's own hands (a pydantic validator, a
+msgspec dec_hook), by the rules of ``hocon.Duration`` and ``hocon.Size``."""
+
+import datetime
+import json
+
+from .config_parser import ConfigFactory
+from .config_tree import ConfigTree
+from .exceptions import ConfigException, ConfigWrongTypeException
+
+__all__ = ["parse_bytes", "parse_duration"]
+
+
+def _single(value: str | int | float, what: str) -> ConfigTree:
+    """``value`` alone in a document, as ``v``, to be read by the getters."""
+    if isinstance(value, bool) or not isinstance(value, (str, int, float)):
+        raise TypeError(f"{what}: expected text or a number, not {type(value).__name__}")
+    return ConfigFactory.parse_string(f"v = {json.dumps(value)}", env=None)
+
+
+def parse_duration(text: str | int | float) -> datetime.timedelta:
+    """``"30s"``, ``"2 minutes"`` or a number of milliseconds as a timedelta,
+    by the rules of ``hocon.Duration``. ConfigWrongTypeException, a
+    ValueError, when it is none."""
+    try:
+        return _single(text, "parse_duration").get_duration("v")
+    except ConfigException:
+        raise ConfigWrongTypeException(f"not a duration: {text!r}", name="WrongType") from None
+
+
+def parse_bytes(text: str | int | float) -> int:
+    """``"512MB"``, ``"1.5 GiB"`` or a number of bytes as an int, by the rules
+    of ``hocon.Size``. ConfigWrongTypeException, a ValueError, when it is none."""
+    try:
+        return _single(text, "parse_bytes").get_bytes("v")
+    except ConfigException:
+        raise ConfigWrongTypeException(f"not a size in bytes: {text!r}", name="WrongType") from None

zig_hocon-0.4.0.dist-info/METADATA

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: zig-hocon
+Version: 0.4.0
+Summary: HOCON configuration for Python: the whole spec, fast, with pyhocon's API
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Requires-Python: >=3.10
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://github.com/lejmr/zig-hocon
+Project-URL: Source, https://github.com/lejmr/zig-hocon/tree/main/python
+Project-URL: Issues, https://github.com/lejmr/zig-hocon/issues
+Project-URL: Conformance, https://htmlpreview.github.io/?https://github.com/lejmr/zig-hocon/blob/main/conformance/report.html
+Project-URL: Migrating, https://github.com/lejmr/zig-hocon/blob/main/python/MIGRATING.md
+Description-Content-Type: text/markdown
+
+<img src="https://raw.githubusercontent.com/lejmr/zig-hocon/main/docs/brand/zig-Hocon-badge-master-1650x500.png" width="600" alt="zig-hocon">
+
+Read [HOCON](https://github.com/lightbend/config/blob/main/HOCON.md) config files in Python, to the spec. Fast, because the parser is written in Zig. Familiar, because the API is pyhocon's.
+
+HOCON is JSON made for people: comments, no quotes needed, units like `30s` and `512MiB`, files that include other files, later settings that merge over earlier ones, and values taken from other keys or from environment variables. One base file, one small file per environment on top.
+
+```hocon
+# app.conf
+db {
+  host = localhost
+  pool = 4
+}
+timeout = 30s
+cache = 512MiB
+retention = 3 months
+debug = false
+ratio = 0.75
+include "prod.conf"
+```
+
+```hocon
+# prod.conf
+db.host = db.example.org
+db.pool = ${?DB_POOL}   # only when DB_POOL is set
+```
+
+```python
+from zig_hocon import ConfigFactory
+
+conf = ConfigFactory.parse_file("app.conf")
+conf.get_string("db.host")   # "db.example.org"
+conf.get_int("db.pool")      # 4, or $DB_POOL when it is set
+```
+
+The rest of this page reads these two files.
+
+## Why zig-hocon
+
+- **Correct.** Passes 442 of the 445 tests in the [conformance suite](https://htmlpreview.github.io/?https://github.com/lejmr/zig-hocon/blob/main/conformance/report.html), one test for each sentence of the spec.\*
+- **Fast.** Orders of magnitude faster than what Python usually has.\*\*
+- **Clear errors.** File, line, column, and a caret under the mistake.
+- **No dependencies.** A thin ctypes layer over one bundled library.
+
+\* The other three are where the spec leaves room and implementations disagree.  
+\*\* A 6 KB config in 1 ms, a 10 MB one in 0.3 s, on an Apple M4 Pro.
+
+## Install
+
+```sh
+pip install zig-hocon
+```
+
+One wheel per platform, for every Python from 3.10 on, free-threaded builds and PyPy included: macOS (arm64, x86_64), Linux (x86_64, aarch64; glibc 2.17+ and musl) and Windows (x86_64). The import name is `zig_hocon`. Anywhere else, build it from source (below).
+
+Beta: the API can still change before 1.0. BSD-3-Clause.
+
+## Use
+
+```python
+from zig_hocon import ConfigFactory, KEEP
+
+conf = ConfigFactory.parse_file("app.conf")                       # DB_POOL from os.environ
+conf = ConfigFactory.parse_file("app.conf", env={"DB_POOL": "8"}) # from a dict
+conf = ConfigFactory.parse_file("app.conf", env=None)             # no variables: pool stays 4
+conf = ConfigFactory.parse_file("app.conf", env=KEEP)             # ${?DB_POOL} kept, for later
+conf = ConfigFactory.parse_file("app.conf", resolve=False)        # every ${…} as written
+conf = ConfigFactory.parse_string('include "app.conf"', basedir=".")  # text, includes from basedir
+
+conf.get_string("db.host")      # "db.example.org"
+conf.get_int("db.pool")         # 4
+conf.get_float("ratio")         # 0.75
+conf.get_bool("debug")          # False: true/yes/on, false/no/off
+conf.get_duration("timeout")    # timedelta(seconds=30)
+conf.get_bytes("cache")         # 536870912: "512MB" counts by 1000, "512MiB" by 1024
+conf.get_period("retention")    # {"years": 0, "months": 3, "days": 0}: a timedelta has no months
+conf.get_config("db")           # the object at db, read the same way
+conf.get_int("db.size", default=10)  # 10: nothing at db.size
+
+conf.as_dict()                  # plain dicts and lists
+conf.to_json()                  # bytes, not str: for msgspec.json.decode
+conf.to_hocon()                 # HOCON text
+```
+
+A path is written as in the file: `db.host`, `a."b.c"`. A getter's default is its second argument, as in pyhocon; `parse_file` and `parse_string` take everything after the path by keyword. The package is typed (`py.typed`): `get_int("a")` is an `int`, `get_int("a", None)` an `int | None`. One document can be read from many threads at once.
+
+**Errors** are `ConfigException`s, with `name`, `file`, `line`, `column` and `source_line`:
+
+| exception | when |
+|---|---|
+| `ConfigParseException` | the text is not valid HOCON, or an include fails |
+| `ConfigSubstitutionException` | a `${…}` with no value, or a cycle |
+| `ConfigMissingException` (also a `KeyError`) | nothing at the path, or `null` |
+| `ConfigWrongTypeException` (also a `ValueError`) | the value is not what the getter wants |
+
+**One file to deploy.** `env=KEEP` resolves includes, overrides and references between keys, and leaves the environment variables in; `to_hocon()` writes the result, to be read on the server with its own environment:
+
+```python
+from pathlib import Path
+
+Path("deploy.conf").write_text(ConfigFactory.parse_file("app.conf", env=KEEP).to_hocon())
+```
+
+**Durations and sizes** have helpers with the same rules as the getters: `zig_hocon.parse_duration("30s")` gives a `timedelta`, `zig_hocon.parse_bytes("512MiB")` an int.
+
+**From the shell**, `python -m zig_hocon [--json] [--env=process|none|keep] app.conf` prints the file resolved.
+
+## Coming from pyhocon
+
+Change the import: `ConfigFactory`, the getters and the exception names are the same. What reads differently:
+
+- **The tree is not a dict.** `conf["db"]["host"]` and `json.dumps(conf)` fail; take `conf.as_dict()` first. `as_plain_ordered_dict()` is `as_dict()`.
+- **Fewer methods.** `get`, `get_list`, `with_fallback` and `put` are not there: a typed getter, an `include`, or the dict does the job.
+- **Durations stay text.** `30s` is `"30s"` in `as_dict()` until a getter or a model reads it.
+- **Strict syntax.** Input pyhocon quietly accepted, such as `a..b = 1` or `a = b:c`, is an error with its line and column.
+- **No `include package(...)`.** It is pyhocon's own; include by path.
+
+The [migration guide](https://github.com/lejmr/zig-hocon/blob/main/python/MIGRATING.md) has every difference, with what to write instead.
+
+## Into a model
+
+The package hands over a dict (`as_dict()`) or JSON bytes (`to_json()`); a model library does the checking. The same `app.conf` into the three usual ones.
+
+**pydantic** reads the dict. A duration is text in the file, `"30s"`, so a `BeforeValidator` turns it into a `timedelta` first:
+
+```python
+from datetime import timedelta
+from typing import Annotated
+
+import zig_hocon
+from pydantic import BaseModel, BeforeValidator
+
+Duration = Annotated[timedelta, BeforeValidator(zig_hocon.parse_duration)]
+
+class Db(BaseModel):
+    host: str
+    pool: int
+
+class Settings(BaseModel):
+    db: Db
+    timeout: Duration
+    debug: bool
+
+conf = zig_hocon.ConfigFactory.parse_file("app.conf")
+settings = Settings.model_validate(conf.as_dict())
+```
+
+**msgspec** decodes the JSON bytes straight into a Struct. It reads a `timedelta` itself only from ISO 8601 (`"PT30S"`), so the field gets a type of its own that msgspec hands to `dec_hook`. An environment variable is always a string, so `strict=False` lets `DB_POOL=16` into the `int`:
+
+```python
+from datetime import timedelta
+
+import msgspec
+import zig_hocon
+
+class Duration(timedelta):
+    pass
+
+def dec_hook(type, value):
+    if type is Duration:
+        d = zig_hocon.parse_duration(value)
+        return Duration(d.days, d.seconds, d.microseconds)
+    raise NotImplementedError(type)
+
+class Db(msgspec.Struct):
+    host: str
+    pool: int
+
+class Settings(msgspec.Struct):
+    db: Db
+    timeout: Duration
+    debug: bool
+
+conf = zig_hocon.ConfigFactory.parse_file("app.conf")
+settings = msgspec.json.decode(conf.to_json(), type=Settings, dec_hook=dec_hook, strict=False)
+```
+
+**`@dataclass`** converts no types and does not build `Db` from a dict, so msgspec builds it, with the `Duration`, `dec_hook` and `conf` from above:
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class Db:
+    host: str
+    pool: int
+
+@dataclass
+class Settings:
+    db: Db
+    timeout: Duration
+    debug: bool
+
+settings = msgspec.json.decode(conf.to_json(), type=Settings, dec_hook=dec_hook, strict=False)
+```
+
+All three give `settings.db.host == "db.example.org"` and `settings.timeout == timedelta(seconds=30)`, and fail with the model's own error, path included, on a value of the wrong type. A size works the same way through `zig_hocon.parse_bytes`. The [examples](https://github.com/lejmr/zig-hocon/tree/main/python/examples) have these as tests, with layered environments, errors and one-file deploys.
+
+## Building from source
+
+```sh
+zig build python -Doptimize=ReleaseSafe   # libhocon into python/zig_hocon/
+pip install python/
+zig build test-python                     # the package's tests, with uv
+zig build wheels                          # a wheel for every platform, into zig-out/wheels/
+```
+
+Needs Zig 0.16. Source, issues and the Zig and C libraries: [github.com/lejmr/zig-hocon](https://github.com/lejmr/zig-hocon). BSD-3-Clause.

zig_hocon-0.4.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+zig_hocon/__init__.py,sha256=btewURXKCpy_hsiiXtskMix-CoDla_XDga3wm_Dc_yg,1114
+zig_hocon/__main__.py,sha256=M1Ptj0fPLhsXBEYY0SkR2RVH1PxpzLUJF85eeA6NWIg,1478
+zig_hocon/_capi.py,sha256=0tM69Db9P0CKCs77qLFBoa87_MtIV7I7MehAQK6Ly1g,3564
+zig_hocon/config_parser.py,sha256=EFn00rF0c1T67PSd3id4rbofR0sn3R8yOvFC7O6Refw,4616
+zig_hocon/config_tree.py,sha256=tKIKvCMgWUhYEmiSBfOWRs5sU8xaWN9F0cS933loCZo,11157
+zig_hocon/exceptions.py,sha256=vhCtHuH0b7hxdp58zpzuX7jFtIvF_D5wNOP8qQ3HMyU,2761
+zig_hocon/units.py,sha256=5d_qq4nvFOEdwomv1CoGurcqNKS6DlsE184cuyCXR9Q,1613
+zig_hocon/hocon.dll,sha256=4k-nehZvkItUaH2_5ZHUae7YKOAL-k7P6jiAPp3ZL7c,1480192
+zig_hocon-0.4.0.dist-info/licenses/LICENSE,sha256=fsLifdlnCi9U8CLJk0WoTd9Neo6Jp6fCbdBJyySDQPM,1498
+zig_hocon-0.4.0.dist-info/METADATA,sha256=7J8zIFm0U5-cj-XKMKXbHZT0WRzu5-NZMdlXBIIjmpM,10157
+zig_hocon-0.4.0.dist-info/WHEEL,sha256=VKUr5WOkpMA6AjsxiecMAxPEFZveA2NmFD5VzmAYwLY,102
+zig_hocon-0.4.0.dist-info/RECORD,,

zig_hocon-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: zig-hocon tools/wheel.py
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64

zig_hocon-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Milos Kozak
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.