Annotate structured template render parameters

[koxudaxi]

Summary

• annotate the public structured-data render APIs with Annotated[Template, "json|toml|yaml"] aliases in the runtime wrappers and Python binding stubs
• keep the runtime validation behavior unchanged while exposing sublanguage metadata through the public function signatures
• cover the public render_data / render_text / render_result annotations in JSON, TOML, and YAML binding regression tests

Testing

• uv run pytest json-tstring/tests/test_json_pep750_binding_regressions.py
• uv run pytest toml-tstring/tests/test_toml_pep750_binding_regressions.py
• uv run pytest yaml-tstring/tests/test_yaml_pep750_binding_regressions.py

Summary by CodeRabbit

• Refactor

  • Introduced format-specific template type aliases and updated public JSON/TOML/YAML render APIs to use them for stronger, format-aware typing (typing-only; no runtime behavior changes).

• Tests

  • Added regression tests to verify exported render functions expose the expected format-specific annotated template parameter hints.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3ff3142e-bc2e-41b6-9f63-efa59bcfe0d6

📥 Commits

Reviewing files that changed from the base of the PR and between 4218827 and 7b352d7.

📒 Files selected for processing (1)

• yaml-tstring/tests/test_yaml_pep750_binding_regressions.py

✅ Files skipped from review due to trivial changes (1)

• yaml-tstring/tests/test_yaml_pep750_binding_regressions.py

---

Walkthrough

Introduces format-specific template type aliases (JsonTemplate, TomlTemplate, YamlTemplate = Annotated[Template, "<format>"]) and updates public render APIs and related Protocol/type-signature declarations to accept these annotated template types instead of the generic Template. No runtime control-flow changes.

Changes

Cohort / File(s)	Summary
JSON runtime & tests json-tstring/src/json_tstring/_runtime.py, json-tstring/tests/test_json_pep750_binding_regressions.py	Add JsonTemplate = Annotated[Template, "json"]; update extension Protocols and render_data / render_text / render_result signatures to use JsonTemplate; add regression test asserting Annotated[Template, "json"] is exposed.
TOML runtime & tests toml-tstring/src/toml_tstring/_runtime.py, toml-tstring/tests/test_toml_pep750_binding_regressions.py	Add TomlTemplate = Annotated[Template, "toml"]; update Protocols and public render_* signatures to use TomlTemplate; add regression test asserting Annotated[Template, "toml"].
YAML runtime & tests yaml-tstring/src/yaml_tstring/_runtime.py, yaml-tstring/tests/test_yaml_pep750_binding_regressions.py	Add YamlTemplate = Annotated[Template, "yaml"]; update Protocols and public render_* signatures to use YamlTemplate; add regression test asserting Annotated[Template, "yaml"].
Python bindings (impl + stubs) rust/python-bindings/python/tstring_bindings/__init__.py, rust/python-bindings/python/tstring_bindings/__init__.pyi, rust/python-bindings/python/tstring_bindings/tstring_bindings.pyi	Add JsonTemplate/TomlTemplate/YamlTemplate aliases and update public render function type annotations and internal Protocol signatures to accept the format-specific Annotated template types. No runtime behavior changes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

breaking-change, breaking-change-analyzed

Poem

🐰 I hopped through lines with gentle paws,
Tagged templates with tiny laws,
JSON, TOML, YAML named—
Types adorned and tests proclaimed,
A cheerful hop for cleaner cause.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Annotate structured template render parameters' accurately describes the primary change: adding Annotated type aliases to template render function parameters across JSON, TOML, and YAML modules.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch annotate-render-template-parameters

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (3)

json-tstring/src/json_tstring/_runtime.py (1)

1-109: ⚠️ Potential issue | 🟠 Major

Apply Ruff formatting to clear this CI blocker.

The pipeline reports this file fails ruff format --check, so formatting must be fixed pre-merge.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@json-tstring/src/json_tstring/_runtime.py` around lines 1 - 109, This file
fails ruff formatting; run ruff format (or apply the project's ruff config) on
json_tstring/src/json_tstring/_runtime.py to fix whitespace, import ordering,
and any minor styling issues so the file passes `ruff format --check`; focus
changes around the top-level imports (Template, Annotated, Literal, Protocol,
cast), the _bind_extension/_validate_template functions, and the
render_data/render_text/render_result definitions and __all__ list to ensure
ruff-compatible formatting without changing logic.

yaml-tstring/src/yaml_tstring/_runtime.py (1)

1-109: ⚠️ Potential issue | 🟠 Major

Fix CI-blocking Ruff formatting in this file.

ruff format --check is failing for this module, so this change set cannot pass CI as-is.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@yaml-tstring/src/yaml_tstring/_runtime.py` around lines 1 - 109, This file is
failing Ruff's formatting checks; run an autoformat and commit the result: run
`ruff format yaml_tstring/src/yaml_tstring/_runtime.py` (or `ruff format --fix`
across the repo) and stage the updated file so import grouping, spacing,
line-wrapping, and quote/whitespace issues around top-level definitions like
_bind_extension, _validate_template, _resolve_profile, render_data, render_text,
and render_result are corrected to satisfy `ruff format --check`. Ensure the
reformatted file preserves the existing symbols and behavior and then push the
formatted changes.

