Coverage for tdom/processor.py: 96%

596 statements  

« 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 

7 

8from markupsafe import Markup 

9 

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 

57 

58type Attribute = tuple[str, object] 

59type AttributesDict = dict[str, object] 

60 

61 

62@dataclass(frozen=True) 

63class TemplateErrorState: 

64 """ 

65 Accumulated and finalized template error state. 

66 """ 

67 

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. " 

80 

81 

82@dataclass() 

83class OpenTemplateErrorState: 

84 """ 

85 Scratchpad to record state during egress through try/except blocks from source of exception. 

86 """ 

87 

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. " 

96 

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 ) 

110 

111 

112class ProcessingError(TemplatingError): 

113 """General error when processing a template.""" 

114 

115 

116class AttributeProcessingError(ProcessingError): 

117 """Error while processing an element or component attribute.""" 

118 

119 

120class TextProcessingError(ProcessingError): 

121 """Error while processing an element or component attribute.""" 

122 

123 

124class ComponentProcessingError(ProcessingError): 

125 """Error while processing an element or component attribute.""" 

126 

127 

128@dataclass 

129class ProcessingErrorHelper: 

130 open_error_state: OpenTemplateErrorState = field( 

131 default_factory=OpenTemplateErrorState 

132 ) 

133 " Currently tracked template error state. " 

134 

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 

138 

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 

144 

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 

148 

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 

152 

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)) 

163 

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 

175 

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 

196 

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) 

206 

207 def _make_tcomment_repr(self, reader: SourceReader, tnode: TComment) -> str: 

208 return f"<!--{reader.ref_to_repr(tnode.ref)}-->" 

209 

210 def _make_ttext_repr(self, reader: SourceReader, tnode: TText) -> str: 

211 return reader.ref_to_repr(tnode.ref) 

212 

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)}" 

217 

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}",) 

231 

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}",) 

240 

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}",) 

262 

263 def _fallback_element_repr(self, tnode: TElement) -> str: 

264 return f"<{tnode.tag} ...>" 

265 

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 ) 

274 

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 

324 

325 

326ProcessingErrorCtx: ContextVar[ProcessingErrorHelper | None] = ContextVar( 

327 "ProcessingErrorCtx", default=None 

328) 

329""" Context variable to manage template error state after exception occurs. """ 

330 

331 

332# -------------------------------------------------------------------------- 

333# Custom formatting for the processor 

334# -------------------------------------------------------------------------- 

335 

336 

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) 

341 

342 

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) 

347 

348 

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() 

353 

354 

355CUSTOM_FORMATTERS = ( 

356 ("safe", _format_safe), 

357 ("unsafe", _format_unsafe), 

358 ("callback", _format_callback), 

359) 

360 

361 

362def format_interpolation(interpolation: Interpolation) -> object: 

363 return base_format_interpolation( 

364 interpolation, 

365 formatters=CUSTOM_FORMATTERS, 

366 ) 

367 

368 

369# -------------------------------------------------------------------------- 

370# Placeholder Substitution 

371# -------------------------------------------------------------------------- 

372 

373 

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 ) 

392 

393 

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 ) 

408 

409 

410def _substitute_spread_attrs(value: object) -> Iterable[Attribute]: 

411 """ 

412 Substitute a spread attribute based on the interpolated value. 

413 

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 ) 

426 

427 

428ATTR_EXPANDERS = { 

429 "data": _expand_data_attr, 

430 "aria": _expand_aria_attr, 

431} 

432 

433 

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 

449 

450 

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) 

465 

466 

467@dataclass 

468class StyleAccumulator: 

469 styles: dict[str, str | None] 

470 

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 ) 

493 

494 def to_value(self) -> str | None: 

495 """ 

496 Serialize the special style value back into a string. 

497 

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 

504 

505 

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) 

518 

519 

520@dataclass 

521class ClassAccumulator: 

522 toggled_classes: dict[str, bool] 

523 

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 ) 

552 

553 def to_value(self) -> str | None: 

554 """ 

555 Serialize the special class value back into a string. 

556 

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 

563 

564 

565ATTR_ACCUMULATOR_MAKERS = { 

566 "class": make_class_accumulator, 

567 "style": make_style_accumulator, 

568} 

569 

570 

571type AttributeValueAccumulator = StyleAccumulator | ClassAccumulator 

572 

573 

574def _resolve_t_attrs( 

575 attrs: Sequence[TAttribute], interpolations: tuple[Interpolation, ...] 

576) -> AttributesDict: 

577 """ 

578 Replace placeholder values in attributes with their interpolated values. 

579 

580 The values returned are not yet processed for HTML output; that is handled 

581 in a later step. 

