Coverage for tdom/processor.py: 96%
596 statements
« prev ^ index » next coverage.py v7.16.0, created at 2026-10-31 18:53 +0000
« prev ^ index » next coverage.py v7.16.0, created at 2026-10-31 18:53 +0000
1import typing as t
2from collections.abc import Callable, Iterable, Mapping, Sequence
3from contextvars import ContextVar
4from dataclasses import dataclass, field
5from functools import lru_cache
6from string.templatelib import Interpolation, Template
8from markupsafe import Markup
10from .callables import CallableInfo, get_callable_info
11from .escaping import (
12 escape_html_comment as default_escape_html_comment,
13)
14from .escaping import (
15 escape_html_script as default_escape_html_script,
16)
17from .escaping import (
18 escape_html_style as default_escape_html_style,
19)
20from .escaping import (
21 escape_html_text as default_escape_html_text,
22)
23from .exc import TemplatingError
24from .format import format_interpolation as base_format_interpolation
25from .format import format_template
26from .htmlspec import (
27 CDATA_CONTENT_ELEMENTS,
28 DEFAULT_NORMAL_TEXT_ELEMENT,
29 RCDATA_CONTENT_ELEMENTS,
30 SVG_ATTR_FIX,
31 SVG_TAG_FIX,
32 VOID_ELEMENTS,
33)
34from .parser import TemplateParser
35from .parser_utils import HTMLAttribute
36from .protocols import HasHTMLDunder
37from .scope import ScopedTemplate
38from .source import SourceReader
39from .template_utils import PartPosition, TemplateRef, TemplateSpan
40from .tnodes import (
41 TagSourceInfo,
42 TAttribute,
43 TComment,
44 TComponent,
45 TDocumentType,
46 TElement,
47 TFragment,
48 TInterpolatedAttribute,
49 TLiteralAttribute,
50 TNode,
51 TSpreadAttribute,
52 TTemplatedAttribute,
53 TText,
54 TTree,
55)
56from .utils import CachableTemplate, LastUpdatedOrderedDict
58type Attribute = tuple[str, object]
59type AttributesDict = dict[str, object]
62@dataclass(frozen=True)
63class TemplateErrorState:
64 """
65 Accumulated and finalized template error state.
66 """
68 template: Template
69 " The nearest template related to the exception. "
70 ttree: TTree
71 " TTree parsed from nearest template. "
72 tnode: TNode
73 " Nearest tnode. "
74 parent_tnode: TFragment | TElement | TComponent | None
75 " Nearest parent tnode. "
76 tattr: TAttribute | None = None
77 " Nearest template attribute, if applicable. "
78 i_index: int | None = None
79 " Nearest interpolation index, if applicable. "
82@dataclass()
83class OpenTemplateErrorState:
84 """
85 Scratchpad to record state during egress through try/except blocks from source of exception.
86 """
88 tnode: TNode | None = None
89 " Nearest tnode. "
90 parent_tnode: TFragment | TElement | TComponent | None = None
91 " Nearest parent tnode. "
92 tattr: TAttribute | None = None
93 " Nearest template attribute, if applicable. "
94 i_index: int | None = None
95 " Nearest interpolation index, if applicable. "
97 def close(self, template: Template, ttree: TTree) -> TemplateErrorState:
98 """
99 Finalize this "scratchpad" into a frozen version to store.
100 """
101 assert self.tnode is not None, "Every template error should have a tnode. "
102 return TemplateErrorState(
103 template=template,
104 ttree=ttree,
105 tnode=self.tnode,
106 parent_tnode=self.parent_tnode,
107 tattr=self.tattr,
108 i_index=self.i_index,
109 )
112class ProcessingError(TemplatingError):
113 """General error when processing a template."""
116class AttributeProcessingError(ProcessingError):
117 """Error while processing an element or component attribute."""
120class TextProcessingError(ProcessingError):
121 """Error while processing an element or component attribute."""
124class ComponentProcessingError(ProcessingError):
125 """Error while processing an element or component attribute."""
128@dataclass
129class ProcessingErrorHelper:
130 open_error_state: OpenTemplateErrorState = field(
131 default_factory=OpenTemplateErrorState
132 )
133 " Currently tracked template error state. "
135 def stash_nearest_tnode(self, tnode: TNode) -> None:
136 if self.open_error_state.tnode is None:
137 self.open_error_state.tnode = tnode
139 def stash_nearest_parent_tnode(self, parent_tnode: TNode) -> None:
140 if self.open_error_state.parent_tnode is None and isinstance(
141 parent_tnode, (TFragment, TElement, TComponent)
142 ):
143 self.open_error_state.parent_tnode = parent_tnode
145 def stash_nearest_tattr(self, tattr: TAttribute) -> None:
146 if self.open_error_state.tattr is None:
147 self.open_error_state.tattr = tattr
149 def stash_nearest_i_index(self, i_index: int) -> None:
150 if self.open_error_state.i_index is None:
151 self.open_error_state.i_index = i_index
153 def pop_error_notes(
154 self,
155 template: Template,
156 ttree: TTree,
157 ) -> tuple[str, ...]:
158 """
159 Add the accumulated notes from unwinding nested processing.
160 """
161 error_state = self._pop_error_state(template, ttree)
162 return tuple(self._make_template_error_notes(error_state))
164 def _pop_error_state(
165 self,
166 template: Template,
167 ttree: TTree,
168 ) -> TemplateErrorState:
169 """Close and return currently tracked template error state."""
170 closed_state = self.open_error_state.close(template, ttree)
171 # @NOTE: We nuke the prior clump of state with a new object because
172 # its less error prone than trying to "reset" it manually.
173 self.open_error_state = OpenTemplateErrorState()
174 return closed_state
176 def _make_attribute_blurb(
177 self, reader: SourceReader, tattr: TAttribute | None
178 ) -> str:
179 """Make a short blurb about which attribute the error occurred in."""
180 if isinstance(tattr, TSpreadAttribute):
181 value_ref = TemplateRef(strings=("", ""), i_start=tattr.i_index)
182 attr_blurb = f"in spread attribute {reader.ref_to_repr(value_ref)}"
183 elif isinstance(tattr, TLiteralAttribute):
184 attr_blurb = f"in literal attribute {tattr.name}"
185 if tattr.value is not None:
186 attr_blurb += f"={tattr.value}"
187 elif isinstance(tattr, TTemplatedAttribute):
188 attr_blurb = f"in templated attribute {tattr.name}={reader.ref_to_repr(tattr.value_ref)}"
189 elif isinstance(tattr, TInterpolatedAttribute):
190 value_ref = TemplateRef(strings=("", ""), i_start=tattr.value_i_index)
191 attr_blurb = f"in interpolated attribute {tattr.name}={reader.ref_to_repr(value_ref)}"
192 else:
193 assert tattr is None, "Unrecognized tattribute type."
194 attr_blurb = ""
195 return attr_blurb
197 def _make_pos_msg(
198 self,
199 reader: SourceReader,
200 source_pos: PartPosition | None,
201 fallback_msg: str = "unknown location",
202 ) -> str:
203 if source_pos is None:
204 return fallback_msg
205 return reader.make_template_pos_msg(source_pos)
207 def _make_tcomment_repr(self, reader: SourceReader, tnode: TComment) -> str:
208 return f"<!--{reader.ref_to_repr(tnode.ref)}-->"
210 def _make_ttext_repr(self, reader: SourceReader, tnode: TText) -> str:
211 return reader.ref_to_repr(tnode.ref)
213 def _make_interpolation_blurb(self, reader: SourceReader, i_index: int) -> str:
214 """Make a short blurb about which interpolation the error occurred in."""
215 i_ref = TemplateRef(strings=("", ""), i_start=i_index)
216 return f"in {reader.ref_to_repr(i_ref)}"
218 def _make_common_text_error_notes(
219 self,
220 reader: SourceReader,
221 tnode: TText | TComment,
222 i_index: int | None,
223 tnode_repr: str,
224 ) -> tuple[str, ...]:
225 pos_msg = self._make_pos_msg(reader, tnode.source_pos)
226 if i_index is not None and not tnode.ref.is_singleton:
227 i_blurb = self._make_interpolation_blurb(reader, i_index)
228 return (f"... {i_blurb} within {tnode_repr} at {pos_msg}",)
229 else:
230 return (f"... in {tnode_repr} at {pos_msg}",)
232 def _make_document_type_error_notes(
233 self,
234 reader: SourceReader,
235 tnode: TDocumentType,
236 ) -> tuple[str, ...]:
237 tnode_repr = f"<!DOCTYPE {tnode.text}>"
238 pos_msg = self._make_pos_msg(reader, tnode.source_pos)
239 return (f"... in {tnode_repr} at {pos_msg}",)
241 def _make_tag_error_notes(
242 self,
243 reader: SourceReader,
244 sinfo_table: dict[PartPosition, TagSourceInfo],
245 tnode: TElement | TComponent,
246 tattr: TAttribute | None,
247 ) -> tuple[str, ...]:
248 attr_blurb = self._make_attribute_blurb(reader, tattr)
249 pos_msg = self._make_pos_msg(reader, tnode.source_pos)
250 sinfo = sinfo_table.get(tnode.source_pos, None) if tnode.source_pos else None
251 if sinfo:
252 tnode_repr = reader.span_to_repr(sinfo.starttag_span)
253 else:
254 if isinstance(tnode, TElement):
255 tnode_repr = self._fallback_element_repr(tnode)
256 else:
257 tnode_repr = self._fallback_component_repr(reader, tnode)
258 if attr_blurb:
259 return (f"... {attr_blurb} for {tnode_repr} at {pos_msg}",)
260 else:
261 return (f"... in {tnode_repr} at {pos_msg}",)
263 def _fallback_element_repr(self, tnode: TElement) -> str:
264 return f"<{tnode.tag} ...>"
266 def _fallback_component_repr(
267 self,
268 reader: SourceReader,
269 tnode: TComponent,
270 ) -> str:
271 return reader.ref_to_repr(
272 TemplateRef(strings=("<", "...>"), i_start=tnode.start_i_index)
273 )
275 def _make_template_error_notes(self, error_state: TemplateErrorState) -> list[str]:
276 """
277 Add notes accumulated either at the initial tnode of the error or
278 a subsequent tnode in another template passed through during unwinding
279 from nested processing.
280 """
281 reader = SourceReader(error_state.template)
282 error_notes = []
283 sinfo_table = error_state.ttree.unpack_sinfo_table()
284 match error_state.tnode:
285 case TElement() | TComponent():
286 error_notes.extend(
287 self._make_tag_error_notes(
288 reader, sinfo_table, error_state.tnode, error_state.tattr
289 ),
290 )
291 case TText():
292 error_notes.extend(
293 self._make_common_text_error_notes(
294 reader,
295 error_state.tnode,
296 error_state.i_index,
297 tnode_repr=self._make_ttext_repr(reader, error_state.tnode),
298 )
299 )
300 if isinstance(error_state.parent_tnode, (TElement, TComponent)):
301 error_notes.extend(
302 self._make_tag_error_notes(
303 reader, sinfo_table, error_state.parent_tnode, tattr=None
304 )
305 )
306 case TComment():
307 error_notes.extend(
308 self._make_common_text_error_notes(
309 reader,
310 error_state.tnode,
311 error_state.i_index,
312 tnode_repr=self._make_tcomment_repr(reader, error_state.tnode),
313 ),
314 )
315 case TDocumentType():
316 error_notes.extend(
317 self._make_document_type_error_notes(reader, error_state.tnode),
318 )
319 case TFragment():
320 pass
321 case _:
322 assert error_state.tnode is not None
323 return error_notes
326ProcessingErrorCtx: ContextVar[ProcessingErrorHelper | None] = ContextVar(
327 "ProcessingErrorCtx", default=None
328)
329""" Context variable to manage template error state after exception occurs. """
332# --------------------------------------------------------------------------
333# Custom formatting for the processor
334# --------------------------------------------------------------------------
337def _format_safe(value: object, format_spec: str) -> str:
338 """Use Markup() to mark a value as safe HTML."""
339 assert format_spec == "safe"
340 return Markup(value)
343def _format_unsafe(value: object, format_spec: str) -> str:
344 """Convert a value to a plain string, forcing it to be treated as unsafe."""
345 assert format_spec == "unsafe"
346 return str(value)
349def _format_callback(value: Callable[..., object], format_spec: str) -> object:
350 """Execute a callback and return the value."""
351 assert format_spec == "callback"
352 return value()
355CUSTOM_FORMATTERS = (
356 ("safe", _format_safe),
357 ("unsafe", _format_unsafe),
358 ("callback", _format_callback),
359)
362def format_interpolation(interpolation: Interpolation) -> object:
363 return base_format_interpolation(
364 interpolation,
365 formatters=CUSTOM_FORMATTERS,
366 )
369# --------------------------------------------------------------------------
370# Placeholder Substitution
371# --------------------------------------------------------------------------
374def _expand_aria_attr(value: object) -> Iterable[HTMLAttribute]:
375 """Produce aria-* attributes based on the interpolated value for "aria"."""
376 if value is None:
377 return
378 elif isinstance(value, Mapping):
379 for sub_k, sub_v in value.items():
380 if sub_v is True:
381 yield f"aria-{sub_k}", "true"
382 elif sub_v is False:
383 yield f"aria-{sub_k}", "false"
384 elif sub_v is None:
385 yield f"aria-{sub_k}", None
386 else:
387 yield f"aria-{sub_k}", str(sub_v)
388 else:
389 raise AttributeProcessingError(
390 f"Cannot use {type(value).__name__} as value for aria attribute"
391 )
394def _expand_data_attr(value: object) -> Iterable[Attribute]:
395 """Produce data-* attributes based on the interpolated value for "data"."""
396 if value is None:
397 return
398 elif isinstance(value, Mapping):
399 for sub_k, sub_v in value.items():
400 if sub_v is True or sub_v is False or sub_v is None:
401 yield f"data-{sub_k}", sub_v
402 else:
403 yield f"data-{sub_k}", str(sub_v)
404 else:
405 raise AttributeProcessingError(
406 f"Cannot use {type(value).__name__} as value for data attribute"
407 )
410def _substitute_spread_attrs(value: object) -> Iterable[Attribute]:
411 """
412 Substitute a spread attribute based on the interpolated value.
414 A spread attribute is one where the key is a placeholder, indicating that
415 the entire attribute set should be replaced by the interpolated value.
416 The value must be a Mapping.
417 """
418 if value is None:
419 return
420 elif isinstance(value, Mapping):
421 yield from value.items()
422 else:
423 raise AttributeProcessingError(
424 f"Cannot use {type(value).__name__} as value for spread attributes"
425 )
428ATTR_EXPANDERS = {
429 "data": _expand_data_attr,
430 "aria": _expand_aria_attr,
431}
434def parse_style_attribute_value(style_str: str) -> list[tuple[str, str | None]]:
435 """
436 Parse the style declarations out of a style attribute string.
437 """
438 props = [p.strip() for p in style_str.split(";")]
439 styles: list[tuple[str, str | None]] = []
440 for prop in props:
441 if prop:
442 prop_parts = [p.strip() for p in prop.split(":") if p.strip()]
443 if len(prop_parts) != 2:
444 raise AttributeProcessingError(
445 f"Invalid number of parts for style property {prop} in {style_str}"
446 )
447 styles.append((prop_parts[0], prop_parts[1]))
448 return styles
451def make_style_accumulator(old_value: object) -> StyleAccumulator:
452 """
453 Initialize the style accumulator.
454 """
455 match old_value:
456 case str():
457 styles = {
458 name: value for name, value in parse_style_attribute_value(old_value)
459 }
460 case True: # A bare attribute will just default to {}.
461 styles = {}
462 case _:
463 raise AttributeProcessingError(f"Unexpected style value: {old_value}")
464 return StyleAccumulator(styles=styles)
467@dataclass
468class StyleAccumulator:
469 styles: dict[str, str | None]
471 def merge_value(self, value: object) -> None:
472 """
473 Merge in an interpolated style value.
474 """
475 match value:
476 case str():
477 self.styles.update(
478 {name: value for name, value in parse_style_attribute_value(value)}
479 )
480 case Mapping():
481 self.styles.update(
482 {
483 str(pn): str(pv) if pv is not None else None
484 for pn, pv in value.items()
485 }
486 )
487 case None:
488 pass
489 case _:
490 raise AttributeProcessingError(
491 f"Unknown interpolated style value {value}, use '' to omit."
492 )
494 def to_value(self) -> str | None:
495 """
496 Serialize the special style value back into a string.
498 @NOTE: If the result would be `''` then use `None` to omit the attribute.
499 """
500 style_value = "; ".join(
501 [f"{pn}: {pv}" for pn, pv in self.styles.items() if pv is not None]
502 )
503 return style_value or None
506def make_class_accumulator(old_value: object) -> ClassAccumulator:
507 """
508 Initialize the class accumulator.
509 """
510 match old_value:
511 case str():
512 toggled_classes = dict.fromkeys(old_value.split(), True)
513 case True:
514 toggled_classes = {}
515 case _:
516 raise AttributeProcessingError(f"Unexpected class value {old_value}")
517 return ClassAccumulator(toggled_classes=toggled_classes)
520@dataclass
521class ClassAccumulator:
522 toggled_classes: dict[str, bool]
524 def merge_value(self, value: object) -> None:
525 """
526 Merge in an interpolated class value.
527 """
528 if isinstance(value, Mapping):
529 self.toggled_classes.update(
530 {str(cn): bool(toggle) for cn, toggle in value.items()}
531 )
532 else:
533 if not isinstance(value, str) and isinstance(value, Sequence):
534 items = value[:]
535 else:
536 items = (value,)
537 for item in items:
538 match item:
539 case str():
540 self.toggled_classes.update(dict.fromkeys(item.split(), True))
541 case None:
542 pass
543 case _:
544 if item == value:
545 raise AttributeProcessingError(
546 f"Unknown interpolated class value: {value}"
547 )
548 else:
549 raise AttributeProcessingError(
550 f"Unknown interpolated class item in {value}: {item}"
551 )
553 def to_value(self) -> str | None:
554 """
555 Serialize the special class value back into a string.
557 @NOTE: If the result would be `''` then use `None` to omit the attribute.
558 """
559 class_value = " ".join(
560 [cn for cn, toggle in self.toggled_classes.items() if toggle]
561 )
562 return class_value or None
565ATTR_ACCUMULATOR_MAKERS = {
566 "class": make_class_accumulator,
567 "style": make_style_accumulator,
568}
571type AttributeValueAccumulator = StyleAccumulator | ClassAccumulator
574def _resolve_t_attrs(
575 attrs: Sequence[TAttribute], interpolations: tuple[Interpolation, ...]
576) -> AttributesDict:
577 """
578 Replace placeholder values in attributes with their interpolated values.
580 The values returned are not yet processed for HTML output; that is handled
581 in a later step.
583 @NOTE: We "touch" the key when accumulating values so that we can predict
584 what order that attribute will be ordered. We skip this step when setting
585 the final value so that the order is not disturbed.
586 """
587 new_attrs: AttributesDict = LastUpdatedOrderedDict()
588 attr_accs: dict[str, AttributeValueAccumulator] = {}
589 for attr in attrs:
590 try:
591 match attr:
592 case TLiteralAttribute(name=name, value=value):
593 attr_value = True if value is None else value
594 if name in ATTR_ACCUMULATOR_MAKERS and name in new_attrs:
595 if name not in attr_accs:
596 attr_accs[name] = ATTR_ACCUMULATOR_MAKERS[name](
597 new_attrs[name]
598 )
599 new_attrs[name] = attr_accs[name].merge_value(attr_value)
600 else:
601 new_attrs[name] = attr_value
602 case TInterpolatedAttribute(name=name, value_i_index=i_index):
603 interpolation = interpolations[i_index]
604 attr_value = format_interpolation(interpolation)
605 if name in ATTR_ACCUMULATOR_MAKERS:
606 if name not in attr_accs:
607 attr_accs[name] = ATTR_ACCUMULATOR_MAKERS[name](
608 new_attrs.get(name, True)
609 )
610 new_attrs[name] = attr_accs[name].merge_value(attr_value)
611 elif expander := ATTR_EXPANDERS.get(name):
612 for sub_k, sub_v in expander(attr_value):
613 new_attrs[sub_k] = sub_v
614 else:
615 new_attrs[name] = attr_value
616 case TTemplatedAttribute(name=name, value_ref=ref):
617 attr_t = ref.bind(interpolations)
618 attr_value = format_template(attr_t)
619 if name in ATTR_ACCUMULATOR_MAKERS:
620 if name not in attr_accs:
621 attr_accs[name] = ATTR_ACCUMULATOR_MAKERS[name](
622 new_attrs.get(name, True)
623 )
624 new_attrs[name] = attr_accs[name].merge_value(attr_value)
625 elif expander := ATTR_EXPANDERS.get(name):
626 raise AttributeProcessingError(
627 f"{name} attributes cannot be templated"
628 )
629 else:
630 new_attrs[name] = attr_value
631 case TSpreadAttribute(i_index=i_index):
632 interpolation = interpolations[i_index]
633 spread_value = format_interpolation(interpolation)
634 for sub_k, sub_v in _substitute_spread_attrs(spread_value):
635 if sub_k in ATTR_ACCUMULATOR_MAKERS:
636 if sub_k not in attr_accs:
637 attr_accs[sub_k] = ATTR_ACCUMULATOR_MAKERS[sub_k](
638 new_attrs.get(sub_k, True)
639 )
640 new_attrs[sub_k] = attr_accs[sub_k].merge_value(sub_v)
641 elif expander := ATTR_EXPANDERS.get(sub_k):
642 for exp_k, exp_v in expander(sub_v):
643 new_attrs[exp_k] = exp_v
644 else:
645 new_attrs[sub_k] = sub_v
646 case _:
647 # @NOTE: This would be an internal error so we use a native
648 # exception.
649 raise TypeError(f"Unknown TAttribute type: {type(attr).__name__}")
650 except Exception:
651 helper = ProcessingErrorCtx.get()
652 assert helper is not None, "Helper instance must be set in ctx."
653 helper.stash_nearest_tattr(attr)
654 raise
655 for acc_name, acc in attr_accs.items():
656 # Skip "touching" the key here so that the order remains intact.
657 super(type(new_attrs), new_attrs).__setitem__(acc_name, acc.to_value())
658 return new_attrs
661def _resolve_html_attrs(attrs: AttributesDict) -> Iterable[HTMLAttribute]:
662 """Resolve attribute values for HTML output."""
663 for key, value in attrs.items():
664 match value:
665 case True:
666 yield key, None
667 case False | None:
668 pass
669 case _:
670 yield key, str(value)
673def _kebab_to_snake(name: str) -> str:
674 """Convert a kebab-case name to snake_case."""
675 return name.replace("-", "_").lower()
678def _prep_component_kwargs(
679 callable_info: CallableInfo,
680 attrs: AttributesDict,
681 children: Template,
682 provided_attrs: tuple[Attribute, ...] = (),
683 raise_on_requires_positional=True,
684 raise_on_missing=True,
685) -> AttributesDict:
686 """
687 Matchup kwargs from multiple sources to target the given callable.
689 `provided_attrs`:
690 These can be used by extensions that want to provide
691 attrs even if they are not specified in the component's `attrs` in
692 the template. If an attribute with the same name is provided in
693 `attrs` then it takes priority over entries in `provided_attrs`.
695 `raise_on_requires_positional`:
696 Optionally check and raise `ComponentProcessingError` if the
697 `callable_info` requires positional arguments which we cannot fulfill
698 normally. An exception might not be desired if the caller will finish
699 preparing the arguments after this call.
701 `raise_on_missing`:
702 Optionally check and raise `ComponentProcessingError` if we are not
703 able to fulfill all the arguments the `callable_info` expects since
704 in the common case this raise an exception whose cause might not be
705 clear. An exception might not be desired if the caller will finish
706 preparing the arguments after this call.
707 """
709 # We can't know what kwarg to put here...
710 if raise_on_requires_positional and callable_info.requires_positional:
711 raise ComponentProcessingError(
712 "Component callables cannot have required positional arguments."
713 )
715 kwargs: AttributesDict = {}
717 # Add all supported attributes
718 for attr_name, attr_value in attrs.items():
719 snake_name = _kebab_to_snake(attr_name)
720 if snake_name in callable_info.named_params:
721 if snake_name in kwargs:
722 raise ComponentProcessingError(
723 f"Ambiguous attribute {attr_name}: Two attributes resolved to the same named param {snake_name}."
724 )
725 kwargs[snake_name] = attr_value
726 elif callable_info.kwargs:
727 kwargs[attr_name] = attr_value # Retain original attribute name
728 else:
729 raise ComponentProcessingError(f"Unexpected attribute {attr_name}.")
731 if "children" in kwargs:
732 raise ComponentProcessingError(
733 "The children attribute is reserved for component children."
734 )
736 if "children" in callable_info.named_params:
737 kwargs["children"] = children
739 # Add in provided attrs if they haven't been set already and are wanted.
740 for pattr_name, pattr_value in provided_attrs:
741 if pattr_name not in kwargs and pattr_name in callable_info.named_params:
742 kwargs[pattr_name] = pattr_value
744 # Check to make sure we've fully satisfied the callable's requirements
745 if raise_on_missing:
746 missing = callable_info.required_named_params - kwargs.keys()
747 if missing:
748 raise ComponentProcessingError(
749 f"Missing required parameters for component: {', '.join(missing)}"
750 )
752 return kwargs
755def serialize_html_attrs(
756 html_attrs: Iterable[HTMLAttribute], escape: Callable = default_escape_html_text
757) -> str:
758 return "".join(
759 (f' {k}="{escape(v)}"' if v is not None else f" {k}" for k, v in html_attrs)
760 )
763def _fix_svg_attrs(html_attrs: Iterable[HTMLAttribute]) -> Iterable[HTMLAttribute]:
764 """
765 Fix the attr name-case of any html attributes on a tag within an SVG namespace.
766 """
767 for k, v in html_attrs:
768 yield SVG_ATTR_FIX.get(k, k), v
771@dataclass(frozen=True, slots=True)
772class ProcessContext:
773 parent_tag: str = DEFAULT_NORMAL_TEXT_ELEMENT
774 ns: str = "html"
776 def copy(
777 self,
778 ns: str | None = None,
779 parent_tag: str | None = None,
780 ) -> ProcessContext:
781 return ProcessContext(
782 parent_tag=parent_tag if parent_tag is not None else self.parent_tag,
783 ns=ns if ns is not None else self.ns,
784 )
787type FunctionComponent = Callable[..., Template]
788type FactoryComponent = Callable[..., ComponentObject]
789type ComponentCallable = FunctionComponent | FactoryComponent
790type ComponentObject = Callable[[], Template]
793type NormalTextInterpolationValue = (
794 bool # to support `showValue and value` idiom
795 | str
796 | HasHTMLDunder
797 | Template
798 | Iterable[NormalTextInterpolationValue]
799 | object
800 | None
801)
802# Applies to both escapable raw text and raw text.
803type RawTextExactInterpolationValue = (
804 bool # to support `showValue and value` idiom
805 | str
806 | HasHTMLDunder
807 | object
808 | None
809)
810# Applies to both escapable raw text and raw text.
811type RawTextInexactInterpolationValue = (
812 bool # to support `showValue and value` idiom
813 | str
814 | object
815 | None
816)
819class ITemplateParserProxy(t.Protocol):
820 def to_ttree(self, template: Template) -> TTree: ...
823@dataclass(frozen=True)
824class TemplateParserProxy(ITemplateParserProxy):
825 def to_ttree(self, template: Template) -> TTree:
826 return TemplateParser.parse(template)
829@dataclass(frozen=True)
830class CachedTemplateParserProxy(TemplateParserProxy):
831 @lru_cache(512) # noqa: B019
832 def _to_ttree(self, ct: CachableTemplate) -> TTree:
833 return super().to_ttree(ct.template)
835 def to_ttree(self, template: Template) -> TTree:
836 return self._to_ttree(CachableTemplate(template))
839class IComponentProcessor(t.Protocol):
840 """Isolate component processing to allow for replacement."""
842 def process(
843 self,
844 template: Template,
845 last_ctx: ProcessContext,
846 component_callable: t.Annotated[object, ComponentCallable],
847 attrs: tuple[TAttribute, ...],
848 component_template: Template,
849 provided_attrs: tuple[Attribute, ...] = (),
850 ) -> Template | ScopedTemplate:
851 """
852 Process available component details into a `Template` (or a
853 `ScopedTemplate`, for context-provider components).
854 """
855 ...
858class ComponentProcessor(IComponentProcessor):
859 """
860 Default component processor.
861 """
863 def process(
864 self,
865 template: Template,
866 last_ctx: ProcessContext,
867 component_callable: t.Annotated[object, ComponentCallable],
868 attrs: tuple[TAttribute, ...],
869 component_template: Template,
870 provided_attrs: tuple[Attribute, ...] = (),
871 ) -> Template | ScopedTemplate:
872 """
873 Process available component details into a Template.
875 Two general "styles" are supported:
877 1. FunctionComponent
879 Calling `component_callable` with the prepared kwargs should
880 return a `Template`.
882 The primary purpose of this style is to support
883 using a normal function as a component.
885 2. FactoryComponent
887 Calling `component_callable` with the prepared kwargs should
888 return another `Callable` which when called with no arguments should
889 return a `Template`.
891 The primary purpose of this style is to support
892 using a `dataclass` with `def __call__(self) -> Template` as a
893 component.
895 Either style may instead return a `ScopedTemplate` -- a
896 `Template` bundled with a `Scope` to activate around its render.
897 Context providers (`tdom.make_provider(cv)` /
898 `tdom.create_context(...)`) use this shape; user code generally
899 won't construct one directly.
900 """
901 if not callable(component_callable):
902 raise ComponentProcessingError(
903 f"Component callable must be callable: {type(component_callable)}"
904 )
905 tattrs = _resolve_t_attrs(attrs, template.interpolations)
906 kwargs = _prep_component_kwargs(
907 get_callable_info(component_callable),
908 tattrs,
909 children=component_template,
910 provided_attrs=provided_attrs,
911 raise_on_requires_positional=True,
912 raise_on_missing=True,
913 )
914 res1 = component_callable(**kwargs) # ty: ignore[call-top-callable]
915 if isinstance(res1, (Template, ScopedTemplate)):
916 return res1
917 elif callable(res1):
918 res2 = res1() # ty: ignore[call-top-callable]
919 if isinstance(res2, (Template, ScopedTemplate)):
920 return res2
921 else:
922 raise ComponentProcessingError(
923 f"Component object must return Template when called: {type(res2)}"
924 )
925 else:
926 raise ComponentProcessingError(
927 f"Component callable must return Template or Callable: {type(res1)}"
928 )
931class ITemplateProcessor(t.Protocol):
932 def process(self, root_template: Template, assume_ctx: ProcessContext) -> str: ...
935@dataclass(frozen=True)
936class TemplateProcessor(ITemplateProcessor):
937 parser_api: ITemplateParserProxy = field(default_factory=CachedTemplateParserProxy)
939 component_processor_api: IComponentProcessor = field(
940 default_factory=ComponentProcessor
941 )
943 escape_html_text: Callable = default_escape_html_text
945 escape_html_comment: Callable = default_escape_html_comment
947 escape_html_script: Callable = default_escape_html_script
949 escape_html_style: Callable = default_escape_html_style
951 slash_void: bool = False # Apply a xhtml-style slash to void html elements.
953 uppercase_doctype: bool = False # DOCTYPE vs doctype
955 def process(
956 self,
957 root_template: Template,
958 assume_ctx: ProcessContext,
959 ) -> str:
960 """
961 Process a TDOM compatible template into a string.
962 """
963 return self._process_template(root_template, assume_ctx)
965 def _process_template(self, template: Template, last_ctx: ProcessContext) -> str:
966 ttree = self.parser_api.to_ttree(template)
967 with ProcessingErrorCtx.set(ProcessingErrorHelper()):
968 try:
969 return self._process_tnode(template, last_ctx, ttree.root)
970 except Exception as e:
971 helper = ProcessingErrorCtx.get()
972 assert helper is not None, "Helper instance must be set in ctx."
973 for note in helper.pop_error_notes(template, ttree):
974 e.add_note(note)
975 raise
977 def _process_tnode(
978 self, template: Template, last_ctx: ProcessContext, tnode: TNode
979 ) -> str:
980 """
981 Process a tnode from a template's "t-tree" into a string.
982 """
983 try:
984 match tnode:
985 case TDocumentType(text):
986 return self._process_document_type(last_ctx, text)
987 case TComment(ref):
988 return self._process_comment(template, last_ctx, ref)
989 case TFragment(children):
990 return self._process_fragment(template, last_ctx, children)
991 case TComponent(start_i_index, end_i_index, children_span, attrs):
992 return self._process_component(
993 template,
994 last_ctx,
995 attrs,
996 start_i_index,
997 end_i_index,
998 children_span,
999 )
1000 case TElement(tag, attrs, children):
1001 return self._process_element(
1002 template, last_ctx, tag, attrs, children
1003 )
1004 case TText(ref):
1005 return self._process_texts(template, last_ctx, ref)
1006 case _:
1007 # @NOTE: This would be an internal error so we use a
1008 # native exception.
1009 raise TypeError(f"Unrecognized tnode: {tnode}")
1010 except Exception:
1011 helper = ProcessingErrorCtx.get()
1012 assert helper is not None, "Helper instance must be set in ctx."
1013 helper.stash_nearest_tnode(tnode)
1014 helper.stash_nearest_parent_tnode(tnode)
1015 raise
1017 def _process_document_type(
1018 self,
1019 last_ctx: ProcessContext,
1020 text: str,
1021 ) -> str:
1022 if last_ctx.ns != "html":
1023 # Nit
1024 raise ProcessingError(
1025 "Cannot process document type in subtree of a foreign element."
1026 )
1027 if self.uppercase_doctype:
1028 return f"<!DOCTYPE {text}>"
1029 else:
1030 return f"<!doctype {text}>"
1032 def _process_fragment(
1033 self,
1034 template: Template,
1035 last_ctx: ProcessContext,
1036 children: Iterable[TNode],
1037 ) -> str:
1038 return "".join(
1039 self._process_tnode(template, last_ctx, child) for child in children
1040 )
1042 def _process_texts(
1043 self,
1044 template: Template,
1045 last_ctx: ProcessContext,
1046 ref: TemplateRef,
1047 ) -> str:
1048 if last_ctx.parent_tag in CDATA_CONTENT_ELEMENTS:
1049 # Must be handled all at once.
1050 return self._process_raw_texts(template, last_ctx, ref)
1051 elif last_ctx.parent_tag in RCDATA_CONTENT_ELEMENTS:
1052 # We can handle all at once because there are no non-text children and everything must be string-ified.
1053 return self._process_escapable_raw_texts(template, last_ctx, ref)
1054 else:
1055 return self._process_normal_texts(template, last_ctx, ref)
1057 def _process_comment(
1058 self,
1059 template: Template,
1060 last_ctx: ProcessContext,
1061 content_ref: TemplateRef,
1062 ) -> str:
1063 """
1064 Process a comment into a string.
1065 """
1066 content_str = resolve_text_without_recursion(template, "<!--", content_ref)
1067 escaped_comment_str = self.escape_html_comment(content_str, allow_markup=True)
1068 return f"<!--{escaped_comment_str}-->"
1070 def _process_element(
1071 self,
1072 template: Template,
1073 last_ctx: ProcessContext,
1074 tag: str,
1075 attrs: tuple[TAttribute, ...],
1076 children: tuple[TNode, ...],
1077 ) -> str:
1078 out: list[str] = []
1079 if tag == "svg":
1080 our_ctx = last_ctx.copy(parent_tag=tag, ns="svg")
1081 elif tag == "math":
1082 our_ctx = last_ctx.copy(parent_tag=tag, ns="math")
1083 else:
1084 our_ctx = last_ctx.copy(parent_tag=tag)
1085 if our_ctx.ns == "svg":
1086 starttag = endtag = SVG_TAG_FIX.get(tag, tag)
1087 else:
1088 starttag = endtag = tag
1089 out.append(f"<{starttag}")
1090 if attrs:
1091 out.append(self._process_attrs(template, our_ctx, attrs))
1092 # @TODO: How can we tell if we write out children or not in
1093 # order to self-close in non-html contexts, ie. SVG?
1094 if self.slash_void and tag in VOID_ELEMENTS:
1095 out.append(" />")
1096 else:
1097 out.append(">")
1098 if tag not in VOID_ELEMENTS:
1099 # We were still in SVG but now we default back into HTML
1100 if tag == "foreignobject":
1101 child_ctx = our_ctx.copy(ns="html")
1102 else:
1103 child_ctx = our_ctx
1104 out.extend(
1105 self._process_tnode(template, child_ctx, child) for child in children
1106 )
1107 out.append(f"</{endtag}>")
1108 return "".join(out)
1110 def _process_attrs(
1111 self,
1112 template: Template,
1113 last_ctx: ProcessContext,
1114 attrs: tuple[TAttribute, ...],
1115 ) -> str:
1116 """
1117 Process an element's attributes into a string.
1118 """
1119 resolved_attrs = _resolve_t_attrs(attrs, template.interpolations)
1120 if last_ctx.ns == "svg":
1121 attrs_str = serialize_html_attrs(
1122 _fix_svg_attrs(_resolve_html_attrs(resolved_attrs))
1123 )
1124 else:
1125 attrs_str = serialize_html_attrs(_resolve_html_attrs(resolved_attrs))
1126 if attrs_str:
1127 return attrs_str
1128 return ""
1130 def _process_component(
1131 self,
1132 template: Template,
1133 last_ctx: ProcessContext,
1134 attrs: tuple[TAttribute, ...],
1135 start_i_index: int,
1136 end_i_index: int | None,
1137 children_span: TemplateSpan | None,
1138 ) -> str:
1139 """
1140 Invoke a component and process the result into a string.
1141 """
1142 children_template = (
1143 children_span.extract(template)
1144 if children_span is not None
1145 else Template("")
1146 )
1147 if (
1148 start_i_index != end_i_index
1149 and end_i_index is not None
1150 and template.interpolations[start_i_index].value
1151 != template.interpolations[end_i_index].value
1152 ):
1153 raise ComponentProcessingError(
1154 "Component callable in start tag must match component callable in end tag."
1155 )
1156 component_callable = template.interpolations[start_i_index].value
1157 result_t = self.component_processor_api.process(
1158 template, last_ctx, component_callable, attrs, children_template
1159 )
1160 if isinstance(result_t, ScopedTemplate):
1161 with result_t.scope.activate():
1162 return self._process_template(result_t.template, last_ctx)
1163 return self._process_template(result_t, last_ctx)
1165 def _process_raw_texts(
1166 self,
1167 template: Template,
1168 last_ctx: ProcessContext,
1169 content_ref: TemplateRef,
1170 ) -> str:
1171 """
1172 Process the given content into a string as "raw text".
1173 """
1174 assert last_ctx.parent_tag in CDATA_CONTENT_ELEMENTS
1175 content = resolve_text_without_recursion(
1176 template, last_ctx.parent_tag, content_ref
1177 )
1178 if last_ctx.parent_tag == "script":
1179 return self.escape_html_script(
1180 content,
1181 allow_markup=True,
1182 )
1183 elif last_ctx.parent_tag == "style":
1184 return self.escape_html_style(
1185 content,
1186 allow_markup=True,
1187 )
1188 else:
1189 raise TextProcessingError(
1190 f"Parent tag {last_ctx.parent_tag} is not supported.",
1191 )
1193 def _process_escapable_raw_texts(
1194 self,
1195 template: Template,
1196 last_ctx: ProcessContext,
1197 content_ref: TemplateRef,
1198 ) -> str:
1199 """
1200 Process the given content into a string as "escapable raw text".
1201 """
1202 assert last_ctx.parent_tag in RCDATA_CONTENT_ELEMENTS
1203 content = resolve_text_without_recursion(
1204 template, last_ctx.parent_tag, content_ref
1205 )
1206 return self.escape_html_text(content)
1208 def _process_normal_texts(
1209 self, template: Template, last_ctx: ProcessContext, content_ref: TemplateRef
1210 ):
1211 """
1212 Process the given context into a string as "normal text".
1213 """
1214 return "".join(
1215 (
1216 self.escape_html_text(part)
1217 if isinstance(part, str)
1218 else self._process_normal_text(template, last_ctx, t.cast(int, part))
1219 )
1220 for part in content_ref
1221 )
1223 def _process_normal_text(
1224 self,
1225 template: Template,
1226 last_ctx: ProcessContext,
1227 values_index: int,
1228 ) -> str:
1229 """
1230 Process the value of the interpolation into a string as "normal text".
1232 @NOTE: This is an interpolation that must be formatted to get the value.
1233 """
1234 try:
1235 value = format_interpolation(template.interpolations[values_index])
1236 value = t.cast(NormalTextInterpolationValue, value) # ty: ignore[redundant-cast]
1237 return self._process_normal_text_from_value(template, last_ctx, value)
1238 except Exception:
1239 helper = ProcessingErrorCtx.get()
1240 assert helper is not None, "Helper instance must be set in ctx."
1241 helper.stash_nearest_i_index(values_index)
1242 raise
1244 def _process_normal_text_from_value(
1245 self,
1246 template: Template,
1247 last_ctx: ProcessContext,
1248 value: NormalTextInterpolationValue,
1249 ) -> str:
1250 """
1251 Process a single value into a string as "normal text".
1253 @NOTE: This is an actual value and NOT an interpolation. This is meant to be
1254 used when processing an iterable of values as normal text.
1255 """
1256 if value is None or isinstance(value, bool):
1257 return ""
1258 elif isinstance(value, str):
1259 # @NOTE: This would apply to Markup() but not to a custom object
1260 # implementing HasHTMLDunder.
1261 return self.escape_html_text(value)
1262 elif isinstance(value, Template):
1263 return self._process_template(value, last_ctx)
1264 elif isinstance(value, Iterable):
1265 return "".join(
1266 self._process_normal_text_from_value(
1267 template,
1268 last_ctx,
1269 v,
1270 )
1271 for v in value
1272 )
1273 elif isinstance(value, HasHTMLDunder):
1274 # @NOTE: markupsafe's escape does this for us but we put this in
1275 # here for completeness.
1276 # @NOTE: An actual Markup() would actually pass as a str() but a
1277 # custom object with __html__ might not.
1278 return Markup(value.__html__())
1279 else:
1280 # @DESIGN: Everything that isn't an object we recognize is
1281 # coerced to a str() and emitted.
1282 return self.escape_html_text(value)
1285def resolve_text_without_recursion(
1286 template: Template, parent_tag: str, content_ref: TemplateRef
1287) -> str:
1288 """
1289 Resolve the text in the given template without recursing into more structured text.
1291 This can be bypassed by interpolating an exact match with an object with `__html__()`.
1293 A non-exact match is not allowed because we cannot process escaping
1294 across the boundary between other content and the pass-through content.
1295 """
1296 if content_ref.is_singleton:
1297 try:
1298 value = format_interpolation(template.interpolations[content_ref.i_start])
1299 value = t.cast(RawTextExactInterpolationValue, value) # ty: ignore[redundant-cast]
1300 if value is None or isinstance(value, bool):
1301 return ""
1302 elif isinstance(value, str):
1303 return value
1304 elif isinstance(value, HasHTMLDunder):
1305 # @DESIGN: We could also force callers to use `:safe` to trigger
1306 # the interpolation in this special case.
1307 return Markup(value.__html__())
1308 elif isinstance(value, (Template, Iterable)):
1309 raise TextProcessingError(
1310 f"Template and Iterable interpolation values are not supported within {parent_tag}",
1311 )
1312 else:
1313 return str(value)
1314 except Exception:
1315 helper = ProcessingErrorCtx.get()
1316 assert helper is not None, "Helper instance must be set in ctx."
1317 helper.stash_nearest_i_index(content_ref.i_start)
1318 raise
1319 else:
1320 text = []
1321 for part in content_ref:
1322 if isinstance(part, str):
1323 if part:
1324 text.append(part)
1325 continue
1326 try:
1327 value = format_interpolation(template.interpolations[part])
1328 value = t.cast(RawTextInexactInterpolationValue, value) # ty: ignore[redundant-cast]
1329 if value is None or isinstance(value, bool):
1330 continue
1331 elif (
1332 type(value) is str
1333 ): # type() check to avoid subclasses, probably something smarter here
1334 if value:
1335 text.append(value)
1336 elif not isinstance(value, str) and isinstance(
1337 value, (Template, Iterable)
1338 ):
1339 raise TextProcessingError(
1340 f"Template and Iterable interpolation values are not supported within {parent_tag}",
1341 )
1342 elif isinstance(value, HasHTMLDunder):
1343 raise TextProcessingError(
1344 f"Non-exact trusted interpolation values are not supported within {parent_tag}",
1345 )
1346 else:
1347 value_str = str(value)
1348 if value_str:
1349 text.append(value_str)
1350 except Exception:
1351 helper = ProcessingErrorCtx.get()
1352 assert helper is not None, "Helper instance must be set in ctx."
1353 helper.stash_nearest_i_index(part)
1354 raise
1356 return "".join(text)
1359def _make_default_template_processor(
1360 parser_api: ITemplateParserProxy | None = None,
1361) -> ITemplateProcessor:
1362 """
1363 Wrap our default options but allow parser api to change for testing.
1364 """
1365 return TemplateProcessor(
1366 parser_api=CachedTemplateParserProxy() if parser_api is None else parser_api,
1367 slash_void=True,
1368 uppercase_doctype=True,
1369 )
1372_default_template_processor_api: ITemplateProcessor = _make_default_template_processor()
1375# --------------------------------------------------------------------------
1376# Public API
1377# --------------------------------------------------------------------------
1380def html(template: Template, assume_ctx: ProcessContext | None = None) -> str:
1381 """Parse an HTML t-string, substitute values, and return a string of HTML."""
1382 if assume_ctx is None:
1383 assume_ctx = ProcessContext()
1384 return _default_template_processor_api.process(template, assume_ctx)
1387def svg(template: Template, assume_ctx: ProcessContext | None = None) -> str:
1388 """Parse a standalone SVG fragment and return a string of HTML.
1390 Use when the template does not contain an ``<svg>`` wrapper element.
1391 Tag and attribute case-fixing (e.g. ``clipPath``, ``viewBox``) are applied
1392 from the root, exactly as they would be inside ``html(t"<svg>...</svg>")``.
1394 When the template does contain ``<svg>``, use ``html()`` — the SVG context
1395 is detected automatically.
1396 """
1397 if assume_ctx is None:
1398 assume_ctx = ProcessContext(ns="svg")
1399 return html(template, assume_ctx=assume_ctx)