| """占位符统一兜底工具。""" |
|
|
| from __future__ import annotations |
|
|
| from collections.abc import Iterable, Mapping |
| from typing import Any |
|
|
| PLACEHOLDER_FALLBACK_VALUE = "/" |
|
|
|
|
| def normalize_placeholder_value(value: Any, *, fallback_value: str = PLACEHOLDER_FALLBACK_VALUE) -> Any: |
| """将 None 统一归一为兜底值。""" |
| return fallback_value if value is None else value |
|
|
|
|
| def get_service_placeholder_keys(service: Any) -> list[str]: |
| """兼容不同服务实现，提取服务声明的占位符键。""" |
| getter = getattr(service, "get_placeholder_keys", None) |
| if callable(getter): |
| keys = getter() |
| else: |
| keys = getattr(service, "placeholder_keys", []) |
|
|
| if not isinstance(keys, Iterable) or isinstance(keys, (str, bytes)): |
| return [] |
|
|
| result: list[str] = [] |
| for key in keys: |
| if isinstance(key, str) and key.strip(): |
| result.append(key) |
| return result |
|
|
|
|
| def normalize_service_result( |
| service_result: Mapping[str, Any] | None, |
| *, |
| expected_keys: Iterable[str] = (), |
| fallback_value: str = PLACEHOLDER_FALLBACK_VALUE, |
| ) -> dict[str, Any]: |
| """标准化单个服务的返回值，并补全服务声明但未返回的键。""" |
| normalized: dict[str, Any] = {} |
|
|
| if service_result: |
| for key, value in service_result.items(): |
| normalized[str(key)] = normalize_placeholder_value(value, fallback_value=fallback_value) |
|
|
| for key in expected_keys: |
| normalized.setdefault(key, fallback_value) |
|
|
| return normalized |
|
|
|
|
| def ensure_required_placeholders( |
| context: Mapping[str, Any], |
| required_placeholders: Iterable[str] | None, |
| *, |
| fallback_value: str = PLACEHOLDER_FALLBACK_VALUE, |
| ) -> dict[str, Any]: |
| """确保 required_placeholders 中所有键都存在且非 None。""" |
| normalized: dict[str, Any] = { |
| str(key): normalize_placeholder_value(value, fallback_value=fallback_value) |
| for key, value in context.items() |
| } |
|
|
| if required_placeholders: |
| for key in required_placeholders: |
| if key not in normalized or normalized[key] is None: |
| normalized[key] = fallback_value |
|
|
| return normalized |
|
|
|
|
| def build_docx_render_context( |
| *, |
| doc: Any, |
| context: Mapping[str, Any], |
| fallback_value: str = PLACEHOLDER_FALLBACK_VALUE, |
| ) -> dict[str, Any]: |
| """在 docxtpl 渲染前补齐缺失变量，保证模板中未命中的变量也会落为兜底值。""" |
| normalized = ensure_required_placeholders(context, None, fallback_value=fallback_value) |
| missing_keys = _get_undeclared_template_variables(doc=doc, context=normalized) |
|
|
| for key in missing_keys: |
| normalized.setdefault(key, fallback_value) |
|
|
| return normalized |
|
|
|
|
| def resolve_render_variable( |
| variables: Mapping[str, Any], |
| key: str, |
| *, |
| fallback_value: str = PLACEHOLDER_FALLBACK_VALUE, |
| ) -> tuple[bool, str]: |
| """字符串模板渲染的统一变量解析。""" |
| if key in variables and variables[key] is not None: |
| return True, str(variables[key]) |
| return False, fallback_value |
|
|
|
|
| def _get_undeclared_template_variables(*, doc: Any, context: Mapping[str, Any]) -> set[str]: |
| getter = getattr(doc, "get_undeclared_template_variables", None) |
| if not callable(getter): |
| return set() |
|
|
| values: Any |
| try: |
| values = getter(context=dict(context)) |
| except TypeError: |
| try: |
| values = getter(dict(context)) |
| except Exception: |
| return set() |
| except Exception: |
| return set() |
|
|
| if not isinstance(values, (set, list, tuple)): |
| return set() |
|
|
| result: set[str] = set() |
| for item in values: |
| if isinstance(item, str) and item.strip(): |
| result.add(item) |
| return result |
|
|