582 

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 

659 

660 

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) 

671 

672 

673def _kebab_to_snake(name: str) -> str: 

674 """Convert a kebab-case name to snake_case.""" 

675 return name.replace("-", "_").lower() 

676 

677 

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. 

688 

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`. 

694 

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. 

700 

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 """ 

708 

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 ) 

714 

715 kwargs: AttributesDict = {} 

716 

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}.") 

730 

731 if "children" in kwargs: 

732 raise ComponentProcessingError( 

733 "The children attribute is reserved for component children." 

734 ) 

735 

736 if "children" in callable_info.named_params: 

737 kwargs["children"] = children 

738 

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 

743 

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 ) 

751 

752 return kwargs 

753 

754 

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 ) 

761 

762 

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 

769 

770 

771@dataclass(frozen=True, slots=True) 

772class ProcessContext: 

773 parent_tag: str = DEFAULT_NORMAL_TEXT_ELEMENT 

774 ns: str = "html" 

775 

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 ) 

785 

786 

787type FunctionComponent = Callable[..., Template] 

788type FactoryComponent = Callable[..., ComponentObject] 

789type ComponentCallable = FunctionComponent | FactoryComponent 

790type ComponentObject = Callable[[], Template] 

791 

792 

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) 

817 

818 

819class ITemplateParserProxy(t.Protocol): 

820 def to_ttree(self, template: Template) -> TTree: ... 

821 

822 

823@dataclass(frozen=True) 

824class TemplateParserProxy(ITemplateParserProxy): 

825 def to_ttree(self, template: Template) -> TTree: 

826 return TemplateParser.parse(template) 

827 

828 

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) 

834 

835 def to_ttree(self, template: Template) -> TTree: 

836 return self._to_ttree(CachableTemplate(template)) 

837 

838 

839class IComponentProcessor(t.Protocol): 

840 """Isolate component processing to allow for replacement.""" 

841 

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 ... 

856 

857 

858class ComponentProcessor(IComponentProcessor): 

859 """ 

860 Default component processor. 

861 """ 

862 

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. 

874 

875 Two general "styles" are supported: 

876 

877 1. FunctionComponent 

878 

879 Calling `component_callable` with the prepared kwargs should 

880 return a `Template`. 

881 

882 The primary purpose of this style is to support 

883 using a normal function as a component. 

884 

885 2. FactoryComponent 

886 

887 Calling `component_callable` with the prepared kwargs should 

888 return another `Callable` which when called with no arguments should 

889 return a `Template`. 

890 

891 The primary purpose of this style is to support 

892 using a `dataclass` with `def __call__(self) -> Template` as a 

893 component. 

894 

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 ) 

929 

930 

931class ITemplateProcessor(t.Protocol): 

932 def process(self, root_template: Template, assume_ctx: ProcessContext) -> str: ... 

933 

934 

935@dataclass(frozen=True) 

936class TemplateProcessor(ITemplateProcessor): 

937 parser_api: ITemplateParserProxy = field(default_factory=CachedTemplateParserProxy) 

938 

939 component_processor_api: IComponentProcessor = field( 

940 default_factory=ComponentProcessor 

941 ) 

942 

943 escape_html_text: Callable = default_escape_html_text 

944 

945 escape_html_comment: Callable = default_escape_html_comment 

946 

947 escape_html_script: Callable = default_escape_html_script 

948 

949 escape_html_style: Callable = default_escape_html_style 

950 

951 slash_void: bool = False # Apply a xhtml-style slash to void html elements. 

952 

953 uppercase_doctype: bool = False # DOCTYPE vs doctype 

954 

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) 

964 

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 

976 

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 

1016 

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}>" 

1031 

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 ) 

1041 

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) 

1056 

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}-->" 

1069 

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) 

1109 

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 "" 

1129 

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) 

1164 

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 ) 

1192 

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) 

1207 

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 ) 

1222 

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". 

1231 

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 

1243 

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". 

1252 

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) 

1283 

1284 

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. 

1290 

1291 This can be bypassed by interpolating an exact match with an object with `__html__()`. 

1292 

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 

1355 

1356 return "".join(text) 

1357 

1358 

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 ) 

1370 

1371 

1372_default_template_processor_api: ITemplateProcessor = _make_default_template_processor() 

1373 

1374 

1375# -------------------------------------------------------------------------- 

1376# Public API 

1377# -------------------------------------------------------------------------- 

1378 

1379 

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) 

1385 

1386 

1387def svg(template: Template, assume_ctx: ProcessContext | None = None) -> str: 

1388 """Parse a standalone SVG fragment and return a string of HTML. 

1389 

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>")``. 

1393 

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)