python-hcl2 8.0.0rc2__tar.gz → 8.1.0__tar.gz

{python_hcl2-8.0.0rc2 → python_hcl2-8.1.0}/CHANGELOG.md

@@ -9,15 +9,15 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 - Nothing yet.
 
-## \[8.0.0\] - rc2
+## \[8.1.0\] - 2026-04-07
 
 ### Added
 
 - Full architecture overhaul: bidirectional HCL2 ↔ JSON pipeline with typed rule classes. ([#203](https://github.com/amplify-education/python-hcl2/pull/203))
-  - add function tuples round-trip test suite ([#268](https://github.com/amplify-education/python-hcl2/pull/268))
-  - Add postlexer to support multiline binary operators and ternary expressions ([#270](https://github.com/amplify-education/python-hcl2/pull/270))
-  - more robust whitespace handling in reconstruction ([#271](https://github.com/amplify-education/python-hcl2/pull/271))
-  - SerializationOptions - add an option to strip string quotes in dict/JSON output ([#272](https://github.com/amplify-education/python-hcl2/pull/272))
+- `hq` read-only query CLI for HCL2 files ([#277](https://github.com/amplify-education/python-hcl2/pull/277))
+- Agent-friendly conversion CLIs: `hcl2tojson` and `jsontohcl2` ([#274](https://github.com/amplify-education/python-hcl2/pull/274))
+- Add template directives support (`%{if}`, `%{for}`) in quoted strings ([#276](https://github.com/amplify-education/python-hcl2/pull/276))
+- Support loading comments ([#134](https://github.com/amplify-education/python-hcl2/issues/134))
 - CLAUDE.md ([#260](https://github.com/amplify-education/python-hcl2/pull/260))
 
 ### Fixed
@@ -34,7 +34,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Interpolation literals added to locals/variables in maps ([#252](https://github.com/amplify-education/python-hcl2/issues/252))
 - Object literal expression can't be serialized ([#253](https://github.com/amplify-education/python-hcl2/issues/253))
 - Heredocs should interpret backslash literally ([#262](https://github.com/amplify-education/python-hcl2/issues/262))
-- Parsing a multi-line multi-conditional expression causes exception - Unexpected token Token('QMARK', '?') ([#269](https://github.com/amplify-education/python-hcl2/issues/269))
+- Parsing a multi-line multi-conditional expression causes exception — Unexpected token Token('QMARK', '?') ([#269](https://github.com/amplify-education/python-hcl2/issues/269))
+- Parsing error for multiline binary operators ([#246](https://github.com/amplify-education/python-hcl2/pull/246))
 
 ### Changed
 

{python_hcl2-8.0.0rc2 → python_hcl2-8.1.0}/CLAUDE.md

@@ -23,11 +23,30 @@ The **Direct** pipeline (`parse_to_tree` → `transform` → `to_lark` → `reco
 | `hcl2/formatter.py` | Whitespace alignment and spacing on LarkElement trees |
 | `hcl2/reconstructor.py` | LarkElement tree → HCL2 text via Lark |
 | `hcl2/builder.py` | Programmatic HCL document construction |
+| `hcl2/walk.py` | Generic tree-walking primitives for the LarkElement IR tree |
 | `hcl2/utils.py` | `SerializationOptions`, `SerializationContext`, string helpers |
 | `hcl2/const.py` | Constants: `IS_BLOCK`, `COMMENTS_KEY`, `INLINE_COMMENTS_KEY` |
 | `cli/helpers.py` | File/directory/stdin conversion helpers |
 | `cli/hcl_to_json.py` | `hcl2tojson` entry point |
 | `cli/json_to_hcl.py` | `jsontohcl2` entry point |
+| `cli/hq.py` | `hq` CLI entry point — query dispatch, formatting, optional operator |
+| `hcl2/query/__init__.py` | Public query API exports |
+| `hcl2/query/_base.py` | `NodeView` base class, view registry, `view_for()` factory |
+| `hcl2/query/body.py` | `DocumentView`, `BodyView` facades for top-level and body queries |
+| `hcl2/query/blocks.py` | `BlockView` facade for block queries |
+| `hcl2/query/attributes.py` | `AttributeView` facade for attribute queries |
+| `hcl2/query/containers.py` | `TupleView`, `ObjectView` facades for container queries |
+| `hcl2/query/expressions.py` | `ConditionalView` facade for conditional expressions |
+| `hcl2/query/functions.py` | `FunctionCallView` facade for function call queries |
+| `hcl2/query/for_exprs.py` | `ForTupleView`, `ForObjectView` facades for for-expressions |
+| `hcl2/query/path.py` | Structural path parser (`PathSegment`, `parse_path`, `[select()]`, `type:name`) |
+| `hcl2/query/resolver.py` | Path resolver — segment-by-segment with label depth, type filter |
+| `hcl2/query/pipeline.py` | Pipe operator — `split_pipeline`, `classify_stage`, `execute_pipeline` |
+| `hcl2/query/builtins.py` | Built-in transforms: `keys`, `values`, `length` |
+| `hcl2/query/diff.py` | Structural diff between two HCL documents |
+| `hcl2/query/predicate.py` | `select()` predicate tokenizer, recursive descent parser, evaluator |
+| `hcl2/query/safe_eval.py` | AST-validated Python expression eval for hybrid/eval modes |
+| `hcl2/query/introspect.py` | `--describe` and `--schema` output generation |
 
 `hcl2/__main__.py` is a thin wrapper that imports `cli.hcl_to_json:main`.
 
@@ -41,10 +60,11 @@ The **Direct** pipeline (`parse_to_tree` → `transform` → `to_lark` → `reco
 | `rules/containers.py` | `TupleRule`, `ObjectRule`, `ObjectElemRule`, `ObjectElemKeyRule` |
 | `rules/expressions.py` | `ExprTermRule`, `BinaryOpRule`, `UnaryOpRule`, `ConditionalRule` |
 | `rules/literal_rules.py` | `IntLitRule`, `FloatLitRule`, `IdentifierRule`, `KeywordRule` |
-| `rules/strings.py` | `StringRule`, `InterpolationRule`, `HeredocTemplateRule` |
+| `rules/strings.py` | `StringRule`, `InterpolationRule`, `HeredocTemplateRule`, `TemplateStringRule` |
 | `rules/functions.py` | `FunctionCallRule`, `ArgumentsRule` |
 | `rules/indexing.py` | `GetAttrRule`, `SqbIndexRule`, splat rules |
 | `rules/for_expressions.py` | `ForTupleExprRule`, `ForObjectExprRule`, `ForIntroRule`, `ForCondRule` |
+| `rules/directives.py` | `TemplateIfRule`, `TemplateForRule`, and flat directive start/end rules |
 | `rules/whitespace.py` | `NewLineOrCommentRule`, `InlineCommentMixIn` |
 
 ## Public API (`api.py`)
@@ -53,12 +73,13 @@ Follows the `json` module convention. All option parameters are keyword-only.
 
 - `load/loads` — HCL2 text → Python dict
 - `dump/dumps` — Python dict → HCL2 text
+- `query` — HCL2 text/file → `DocumentView` for structured queries
 - Intermediate stages: `parse/parses`, `parse_to_tree/parses_to_tree`, `transform`, `serialize`, `from_dict`, `from_json`, `reconstruct`
 
 ### Option Dataclasses
 
 **`SerializationOptions`** (LarkElement → dict):
-`with_comments`, `with_meta`, `wrap_objects`, `wrap_tuples`, `explicit_blocks`, `preserve_heredocs`, `force_operation_parentheses`, `preserve_scientific_notation`
+`with_comments`, `with_meta`, `wrap_objects`, `wrap_tuples`, `explicit_blocks`, `preserve_heredocs`, `force_operation_parentheses`, `preserve_scientific_notation`, `strip_string_quotes`
 
 **`DeserializerOptions`** (dict → LarkElement):
 `heredocs_to_strings`, `strings_to_heredocs`, `object_elements_colon`, `object_elements_trailing_comma`
@@ -68,13 +89,52 @@ Follows the `json` module convention. All option parameters are keyword-only.
 
 ## CLI
 
-Console scripts defined in `pyproject.toml`. Each uses argparse flags that map directly to the option dataclass fields above.
+Console scripts defined in `pyproject.toml`. All three CLIs accept positional `PATH` arguments (files, directories, glob patterns, or `-` for stdin). When no `PATH` is given, stdin is read by default (like `jq`).
 
+### Exit Codes
+
+All CLIs use structured error output (plain text to stderr) and distinct exit codes:
+
+| Code | `hcl2tojson` | `jsontohcl2` | `hq` |
+|------|---|---|---|
+| 0 | Success | Success | Success |
+| 1 | Partial (some skipped) | JSON/encoding parse error | No results |
+| 2 | All unparsable | Bad HCL structure | Parse error |
+| 3 | — | — | Query error |
+| 4 | I/O error | I/O error | I/O error |
+| 5 | — | Differences found (`--diff` / `--semantic-diff`) | — |
+
+### `hcl2tojson`
+
+```
+hcl2tojson file.tf                          # single file to stdout
+hcl2tojson --ndjson dir/                    # directory → NDJSON to stdout
+hcl2tojson a.tf b.tf -o out/               # multiple files to output dir
+hcl2tojson --ndjson 'modules/**/*.tf'      # glob + NDJSON streaming
+hcl2tojson --only resource,module file.tf  # block type filtering
+hcl2tojson --exclude variable file.tf      # exclude block types
+hcl2tojson --fields cpu,memory file.tf     # field projection
+hcl2tojson --compact file.tf               # single-line JSON
+hcl2tojson -q dir/ -o out/                 # quiet (no stderr progress)
+echo 'x = 1' | hcl2tojson                 # stdin (no args needed)
 ```
-hcl2tojson --json-indent 2 --with-meta file.tf
+
+Key flags: `--ndjson`, `--compact`, `--only`/`--exclude`, `--fields`, `-q`/`--quiet`, `--json-indent N`, `--with-meta`, `--with-comments`, `--strip-string-quotes` (breaks round-trip). Multi-file NDJSON adds a `__file__` provenance key to each object.
+
+### `jsontohcl2`
+
+```
+jsontohcl2 file.json                                       # single file to stdout
+jsontohcl2 --diff original.tf modified.json                # preview text changes
+jsontohcl2 --semantic-diff original.tf modified.json       # semantic-only changes
+jsontohcl2 --semantic-diff original.tf --diff-json m.json  # semantic diff as JSON
+jsontohcl2 --dry-run file.json                             # convert without writing
+jsontohcl2 --fragment -                                    # attribute snippets from stdin
 jsontohcl2 --indent 4 --no-align file.json
 ```
 
+Key flags: `--diff ORIGINAL`, `--semantic-diff ORIGINAL`, `--diff-json`, `--dry-run`, `--fragment`, `-q`/`--quiet`, `--indent N`, `--no-align`, `--colon-separator`.
+
 Add new options as `parser.add_argument()` calls in the relevant entry point module.
 
 ## PostLexer (`postlexer.py`)
@@ -141,4 +201,4 @@ Hooks are defined in `.pre-commit-config.yaml` (includes black, mypy, pylint, an
 
 ## Keeping Docs Current
 
-Update this file when architecture, modules, API surface, or testing conventions change. Also update `README.md` and `docs/usage.md` when changes affect the public API, CLI flags, or option fields.
+Update this file when architecture, modules, API surface, or testing conventions change. Also update `README.md` and the docs in `docs/` (`01_getting_started.md`, `02_querying.md`, `03_advanced_api.md`, `04_hq.md`, `05_hq_examples.md`) when changes affect the public API, CLI flags, or option fields.

{python_hcl2-8.0.0rc2/python_hcl2.egg-info → python_hcl2-8.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hcl2
-Version: 8.0.0rc2
+Version: 8.1.0
 Summary: A parser for HCL2
 Author-email: Amplify Education <github@amplify.com>
 License: MIT
@@ -34,8 +34,9 @@ Dynamic: license-file
 # Python HCL2
 
 A parser for [HCL2](https://github.com/hashicorp/hcl/blob/hcl2/hclsyntax/spec.md) written in Python using
-[Lark](https://github.com/lark-parser/lark). This parser only supports HCL2 and isn't backwards compatible
-with HCL v1. It can be used to parse any HCL2 config file such as Terraform.
+[Lark](https://github.com/lark-parser/lark). It can be used as a Python library or through its CLI tools:
+`hcl2tojson`, `jsontohcl2`, and `hq` — a jq-like query tool for HCL files.
+Supports HCL2 only (not backwards compatible with HCL v1) and works with any HCL2 config file such as Terraform.
 
 ## About Amplify
 
@@ -60,6 +61,12 @@ This package can be installed using `pip`
 pip3 install python-hcl2
 ```
 
+To install the CLI tools (`hcl2tojson`, `jsontohcl2`, `hq`) globally without affecting your project environments, use [pipx](https://pipx.pypa.io/):
+
+```sh
+pipx install python-hcl2
+```
+
 ### Usage
 
 **HCL2 to Python dict:**
@@ -94,12 +101,19 @@ res.block("tags", Name="HelloWorld")
 hcl_string = hcl2.dumps(doc.build())
 ```
 
-For the full API reference, option dataclasses, intermediate pipeline stages, and more examples
-see [docs/usage.md](https://github.com/amplify-education/python-hcl2/blob/main/docs/usage.md).
+### Documentation
+
+| Guide | Contents |
+|---|---|
+| [Getting Started](docs/01_getting_started.md) | Installation, load/dump, options, CLI converters |
+| [Querying HCL (Python)](docs/02_querying.md) | DocumentView, BlockView, tree walking, view hierarchy |
+| [Advanced API](docs/03_advanced_api.md) | Pipeline stages, Builder |
+| [hq Reference](docs/04_hq.md) | `hq` CLI — structural queries, hybrid/eval, introspection |
+| [hq Examples](docs/05_hq_examples.md) | Real-world queries for discovery, compliance, extraction |
 
 ### CLI Tools
 
-python-hcl2 ships two command-line converters:
+python-hcl2 ships three command-line tools:
 
 ```sh
 # HCL2 → JSON
@@ -111,9 +125,13 @@ hcl2tojson terraform/ output/          # converts a directory
 jsontohcl2 output.json                 # prints HCL2 to stdout
 jsontohcl2 output.json main.tf         # writes to file
 jsontohcl2 output/ terraform/          # converts a directory
+
+# Query HCL2 files
+hq 'resource.aws_instance.main.ami' main.tf
+hq 'variable[*]' variables.tf --json
 ```
 
-Both commands accept `-` as PATH to read from stdin. Run `hcl2tojson --help` or `jsontohcl2 --help` for the full list of flags.
+All commands accept `-` as PATH to read from stdin. Run `--help` on any command for the full list of flags.
 
 ## Building From Source
 
@@ -136,6 +154,17 @@ To create a new release go to Releases page, press 'Draft a new release', create
 with a version you want to be released, fill the release notes and press 'Publish release'.
 Github actions will take care of publishing it to PyPi.
 
+## Roadmap
+
+Planned features, roughly in priority order:
+
+- **MCP server** — expose parsing, querying, and formatting as MCP tools for AI agents
+- **Predictable formatting** — source-derived formatting heuristics and stable whitespace defaults
+- **In-place tree edits** — `hq set`, `hq delete` for programmatic HCL modification
+- **Comment deserialization** — comments survive JSON round-trips and tree edits
+- **Expression intelligence** — variable reference tracking, unused variable detection, cross-file analysis
+- **Refactoring operations** — `hq rename`, `hq extract-module`, `hq sort` for high-level code transforms
+
 ## Responsible Disclosure
 
 If you have any security issue to report, contact project maintainers privately.

{python_hcl2-8.0.0rc2 → python_hcl2-8.1.0}/README.md

@@ -7,8 +7,9 @@
 # Python HCL2
 
 A parser for [HCL2](https://github.com/hashicorp/hcl/blob/hcl2/hclsyntax/spec.md) written in Python using
-[Lark](https://github.com/lark-parser/lark). This parser only supports HCL2 and isn't backwards compatible
-with HCL v1. It can be used to parse any HCL2 config file such as Terraform.
+[Lark](https://github.com/lark-parser/lark). It can be used as a Python library or through its CLI tools:
+`hcl2tojson`, `jsontohcl2`, and `hq` — a jq-like query tool for HCL files.
+Supports HCL2 only (not backwards compatible with HCL v1) and works with any HCL2 config file such as Terraform.
 
 ## About Amplify
 
@@ -33,6 +34,12 @@ This package can be installed using `pip`
 pip3 install python-hcl2
 ```
 
+To install the CLI tools (`hcl2tojson`, `jsontohcl2`, `hq`) globally without affecting your project environments, use [pipx](https://pipx.pypa.io/):
+
+```sh
+pipx install python-hcl2
+```
+
 ### Usage
 
 **HCL2 to Python dict:**
@@ -67,12 +74,19 @@ res.block("tags", Name="HelloWorld")
 hcl_string = hcl2.dumps(doc.build())
 ```
 
-For the full API reference, option dataclasses, intermediate pipeline stages, and more examples
-see [docs/usage.md](https://github.com/amplify-education/python-hcl2/blob/main/docs/usage.md).
+### Documentation
+
+| Guide | Contents |
+|---|---|
+| [Getting Started](docs/01_getting_started.md) | Installation, load/dump, options, CLI converters |
+| [Querying HCL (Python)](docs/02_querying.md) | DocumentView, BlockView, tree walking, view hierarchy |
+| [Advanced API](docs/03_advanced_api.md) | Pipeline stages, Builder |
+| [hq Reference](docs/04_hq.md) | `hq` CLI — structural queries, hybrid/eval, introspection |
+| [hq Examples](docs/05_hq_examples.md) | Real-world queries for discovery, compliance, extraction |
 
 ### CLI Tools
 
-python-hcl2 ships two command-line converters:
+python-hcl2 ships three command-line tools:
 
 ```sh
 # HCL2 → JSON
@@ -84,9 +98,13 @@ hcl2tojson terraform/ output/          # converts a directory
 jsontohcl2 output.json                 # prints HCL2 to stdout
 jsontohcl2 output.json main.tf         # writes to file
 jsontohcl2 output/ terraform/          # converts a directory
+
+# Query HCL2 files
+hq 'resource.aws_instance.main.ami' main.tf
+hq 'variable[*]' variables.tf --json
 ```
 
-Both commands accept `-` as PATH to read from stdin. Run `hcl2tojson --help` or `jsontohcl2 --help` for the full list of flags.
+All commands accept `-` as PATH to read from stdin. Run `--help` on any command for the full list of flags.
 
 ## Building From Source
 
@@ -109,6 +127,17 @@ To create a new release go to Releases page, press 'Draft a new release', create
 with a version you want to be released, fill the release notes and press 'Publish release'.
 Github actions will take care of publishing it to PyPi.
 
+## Roadmap
+
+Planned features, roughly in priority order:
+
+- **MCP server** — expose parsing, querying, and formatting as MCP tools for AI agents
+- **Predictable formatting** — source-derived formatting heuristics and stable whitespace defaults
+- **In-place tree edits** — `hq set`, `hq delete` for programmatic HCL modification
+- **Comment deserialization** — comments survive JSON round-trips and tree edits
+- **Expression intelligence** — variable reference tracking, unused variable detection, cross-file analysis
+- **Refactoring operations** — `hq rename`, `hq extract-module`, `hq sort` for high-level code transforms
+
 ## Responsible Disclosure
 
 If you have any security issue to report, contact project maintainers privately.