hocon-parser 1.8.0__py3-none-any.whl

hocon/_internal/resolver/types.py

@@ -0,0 +1,162 @@
+"""Resolver-shared types: placeholder nodes, ``ResObj``, ``ResolveOptions``,
+and the unresolved-tree merge helpers.
+
+Mirrors ts.hocon ``src/internal/resolver/types.ts``. ``ResolverValue`` is the
+union carried through phase 1 (build) before phase 2 (resolve) replaces the
+placeholders.
+"""
+
+from __future__ import annotations
+
+import weakref
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TypeGuard
+
+from ...value import HoconScalar, HoconValue
+from ..lexer.token import Segment
+
+__all__ = [
+    "ConcatPlaceholder",
+    "PackageResolver",
+    "ResObj",
+    "ResolveOptions",
+    "ResolverValue",
+    "SubstPlaceholder",
+    "get_prior",
+    "is_concat",
+    "is_res_obj",
+    "is_subst",
+    "make_res_obj",
+    "merge_unresolved",
+    "separator_values",
+    "set_prior",
+]
+
+
+class SubstPlaceholder:
+    def __init__(
+        self,
+        segments: list[Segment],
+        optional: bool,
+        known_absent: bool,
+        list_suffix: bool,
+        line: int,
+        col: int,
+        prefix_len: int,
+    ) -> None:
+        self.segments = segments
+        self.optional = optional
+        # Internal sentinel for a folded optional self-ref with no prior value.
+        self.known_absent = known_absent
+        self.list_suffix = list_suffix
+        self.line = line
+        self.col = col
+        # 0 for normal, >0 for relativized (number of prefix segments).
+        self.prefix_len = prefix_len
+
+
+class ConcatPlaceholder:
+    def __init__(self, nodes: list[ResolverValue], line: int, col: int) -> None:
+        self.nodes = nodes
+        self.line = line
+        self.col = col
+
+
+class ResObj:
+    def __init__(self) -> None:
+        self.fields: dict[str, ResolverValue] = {}
+        self.prior_values: dict[str, ResolverValue] = {}
+        # Keys whose net value was established by an explicit non-self-referential
+        # assignment (a reset rather than a += / self-ref append). See go.hocon#134.
+        self.reset_keys: set[str] = set()
+
+
+ResolverValue = HoconValue | SubstPlaceholder | ConcatPlaceholder | ResObj
+
+PackageResolver = Callable[[str, str, str | None, str | None], str]
+
+
+def _no_files(_path: str) -> str:
+    raise RuntimeError("no file reader configured")
+
+
+@dataclass
+class ResolveOptions:
+    env: dict[str, str] = field(default_factory=dict)
+    base_dir: str | None = None
+    read_file_sync: Callable[[str], str] = _no_files
+    include_stack: list[str] = field(default_factory=list)
+    # Override the starting dir(s) for the default package resolver.
+    resolve_from: str | list[str] | None = None
+    package_resolver: PackageResolver | None = None
+    # When False, env var lookups in SubstitutionResolver are suppressed.
+    use_system_environment: bool | None = None
+    # When True, leaves unresolved non-optional placeholders in place.
+    allow_unresolved: bool | None = None
+    # Human-readable origin for error messages.
+    origin_description: str | None = None
+
+
+# Track parser-inserted separator whitespace values without leaking a flag into
+# the public HoconValue type. WeakSet keys on identity, so values GC normally.
+separator_values: weakref.WeakSet[HoconScalar] = weakref.WeakSet()
+
+
+def is_subst(v: ResolverValue) -> TypeGuard[SubstPlaceholder]:
+    return isinstance(v, SubstPlaceholder)
+
+
+def is_concat(v: ResolverValue) -> TypeGuard[ConcatPlaceholder]:
+    return isinstance(v, ConcatPlaceholder)
+
+
+def is_res_obj(v: ResolverValue) -> TypeGuard[ResObj]:
+    return isinstance(v, ResObj)
+
+
+def make_res_obj() -> ResObj:
+    return ResObj()
+
+
+def set_prior(o: ResObj, key: str, v: ResolverValue) -> None:
+    o.prior_values[key] = v
+
+
+def get_prior(o: ResObj, key: str) -> ResolverValue | None:
+    return o.prior_values.get(key)
+
+
+def merge_unresolved(receiver: ResObj, fallback: ResObj) -> ResObj:
+    """E12 withFallback merge of two unresolved trees. Receiver's keys win; on a
+    non-object collision the fallback's value is recorded as a prior on the
+    result for cross-layer self-reference lookback in phase 2."""
+    # Function-local import breaks the types ↔ fold_self_ref cycle (both only
+    # touch the other's bindings inside function bodies, as ts.hocon notes).
+    from .fold_self_ref import fold_or_skip_prior
+
+    result = make_res_obj()
+    for k, v in fallback.fields.items():
+        result.fields[k] = v
+    for k, v in fallback.prior_values.items():
+        result.prior_values[k] = v
+    for k, rv in receiver.fields.items():
+        existing = result.fields.get(k)
+        if existing is not None:
+            rec_prior = receiver.prior_values.get(k)
+            if rec_prior is not None and not is_res_obj(rec_prior):
+                result.fields[k] = rv
+                continue
+            if is_res_obj(rv) and is_res_obj(existing):
+                result.fields[k] = merge_unresolved(rv, existing)
+                continue
+            # Non-object collision: receiver wins; capture the fallback's value
+            # (existing) as prior, folded self-ref-free first (go.hocon#134).
+            folded_prior = fold_or_skip_prior(existing, k, None)
+            if folded_prior is not None:
+                result.prior_values[k] = folded_prior
+        result.fields[k] = rv
+    for k, v in receiver.prior_values.items():
+        if k in receiver.fields:
+            result.prior_values[k] = v
+    return result

