hocon-parser 1.8.0__py3-none-any.whl

hocon/parse.py

@@ -0,0 +1,122 @@
+"""Public parse entry points.
+
+Mirrors ts.hocon ``src/parse.ts`` (``parse`` / ``parseFile`` / ``parseString``
+and the deferred ``resolveSubstitutions=False`` path). Python has no sync/async
+split at this layer, so the ``*Async`` variants have no counterpart. Options are
+keyword arguments rather than a TS options object.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+
+from ._internal.lexer.lexer import tokenize
+from ._internal.parser.empty_check import assert_non_empty_document
+from ._internal.parser.parser import parse_tokens
+from ._internal.resolver.resolver import build_tree, contains_placeholders, resolve
+from ._internal.resolver.types import PackageResolver, ResolveOptions
+from .config import Config
+from .value import HoconObject
+
+__all__ = ["parse", "parse_file", "parse_string"]
+
+_ReadFile = Callable[[str], str]
+_ResolveFrom = str | list[str] | None
+
+
+def _default_read_file_sync(path: str) -> str:
+    with open(path, encoding="utf-8") as f:
+        return f.read()
+
+
+def _get_env(env: dict[str, str] | None) -> dict[str, str]:
+    return env if env is not None else dict(os.environ)
+
+
+def _build_resolve_context(
+    text: str,
+    base_dir: str | None,
+    env: dict[str, str] | None,
+    read_file: _ReadFile | None,
+    origin_description: str | None,
+    resolve_from: _ResolveFrom,
+    package_resolver: PackageResolver | None,
+) -> tuple[object, ResolveOptions]:
+    tokens = tokenize(text)
+    # S3.1 — HOCON.md L130: empty / whitespace-only / comment-only files are invalid.
+    assert_non_empty_document(tokens, "input")
+    ast = parse_tokens(tokens)
+    opts = ResolveOptions(
+        env=_get_env(env),
+        base_dir=base_dir,
+        read_file_sync=read_file or _default_read_file_sync,
+        resolve_from=resolve_from,
+        package_resolver=package_resolver,
+        origin_description=origin_description,
+    )
+    return ast, opts
+
+
+def parse(
+    text: str,
+    *,
+    base_dir: str | None = None,
+    env: dict[str, str] | None = None,
+    read_file: _ReadFile | None = None,
+    resolve_substitutions: bool = True,
+    origin_description: str | None = None,
+    resolve_from: _ResolveFrom = None,
+    package_resolver: PackageResolver | None = None,
+) -> Config:
+    """Parse HOCON source text. Fully resolves by default; pass
+    ``resolve_substitutions=False`` to return an unresolved Config with
+    substitution placeholders intact (complete later with ``Config.resolve``)."""
+    ast, opts = _build_resolve_context(
+        text, base_dir, env, read_file, origin_description, resolve_from, package_resolver
+    )
+    if resolve_substitutions:
+        value = resolve(ast, opts)  # type: ignore[arg-type]
+        if not isinstance(value, HoconObject):
+            raise RuntimeError("resolved value is not an object")
+        return Config._from_resolved_value(value, origin_description)
+    tree = build_tree(ast, opts)  # type: ignore[arg-type]
+    has_placeholders = contains_placeholders(tree)
+    return Config._from_unresolved_res_obj(
+        tree,
+        parse_base_dir=base_dir,
+        origin_description=origin_description,
+        resolved=not has_placeholders,
+        resolve_opts=opts,
+    )
+
+
+# Lightbend-aligned alias for parse(). Produces a fully resolved Config.
+parse_string = parse
+
+
+def parse_file(
+    path: str,
+    *,
+    base_dir: str | None = None,
+    env: dict[str, str] | None = None,
+    read_file: _ReadFile | None = None,
+    resolve_substitutions: bool = True,
+    origin_description: str | None = None,
+    resolve_from: _ResolveFrom = None,
+    package_resolver: PackageResolver | None = None,
+) -> Config:
+    """Parse a HOCON file, resolving relative includes against its directory."""
+    resolved_path = os.path.abspath(path)
+    reader = read_file or _default_read_file_sync
+    text = reader(resolved_path)
+    return parse(
+        text,
+        base_dir=base_dir if base_dir is not None else os.path.dirname(resolved_path),
+        env=env,
+        read_file=reader,
+        resolve_substitutions=resolve_substitutions,
+        origin_description=origin_description,
+        resolve_from=resolve_from,
+        package_resolver=package_resolver,
+    )

hocon/value.py

@@ -0,0 +1,111 @@
+"""Value model for parsed/resolved HOCON trees.
+
+Mirrors ts.hocon ``src/value.ts``. The three variants (object / array / scalar)
+are plain classes discriminated by ``isinstance`` (Python's structural narrowing
+replaces the TS ``kind`` discriminated union). Object fields use a ``dict``,
+which preserves insertion order like the JS ``Map`` ts.hocon relies on.
+
+Standalone ``as_*`` / ``is_*`` accessors mirror rs.hocon's ``HoconValue::as_*``
+(a discriminated union has no methods of its own).
+"""
+
+from __future__ import annotations
+
+from typing import Literal, TypeGuard
+
+from .coerce import coerce_boolean, coerce_number
+
+__all__ = [
+    "HoconArray",
+    "HoconObject",
+    "HoconScalar",
+    "HoconValue",
+    "ScalarValueType",
+    "as_array",
+    "as_boolean",
+    "as_number",
+    "as_object",
+    "as_string",
+    "is_array",
+    "is_null",
+    "is_object",
+    "is_scalar",
+]
+
+ScalarValueType = Literal["string", "number", "boolean", "null"]
+
+
+class HoconObject:
+    kind: Literal["object"] = "object"
+
+    def __init__(self, fields: dict[str, HoconValue]) -> None:
+        self.fields = fields
+
+
+class HoconArray:
+    kind: Literal["array"] = "array"
+
+    def __init__(self, items: list[HoconValue]) -> None:
+        self.items = items
+
+
+class HoconScalar:
+    kind: Literal["scalar"] = "scalar"
+
+    def __init__(self, raw: str, value_type: ScalarValueType) -> None:
+        self.raw = raw
+        self.value_type = value_type
+
+
+HoconValue = HoconObject | HoconArray | HoconScalar
+
+
+# ─── value accessors ──────────────────────────────────────────────────────────
+
+
+def as_string(v: HoconValue) -> str | None:
+    """Scalar string only (strict): non-string scalars and containers → None."""
+    if isinstance(v, HoconScalar) and v.value_type == "string":
+        return v.raw
+    return None
+
+
+def as_number(v: HoconValue) -> float | None:
+    """Scalar coerced to a number via :func:`coerce_number` (lenient)."""
+    if isinstance(v, HoconScalar):
+        return coerce_number(v.raw)
+    return None
+
+
+def as_boolean(v: HoconValue) -> bool | None:
+    """Scalar coerced to a boolean (true/yes/on, false/no/off)."""
+    if isinstance(v, HoconScalar):
+        return coerce_boolean(v.raw)
+    return None
+
+
+def as_object(v: HoconValue) -> dict[str, HoconValue] | None:
+    """The object's fields, or None if not an object."""
+    return v.fields if isinstance(v, HoconObject) else None
+
+
+def as_array(v: HoconValue) -> list[HoconValue] | None:
+    """The array's items, or None if not an array."""
+    return v.items if isinstance(v, HoconArray) else None
+
+
+def is_object(v: HoconValue) -> TypeGuard[HoconObject]:
+    return isinstance(v, HoconObject)
+
+
+def is_array(v: HoconValue) -> TypeGuard[HoconArray]:
+    return isinstance(v, HoconArray)
+
+
+def is_scalar(v: HoconValue) -> TypeGuard[HoconScalar]:
+    return isinstance(v, HoconScalar)
+
+
+def is_null(v: HoconValue) -> bool:
+    """True for a null scalar."""
+    return isinstance(v, HoconScalar) and v.value_type == "null"