toml-tstring/src/toml_tstring/_runtime.py (1)

1-113: ⚠️ Potential issue | 🟠 Major

Resolve Ruff format check failure for this module.

CI reports this file would be reformatted, so formatting needs to be applied before merge.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@toml-tstring/src/toml_tstring/_runtime.py` around lines 1 - 113, The file
fails Ruff formatting; run Ruff (or your project's formatter) to reformat this
module (fix import ordering, spacing, line breaks and any minor style issues)
and commit the changes so _runtime.py matches the project's lint/format rules;
focus on the top-level imports and type alias lines (Template, Annotated,
Literal, TypeIs usage), and ensure functions like _bind_extension,
_validate_template, _resolve_profile, render_data, render_text, and
render_result remain unchanged semantically but are reformatted per Ruff (or run
ruff --fix or the project's pre-commit formatter).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@json-tstring/src/json_tstring/_runtime.py`:
- Around line 1-109: This file fails ruff formatting; run ruff format (or apply
the project's ruff config) on json_tstring/src/json_tstring/_runtime.py to fix
whitespace, import ordering, and any minor styling issues so the file passes
`ruff format --check`; focus changes around the top-level imports (Template,
Annotated, Literal, Protocol, cast), the _bind_extension/_validate_template
functions, and the render_data/render_text/render_result definitions and __all__
list to ensure ruff-compatible formatting without changing logic.

In `@toml-tstring/src/toml_tstring/_runtime.py`:
- Around line 1-113: The file fails Ruff formatting; run Ruff (or your project's
formatter) to reformat this module (fix import ordering, spacing, line breaks
and any minor style issues) and commit the changes so _runtime.py matches the
project's lint/format rules; focus on the top-level imports and type alias lines
(Template, Annotated, Literal, TypeIs usage), and ensure functions like
_bind_extension, _validate_template, _resolve_profile, render_data, render_text,
and render_result remain unchanged semantically but are reformatted per Ruff (or
run ruff --fix or the project's pre-commit formatter).

In `@yaml-tstring/src/yaml_tstring/_runtime.py`:
- Around line 1-109: This file is failing Ruff's formatting checks; run an
autoformat and commit the result: run `ruff format
yaml_tstring/src/yaml_tstring/_runtime.py` (or `ruff format --fix` across the
repo) and stage the updated file so import grouping, spacing, line-wrapping, and
quote/whitespace issues around top-level definitions like _bind_extension,
_validate_template, _resolve_profile, render_data, render_text, and
render_result are corrected to satisfy `ruff format --check`. Ensure the
reformatted file preserves the existing symbols and behavior and then push the
formatted changes.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d8d1f5a2-1111-4515-8f76-bb2c39148c85

📥 Commits

Reviewing files that changed from the base of the PR and between b2455fd and 7281e29.

📒 Files selected for processing (9)

• json-tstring/src/json_tstring/_runtime.py
• json-tstring/tests/test_json_pep750_binding_regressions.py
• rust/python-bindings/python/tstring_bindings/__init__.py
• rust/python-bindings/python/tstring_bindings/__init__.pyi
• rust/python-bindings/python/tstring_bindings/tstring_bindings.pyi
• toml-tstring/src/toml_tstring/_runtime.py
• toml-tstring/tests/test_toml_pep750_binding_regressions.py
• yaml-tstring/src/yaml_tstring/_runtime.py
• yaml-tstring/tests/test_yaml_pep750_binding_regressions.py

[github-actions]

Breaking Change Analysis

Result: No breaking changes detected

Reasoning: PR #26 adds type annotations using Annotated[Template, "format"] aliases to public render API parameters. This is a typing-only change with no runtime behavior modifications. Python's Annotated type preserves compatibility with the base Template type - existing code passing Template objects continues to work without changes. The runtime validation still uses isinstance(value, Template) which accepts any Template object regardless of annotations. This is purely additive metadata for static analysis tools.

---

This analysis was performed by Claude Code Action