概览
包结构、类型体系与阅读本参考的方式。
Python 包是 Rust 核心的类型化封装：计算在 Rust 里完成， Python 侧提供 dataclass 与 StrEnum 构成的强类型 API，零外部依赖。
这一栏是 Python 侧的完整 API 参考——每个函数、类与方法都有独立条目。
安装
pip install x-iztro要求 Python 3.10 及以上。发行版内含预编译的原生扩展（abi3-py310 轮子）， 安装时不需要 Rust 工具链。
3.10 上也能用 StrEnum
enum.StrEnum 是 3.11 才进标准库的。x_iztro.enums 在 3.10 上自动回退到等价的
class StrEnum(str, Enum) 实现——枚举成员照样既是字符串又能补全，两个版本行为一致。
第一张盘
from x_iztro import Astro
chart = Astro().by_solar("2000-8-16", 2, "female") # 2 = 寅时（03:00–05:00）
print(chart.solar_date, chart.lunar_date)
# 2000-8-16 二〇〇〇年七月十七
soul = chart.palace("soulPalace")
print(" ".join(s.name for s in soul.major_stars))
# 紫微包结构
| 模块 | 内容 | 本参考对应页 |
|---|---|---|
x_iztro.Astro | 排盘主类 | 排盘入口 |
x_iztro.models | Astrolabe、Palace、Star、Horoscope、ChartConfig 等 dataclass | 星盘对象 起的四页 |
x_iztro.enums | 全部语言无关标识的 StrEnum，以及 GenderType、LanguageType、TimeIndexType 等类型别名 | 数据表、本页下方 |
x_iztro.query | 生肖、星座、命宫主星的轻量查询 | 轻量查询 |
x_iztro.utils | 索引换算、亮度与四化查表 | 工具函数 |
x_iztro.star | 按出生数据安星 | 安星模块 |
x_iztro.data | 星耀与干支数据表、顺序常量 | 数据表 |
x_iztro.i18n | 标识与译名的双向查找 | 翻译 |
x_iztro.plugin | 给星盘类挂自定义方法 | 扩展星盘 |
models 是聚合层：Astrolabe 实际定义在 x_iztro.astrolabe，Palace 在 x_iztro.palace，
Star 在 x_iztro.star_object，Horoscope 在 x_iztro.horoscope，
ChartConfig 在 x_iztro.config，SurroundedPalaces 在 x_iztro.surpalaces。
从 x_iztro 顶层或 x_iztro.models 导入都拿得到，按哪个都行。
类型别名
x_iztro.enums 里几个 Literal 别名，作用是让编辑器在参数写错时立刻标红：
| 别名 | 定义 |
|---|---|
GenderType | Literal["male", "female"] |
LanguageType | Literal["zh-CN", "zh-TW", "en-US", "ja-JP", "ko-KR", "vi-VN"] |
TimeIndexType | Literal[0, 1, …, 12] |
StarTypeLiteral | Literal["major", "soft", "tough", "adjective", "flower", "helper", "lucun", "tianma"] |
ScopeLiteral | Literal["origin", "decadal", "yearly", "monthly", "daily", "hourly"] |
它们只是类型标注，运行期不做校验——真正的取值校验在核心层，非法值抛 IztroError。
枚举即标识
x_iztro.enums 里的每个枚举都是 StrEnum，其取值就是语言无关标识，
可以直接与数据对象上的 *_key 字段比较：
from x_iztro import MajorStar, PalaceName
soul = chart.palace(PalaceName.SOUL)
print(soul.major_stars[0].key == MajorStar.ZIWEI)
# True因为是 StrEnum，字符串字面量同样有效——chart.palace("soulPalace") 与
chart.palace(PalaceName.SOUL) 等价。枚举的价值在于 IDE 补全与拼写检查。
判断用 key，不要用 name
star.name 随排盘语言变化（中文盘是「紫微」，英文盘是 emperor）；
star.key 在任何语言下都是 ziweiMaj。所有判断都应基于 *_key 字段或内置判断方法。
数据对象是不可变的
星盘、宫位、星耀都是 frozen=True 的 dataclass，构造后不能修改字段。
需要变体时用返回新对象的方法，如 chart.rearranged(...)。
try:
chart.solar_date = "2001-1-1"
except Exception as e:
print(type(e).__name__, e)输出
FrozenInstanceError cannot assign to field 'solar_date'不可变让星盘可以安全地在多个分析函数之间传递、放进缓存、跨线程共享， 不必担心某一处的修改影响到别处。
条目怎么读
每个 API 条目按固定八段组织：
示例统一用同一张盘：2000 年 8 月 16 日寅时女命（by_solar("2000-8-16", 2, "female")），
方便跨页对照。这张盘的完整数据见数据结构。
排盘语言不传时默认 zh-CN，因此本参考所有输出块里的展示值都是中文。
换语言只改这些展示串，*_key 标识与全部判断方法的结果不变。