trmnl-liquid-py 0.1.0__tar.gz

trmnl_liquid_py-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.1.0 - unreleased
+
+Initial public release target for the Python port of `usetrmnl/trmnl-liquid` 0.8.2.
+
+### Added
+
+- TRMNL-compatible `Environment` and one-shot `render()` API.
+- Inline `{% template %}` definitions backed by an in-memory template system.
+- TRMNL filter surface for the supported non-I18n 0.8.2 scope.
+- Ruby Liquid lax filter argument syntax used by TRMNL templates.
+- Redcarpet-compatible Markdown rendering implemented on Mistune public APIs.
+- RQRCode-compatible SVG output and QR mask selection using public `qrcode` APIs.
+- Ruby-compatible scalar coercion for fallback filters.
+- Ruby-compatible runtime error rendering and nested block continuation semantics.
+- Typed package support through PEP 561 `py.typed` metadata.
+
+### Compatibility
+
+- Ruby/Python exact differential corpus: 574 cases with 0 known supported-scope mismatches.
+- All 73 official TRMNL Liquid 0.8.2 RSpec examples classified and tracked:
+  - 46 exact differential examples,
+  - 16 property/API contract examples,
+  - 11 Rails/I18n examples explicitly deferred.
+- CI coverage for Python 3.11, 3.12, 3.13, and 3.14.
+
+### Deferred
+
+- Rails/ActionView integration.
+- Full I18n/localized `l_word` and `l_date` behavior.
+- Features introduced after upstream `trmnl-liquid` 0.8.2.

trmnl_liquid_py-0.1.0/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Portions derived from usetrmnl/trmnl-liquid:
+Copyright (c) 2025 Rockwell Schrock
+
+Python port:
+Copyright (c) 2026 Tomasz Jagusz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