hocon/value_factory.py

@@ -0,0 +1,71 @@
+"""Programmatic construction of resolved Configs (``from_map`` / ``empty``).
+
+Mirrors ts.hocon ``src/value-factory.ts``. Keys are treated as plain keys (NOT
+path expressions — ``"a.b"`` is a literal top-level key, not nested). Values are
+coerced per E12 § "Value factories".
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+from .config import Config
+from .errors import ConfigError
+from .value import HoconArray, HoconObject, HoconScalar, HoconValue
+
+__all__ = ["empty", "from_map"]
+
+
+def from_map(values: dict[str, Any], origin_description: str | None = None) -> Config:
+    """Construct a resolved Config from a plain ``dict``."""
+    fields = _coerce_object(values, "")
+    return Config._from_resolved_value(HoconObject(fields), origin_description)
+
+
+def empty(origin_description: str | None = None) -> Config:
+    """Return a resolved Config with no keys (equivalent to ``from_map({})``)."""
+    return Config._from_resolved_value(HoconObject({}), origin_description)
+
+
+def _coerce_object(obj: dict[str, Any], at_path: str) -> dict[str, HoconValue]:
+    fields: dict[str, HoconValue] = {}
+    for k, v in obj.items():
+        child_path = f"{at_path}.{k}" if at_path else k
+        fields[str(k)] = _coerce_value(v, child_path)
+    return fields
+
+
+def _coerce_value(v: Any, at_path: str) -> HoconValue:
+    if v is None:
+        return HoconScalar("null", "null")
+    # bool must precede int — bool is a subclass of int in Python.
+    if isinstance(v, bool):
+        return HoconScalar("true" if v else "false", "boolean")
+    if isinstance(v, int):
+        return HoconScalar(str(v), "number")
+    if isinstance(v, float):
+        if math.isnan(v) or math.isinf(v):
+            raise ConfigError(
+                f"from_map: {v} is not representable in HOCON "
+                f'(NaN/Infinity not allowed) at path "{at_path}"',
+                at_path,
+            )
+        return HoconScalar(_render_float(v), "number")
+    if isinstance(v, str):
+        return HoconScalar(v, "string")
+    if isinstance(v, (list, tuple)):
+        return HoconArray([_coerce_value(item, f"{at_path}[{i}]") for i, item in enumerate(v)])
+    if isinstance(v, dict):
+        return HoconObject(_coerce_object(v, at_path))
+    raise ConfigError(
+        f'from_map: unsupported value type "{type(v).__name__}" at path "{at_path}"',
+        at_path,
+    )
+
+
+def _render_float(v: float) -> str:
+    """Render a float like JS ``String(v)``: integral floats drop the ``.0``."""
+    if v.is_integer():
+        return str(int(v))
+    return repr(v)