Skip to content

feat(python): zig_hocon.pyhocon, pyhocon's API over zig-hocon - #25

Open
lejmr wants to merge 7 commits into
mainfrom
agent/24-pyhocon-api
Open

lejmr wants to merge 7 commits into
mainfrom
agent/24-pyhocon-api

Conversation

@lejmr

@lejmr lejmr commented Oct 20, 2026 •

Copy link
Copy Markdown
Owner

Closes #24.

from zig_hocon.pyhocon import ConfigFactory   # was: from pyhocon import ConfigFactory
  • python/zig_hocon/pyhocon/: pyhocon 0.3.63's modules (config_parser, config_tree, converter, exceptions, tool), names and arguments. The tree is an OrderedDict with get, the getters, get_list, put, pop, with_fallback, merge_configs; parse_file(encoding=, required=), parse_URL, from_dict, resolve_substitutions, resolve_package_path; HOCONConverter output identical to pyhocon's, checked against pyhocon itself.
  • The document is read by libhocon; zig_hocon itself is unchanged. A resolve=False document keeps its text, so with_fallback() and resolve_substitutions() resolve it as two files one after the other.
  • pyhocon's own test suite with the import swapped: 263 of 308 pass. The 45 others are listed in python/MIGRATING.md: 44 are spec differences (pyparsing exception classes 12, += appends one element 9, unquoted -Xmx1g 6, pyhocon's include extensions 6, self-references Java refuses too 5, …), 1 is ConfigTree.resolve(), not there.
  • Durations have pyhocon's types: 30s is a timedelta, a relativedelta with python-dateutil; only a quoted "30s" differs (a duration here, text in pyhocon).
  • Held against the newest pyhocon on every change: test_pyhocon_signatures.py (every public name, same parameters, via inspect) and test_pyhocon_compat.py (same values, types and converter output), differences by design as strict xfails.
  • Speed: 5 KB in 0.24 ms, 10 MB in 0.32 s (ReleaseFast, M4 Pro); pyhocon 29 ms and 68 s.
  • zig build test-python green on 3.10, 3.12 and 3.14, 100 % coverage, mypy --strict. The wheel carries the subpackage (pyproject.toml packages).
  • Licence: parts of the module are changed from pyhocon's code (Apache-2.0), so pyhocon's LICENSE sits next to it, each changed file says so, and the package's licence is BSD-3-Clause AND Apache-2.0.
  • Fix found on the way: tools/wheel.py packed only top-level .py files, so release wheels would have lacked zig_hocon.pyhocon and have always lacked py.typed; it takes the whole package now.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CbBo1aotFTDLY2gery7qYD

lejmr and others added 7 commits October 20, 2026 23:16
Moving over from pyhocon is a change of import: the modules, names,
arguments and output of pyhocon 0.3.63, the tree an OrderedDict with
get, put, pop and with_fallback, parse_URL, from_dict, HOCONConverter
and the command line. The document is read by libhocon as zig_hocon
reads it, so a config means what the spec says; pyhocon's own test
suite passes 167 of 263 with the import swapped, and MIGRATING.md says
what the other 96 are.

Closes #24

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CbBo1aotFTDLY2gery7qYD
`30s` is a timedelta, a relativedelta with python-dateutil, in objects and
lists too, as pyhocon parses it; they stay durations through with_fallback,
and HOCONConverter writes a relativedelta as pyhocon does. pyhocon's own suite
goes from 167 to 218 of 263. A quoted "30s" is a duration too: libhocon's
JSON has no quotes left.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CbBo1aotFTDLY2gery7qYD
ruff check, ruff format --check and ty check on the package, pinned, with
their settings in python/pyproject.toml. The tests and examples stay out:
they are the users' side, as they are written. mypy --strict stays.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CbBo1aotFTDLY2gery7qYD
One parametrized test reads each document with both: the values with their
types, and HOCONConverter's four outputs to the character. A difference by
design is a strict xfail with its reason, so one that goes away shows.
pyhocon joins the test environment for it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CbBo1aotFTDLY2gery7qYD
test_pyhocon_signatures.py reads every public name of the installed
pyhocon's modules and checks each is here, in the same module, a function
with pyhocon's parameters and at most more with a default after them, a
class with pyhocon's bases. A difference by design is a strict xfail with
its reason. The test environment takes the newest pyhocon, so its next
release shows.

What it found is added: period_parser and period_serializer, the duration
code moved there, and the names pyhocon's config_parser and converter have
from where they import them. pyhocon's own suite, test_periods.py now
included: 263 of 308.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CbBo1aotFTDLY2gery7qYD
…eels

zig_hocon.pyhocon is changed in parts from pyhocon's code, which is
Apache-2.0: pyhocon's LICENSE goes next to it, each changed file says what
it comes from, and the package's license is BSD-3-Clause AND Apache-2.0
with both texts in license-files.

tools/wheel.py packed only the .py files at the top of zig_hocon/: the
release wheels would have had no zig_hocon.pyhocon, and have never had
py.typed. It takes the whole package now, and both licenses into
.dist-info/licenses/. tools/test-wheel.sh installs python-dateutil and
pyhocon for the tests that hold the module against it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CbBo1aotFTDLY2gery7qYD
… makes OrderedDict.items's positional-only

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CbBo1aotFTDLY2gery7qYD

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

zig_hocon.pyhocon: pyhocon's API 1:1, the spec's meaning

1 participant