trmnl_liquid_py-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.5
+Name: trmnl-liquid-py
+Version: 0.1.0
+Summary: TRMNL Liquid 0.8.2 compatibility layer for Python
+Project-URL: Homepage, https://github.com/Misiu/trmnl-liquid-py
+Project-URL: Repository, https://github.com/Misiu/trmnl-liquid-py
+Project-URL: Issues, https://github.com/Misiu/trmnl-liquid-py/issues
+Project-URL: Changelog, https://github.com/Misiu/trmnl-liquid-py/blob/main/CHANGELOG.md
+Author: Misiu
+License: MIT
+License-File: LICENSE
+Keywords: home-assistant,liquid,templates,trmnl
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: mistune==3.3.4
+Requires-Dist: python-dateutil==2.9.0.post0
+Requires-Dist: python-liquid==2.3.1
+Requires-Dist: qrcode==8.2
+Description-Content-Type: text/markdown
+
+# trmnl-liquid-py
+
+A Python compatibility layer for [`usetrmnl/trmnl-liquid`](https://github.com/usetrmnl/trmnl-liquid), targeting byte-for-byte compatible rendering for the supported TRMNL Liquid 0.8.2 surface.
+
+> [!NOTE]
+> The first release target is `trmnl-liquid-py` **0.1.0**, compatible with `trmnl-liquid` **0.8.2** for the supported non-I18n surface. Rails/ActionView and full I18n behavior are intentionally deferred.
+
+## Installation
+
+Once 0.1.0 is published to PyPI:
+
+```bash
+python -m pip install trmnl-liquid-py
+```
+
+Python **3.11–3.14** is supported.
+
+## Quick start
+
+```python
+from trmnl_liquid import Environment
+
+env = Environment()
+template = env.from_string("Hello {{ name }}!")
+print(template.render(name="TRMNL"))
+```
+
+For one-shot rendering:
+
+```python
+from trmnl_liquid import render
+
+html = render("{{ value | number_with_delimiter }}", value=1234567)
+```
+
+## Inline templates
+
+TRMNL adds an inline `{% template %}` definition that can later be rendered with Liquid's `{% render %}` tag:
+
+```liquid
+{% template card %}
+<div>{{ title }}</div>
+{% endtemplate %}
+
+{% render 'card', title: 'Status' %}
+```
+
+`trmnl-liquid-py` reproduces TRMNL 0.8.2's raw-body and template-storage semantics, including its exact `{% endtemplate %}` terminator behavior.
+
+## TRMNL filters
+
+The 0.1.0 compatibility surface includes:
+
+- `append_random`
+- `days_ago`
+- `group_by`
+- `find_by`
+- `markdown_to_html`
+- `number_with_delimiter`
+- `number_to_currency`
+- `l_word` fallback behavior
+- `l_date` fallback behavior
+- `map_to_i`
+- `pluralize`
+- `json`
+- `parse_json`
+- `sample`
+- `where_exp`
+- `ordinalize`
+- `qr_code`
+
+Important TRMNL/Ruby syntax differences are preserved where required. For example, Ruby Liquid's lax filter syntax accepts a leading comma before the first filter argument:
+
+```liquid
+{{ value | qr_code, 11 }}
+```
+
+### Markdown
+
+`markdown_to_html` reproduces the tested output of TRMNL 0.8.2's default Redcarpet 3.6.1 configuration using Mistune on Python.
+
+```liquid
+{{ markdown | markdown_to_html }}
+```
+
+### QR codes
+
+`qr_code` renders the SVG shape expected from TRMNL's RQRCode-based implementation, including compatible QR mask selection/scoring behavior.
+
+```liquid
+{{ 'https://example.com' | qr_code: 11 }}
+```
+
+## Compatibility target
+
+The baseline is exactly:
+
+- `trmnl-liquid` **0.8.2**
+- Python **3.11, 3.12, 3.13, 3.14**
+- non-I18n behavior
+- Rails/ActionView and full localized `l_word` / `l_date` behavior deferred
+- features added after upstream 0.8.2 excluded until a later compatibility target is adopted
+
+Ruby `trmnl-liquid` 0.8.2 is the reference implementation. Differences in parsing, coercion, formatting, Markdown rendering, QR generation, template behavior, error handling, or rendered output are treated as compatibility issues when they affect the supported scope.
+
+<!-- compatibility-report:start -->
+### Compatibility evidence
+
+| Gate | Result |
+| --- | ---: |
+| Ruby 0.8.2 vs Python exact differential corpus | **574/574** |
+| Known mismatches in the supported scope | **0** |
+| Official TRMNL 0.8.2 RSpec examples mapped | **73/73** |
+| Upstream examples covered by exact differential tests | **46** |
+| Upstream examples covered by property/unit tests | **16** |
+| Upstream examples covered in the initial non-I18n scope | **62/73** |
+| Deferred Rails/I18n upstream examples | **11** |
+| Python CI matrix | **3.11, 3.12, 3.13, 3.14** |
+| Comparison | **exact rendered output** |
+
+The `Compatibility` workflow runs the Ruby oracle first and fails on any mismatch. It then checks that this generated report still matches the checked-in corpus and upstream-spec manifest.
+<!-- compatibility-report:end -->
+
+See [`COMPATIBILITY.md`](COMPATIBILITY.md) for the compatibility contract, upstream spec mapping, and Ruby oracle details.
+
+## Development
+
+Install the project with development dependencies, then run the normal quality gates:
+
+```bash
+python -m pip install -e . pytest ruff mypy build twine \
+  types-python-dateutil==2.9.0.20260807 \
+  types-qrcode==8.2.0.20260518
+ruff check .
+mypy src/trmnl_liquid
+pytest
+python -m build
+twine check dist/*
+```
+
+The Ruby/Python differential suite additionally requires Ruby and the bundle in `compatibility/ruby`:
+
+```bash
+bundle install --gemfile compatibility/ruby/Gemfile
+python compatibility/compare.py
+python -m compatibility.report --check
+```
+
+## Release process
+
+Releases are tag-driven. There is no manual publish workflow and no PyPI API token stored in GitHub.
+
+1. Update `src/trmnl_liquid/__about__.py` and `CHANGELOG.md` in a normal PR.
+2. Merge the PR to `main` and wait for both `CI` and `Compatibility` to pass on `main`.
+3. Create and push a tag whose name is exactly the package version, for example `0.1.0`.
+4. The `Release` workflow verifies that the tag equals `__version__` and points to a commit on `main`.
+5. The workflow builds and validates the wheel/sdist, publishes them to PyPI through Trusted Publishing, and only after a successful PyPI publish creates the matching GitHub Release with the distributions attached.
+
+A tag such as `v0.1.0` is intentionally invalid when `__version__ == "0.1.0"`.
+
+## License
+
+MIT. The repository license includes attribution for portions derived from `usetrmnl/trmnl-liquid`.

trmnl_liquid_py-0.1.0/README.md

@@ -0,0 +1,163 @@
+# trmnl-liquid-py
+
+A Python compatibility layer for [`usetrmnl/trmnl-liquid`](https://github.com/usetrmnl/trmnl-liquid), targeting byte-for-byte compatible rendering for the supported TRMNL Liquid 0.8.2 surface.
+
+> [!NOTE]
+> The first release target is `trmnl-liquid-py` **0.1.0**, compatible with `trmnl-liquid` **0.8.2** for the supported non-I18n surface. Rails/ActionView and full I18n behavior are intentionally deferred.
+
+## Installation
+
+Once 0.1.0 is published to PyPI:
+
+```bash
+python -m pip install trmnl-liquid-py
+```
+
+Python **3.11–3.14** is supported.
+
+## Quick start
+
+```python
+from trmnl_liquid import Environment
+
+env = Environment()
+template = env.from_string("Hello {{ name }}!")
+print(template.render(name="TRMNL"))
+```
+
+For one-shot rendering:
+
+```python
+from trmnl_liquid import render
+
+html = render("{{ value | number_with_delimiter }}", value=1234567)
+```
+
+## Inline templates
+
+TRMNL adds an inline `{% template %}` definition that can later be rendered with Liquid's `{% render %}` tag:
+
+```liquid
+{% template card %}
+<div>{{ title }}</div>
+{% endtemplate %}
+
+{% render 'card', title: 'Status' %}
+```
+
+`trmnl-liquid-py` reproduces TRMNL 0.8.2's raw-body and template-storage semantics, including its exact `{% endtemplate %}` terminator behavior.
+
+## TRMNL filters
+
+The 0.1.0 compatibility surface includes:
+
+- `append_random`
+- `days_ago`
+- `group_by`
+- `find_by`
+- `markdown_to_html`
+- `number_with_delimiter`
+- `number_to_currency`
+- `l_word` fallback behavior
+- `l_date` fallback behavior
+- `map_to_i`
+- `pluralize`
+- `json`
+- `parse_json`
+- `sample`
+- `where_exp`
+- `ordinalize`
+- `qr_code`
+
+Important TRMNL/Ruby syntax differences are preserved where required. For example, Ruby Liquid's lax filter syntax accepts a leading comma before the first filter argument:
+
+```liquid
+{{ value | qr_code, 11 }}
+```
+
+### Markdown
+
+`markdown_to_html` reproduces the tested output of TRMNL 0.8.2's default Redcarpet 3.6.1 configuration using Mistune on Python.
+
+```liquid
+{{ markdown | markdown_to_html }}
+```
+
+### QR codes
+
+`qr_code` renders the SVG shape expected from TRMNL's RQRCode-based implementation, including compatible QR mask selection/scoring behavior.
+
+```liquid
+{{ 'https://example.com' | qr_code: 11 }}
+```
+
+## Compatibility target
+
+The baseline is exactly:
+
+- `trmnl-liquid` **0.8.2**
+- Python **3.11, 3.12, 3.13, 3.14**
+- non-I18n behavior
+- Rails/ActionView and full localized `l_word` / `l_date` behavior deferred
+- features added after upstream 0.8.2 excluded until a later compatibility target is adopted
+
+Ruby `trmnl-liquid` 0.8.2 is the reference implementation. Differences in parsing, coercion, formatting, Markdown rendering, QR generation, template behavior, error handling, or rendered output are treated as compatibility issues when they affect the supported scope.
+
+<!-- compatibility-report:start -->
+### Compatibility evidence
+
+| Gate | Result |
+| --- | ---: |
+| Ruby 0.8.2 vs Python exact differential corpus | **574/574** |
+| Known mismatches in the supported scope | **0** |
+| Official TRMNL 0.8.2 RSpec examples mapped | **73/73** |
+| Upstream examples covered by exact differential tests | **46** |
+| Upstream examples covered by property/unit tests | **16** |
+| Upstream examples covered in the initial non-I18n scope | **62/73** |
+| Deferred Rails/I18n upstream examples | **11** |
+| Python CI matrix | **3.11, 3.12, 3.13, 3.14** |
+| Comparison | **exact rendered output** |
+
+The `Compatibility` workflow runs the Ruby oracle first and fails on any mismatch. It then checks that this generated report still matches the checked-in corpus and upstream-spec manifest.
+<!-- compatibility-report:end -->
+
+See [`COMPATIBILITY.md`](COMPATIBILITY.md) for the compatibility contract, upstream spec mapping, and Ruby oracle details.
+
+## Development
+
+Install the project with development dependencies, then run the normal quality gates:
+
+```bash
+python -m pip install -e . pytest ruff mypy build twine \
+  types-python-dateutil==2.9.0.20260807 \
+  types-qrcode==8.2.0.20260518
+ruff check .
+mypy src/trmnl_liquid
+pytest
+python -m build
+twine check dist/*
+```
+
+The Ruby/Python differential suite additionally requires Ruby and the bundle in `compatibility/ruby`:
+
+```bash
+bundle install --gemfile compatibility/ruby/Gemfile
+python compatibility/compare.py
+python -m compatibility.report --check
+```
+
+## Release process
+
+Releases are tag-driven. There is no manual publish workflow and no PyPI API token stored in GitHub.
+
+1. Update `src/trmnl_liquid/__about__.py` and `CHANGELOG.md` in a normal PR.
+2. Merge the PR to `main` and wait for both `CI` and `Compatibility` to pass on `main`.
+3. Create and push a tag whose name is exactly the package version, for example `0.1.0`.
+4. The `Release` workflow verifies that the tag equals `__version__` and points to a commit on `main`.
+5. The workflow builds and validates the wheel/sdist, publishes them to PyPI through Trusted Publishing, and only after a successful PyPI publish creates the matching GitHub Release with the distributions attached.
+
+A tag such as `v0.1.0` is intentionally invalid when `__version__ == "0.1.0"`.
+
+## License
+
+MIT. The repository license includes attribution for portions derived from `usetrmnl/trmnl-liquid`.

trmnl_liquid_py-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "trmnl-liquid-py"
+dynamic = ["version"]
+description = "TRMNL Liquid 0.8.2 compatibility layer for Python"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Misiu" }]
+keywords = ["trmnl", "liquid", "templates", "home-assistant"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = [
+  "mistune==3.3.4",
+  "python-dateutil==2.9.0.post0",
+  "python-liquid==2.3.1",
+  "qrcode==8.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/Misiu/trmnl-liquid-py"
+Repository = "https://github.com/Misiu/trmnl-liquid-py"
+Issues = "https://github.com/Misiu/trmnl-liquid-py/issues"
+Changelog = "https://github.com/Misiu/trmnl-liquid-py/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "src/trmnl_liquid/__about__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/trmnl_liquid"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/trmnl_liquid",
+  "README.md",
+  "CHANGELOG.md",
+  "LICENSE",
+  "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+addopts = "-ra --strict-config --strict-markers"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+packages = ["trmnl_liquid"]
+
+[dependency-groups]
+dev = [
+  "build>=1.3",
+  "mypy>=1.17",
+  "pytest>=8.4",
+  "ruff>=0.12",
+  "twine>=6.1",
+  "types-python-dateutil==2.9.0.20260807",
+  "types-qrcode==8.2.0.20260518",
+]

trmnl_liquid_py-0.1.0/src/trmnl_liquid/__about__.py

@@ -0,0 +1,3 @@
+"""Package metadata kept separate from runtime imports."""
+
+__version__ = "0.1.0"

trmnl_liquid_py-0.1.0/src/trmnl_liquid/__init__.py

@@ -0,0 +1,6 @@
+"""TRMNL Liquid compatibility layer for Python."""
+
+from .__about__ import __version__
+from .environment import Environment, render
+
+__all__ = ["Environment", "__version__", "render"]

trmnl_liquid_py-0.1.0/src/trmnl_liquid/control_flow.py

@@ -0,0 +1,125 @@
+"""Ruby-compatible nested control-flow nodes for python-liquid.
+
+Ruby Liquid rescues runtime errors per child node in every ``BlockBody``. We keep
+python-liquid's public ``IfTag`` and ``ForTag`` parsers and adapt only their parsed
+child blocks to :class:`TRMNLBlockNode`.
+
+References:
+- Ruby Liquid 5.13 BlockBody rendering:
+  https://github.com/Shopify/liquid/blob/v5.13.0/lib/liquid/block_body.rb
+- python-liquid 2.3.1 IfTag/IfNode:
+  https://github.com/jg-rp/liquid/blob/v2.3.1/liquid/builtin/tags/if_tag.py
+- python-liquid 2.3.1 ForTag/ForNode:
+  https://github.com/jg-rp/liquid/blob/v2.3.1/liquid/builtin/tags/for_tag.py
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from liquid.ast import BlockNode, ConditionalBlockNode, Node
+from liquid.builtin.expressions import LoopExpression
+from liquid.builtin.tags.for_tag import ForNode, ForTag
+from liquid.builtin.tags.if_tag import IfNode, IfTag
+from liquid.expression import Expression
+from liquid.token import Token
+
+from .template import TRMNLBlockNode
+
+if TYPE_CHECKING:
+    from liquid.stream import TokenStream
+
+
+def _block(block: BlockNode) -> TRMNLBlockNode:
+    return TRMNLBlockNode(block.token, block.nodes)
+
+
+def _optional_block(block: BlockNode | None) -> TRMNLBlockNode | None:
+    return _block(block) if block is not None else None
+
+
+class TRMNLIfNode(IfNode):
+    """IfNode whose branch bodies continue after individual runtime errors."""
+
+    def __init__(
+        self,
+        token: Token,
+        condition: Expression,
+        consequence: BlockNode,
+        alternatives: list[ConditionalBlockNode],
+        default: BlockNode | None,
+    ) -> None:
+        wrapped_alternatives = [
+            ConditionalBlockNode(
+                alternative.token,
+                expression=alternative.expression,
+                block=_block(alternative.block),
+            )
+            for alternative in alternatives
+        ]
+        super().__init__(
+            token=token,
+            condition=condition,
+            consequence=_block(consequence),
+            alternatives=wrapped_alternatives,
+            default=_optional_block(default),
+        )
+
+    @classmethod
+    def from_upstream(cls, node: IfNode) -> TRMNLIfNode:
+        """Wrap an upstream IfNode without changing its parsed expressions."""
+        return cls(
+            token=node.token,
+            condition=node.condition,
+            consequence=node.consequence,
+            alternatives=node.alternatives,
+            default=node.default,
+        )
+
+
+class TRMNLIfTag(IfTag):
+    """Built-in ``if`` parser with TRMNL's nested block runtime semantics."""
+
+    def parse(self, stream: TokenStream) -> Node:
+        node = super().parse(stream)
+        if not isinstance(node, IfNode):
+            return node
+        return TRMNLIfNode.from_upstream(node)
+
+
+class TRMNLForNode(ForNode):
+    """ForNode whose iteration body continues after individual runtime errors."""
+
+    def __init__(
+        self,
+        token: Token,
+        expression: LoopExpression,
+        block: BlockNode,
+        default: BlockNode | None = None,
+    ) -> None:
+        super().__init__(
+            token=token,
+            expression=expression,
+            block=_block(block),
+            default=_optional_block(default),
+        )
+
+    @classmethod
+    def from_upstream(cls, node: ForNode) -> TRMNLForNode:
+        """Wrap an upstream ForNode without changing its parsed expression."""
+        return cls(
+            token=node.token,
+            expression=node.expression,
+            block=node.block,
+            default=node.default,
+        )
+
+
+class TRMNLForTag(ForTag):
+    """Built-in ``for`` parser with TRMNL's nested block runtime semantics."""
+
+    def parse(self, stream: TokenStream) -> Node:
+        node = super().parse(stream)
+        if not isinstance(node, ForNode):
+            return node
+        return TRMNLForNode.from_upstream(node)