hocon/_internal/resolver/utils.py

@@ -0,0 +1,144 @@
+"""Resolver helpers. Mirrors ts.hocon ``src/internal/resolver/utils.ts``.
+
+Path lookup, deep-merge (both ``HoconValue`` and ``ResObj`` variants), and the
+cross-include splice logic (go.hocon#134, S13b.2).
+"""
+
+from __future__ import annotations
+
+import re
+
+from ...value import HoconObject, HoconValue
+from ..lexer.token import Segment
+from .fold_self_ref import (
+    fold_known_absent_self_ref,
+    fold_or_skip_prior,
+    string_segments_to_key,
+)
+from .types import ResObj, ResolverValue, is_res_obj, make_res_obj
+
+__all__ = [
+    "deep_merge_hocon_values",
+    "deep_merge_res_obj_into",
+    "hocon_value_to_res_obj",
+    "is_file_not_found_error",
+    "lookup_path",
+    "lookup_res_obj",
+    "segments_to_key",
+]
+
+_NON_BARE_KEY = re.compile(r"[^a-zA-Z0-9\-_]")
+
+
+def segments_to_key(segments: list[Segment]) -> str:
+    parts = []
+    for s in segments:
+        t = s.text
+        if t == "" or _NON_BARE_KEY.search(t):
+            parts.append('"' + t.replace("\\", "\\\\").replace('"', '\\"') + '"')
+        else:
+            parts.append(t)
+    return ".".join(parts)
+
+
+def lookup_path(root: ResObj, segments: list[Segment]) -> ResolverValue | None:
+    if len(segments) == 0:
+        return None
+    head, tail = segments[0], segments[1:]
+    key = head.text
+    val = root.fields.get(key)
+    if val is None:
+        return None
+    if len(tail) == 0:
+        return val
+    if is_res_obj(val):
+        return lookup_path(val, tail)
+    return None
+
+
+def lookup_res_obj(root: ResObj, segments: list[Segment]) -> ResObj | None:
+    cur: ResObj = root
+    for seg in segments:
+        val = cur.fields.get(seg.text)
+        if val is None or not is_res_obj(val):
+            return None
+        cur = val
+    return cur
+
+
+def deep_merge_hocon_values(base: HoconObject, overlay: HoconObject) -> HoconObject:
+    merged: dict[str, HoconValue] = dict(base.fields)
+    for k, v in overlay.fields.items():
+        existing = merged.get(k)
+        if isinstance(existing, HoconObject) and isinstance(v, HoconObject):
+            merged[k] = deep_merge_hocon_values(existing, v)
+        else:
+            merged[k] = v
+    return HoconObject(merged)
+
+
+def deep_merge_res_obj_into(
+    dst: ResObj, src: ResObj, path_prefix: list[str] | None = None
+) -> None:
+    if path_prefix is None:
+        path_prefix = []
+    for k, src_val in src.fields.items():
+        child_prefix = [*path_prefix, k]
+        full_key = string_segments_to_key(child_prefix)
+        dst_val = dst.fields.get(k)
+        if dst_val is not None and is_res_obj(dst_val) and is_res_obj(src_val):
+            # #120: save dst's pre-merge value as the prior at the OUTER level
+            # even when both sides are objects and we recurse.
+            prior_existing = dst.prior_values.get(k)
+            prior = fold_or_skip_prior(dst_val, full_key, prior_existing)
+            if prior is not None:
+                dst.prior_values[k] = prior
+            deep_merge_res_obj_into(dst_val, src_val, child_prefix)
+        else:
+            # Non-object collision: distinguish how src's value composes with
+            # dst's pre-merge value (go.hocon#134, S13b.2).
+            if dst_val is not None:
+                if k in src.reset_keys:
+                    dst.prior_values.pop(k, None)
+                else:
+                    dst_folded = fold_or_skip_prior(dst_val, full_key, dst.prior_values.get(k))
+                    if dst_folded is not None:
+                        src_prior = src.prior_values.get(k)
+                        if src_prior is not None:
+                            dst.prior_values[k] = fold_known_absent_self_ref(
+                                src_prior, full_key, dst_folded
+                            )
+                        else:
+                            dst.prior_values[k] = dst_folded
+            dst.fields[k] = src_val
+    # Carry over priors src has that dst lacks.
+    for k, src_prior in src.prior_values.items():
+        if k not in dst.prior_values:
+            dst.prior_values[k] = src_prior
+    # Propagate reset origin (union).
+    for k in src.reset_keys:
+        dst.reset_keys.add(k)
+
+
+def hocon_value_to_res_obj(hv: HoconValue) -> ResObj:
+    obj = make_res_obj()
+    if not isinstance(hv, HoconObject):
+        return obj
+    for key, val in hv.fields.items():
+        if isinstance(val, HoconObject):
+            obj.fields[key] = hocon_value_to_res_obj(val)
+        else:
+            obj.fields[key] = val
+    return obj
+
+
+def is_file_not_found_error(e: BaseException) -> bool:
+    if isinstance(e, FileNotFoundError):
+        return True
+    if isinstance(e, OSError):
+        import errno
+
+        if e.errno == errno.ENOENT:
+            return True
+    msg = str(e).lower()
+    return "not found" in msg or "no such file" in msg or "enoent" in msg

