Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
feature/Markdown-renderer-docgen-contract · L-261008-5ad954 (#1382)
Louis Choquelf955d6c71eef
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 545c6f8e7..f08f5a6e6 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,7 @@- **`pipelex login`**: gets a Pipelex API key through the browser, with a one-time `state` value the app must echo, or from a hidden prompt with `--paste`, checks it against the hosted API, and saves it to `~/.pipelex/.env` as `PIPELEX_API_KEY` (mode 0600, other lines kept, a symlinked file written through, the key never printed), naming a working-directory `.env` whose own `PIPELEX_API_KEY` line would override it, and exiting 1 with the path and the error when the file cannot be written; `PIPELEX_APP_URL` aims it at another Pipelex app.- **`pipelex init` asks where runs execute**: Enter takes the hosted Pipelex API, which signs you in unless a key is already set and asks for no provider key, and the other answer runs today's backend, routing and credential steps; the answer is written to `[run] execution`, with a warning when the working directory's project overrides it. `pipelex doctor --fix` keeps a `[run] execution` already set, keeps a `pipelex.toml` that sets none local, and takes the hosted default only for a brand-new home, `pipelex doctor` and `pipelex-agent doctor` judge a hosted setup by its Pipelex API key and report provider credentials as needed only for `--local` runs, and `pipelex-agent init` takes `"execution": "hosted"` in `--config` and reports `execution`.- **`pipelex migrate` cleans up what a former release left for the Pipelex Gateway**: a configuration set up by a release that ran on the Pipelex Gateway is refused at boot with the new `FormerReleaseConfigError`, which names what stops it and `pipelex migrate`. That command and `pipelex-agent migrate` (under the new `former_release` key) remove the Gateway's backend, routing profiles, routes and files and leave Pipelex Manifold's, which is not retired; they keep a copy of each file they change or remove, and report what they leave for a hand edit or what would still stop Pipelex from starting. `pipelex init` and `pipelex doctor --fix` offer the same cleanup, and `pipelex doctor` lists the files.+- **The document engine contract names what an engine shares with the built-in one**: `pipelex.cogt.doc_gen.layout_display` holds `display_scalar` and `is_numeric_column`, by which the built-in PDF engine and a plugin's engines show a layout tree's values, and `markdown_as_html`, which converts a Markdown block with the parser the `markdown` filter uses; `pipelex.cogt.doc_gen.template_environment` holds `make_plain_data_template_environment()`, the synchronous, sandboxed and strict Jinja environment an engine fills a template file's tags in. Neither imports ReportLab, and both join the plugin contract with `PLUGIN_API_VERSION` 6, so an engine no longer copies these helpers or imports them from Pipelex's internals.### Changeddiff --git a/docs/under-the-hood/document-engine-plugins.md b/docs/under-the-hood/document-engine-plugins.mdindex 953444b05..52f4625eb 100644--- a/docs/under-the-hood/document-engine-plugins.md+++ b/docs/under-the-hood/document-engine-plugins.md@@ -1,6 +1,6 @@---title: "Document Engine Plugins"-description: "How a PipeDocGen step finds the engine that prints it, a model of the doc_gen family, how a plugin declares its engines and their defaults, the render job an engine receives, the template checker it may offer, and how a runtime refuses at load what it cannot print."+description: "How a PipeDocGen step finds the engine that prints it, a model of the doc_gen family, how a plugin declares its engines and their defaults, the render job an engine receives, what it shares with the built-in engine, the template checker it may offer, and how a runtime refuses at load what it cannot print."---# Document Engine Plugins@@ -124,6 +124,8 @@ def render(self, *, job: RenderJob, resources: RenderResources) -> RenderedDocum`render` is synchronous and runs on a thread of a print pool of its own, never on the event loop's default executor, which the engine's reads need, while `RenderResources.load` hands each read back to the event loop the print started from. An engine keeps no state from one print into the next. It signals a document it cannot print by raising `DocGenRenderError`, which passes through; anything else it raises, beyond a Pipelex error, is reported as a `DocGenRenderError` naming the engine and the file.+The contract is what an engine uses in `pipelex.cogt.doc_gen`: the worker; the render job, its resources, the `LoadedResource` they return and the rendered document (`render_job.py`); the formats and sources (`doc_gen_format.py`); `DocGenRenderError`, the one error of `exceptions.py` an engine raises; the layout tree (`layout_tree.py`); the template check request and the findings a checker returns (`template_check.py`), with the input shapes the request carries (`InputShape` and `InputShapeKind` in `input_shape.py`); and the two modules of the next section. The rest of the package is Pipelex's own side of the print. An engine reaches Pipelex only through the contract and the registration seam every plugin uses, which also hands a worker its model spec, its backend, its SDK clients and its reporting delegate: anything else in Pipelex may move or change in an ordinary release, while a breaking change to the contract moves `PLUGIN_API_VERSION`. A piece an engine is missing is added to the contract, rather than imported from elsewhere in Pipelex.+### The media type of a file an engine reads`LoadedResource.mime_type` is the type the file's source gives it, lowercased and without its parameters, such as `text/css`. Pipelex never guesses it, so it is `None` when the source gives none:@@ -140,6 +142,20 @@ A declared type is returned as declared, even a generic one such as `application---+## What an engine shares with the built-in one++A document should read the same whichever engine printed it, and a template should be held to the same rules whichever engine fills it, so an engine takes these from the contract rather than writing its own. None of them imports ReportLab, so an engine can use them without loading the built-in engine's library.++`pipelex.cogt.doc_gen.layout_display` holds the rules by which every engine shows a layout tree's values, the built-in engine included:++- **`display_scalar(value=…)`** writes a scalar as text: blank for nothing, `Yes` or `No` for a boolean, a whole float without its decimals, a date as `2026-09-29`, a datetime as `2026-09-29 14:05`, and a time of day as `09:07`, each followed by the UTC offset it states (` UTC`, ` +02:00`), if any.+- **`is_numeric_column(values=…)`** says whether a table's column holds numbers only, blanks aside, and at least one, a boolean not counting as a number: such a column is aligned right.+- **`markdown_as_html(markdown=…)`** converts a `MarkdownBlock` to an HTML fragment for an engine that writes HTML, with the one parser Pipelex reads Markdown with, as the `markdown` filter and the `Markdown` concept's HTML view do: CommonMark with tables and strikethrough, raw HTML shown as text, and only a URL with a scheme turned into a link, so `README.md` stays text. Called from an engine's own code, outside a template render, it is charged to no render budget, so an engine bounds what it converts itself.++`pipelex.cogt.doc_gen.template_environment` holds **`make_plain_data_template_environment()`**, the Jinja environment an engine fills a template file's tags in when it fills them itself, as a Word template's tags are filled through docxtpl. It is synchronous; sandboxed as every Pipelex template is, each render spending from a budget of its own (see [Template Sandbox](template-sandbox.md)); strict, so a missing value fails the render instead of printing as empty text; and it registers only Jinja's built-in filters, since the plain data it reads holds no stuff for Pipelex's filters to work on.++---+## The template checkerAn office template names the fields it is filled with in its own way, which Pipelex cannot read: an Excel workbook through its defined names and Tables, a Word document through its tags. So an engine that fills a template file overrides its worker's `check_template` (the request and findings are in `pipelex.cogt.doc_gen.template_check`):diff --git a/pipelex/cogt/doc_gen/layout_display.py b/pipelex/cogt/doc_gen/layout_display.pynew file mode 100644index 000000000..6557cbba2--- /dev/null+++ b/pipelex/cogt/doc_gen/layout_display.py@@ -0,0 +1,78 @@+"""How every document engine shows a layout tree's values, so a document reads the same whichever engine printed it.++The built-in PDF engine and the engines of the Pipelex document generation plugin write the same layout tree+(`layout_tree.py`) in different formats, and they show its values through these functions rather than through+rules of their own:++- `display_scalar` writes a scalar as text: blank for nothing, Yes or No, numbers plainly, dates and times in+ ISO order with the UTC offset they state;+- `is_numeric_column` says whether a table's column holds numbers only, which an engine aligns right;+- `markdown_as_html` converts a `MarkdownBlock` to an HTML fragment with the one parser Pipelex reads Markdown+ with, for an engine that writes HTML.++This module is part of the document engine contract (`pipelex/plugins/contract.py`), and it imports no engine,+so a plugin's engine can use it without loading ReportLab.+"""++import datetime++from pipelex.cogt.doc_gen.layout_tree import LayoutScalar+from pipelex.tools.markdown.markdown_parser import render_markdown_as_html+++def display_scalar(*, value: LayoutScalar) -> str:+ """A scalar as the document prints it: blank for nothing, Yes or No, numbers plainly, dates and times in ISO order.++ A time of day prints to the minute, with the UTC offset the value states, if any.+ """+ match value:+ case None:+ return ""+ case bool():+ return "Yes" if value else "No"+ case int():+ return str(value)+ case float():+ if value.is_integer():+ return str(int(value))+ return format(value, ".15g")+ case datetime.datetime():+ return value.strftime("%Y-%m-%d %H:%M") + _utc_offset_suffix(value=value)+ case datetime.date():+ return value.isoformat()+ case datetime.time():+ return value.strftime("%H:%M") + _utc_offset_suffix(value=value)+ case str():+ return value+++def _utc_offset_suffix(*, value: datetime.datetime | datetime.time) -> str:+ """The UTC offset a value states, as ' UTC' or ' +02:00', or nothing for a value that states none."""+ offset = value.utcoffset()+ if offset is None:+ return ""+ total_minutes = int(offset.total_seconds()) // 60+ if total_minutes == 0:+ return " UTC"+ sign = "+" if total_minutes > 0 else "-"+ hours, minutes = divmod(abs(total_minutes), 60)+ return f" {sign}{hours:02d}:{minutes:02d}"+++def is_numeric_column(*, values: list[LayoutScalar]) -> bool:+ """Whether a column holds numbers only, blanks aside, and at least one: such a column is aligned right."""+ present = [value for value in values if value is not None]+ return bool(present) and all(isinstance(value, (int, float)) and not isinstance(value, bool) for value in present)+++def markdown_as_html(*, markdown: str) -> str:+ """Markdown as an HTML fragment, parsed as the `markdown` filter, the `Markdown` concept and the built-in engine parse it.++ The parser reads CommonMark with tables and strikethrough; raw HTML in the source comes out escaped, so it+ shows as text rather than entering the document; and only a URL with a scheme becomes a link, so `README.md`+ or `www.example.com` stays text.++ A conversion is charged to the budget of the template render running at the time, so one an engine makes from+ its own code, outside any template render, is charged to none: the engine bounds what it converts and prints.+ """+ return render_markdown_as_html(markdown)diff --git a/pipelex/cogt/doc_gen/layout_tree.py b/pipelex/cogt/doc_gen/layout_tree.pyindex bdcf06ba8..58908046f 100644--- a/pipelex/cogt/doc_gen/layout_tree.py+++ b/pipelex/cogt/doc_gen/layout_tree.py@@ -1,10 +1,11 @@"""The layout tree: what the auto-layout of a step's inputs is, before any engine writes it.A `PipeDocGen` step with no template lays its inputs out by itself, and every format's engine writes the-same tree: the built-in PDF engine on ReportLab, and the Excel and Word engines of the Pipelex document-generation plugin. The tree is plain data with a JSON round trip, and it is part of the engines' contract+same tree: the built-in PDF engine on ReportLab, and the engines of the Pipelex document generation+plugin. The tree is plain data with a JSON round trip, and it is part of the engines' contract(`render_job.py`). Every print today hands it to an engine in the same process; across a JSON boundary a-date, a time or a datetime comes back as its ISO text, since nothing in the wire format tags it. It shows:+date, a time or a datetime comes back as its ISO text, since nothing in the wire format tags it. Every+engine shows its values by the same rules, in `layout_display.py`. It shows:- the scalar fields of a structure make a **field grid**, labelled from the field titles;- a list of flat structures makes a **table**;diff --git a/pipelex/cogt/doc_gen/template_environment.py b/pipelex/cogt/doc_gen/template_environment.pynew file mode 100644index 000000000..586049f7c--- /dev/null+++ b/pipelex/cogt/doc_gen/template_environment.py@@ -0,0 +1,36 @@+"""The template environment a document engine fills a template file's Jinja tags in, when they read plain data.++An engine that fills a template file itself, such as a Word template's tags filled through docxtpl, renders them in+this environment rather than in one of its own, so a document template gets the sandbox every other Pipelex template+gets. The values it reads are the plain data of the step's inputs (`plain_data.py`), with no stuff in them, so the+environment registers none of Pipelex's filters, which are made for stuff.++This module is part of the document engine contract (`pipelex/plugins/contract.py`).+"""++from jinja2 import BaseLoader++from pipelex.tools.jinja2.jinja2_environment import make_jinja2_env_from_loader+from pipelex.tools.jinja2.jinja2_sandbox import PipelexTemplateEnvironment+from pipelex.tools.jinja2.template_category import TemplateCategory+++def make_plain_data_template_environment() -> PipelexTemplateEnvironment:+ """A new environment for a template of plain data: synchronous, sandboxed, strict about missing values, filterless.++ - **Synchronous**: a template renders with `render`, as a library like docxtpl calls it.+ - **Sandboxed** as every Pipelex template is (`jinja2_sandbox.py`): a template reads data and calls the+ methods of plain values, and anything else raises `jinja2.exceptions.SecurityError`; and each render spends+ from a budget of its own, an overdraft raising `RenderBudgetExceededError`.+ - **Strict**: a missing value fails the render with `jinja2.exceptions.UndefinedError` rather than printing+ as empty text, as in every document template.+ - **Without Pipelex's filters**: Jinja's built-in filters only, under the sandbox.++ It loads no template by name, so a template is built from its source with `from_string`.+ """+ return make_jinja2_env_from_loader(+ template_category=TemplateCategory.BASIC,+ loader=BaseLoader(),+ enable_async=False,+ is_undefined_strict=True,+ )diff --git a/pipelex/plugins/contract.py b/pipelex/plugins/contract.pyindex b46686ca2..dbbcdb7d3 100644--- a/pipelex/plugins/contract.py+++ b/pipelex/plugins/contract.py@@ -26,9 +26,14 @@ if TYPE_CHECKING:# targets v4, and a bump would have made every installed plugin re-declare ``targets_api`` for nothing.## ``InferenceFamily.DOC_GEN`` — the document engines a ``PipeDocGen`` step prints with, each a model of the-# ``doc_gen`` family registered through ``add_inference_backend`` — joined under v4 on the same reasoning. Its-# worker (``DocGenWorkerAbstract``), render job and template check request (``pipelex.cogt.doc_gen``) are part-# of the contract: a breaking change to any of them is a bump.+# ``doc_gen`` family registered through ``add_inference_backend`` — joined under v4 on the same reasoning. What an+# engine uses in ``pipelex.cogt.doc_gen`` is part of the contract, and a breaking change to any of it is a bump: the+# worker (``DocGenWorkerAbstract``), the render job with its resources and rendered document (``render_job``), the+# formats and sources (``doc_gen_format``), ``DocGenRenderError``, the layout tree an engine writes (``layout_tree``),+# and the template check request with its findings (``template_check``) and input shapes (``InputShape`` and+# ``InputShapeKind``). Two modules joined it with v6, as additions that would have needed no bump of their own: the+# rules by which every engine shows the tree's values (``layout_display``: ``display_scalar``, ``is_numeric_column``,+# ``markdown_as_html``) and the environment an engine fills a template of plain data in (``template_environment``).## ``add_internal_model`` and ``add_doc_gen_default`` — plain data a plugin declares for the model manager to merge at# boot: a model of the internal backend, as the table a backend file would hold, and the model deck's default engine fordiff --git a/pipelex/providers/reportlab/reportlab_pdf_renderer.py b/pipelex/providers/reportlab/reportlab_pdf_renderer.pyindex aa4c44cee..a496fa564 100644--- a/pipelex/providers/reportlab/reportlab_pdf_renderer.py+++ b/pipelex/providers/reportlab/reportlab_pdf_renderer.py@@ -11,6 +11,9 @@ It writes the tree as ReportLab flowables on A4 portrait pages:- paragraphs as they are, Markdown through its converter (`markdown_flowables`), and an image from the bytes therender's resources read, scaled to the page with its caption under it.+A value is written as text, and a column found numeric, by the contract's rules (`layout_display.py`), which every+engine shares, so a document reads the same whichever engine printed it.+Every text is escaped before it enters ReportLab's paragraph markup, so a value prints as written. The enginefetches nothing itself: an image is read through `RenderResources`, which applies the run's read scope, and aMarkdown image is not read at all. It is the worker of the `reportlab-pdf` model, made for each print; it registers@@ -23,7 +26,6 @@ throughput, since a build is pure Python and would hold the interpreter lock anythe lock is taken, so a slow image does not hold up another render."""-import datetimeimport ioimport threadingfrom functools import cache@@ -40,12 +42,12 @@ from typing_extensions import overridefrom pipelex.cogt.doc_gen.doc_gen_format import DocGenFormat, DocGenSourcefrom pipelex.cogt.doc_gen.doc_gen_worker_abstract import DocGenWorkerAbstractfrom pipelex.cogt.doc_gen.exceptions import DocGenRenderError+from pipelex.cogt.doc_gen.layout_display import display_scalar, is_numeric_columnfrom pipelex.cogt.doc_gen.layout_tree import (FieldGridBlock,ImageBlock,LayoutBlock,LayoutDocument,- LayoutScalar,MarkdownBlock,ParagraphsBlock,SectionBlock,@@ -373,7 +375,7 @@ class _LayoutWriter:for index, column in enumerate(block.columns)]col_widths = fit_column_widths(extents=extents, available_width=FRAME_WIDTH)- numeric_columns = [_is_numeric_column(values=[row.get(column.key) for row in block.rows]) for column in block.columns]+ numeric_columns = [is_numeric_column(values=[row.get(column.key) for row in block.rows]) for column in block.columns]styles = self._stylesheader_row: list[TableCell] = [text_cell(text=column.label, width=col_widths[index], style=styles.cell_header_right if numeric_columns[index] else styles.cell_header)@@ -405,48 +407,3 @@ class _LayoutWriter:if block.caption:members.append(Paragraph(escape_text(text=block.caption), self._styles.caption))return self._tagged(flowable=KeepTogether(members), origin=f"image {number} of the document")---def _is_numeric_column(*, values: list[LayoutScalar]) -> bool:- """Whether a column holds numbers only, blanks aside, and at least one: such a column is aligned right."""- present = [value for value in values if value is not None]- return bool(present) and all(isinstance(value, (int, float)) and not isinstance(value, bool) for value in present)---def _utc_offset_suffix(*, value: datetime.datetime | datetime.time) -> str:- """The UTC offset a value states, as ' UTC' or ' +02:00', or nothing for a value that states none."""- offset = value.utcoffset()- if offset is None:- return ""- total_minutes = int(offset.total_seconds()) // 60- if total_minutes == 0:- return " UTC"- sign = "+" if total_minutes > 0 else "-"- hours, minutes = divmod(abs(total_minutes), 60)- return f" {sign}{hours:02d}:{minutes:02d}"---def display_scalar(*, value: LayoutScalar) -> str:- """A scalar as the document prints it: blank for nothing, Yes or No, numbers plainly, dates and times in ISO order.-- A time of day prints to the minute, with the UTC offset the value states, if any.- """- match value:- case None:- return ""- case bool():- return "Yes" if value else "No"- case int():- return str(value)- case float():- if value.is_integer():- return str(int(value))- return format(value, ".15g")- case datetime.datetime():- return value.strftime("%Y-%m-%d %H:%M") + _utc_offset_suffix(value=value)- case datetime.date():- return value.isoformat()- case datetime.time():- return value.strftime("%H:%M") + _utc_offset_suffix(value=value)- case str():- return valuediff --git a/tests/unit/pipelex/cogt/doc_gen/test_contract_import_light.py b/tests/unit/pipelex/cogt/doc_gen/test_contract_import_light.pynew file mode 100644index 000000000..8501f827f--- /dev/null+++ b/tests/unit/pipelex/cogt/doc_gen/test_contract_import_light.py@@ -0,0 +1,46 @@+import subprocess # ruff: ignore[suspicious-subprocess-import]+import sys+import textwrap++# Imports every module of the document engine contract in a fresh interpreter whose import system refuses ReportLab,+# so a module-level import of ReportLab anywhere on the contract's import path fails loudly, naming the importer. A+# plugin's engine imports the contract, and a contract that loaded the built-in engine's library would make it copy+# what it needs instead.+_CONTRACT_IMPORT_SCRIPT = textwrap.dedent(+ """+ import importlib+ import importlib.abc+ import pkgutil+ import sys++ class _ReportlabBlocker(importlib.abc.MetaPathFinder):+ def find_spec(self, fullname, path, target=None):+ if fullname == "reportlab" or fullname.startswith("reportlab."):+ raise ImportError(f"the import-light guard blocked '{fullname}'")+ return None++ sys.meta_path.insert(0, _ReportlabBlocker())++ import pipelex.cogt.doc_gen++ names = sorted(module.name for module in pkgutil.iter_modules(pipelex.cogt.doc_gen.__path__, "pipelex.cogt.doc_gen."))+ assert "pipelex.cogt.doc_gen.layout_display" in names+ assert "pipelex.cogt.doc_gen.template_environment" in names+ for name in names:+ importlib.import_module(name)+ assert not [name for name in sys.modules if name == "reportlab" or name.startswith("reportlab.")]+ print(f"import-light OK: {len(names)} modules")+ """+)+++class TestContractImportLight:+ def test_importing_the_contract_imports_no_reportlab(self) -> None:+ result = subprocess.run( # ruff: ignore[subprocess-without-shell-equals-true]+ [sys.executable, "-c", _CONTRACT_IMPORT_SCRIPT],+ capture_output=True,+ text=True,+ check=False,+ )+ assert result.returncode == 0, f"import-light guard failed:\nstdout={result.stdout}\nstderr={result.stderr}"+ assert "import-light OK" in result.stdoutdiff --git a/tests/unit/pipelex/cogt/doc_gen/test_data.py b/tests/unit/pipelex/cogt/doc_gen/test_data.pynew file mode 100644index 000000000..270d558f0--- /dev/null+++ b/tests/unit/pipelex/cogt/doc_gen/test_data.py@@ -0,0 +1,36 @@+import datetime+from typing import ClassVar++from pipelex.cogt.doc_gen.layout_tree import LayoutScalar+++class LayoutDisplayTestData:+ """Each scalar case: (value, its text). Each numeric column case: (topic, values, whether the column is numeric)."""++ SCALAR_CASES: ClassVar[list[tuple[LayoutScalar, str]]] = [+ (None, ""),+ (True, "Yes"),+ (False, "No"),+ (42, "42"),+ (2.0, "2"),+ (2.5, "2.5"),+ (0.1 + 0.2, "0.3"),+ (datetime.date(2026, 9, 29), "2026-09-29"),+ (datetime.datetime(2026, 9, 29, 14, 5, 59), "2026-09-29 14:05"),+ (datetime.time(9, 7, 30), "09:07"),+ (datetime.datetime(2026, 9, 29, 14, 5, tzinfo=datetime.UTC), "2026-09-29 14:05 UTC"),+ (datetime.datetime(2026, 9, 29, 14, 5, tzinfo=datetime.timezone(datetime.timedelta(hours=2))), "2026-09-29 14:05 +02:00"),+ (datetime.time(9, 7, tzinfo=datetime.timezone(datetime.timedelta(hours=-5, minutes=-30))), "09:07 -05:30"),+ ("As written", "As written"),+ ]++ NUMERIC_COLUMN_CASES: ClassVar[list[tuple[str, list[LayoutScalar], bool]]] = [+ ("integers and floats", [1, 2.5, 3], True),+ ("numbers with blanks", [None, 4, None], True),+ ("no rows", [], False),+ ("blanks only", [None, None], False),+ ("booleans", [True, False], False),+ ("a boolean among numbers", [1, True], False),+ ("a text among numbers", [1, "2"], False),+ ("dates", [datetime.date(2026, 9, 29)], False),+ ]diff --git a/tests/unit/pipelex/cogt/doc_gen/test_layout_display.py b/tests/unit/pipelex/cogt/doc_gen/test_layout_display.pynew file mode 100644index 000000000..bd5424513--- /dev/null+++ b/tests/unit/pipelex/cogt/doc_gen/test_layout_display.py@@ -0,0 +1,35 @@+import pytest++from pipelex.cogt.doc_gen.layout_display import display_scalar, is_numeric_column, markdown_as_html+from pipelex.cogt.doc_gen.layout_tree import LayoutScalar+from tests.unit.pipelex.cogt.doc_gen.test_data import LayoutDisplayTestData+++class TestLayoutDisplay:+ @pytest.mark.parametrize(("value", "expected"), LayoutDisplayTestData.SCALAR_CASES)+ def test_a_scalar_prints_plainly(self, value: LayoutScalar, expected: str) -> None:+ assert display_scalar(value=value) == expected++ @pytest.mark.parametrize(("topic", "values", "expected"), LayoutDisplayTestData.NUMERIC_COLUMN_CASES)+ def test_a_column_is_numeric_when_it_holds_numbers_only(self, topic: str, values: list[LayoutScalar], expected: bool) -> None:+ assert is_numeric_column(values=values) is expected, topic++ def test_raw_html_in_markdown_comes_out_escaped(self) -> None:+ html = markdown_as_html(markdown='Before <script>alert("x")</script> after.\n\n<div onclick="steal()">block</div>')+ assert "<script>" not in html+ assert "<div" not in html+ assert "<script>" in html+ assert "<div onclick=" in html++ def test_a_table_and_a_strikethrough_are_formatted(self) -> None:+ html = markdown_as_html(markdown="| Item | Qty |\n| - | - |\n| Tea | 2 |\n\n~~withdrawn~~")+ assert "<table>" in html+ assert "<th>Item</th>" in html+ assert "<td>Tea</td>" in html+ assert "<s>withdrawn</s>" in html++ def test_only_a_url_with_a_scheme_becomes_a_link(self) -> None:+ html = markdown_as_html(markdown="See https://pipelex.com, README.md, www.example.com and [email protected].")+ assert '<a href="https://pipelex.com">https://pipelex.com</a>' in html+ assert html.count("<a ") == 1+ assert "README.md" in htmldiff --git a/tests/unit/pipelex/cogt/doc_gen/test_template_environment.py b/tests/unit/pipelex/cogt/doc_gen/test_template_environment.pynew file mode 100644index 000000000..0ec4c9d75--- /dev/null+++ b/tests/unit/pipelex/cogt/doc_gen/test_template_environment.py@@ -0,0 +1,44 @@+import pytest+from jinja2.exceptions import SecurityError, UndefinedError+from jinja2.filters import FILTERS as JINJA_FILTERS++from pipelex.cogt.doc_gen.template_environment import make_plain_data_template_environment+from pipelex.tools.jinja2.jinja2_render_budget import DEFAULT_RENDER_BUDGET_UNITS, RenderBudgetExceededError+++class TestPlainDataTemplateEnvironment:+ def test_a_template_renders_synchronously(self) -> None:+ environment = make_plain_data_template_environment()+ assert environment.is_async is False+ rendered = environment.from_string("{{ customer.name|upper }} owes {{ '%.2f'|format(total) }}").render(customer={"name": "Ada"}, total=12.5)+ assert rendered == "ADA owes 12.50"++ def test_a_missing_value_fails_the_render(self) -> None:+ template = make_plain_data_template_environment().from_string("Dear {{ customer.name }}")+ with pytest.raises(UndefinedError):+ template.render(customer={})++ @pytest.mark.parametrize(+ ("source", "variables"),+ [+ ("{{ total.__class__ }}", {"total": 3}),+ ("{{ record._secret }}", {"record": {"_secret": "x"}}),+ ("{{ action() }}", {"action": print}),+ ],+ )+ def test_the_sandbox_refuses_what_a_template_may_not_reach(self, source: str, variables: dict[str, object]) -> None:+ template = make_plain_data_template_environment().from_string(source)+ with pytest.raises(SecurityError):+ template.render(**variables)++ def test_a_render_spends_from_a_budget(self) -> None:+ # More iterations than the budget affords at 32 units each, but few enough to end within a second without one.+ template = make_plain_data_template_environment().from_string("{% for i in range(64) %}{% for j in range(inner) %}{% endfor %}{% endfor %}")+ with pytest.raises(RenderBudgetExceededError):+ template.render(inner=DEFAULT_RENDER_BUDGET_UNITS // 64 // 32)++ def test_the_filters_are_jinjas_own(self) -> None:+ # The names with a leading underscore are the render budget's own, which its rewrite of a template calls.+ filters = make_plain_data_template_environment().filters+ named_filters = {name: function for name, function in filters.items() if not name.startswith("_")}+ assert named_filters == JINJA_FILTERSdiff --git a/tests/unit/pipelex/cogt/test_cogt_dependency_boundaries.py b/tests/unit/pipelex/cogt/test_cogt_dependency_boundaries.pyindex 8c4faae34..28624fd46 100644--- a/tests/unit/pipelex/cogt/test_cogt_dependency_boundaries.py+++ b/tests/unit/pipelex/cogt/test_cogt_dependency_boundaries.py@@ -67,6 +67,7 @@ EXPECTED_THIRD_PARTY_ROOTS: frozenset[str] = frozenset("datamodel_code_generator","httpx","instructor",+ "jinja2","opentelemetry","polyfactory","pydantic",diff --git a/tests/unit/pipelex/providers/reportlab/test_data.py b/tests/unit/pipelex/providers/reportlab/test_data.pyindex a4290fc62..024bfda88 100644--- a/tests/unit/pipelex/providers/reportlab/test_data.py+++ b/tests/unit/pipelex/providers/reportlab/test_data.py@@ -1,4 +1,3 @@-import datetimefrom typing import ClassVarfrom pipelex.cogt.doc_gen.layout_tree import (@@ -7,7 +6,6 @@ from pipelex.cogt.doc_gen.layout_tree import (LayoutBlock,LayoutColumn,LayoutField,- LayoutScalar,ParagraphsBlock,SectionBlock,TableBlock,@@ -64,23 +62,6 @@ class ReportlabRendererTestData:("Vietnamese", "Tiếng Việt có dấu"),]- SCALAR_CASES: ClassVar[list[tuple[LayoutScalar, str]]] = [- (None, ""),- (True, "Yes"),- (False, "No"),- (42, "42"),- (2.0, "2"),- (2.5, "2.5"),- (0.1 + 0.2, "0.3"),- (datetime.date(2026, 9, 29), "2026-09-29"),- (datetime.datetime(2026, 9, 29, 14, 5, 59), "2026-09-29 14:05"),- (datetime.time(9, 7, 30), "09:07"),- (datetime.datetime(2026, 9, 29, 14, 5, tzinfo=datetime.UTC), "2026-09-29 14:05 UTC"),- (datetime.datetime(2026, 9, 29, 14, 5, tzinfo=datetime.timezone(datetime.timedelta(hours=2))), "2026-09-29 14:05 +02:00"),- (datetime.time(9, 7, tzinfo=datetime.timezone(datetime.timedelta(hours=-5, minutes=-30))), "09:07 -05:30"),- ("As written", "As written"),- ]-class MarkdownFlowablesTestData:"""Each link case: (href, whether it becomes a link)."""diff --git a/tests/unit/pipelex/providers/reportlab/test_reportlab_pdf_renderer.py b/tests/unit/pipelex/providers/reportlab/test_reportlab_pdf_renderer.pyindex ffa48fc9c..eac21f1af 100644--- a/tests/unit/pipelex/providers/reportlab/test_reportlab_pdf_renderer.py+++ b/tests/unit/pipelex/providers/reportlab/test_reportlab_pdf_renderer.py@@ -19,14 +19,12 @@ from pipelex.cogt.doc_gen.layout_tree import (LayoutColumn,LayoutDocument,LayoutField,- LayoutScalar,MarkdownBlock,ParagraphsBlock,SectionBlock,TableBlock,)from pipelex.cogt.doc_gen.render_job import RenderJob-from pipelex.providers.reportlab.reportlab_pdf_renderer import display_scalarfrom tests.unit.pipelex.providers.reportlab.reportlab_test_helpers import (TEST_FILENAME,TEST_TITLE,@@ -163,10 +161,6 @@ class TestReportlabPdfRenderer:)assert exc_info.value.error_domain == ErrorDomain.INPUT- @pytest.mark.parametrize(("value", "expected"), ReportlabRendererTestData.SCALAR_CASES)- def test_a_scalar_prints_plainly(self, value: LayoutScalar, expected: str) -> None:- assert display_scalar(value=value) == expected-def test_table_cells_print_their_scalars(self) -> None:table = TableBlock(title="Mixed",