# Copyright (c) 2025, JINGROW
# License: MIT. See LICENSE

"""
仅实现最小必需的 `render_template`，用于对字符串模板进行 Jinja2 渲染。

最佳实践原则：
- 复用单例 Environment，启用 trim_blocks/lstrip_blocks 提升可读性；
- 默认采用宽松 Undefined（与 Jinja2 默认一致），便于条件表达式渲染；
- 不启用 autoescape（后端逻辑条件渲染，不输出到 HTML）。
"""

from typing import Any, Dict


_env = None


def _get_env():
	"""延迟初始化 Jinja2 Environment。"""
	global _env
	if _env is not None:
		return _env
	try:
		from jinja2 import Environment, Undefined
		_env = Environment(
			autoescape=False,
			undefined=Undefined,
			trim_blocks=True,
			lstrip_blocks=True,
		)
		return _env
	except Exception as e:
		# 将异常原样抛出，调用方可根据自身策略处理
		raise e


def render_template(template_string: str, context: Dict[str, Any] | None = None) -> str:
	"""渲染 Jinja2 字符串模板。

	Args:
		template_string: 模板字符串
		context: 渲染上下文

	Returns:
		渲染后字符串
	"""
	if not template_string:
		return ""

	context = context or {}
	env = _get_env()
	template = env.from_string(str(template_string))
	return template.render(**context)