hocon/coerce.py

@@ -0,0 +1,257 @@
+"""Typed coercions for Config accessors: numbers, booleans, durations, byte sizes.
+
+Mirrors ts.hocon ``src/coerce.ts``. Duration unit names are case-sensitive
+(S19.8, HOCON.md L1304). Single-letter byte abbreviations are powers of two
+(S21.4, HOCON.md L1385).
+
+Standalone module: it must not import :mod:`hocon.value` (value imports this).
+"""
+
+from __future__ import annotations
+
+import math
+import re
+
+__all__ = [
+    "DECIMAL_NUMBER_RE",
+    "ByteUnit",
+    "DurationUnit",
+    "coerce_boolean",
+    "coerce_number",
+    "parse_bytes",
+    "parse_duration",
+    "parse_period",
+]
+
+DECIMAL_NUMBER_RE = re.compile(r"-?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?")
+
+# HOCON_WS = Java Character.isWhitespace set
+#          ∪ { 0x00A0 NBSP, 0x2007 FIGURE SPACE, 0x202F NARROW NO-BREAK SPACE }
+#          ∪ { 0xFEFF BOM }
+# Do NOT use str.strip() — it strips NEL (U+0085) and other Unicode space
+# separators that HOCON does not classify as whitespace. Mirrors
+# ``isHoconWhitespace`` in lexer.py byte-for-byte.
+
+
+def _is_hocon_ws(cp: int) -> bool:
+    if cp in (0x09, 0x0A, 0x0B, 0x0C, 0x0D):
+        return True
+    if 0x1C <= cp <= 0x1F:
+        return True
+    if cp in (0x20, 0xA0, 0xFEFF):
+        return True
+    if cp == 0x1680:
+        return True
+    if 0x2000 <= cp <= 0x200A:
+        return True
+    if cp in (0x2028, 0x2029, 0x202F, 0x205F):
+        return True
+    if cp == 0x3000:
+        return True
+    return False
+
+
+def _trim_hocon_ws(s: str) -> str:
+    start = 0
+    end = len(s)
+    while start < end and _is_hocon_ws(ord(s[start])):
+        start += 1
+    while end > start and _is_hocon_ws(ord(s[end - 1])):
+        end -= 1
+    return s[start:end]
+
+
+_TRUTHY = frozenset(("true", "yes", "on"))
+_FALSY = frozenset(("false", "no", "off"))
+
+
+def coerce_boolean(value: str) -> bool | None:
+    lower = value.lower()
+    if lower in _TRUTHY:
+        return True
+    if lower in _FALSY:
+        return False
+    return None
+
+
+def coerce_number(value: str) -> float | int | None:
+    if not DECIMAL_NUMBER_RE.fullmatch(value):
+        return None
+    if any(c in value for c in ".eE"):
+        return float(value)
+    return int(value)
+
+
+DurationUnit = str  # 'ns' | 'us' | 'ms' | 's' | 'm' | 'h' | 'd'
+
+_DURATION_UNITS: dict[str, float] = {
+    "ns": 1e-6, "nanosecond": 1e-6, "nanoseconds": 1e-6,
+    "us": 1e-3, "microsecond": 1e-3, "microseconds": 1e-3,
+    "ms": 1, "millisecond": 1, "milliseconds": 1,
+    "s": 1_000, "second": 1_000, "seconds": 1_000,
+    "m": 60_000, "minute": 60_000, "minutes": 60_000,
+    "h": 3_600_000, "hour": 3_600_000, "hours": 3_600_000,
+    "d": 86_400_000, "day": 86_400_000, "days": 86_400_000,
+}
+
+_OUTPUT_DURATION_UNITS: dict[str, float] = {
+    "ns": 1e-6, "us": 1e-3, "ms": 1, "s": 1_000, "m": 60_000, "h": 3_600_000, "d": 86_400_000,
+}
+
+
+def _leading_numeric_prefix_len(trimmed: str) -> int:
+    i = 0
+    while i < len(trimmed):
+        ch = trimmed[i]
+        if i == 0 and (ch == "-" or ch == "+"):
+            i += 1
+            continue
+        if ch != "." and not ("0" <= ch <= "9"):
+            break
+        i += 1
+    return i
+
+
+def parse_duration(value: str, output_unit: DurationUnit | None = None) -> float:
+    unit_out = output_unit if output_unit is not None else "ms"
+    trimmed = _trim_hocon_ws(value)
+    i = _leading_numeric_prefix_len(trimmed)
+    if i == 0:
+        return math.nan
+    try:
+        num = float(trimmed[:i])
+    except ValueError:
+        return math.nan
+    if math.isnan(num):
+        return math.nan
+    # S19.8 — unit match is case-sensitive per HOCON.md L1304 (lowercase only).
+    unit = _trim_hocon_ws(trimmed[i:])
+    divisor = _OUTPUT_DURATION_UNITS.get(unit_out)
+    if divisor is None:
+        return math.nan
+    # S18.1 + S18.4: bare number (no unit) → treat as default unit (ms).
+    if unit == "":
+        return num / divisor
+    mult = _DURATION_UNITS.get(unit)
+    if mult is None:
+        return math.nan
+    ms = num * mult
+    return ms / divisor
+
+
+# S20 — Period format. Values are bounded to i32 like Lightbend
+# (`Integer.parseInt`) and rs.hocon's `Period { i32, i32, i32 }`, so a period
+# that would overflow there is invalid here too, not silently widened.
+_I32_MIN = -(2**31)
+_I32_MAX = 2**31 - 1
+
+
+def parse_period(value: str) -> tuple[int, int, int] | None:
+    """Parse a HOCON period string into a ``(years, months, days)`` tuple.
+
+    Accepts ``[ws] integer [ws] [unit] [ws]``; a bare number is taken as days
+    (S20.1, HOCON.md L1321). Unit names are case-sensitive lowercase (the
+    S19.8 duration rule applies to periods too, HOCON.md L1304). Period is
+    integer-only per Lightbend ``Integer.parseInt`` — fractional strings like
+    ``"7.5"`` return None (up03), unlike duration/bytes which accept them.
+    """
+    trimmed = _trim_hocon_ws(value)
+    if not trimmed:
+        return None
+    i = 0
+    while i < len(trimmed) and (("0" <= trimmed[i] <= "9") or trimmed[i] in "+-"):
+        i += 1
+    num_str = trimmed[:i]
+    unit = _trim_hocon_ws(trimmed[i:])
+    if not num_str:
+        return None
+    try:
+        n = int(num_str)
+    except ValueError:
+        return None
+    if not _I32_MIN <= n <= _I32_MAX:
+        return None
+    if unit == "" or unit in ("d", "day", "days"):
+        return (0, 0, n)
+    if unit in ("w", "week", "weeks"):
+        days = n * 7
+        if not _I32_MIN <= days <= _I32_MAX:
+            return None
+        return (0, 0, days)
+    if unit in ("m", "mo", "month", "months"):
+        return (0, n, 0)
+    if unit in ("y", "year", "years"):
+        return (n, 0, 0)
+    return None
+
+
+ByteUnit = str  # 'B' | 'KB' | 'KiB' | 'MB' | 'MiB' | 'GB' | 'GiB' | 'TB' | 'TiB'
+
+_BYTE_UNITS: dict[str, float] = {
+    "B": 1, "byte": 1, "bytes": 1,
+    "KB": 1_000, "kilobyte": 1_000, "kilobytes": 1_000,
+    "KiB": 1_024, "kibibyte": 1_024, "kibibytes": 1_024,
+    "MB": 1_000_000, "megabyte": 1_000_000, "megabytes": 1_000_000,
+    "MiB": 1_048_576, "mebibyte": 1_048_576, "mebibytes": 1_048_576,
+    "GB": 1_000_000_000, "gigabyte": 1_000_000_000, "gigabytes": 1_000_000_000,
+    "GiB": 1_073_741_824, "gibibyte": 1_073_741_824, "gibibytes": 1_073_741_824,
+    "TB": 1_000_000_000_000, "terabyte": 1_000_000_000_000, "terabytes": 1_000_000_000_000,
+    "TiB": 1_099_511_627_776, "tebibyte": 1_099_511_627_776, "tebibytes": 1_099_511_627_776,
+    # S21.4 — single-letter abbreviations → powers of two (java -Xmx convention).
+    "K": 1_024, "k": 1_024,
+    "M": 1_024 ** 2, "m": 1_024 ** 2,
+    "G": 1_024 ** 3, "g": 1_024 ** 3,
+    "T": 1_024 ** 4, "t": 1_024 ** 4,
+    "P": 1_024 ** 5, "p": 1_024 ** 5,
+    "E": 1_024 ** 6, "e": 1_024 ** 6,
+    # lowercase short-form aliases
+    "b": 1,
+    "kb": 1_000, "kib": 1_024,
+    "mb": 1_000_000, "mib": 1_048_576,
+    "gb": 1_000_000_000, "gib": 1_073_741_824,
+    "tb": 1_000_000_000_000, "tib": 1_099_511_627_776,
+}
+
+_OUTPUT_BYTE_UNITS: dict[str, float] = {
+    "B": 1, "KB": 1_000, "KiB": 1_024, "MB": 1_000_000, "MiB": 1_048_576,
+    "GB": 1_000_000_000, "GiB": 1_073_741_824, "TB": 1_000_000_000_000, "TiB": 1_099_511_627_776,
+}
+
+# JS Number.MAX_SAFE_INTEGER = 2^53 - 1. Kept for parity with the ts.hocon
+# overflow guard even though Python ints are unbounded.
+_MAX_SAFE_INTEGER = 2 ** 53 - 1
+
+
+def parse_bytes(value: str, output_unit: ByteUnit | None = None) -> float:
+    unit_out = output_unit if output_unit is not None else "B"
+    trimmed = _trim_hocon_ws(value)
+    i = _leading_numeric_prefix_len(trimmed)
+    if i == 0:
+        return math.nan
+    try:
+        num = float(trimmed[:i])
+    except ValueError:
+        return math.nan
+    if math.isnan(num):
+        return math.nan
+    unit = _trim_hocon_ws(trimmed[i:])
+    divisor = _OUTPUT_BYTE_UNITS.get(unit_out)
+    if divisor is None:
+        return math.nan
+    # S18.1 + S18.4: bare number (no unit) → truncate toward zero (Lightbend
+    # BigDecimal.toBigInteger) and treat as default unit (bytes).
+    if unit == "":
+        num_bytes = math.trunc(num)
+        if abs(num_bytes) > _MAX_SAFE_INTEGER:
+            raise OverflowError("byte size overflows representable range (max 2^53-1 bytes)")
+        return num_bytes / divisor
+    mult = _BYTE_UNITS.get(unit)
+    if mult is None:
+        mult = _BYTE_UNITS.get(unit.lower())
+    if mult is None:
+        return math.nan
+    num_bytes_f = num * mult
+    if abs(num_bytes_f) > _MAX_SAFE_INTEGER:
+        raise OverflowError("byte size overflows representable range (max 2^53-1 bytes)")
+    result = num_bytes_f / divisor
+    return round(result) if unit_out == "B" else result