"""Reader names for internal keys that reach the personal report's data chapters (BUG-2095). The astrologer's layering rule (2026-11-19): readers never see internal codes. Several data tables printed packet keys as they are stored (`bhrigu_bindu`, `day_lord`, `punya_saham`, `goel_method_1_v1` ...). Technique names stay (owner 2026-11-20): a key becomes the technique's proper name, never a lay paraphrase. Names are taken from the report's existing wording (parity_chapters year-lord offices, tajika_mudda balance profiles, appendix_language reference points, functional_layer_table profiles). A key with no known reader name is written in Title Case without underscores, never translated by guess. """ from __future__ import annotations import re from typing import Any SNAKE_TOKEN = re.compile(r"\b[a-z]+(?:_[a-z0-9]+)+\b") _VERSION_SUFFIX = re.compile(r"_v\d+$") # key: (Chinese edition, English edition) READER_KEY_NAMES: dict[str, tuple[str, str]] = { # Sensitive points (technique names stay in both editions). "bhrigu_bindu": ("Bhrigu Bindu", "Bhrigu Bindu"), "sarpa_drekkana": ("Sarpa Drekkana", "Sarpa Drekkana"), # Tajika year-lord offices: same words as parity_chapters._YEAR_LORD_OFFICES. "new_year_lord": ("年首星座主", "Lord of the year's opening sign"), "natal_lagna_lord": ("本命上升主", "Natal Lagna lord"), "muntha_lord": ("Muntha 主星", "Muntha lord"), "varsha_lagna_lord": ("年盘上升主", "Annual Lagna lord"), "tri_rasi_lord": ("Tri-rasi 主", "Tri-rasi lord"), # KP ruling planets. "day_lord": ("日主", "Day lord"), "moon_sign_lord": ("月亮星座主", "Moon sign lord"), "moon_star_lord": ("月亮星宿主", "Moon star lord"), "moon_sub_lord": ("月亮子主", "Moon sub lord"), "ascendant_sign_lord": ("上升星座主", "Ascendant sign lord"), "ascendant_star_lord": ("上升星宿主", "Ascendant star lord"), "ascendant_sub_lord": ("上升子主", "Ascendant sub lord"), # KP house basis. "explicit_cusps": ("按实际宫头度数", "Explicit cusp degrees"), "cusp_to_cusp": ("宫头到下一宫头", "Cusp to next cusp"), # Annual table column (Chinese: appendix_language.FIELD_ZH). "boundary_status": ("边界状态", "Boundary status"), # Annual anchors. "asc_sign": ("年盘上升", "Annual ascendant"), # Mudda balance profiles: the words the Chinese edition already used (pl9_full_data_export). "moon_at_birth_time": ("出生时月亮", "Moon at birth"), "moon_in_varshaphala": ("年盘月亮", "Annual-chart Moon"), "without_dasha_balance": ("不计余额", "No opening balance"), # Sudarshana reference points (Chinese: appendix_language.REFERENCE_POINT_ZH). "ascendant_lagna": ("出生上升参考点", "Birth Ascendant reference"), "moon_lagna": ("月亮参考点", "Moon reference"), "sun_lagna": ("太阳参考点", "Sun reference"), # Yoga categories without an existing reader word. "chandra_extended": ("月亮类(扩展)", "Chandra (extended)"), "neecha_bhanga": ("Neecha Bhanga", "Neecha Bhanga"), # Rashi dasha method profiles: the author or book stays named; the version code is not printed. "goel_full_brahma_ch1_ch5_v1": ("Goel 完整 Brahma 法", "Goel's full Brahma method"), "goel_rao_short_brahma_method_v1": ("K.N. Rao 简法 Brahma", "K.N. Rao short Brahma method"), "goel_method_1_v1": ("Goel 第一法", "Goel method 1"), "kn_rao": ("K.N. Rao 法", "K.N. Rao method"), "drig_rath_aspect_sequence_v1": ("Drig 相位顺序(Rath)", "Drig aspect sequence (Rath)"), "kendradi_narayana_duration_candidate_v1": ("Kendradi 顺序加 Narayana 年数", "Kendradi order with Narayana years"), "pvr_niryaana_shoola_v1": ("PVR Niryaana Shoola", "PVR Niryaana Shoola"), "shoola_forward_md_direct_ad_v1": ("Shoola 大运顺排、小运直排", "Shoola: Mahadasha forward, Antardasha direct"), "jaimini_odd_footed_v1": ("Jaimini 奇数足排法", "Jaimini odd-footed method"), # Functional profiles (functional_layer_table._PROFILE_SHORT). "pvr_table30_v1": ("PVR 表 30", "PVR Table 30"), "bphs_exception_profile": ("BPHS 例外表", "BPHS exception table"), # Conditional-evidence words in the technique audit. "parameter_sensitive": ("结果会随算法设置变化", "results change with the calculation settings"), "profile_sensitive": ("结果会随所选口径变化", "results change with the chosen profile"), "single_system_inference": ("只有一种方法给出", "given by one method only"), "unclosed_divisional_chart": ("相关分盘还没有核定", "the divisional chart is not settled yet"), "user_history_verification_required": ("需要对照本人经历核对", "needs checking against the person's own history"), # BUG-2104: Mudda sub-period rows (balance-profile column); 小运 is the report's word for this level. "antardasha": ("小运", "Antardasha"), # BUG-2104: the annual rows' boundary status (Chinese edition already printed 已列出). "listed": ("已列出", "Listed"), # BUG-2104: capitalised point keys. Names already printed elsewhere in the report: the annual # special points (「Arudha 上升 (AL)」) and BUG-2065 (「A10(Karma Pada)」). "Arudha_Lagna": ("Arudha 上升(AL)", "Arudha Lagna (AL)"), "Upapada_Lagna": ("Upapada 上升(UL)", "Upapada Lagna (UL)"), "A10_Karma_Pada": ("A10(Karma Pada)", "A10 (Karma Pada)"), "ViGhati_Lagna": ("Vighati 上升", "Vighati Lagna"), } # BUG-2104: a capitalised key with underscores (`Artha_Praharaka`, `Bhava_Lagna`, `D2_Hora`). UNDERSCORED_NAME = re.compile(r"^[A-Za-z0-9]+(?:_[A-Za-z0-9]+)+$") def title_case_key(raw: str) -> str: """`punya_saham` -> `Punya Saham`; a trailing version code (`_v1`) is dropped.""" words = _VERSION_SUFFIX.sub("", raw).split("_") return " ".join(word[:1].upper() + word[1:] for word in words if word) def reader_key(value: Any, language: str, title_case: bool = True) -> Any: """Reader name for an internal key; any other value is returned unchanged. ``title_case=False`` is for generic tables whose other keys the edition's later word pass already translates (`dt_local` -> 本地时间): only keys named above are replaced there. """ if not isinstance(value, str): return value raw = value.strip() names = READER_KEY_NAMES.get(raw) if names: return names[1] if language == "en" else names[0] if title_case and SNAKE_TOKEN.fullmatch(raw): fallback = raw[:-len("_fallback")] if raw.endswith("_fallback") else None if fallback and fallback in READER_KEY_NAMES: return reader_key(fallback, language) return title_case_key(raw) return value def reader_point_name(value: Any, language: str) -> Any: """BUG-2104: a point or chart key (`Arudha_Lagna`, `Artha_Praharaka`, `D2_Hora`) as its reader name. Known keys use the names above; any other underscored key keeps its words with spaces (the Chinese edition's later word pass turns `Lagna` into 上升, as for the other special lagnas). """ if not isinstance(value, str): return value named = reader_key(value, language) if named != value: return named raw = value.strip() return raw.replace("_", " ") if UNDERSCORED_NAME.fullmatch(raw) else value def _ordinal(number: str) -> str: value = int(number) suffix = "th" if value % 100 in (11, 12, 13) else {1: "st", 2: "nd", 3: "rd"}.get(value % 10, "th") return f"{value}{suffix}" _SPECIAL_ASPECT = re.compile(r"^(Mars|Jupiter|Saturn)_aspect_(\d+)$") _HOUSE_LORD = re.compile(r"\bH(\d+)_Lord\((\w+)\)") def aspect_type_en(value: Any) -> Any: """BUG-2104: `Mars_aspect_8` -> `Mars special 8th-house aspect` (the Chinese edition already says 「火星特殊8宫相位」); other aspect names are unchanged.""" if not isinstance(value, str): return value match = _SPECIAL_ASPECT.fullmatch(value.strip()) return f"{match[1]} special {_ordinal(match[2])}-house aspect" if match else value def house_lord_text_en(text: Any) -> Any: """BUG-2104: `H2_Lord(Venus)` in an English combination -> `2nd lord Venus` (Chinese: 「2宫主金星」).""" if not isinstance(text, str): return text return _HOUSE_LORD.sub(lambda match: f"{_ordinal(match[1])} lord {match[2]}", text) # BUG-2109: the candidate yoga table's category column printed raw keys (`extended`, `kalatra`, # `chandra`, `surya`, `auspicious`, `durbhaga`, `PMC` ...). Chinese words are the ones the report # already printed for these keys (pl9_reader_export word map); English words follow the appendix # glossary (pl9_full_data_export: 吉性 -> benefic, 王权/事业 -> authority/career ...). YOGA_CATEGORY_NAMES: dict[str, tuple[str, str]] = { "auspicious": ("吉性", "Benefic"), "chandra": ("月亮类", "Moon-based"), "chandra_extended": ("月亮类(扩展)", "Moon-based (extended)"), "lunar_yoga": ("月亮瑜伽", "Moon-based"), "surya": ("太阳类", "Sun-based"), "solar_yoga": ("太阳瑜伽", "Sun-based"), "kalatra": ("婚恋", "Marriage and partnership"), "durbhaga": ("不利组合", "Adverse combination"), "ari": ("障碍组合", "Obstacle combination"), "special": ("特殊组合", "Special combination"), "conjunction": ("合相", "Conjunction"), "raja": ("王权/事业", "Authority/career"), "dhana": ("财富", "Wealth"), "putra": ("子女/创造", "Children/creativity"), "ayur": ("体质参考", "Constitution reference"), "nabhasa": ("天象格局", "Nabhasa configuration"), "asha": ("愿望/收益", "Desire/gains"), "aryama": ("贵人/助力", "Patronage/support"), "moksha": ("解脱/内在", "Moksha/inner life"), "health": ("健康", "Health"), "travel": ("迁移/出行", "Travel/movement"), "vidya": ("学业/才智", "Learning/intellect"), "extended": ("扩展规则", "Extended rule set"), "PMC": ("大人格瑜伽", "Mahapurusha"), "mahapurusha": ("大人格瑜伽", "Mahapurusha"), } def yoga_category_name(value: Any, language: str) -> str | None: """Reader word for a yoga category key, or None when the key has no listed name.""" if not isinstance(value, str): return None names = YOGA_CATEGORY_NAMES.get(value.strip()) or YOGA_CATEGORY_NAMES.get(value.strip().lower()) if not names: return None return names[1] if language == "en" else names[0]