yaml-tstring 0.1.0__tar.gz

yaml_tstring-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.3
+Name: yaml-tstring
+Version: 0.1.0
+Summary: YAML renderer for t-string structured data templates
+Keywords: pep750,t-strings,yaml,template-strings,structured-data
+Author: Koudai Aono
+Author-email: Koudai Aono <koxudaxi@gmail.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: tstring-bindings>=0.1.0
+Requires-Dist: tstring-core>=0.1.0
+Maintainer: Koudai Aono
+Maintainer-email: Koudai Aono <koxudaxi@gmail.com>
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/koxudaxi/tstring-structured-data
+Project-URL: Repository, https://github.com/koxudaxi/tstring-structured-data
+Project-URL: Documentation, https://github.com/koxudaxi/tstring-structured-data/blob/main/yaml-tstring/README.md
+Project-URL: Changelog, https://github.com/koxudaxi/tstring-structured-data/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/koxudaxi/tstring-structured-data/issues
+Description-Content-Type: text/markdown
+
+# yaml-tstring
+
+YAML rendering for PEP 750 t-strings. Parsing and rendering happen in Rust;
+this package is the Python wrapper.
+
+Requires Python 3.14+.
+
+This package depends on `tstring-bindings`, a native PyO3 extension. On
+supported platforms, install from prebuilt wheels. Other environments require a
+local Rust 1.94.0 toolchain build.
+
+## API
+
+```python
+render_data(template, profile="1.2.2")  # -> Python data (list for multi-doc)
+render_text(template, profile="1.2.2")  # -> YAML text
+render_result(template, profile="1.2.2")  # -> RenderResult (.text + .data)
+```
+
+Type alias: `YamlProfile = Literal["1.2.2"]`
+
+Parsed template structure is cached per process using `template.strings` +
+profile as the key.
+
+## How it works
+
+The Python `Template` is converted to a Rust token stream and parsed by an
+interpolation-aware YAML scanner/parser. Block mappings, block sequences, flow
+collections, scalar styles, anchors, aliases, and tags are all parsed
+explicitly in Rust with interpolation nodes preserved. `saphyr` handles
+data materialization and normalization.
+
+## Supported positions
+
+- mapping-key interpolation
+- plain, single-quoted, double-quoted, and block scalar assembly
+- anchor, alias, and tag interpolation (including verbatim `!<...>` tags)
+- block and flow collections, multi-document streams
+- directives, `%TAG` handles, explicit document markers
+- merge keys, complex keys, trailing commas in flow collections
+- YAML 1.2.2 escape sequences in double-quoted scalars
+
+The full tested boundary is in the
+[backend support matrix](https://github.com/koxudaxi/tstring-structured-data/blob/main/docs/backend-support-matrix.md).
+
+## Limits
+
+- non-finite floats rejected
+- metadata fragments must be non-empty and whitespace-free
+- integers keep exact Python text (no silent `float` coercion)
+- values must be representable in the current YAML 1.2+ surface
+
+## Verify
+
+```bash
+uv sync --group dev
+uv run --group dev pytest
+```
+
+## See also
+
+- [Project README](https://github.com/koxudaxi/tstring-structured-data#readme)
+- [Backend support matrix](https://github.com/koxudaxi/tstring-structured-data/blob/main/docs/backend-support-matrix.md)

yaml_tstring-0.1.0/README.md

@@ -0,0 +1,63 @@
+# yaml-tstring
+
+YAML rendering for PEP 750 t-strings. Parsing and rendering happen in Rust;
+this package is the Python wrapper.
+
+Requires Python 3.14+.
+
+This package depends on `tstring-bindings`, a native PyO3 extension. On
+supported platforms, install from prebuilt wheels. Other environments require a
+local Rust 1.94.0 toolchain build.
+
+## API
+
+```python
+render_data(template, profile="1.2.2")  # -> Python data (list for multi-doc)
+render_text(template, profile="1.2.2")  # -> YAML text
+render_result(template, profile="1.2.2")  # -> RenderResult (.text + .data)
+```
+
+Type alias: `YamlProfile = Literal["1.2.2"]`
+
+Parsed template structure is cached per process using `template.strings` +
+profile as the key.
+
+## How it works
+
+The Python `Template` is converted to a Rust token stream and parsed by an
+interpolation-aware YAML scanner/parser. Block mappings, block sequences, flow
+collections, scalar styles, anchors, aliases, and tags are all parsed
+explicitly in Rust with interpolation nodes preserved. `saphyr` handles
+data materialization and normalization.
+
+## Supported positions
+
+- mapping-key interpolation
+- plain, single-quoted, double-quoted, and block scalar assembly
+- anchor, alias, and tag interpolation (including verbatim `!<...>` tags)
+- block and flow collections, multi-document streams
+- directives, `%TAG` handles, explicit document markers
+- merge keys, complex keys, trailing commas in flow collections
+- YAML 1.2.2 escape sequences in double-quoted scalars
+
+The full tested boundary is in the
+[backend support matrix](https://github.com/koxudaxi/tstring-structured-data/blob/main/docs/backend-support-matrix.md).
+
+## Limits
+
+- non-finite floats rejected
+- metadata fragments must be non-empty and whitespace-free
+- integers keep exact Python text (no silent `float` coercion)
+- values must be representable in the current YAML 1.2+ surface
+
+## Verify
+
+```bash
+uv sync --group dev
+uv run --group dev pytest
+```
+
+## See also
+
+- [Project README](https://github.com/koxudaxi/tstring-structured-data#readme)
+- [Backend support matrix](https://github.com/koxudaxi/tstring-structured-data/blob/main/docs/backend-support-matrix.md)

yaml_tstring-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[project]
+name = "yaml-tstring"
+version = "0.1.0"
+description = "YAML renderer for t-string structured data templates"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Koudai Aono", email = "koxudaxi@gmail.com" }]
+maintainers = [{ name = "Koudai Aono", email = "koxudaxi@gmail.com" }]
+requires-python = ">=3.14"
+dependencies = [
+    "tstring-bindings>=0.1.0",
+    "tstring-core>=0.1.0",
+]
+keywords = ["pep750", "t-strings", "yaml", "template-strings", "structured-data"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/koxudaxi/tstring-structured-data"
+Repository = "https://github.com/koxudaxi/tstring-structured-data"
+Documentation = "https://github.com/koxudaxi/tstring-structured-data/blob/main/yaml-tstring/README.md"
+Changelog = "https://github.com/koxudaxi/tstring-structured-data/blob/main/CHANGELOG.md"
+Issues = "https://github.com/koxudaxi/tstring-structured-data/issues"
+
+[build-system]
+requires = ["uv_build>=0.10.9,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "coverage[toml]>=7.8.0",
+    "inline-snapshot>=0.32.4",
+    "pytest>=8.4.0",
+    "ruff>=0.11.0",
+    "ty>=0.0.23",
+]
+
+[tool.uv.sources]
+tstring-bindings = { workspace = true }
+tstring-core = { workspace = true }
+
+[tool.uv.build-backend]
+source-exclude = [".DS_Store"]
+wheel-exclude = [".DS_Store"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.inline-snapshot]
+format-command = "ruff format --stdin-filename {filename}"
+
+[tool.coverage.run]
+branch = true
+source_pkgs = ["yaml_tstring", "tstring_core"]
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 100
+
+[tool.ty.environment]
+extra-paths = [
+    "../rust/python-bindings/python",
+    "../tstring-core/src",
+    "../examples",
+]
+
+[tool.ruff]
+target-version = "py314"
+
+[tool.ruff.lint]
+select = ["B", "E", "F", "I"]

yaml_tstring-0.1.0/src/yaml_tstring/__init__.py

@@ -0,0 +1,21 @@
+from tstring_core import (
+    RenderResult,
+    TemplateError,
+    TemplateParseError,
+    TemplateSemanticError,
+    UnrepresentableValueError,
+)
+
+from ._runtime import YamlProfile, render_data, render_result, render_text
+
+__all__ = [
+    "RenderResult",
+    "TemplateError",
+    "TemplateParseError",
+    "TemplateSemanticError",
+    "UnrepresentableValueError",
+    "YamlProfile",
+    "render_data",
+    "render_result",
+    "render_text",
+]

yaml_tstring-0.1.0/src/yaml_tstring/_errors.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from tstring_core import (
+    TemplateError,
+    TemplateParseError,
+    TemplateSemanticError,
+    UnrepresentableValueError,
+)
+
+__all__ = [
+    "TemplateError",
+    "TemplateParseError",
+    "TemplateSemanticError",
+    "UnrepresentableValueError",
+]

yaml_tstring-0.1.0/src/yaml_tstring/_runtime.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from string.templatelib import Template
+from typing import Literal, Protocol, TypeIs, cast
+
+from tstring_bindings import tstring_bindings as _bindings
+from tstring_core import RenderResult, YamlValue
+
+type YamlProfile = Literal["1.2.2"]
+
+_CONTRACT_VERSION = 1
+_REQUIRED_SYMBOLS = {
+    "render_yaml",
+    "render_yaml_text",
+    "_render_yaml_result_payload",
+}
+
+
+class _RenderYaml(Protocol):
+    def __call__(self, template: Template, *, profile: YamlProfile) -> YamlValue: ...
+
+
+class _RenderYamlText(Protocol):
+    def __call__(self, template: Template, *, profile: YamlProfile) -> str: ...
+
+
+class _RenderYamlResultPayload(Protocol):
+    def __call__(
+        self, template: Template, *, profile: YamlProfile
+    ) -> tuple[str, YamlValue]: ...
+
+
+def _bind_extension() -> tuple[_RenderYaml, _RenderYamlText, _RenderYamlResultPayload]:
+    version = getattr(_bindings, "__contract_version__", None)
+    if version != _CONTRACT_VERSION:
+        raise ImportError(
+            "yaml_tstring extension contract mismatch: "
+            f"expected version {_CONTRACT_VERSION}, got {version!r}."
+        )
+
+    exported = set(getattr(_bindings, "__contract_symbols__", ()))
+    missing = sorted(_REQUIRED_SYMBOLS - exported)
+    if missing:
+        raise ImportError(
+            "yaml_tstring could not bind required extension symbols: "
+            + ", ".join(missing)
+        )
+
+    return (
+        cast(_RenderYaml, _bindings.render_yaml),
+        cast(_RenderYamlText, _bindings.render_yaml_text),
+        cast(_RenderYamlResultPayload, _bindings._render_yaml_result_payload),
+    )
+
+
+_render_yaml, _render_yaml_text, _render_yaml_result_payload = _bind_extension()
+
+
+def _is_template(value: object) -> TypeIs[Template]:
+    return isinstance(value, Template)
+
+
+def _validate_template(template: object, api_name: str) -> Template:
+    if _is_template(template):
+        return template
+    raise TypeError(
+        f"{api_name} requires a PEP 750 Template object. "
+        f"Got {type(template).__name__} instead."
+    )
+
+
+def _resolve_profile(profile: YamlProfile | str | None) -> YamlProfile:
+    if profile is None or profile == "1.2.2":
+        return "1.2.2"
+    raise ValueError(
+        f"Unsupported YAML profile {profile!r}. Supported profiles: '1.2.2'."
+    )
+
+
+def render_data(
+    template: Template, *, profile: YamlProfile | str | None = None
+) -> YamlValue:
+    checked = _validate_template(template, "render_data")
+    return _render_yaml(checked, profile=_resolve_profile(profile))
+
+
+def render_text(template: Template, *, profile: YamlProfile | str | None = None) -> str:
+    checked = _validate_template(template, "render_text")
+    return _render_yaml_text(checked, profile=_resolve_profile(profile))
+
+
+def render_result(
+    template: Template, *, profile: YamlProfile | str | None = None
+) -> RenderResult[YamlValue]:
+    checked = _validate_template(template, "render_result")
+    text, data = _render_yaml_result_payload(checked, profile=_resolve_profile(profile))
+    return RenderResult(text=text, data=data)
+
+
+__all__ = [
+    "RenderResult",
+    "YamlProfile",
+    "render_data",
+    "render_result",
+    "render_text",
+]

yaml_tstring-0.1.0/src/yaml_tstring/_slots.py

@@ -0,0 +1,3 @@
+from tstring_core import FragmentGroup, Slot, SlotContext
+
+__all__ = ["FragmentGroup", "Slot", "SlotContext"]

yaml_tstring-0.1.0/src/yaml_tstring/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561 typing support.