排盘入口

排盘是一切的起点：给出生日期、时辰、性别，得到一个 Astrolabe。

from x_iztro import Astro

astro = Astro()

Astro 无内部状态，实例化一次到处用；也可以每次调用时临时构造。

所有入口在入参非法时抛 IztroError（继承自 ValueError，因此 except ValueError 也接得住）。日期格式与存在性、公历年份范围、时辰索引在核心层前置校验；性别、语言、宫名这类字符串取值在绑定层校验。异常带 .code 给出机器可读分类，详见错误处理。

ChartConfig

排盘配置：六个开关加两张可选的自定义表。冻结的 dataclass，全部字段都有默认值，默认值与 JS iztro 一致——ChartConfig() 与不传 config 等价。

字段	类型	默认	取值（对应枚举）
`year_divide`	`str`	`"normal"`	`normal` 正月初一 / `exact` 立春（`YearDivide`）
`horoscope_divide`	`str`	`"normal"`	`normal` 初一 / `exact` 节气（`HoroscopeDivide`）
`age_divide`	`str`	`"normal"`	`normal` 跨年即加 / `birthday` 过生日才加（`AgeDivide`）
`day_divide`	`str`	`"forward"`	`forward` 晚子时归次日 / `current` 归当天（`DayDivide`）
`algorithm`	`str`	`"default"`	`default` / `zhongzhou`（`Algorithm`）
`astro_type`	`str`	`"heaven"`	`heaven` 天盘 / `earth` 地盘 / `human` 人盘（`AstroType`）
`mutagens`	`dict[str, list[str]] \| None`	`None`	天干标识 → 四颗星标识（禄、权、科、忌）
`brightness`	`dict[str, list[str]] \| None`	`None`	星耀标识 → 十二项亮度标识，索引 0 为寅宫，空串表示该宫无亮度

六个开关的取值语义与流派背景见 Config 详解。

方法

方法	说明
`to_dict() -> dict`	转成绑定层接受的 camelCase 配置对象；两张表为 `None` 时不出现在结果里

示例

from x_iztro import Astro, ChartConfig, AstroType, HeavenlyStem, MajorStar

cfg = ChartConfig(
    astro_type="earth",
    mutagens={HeavenlyStem.GENG: [MajorStar.TAIYANG, MajorStar.WUQU,
                                  MajorStar.TIANFU, MajorStar.TIANTONG]},
)

print(cfg.to_dict())

chart = Astro().by_solar("2000-8-16", 2, "female", config=cfg)
print(chart.five_elements_class, chart.config.astro_type)
print(chart.palace("soulPalace").mutagen_star_keys)

输出

{'yearDivide': 'normal', 'horoscopeDivide': 'normal', 'ageDivide': 'normal', 'dayDivide': 'forward', 'algorithm': 'default', 'astroType': 'earth', 'mutagens': {'gengHeavenly': ['taiyangMaj', 'wuquMaj', 'tianfuMaj', 'tiantongMaj']}}
土五局 earth
['tiantongMaj', 'tianjiMaj', 'wenchangMin', 'lianzhenMaj']

地盘的命宫落在原盘身宫（官禄，丙戌），因此宫干四化按丙干取。

边界与陷阱

by_solar

用途　由公历日期排出本命盘。

斗数含义　紫微斗数以农历为算法基础，但绝大多数人只记得公历生日。本方法先把公历转农历（含年、月、日、时四柱），再据此安星。换年的时点受 year_divide 影响——正月初一与立春之间出生的人，两种配置会得到不同的年干支，进而影响四化、命主身主与全部年系星。

签名

def by_solar(
    self,
    solar_date: str,
    time_index: TimeIndexType,
    gender: GenderType,
    *,
    fix_leap: bool = True,
    language: LanguageType = "zh-CN",
    config: ChartConfig | None = None,
) -> Astrolabe

参数

参数	类型	必填	默认	说明
`solar_date`	`str`	是	—	公历日期，格式 `YYYY-M-D`，月日不必补零。支持 1583–9999 年
`time_index`	`int`	是	—	时辰索引 0–12。0 为早子时（00:00–01:00），12 为晚子时（23:00–24:00）
`gender`	`str`	是	—	`"male"` 或 `"female"`。决定大限顺逆与长生、博士十二神的排列方向
`fix_leap`	`bool`	否	`True`	仅限关键字。是否调整农历闰月。为真时闰月十六日起按下月算（晚子时除外，见下）
`language`	`str`	否	`"zh-CN"`	输出语言，影响所有译名字段；`*_key` 标识字段不受影响
`config`	`ChartConfig \| None`	否	`None`	排盘配置，`None` 取默认

返回值　Astrolabe——十二宫、四柱、命主身主、五行局俱全的完整星盘。

示例

from x_iztro import Astro

chart = Astro().by_solar("2000-8-16", 2, "female")

print(chart.solar_date, "|", chart.lunar_date, "|", chart.chinese_date)
print(chart.sign, chart.zodiac, chart.five_elements_class)
print("命主", chart.soul, "身主", chart.body)

输出

2000-8-16 | 二〇〇〇年七月十七 | 庚辰 甲申 丙午 庚寅
狮子座 龙 木三局
命主 破军 身主 文昌

边界与陷阱

by_lunar

用途　由农历日期排出本命盘。

斗数含义　农历日期是斗数的原生输入，跳过公历转换这一步。知道自己农历生日的人直接用它，结果与用对应公历日期调 by_solar 完全一致。

签名

def by_lunar(
    self,
    lunar_date: str,
    time_index: TimeIndexType,
    gender: GenderType,
    *,
    is_leap_month: bool = False,
    fix_leap: bool = True,
    language: LanguageType = "zh-CN",
    config: ChartConfig | None = None,
) -> Astrolabe

参数　除以下一项外，其余与 by_solar 相同。gender 之后的参数只能按关键字传入—— is_leap_month 与 fix_leap 相邻，位置传参写反了不报错、盘会静默错一个月。

参数	类型	必填	默认	说明
`lunar_date`	`str`	是	—	农历日期，格式 `YYYY-M-D`，月份写正数（闰月由下一参数标记）
`is_leap_month`	`bool`	否	`False`	仅限关键字。该农历月是否为闰月。若那一年那个月本来就没有闰月，此参数不生效

返回值　同 by_solar。

示例

a = Astro().by_lunar("2000-7-17", 2, "female")
b = Astro().by_solar("2000-8-16", 2, "female")

print(a.solar_date, a.solar_date == b.solar_date)

输出

2000-8-16 True

边界与陷阱

is_leap_month 的静默失效

传 True 但那个月并非闰月时，参数被静默忽略，不报错。如果需要严格校验，调用前先自行确认该年该月确实有闰月。

get_horoscope

用途　以某张本命盘为起点计算目标日期的运限。

签名

def get_horoscope(
    self,
    astrolabe: Astrolabe,
    target_date: str | None = None,
    target_time_index: TimeIndexType | None = None,
) -> Horoscope

参数

参数	类型	必填	默认	说明
`astrolabe`	`Astrolabe`	是	—	本命盘
`target_date`	`str \| None`	否	`None`	目标公历日期；不传取今天
`target_time_index`	`int \| None`	否	`None`	目标时辰索引；不传取此刻所属时辰

返回值　Horoscope，持有传入的星盘。详见运限对象。

示例

chart = Astro().by_solar("2000-8-16", 2, "female")
h = Astro().get_horoscope(chart, "2025-6-1", 0)

print(h.decadal.heavenly_stem + h.decadal.earthly_branch)
print(h.yearly.heavenly_stem + h.yearly.earthly_branch)

输出

庚辰
乙巳

边界与陷阱

星盘上有等价的方法

chart.horoscope("2025-6-1", 0) 与本方法完全等价，且不必再持有 Astro 实例。 Astro.get_horoscope 存在是为了让「所有入口都在一个类上」这种用法也成立。

rearranged

用途　以指定干支为命宫重排本盘，返回新盘；原盘不变。

斗数含义　中州派把同一组出生数据看作三张盘：天盘以命宫干支起五行局，地盘以身宫干支起，人盘以福德宫干支起。起局的干支一变，五行局就变，紫微天府落点、十二宫名、长生十二神、大限小限随之全部重算。本方法把这个能力放开到任意干支。

签名

def rearranged(self, from_stem: str, from_branch: str) -> Astrolabe

这是 Astrolabe 上的方法，不在 Astro 类上。

参数

参数	类型	必填	默认	说明
`from_stem`	`str`	是	—	新命宫的天干标识，`HeavenlyStem` 枚举值域
`from_branch`	`str`	是	—	新命宫的地支标识，`EarthlyBranch` 枚举值域

返回值　新的 Astrolabe。重算：命宫身宫、五行局、十四主星、十二宫名、长生十二神、大限小限、命主星，以及随命宫挪位的天伤、天使、天才。沿用原盘：辅星、其余杂耀、博士十二神、岁前与将前十二神、身主星。

示例

chart = Astro().by_solar("2000-8-16", 2, "female")

# 从原盘身宫的干支起盘，等价于地盘
body = next(p for p in chart.palaces if p.is_body_palace)
earth = chart.rearranged(body.heavenly_stem_key, body.earthly_branch_key)

print("天盘", chart.five_elements_class, "→ 地盘", earth.five_elements_class)

输出

天盘 木三局 → 地盘 土五局

边界与陷阱

常规三盘不必用这个方法

天盘、地盘、人盘用 ChartConfig(astro_type="earth") 直接排即可，两个排盘入口都支持。rearranged 是为「从任意干支起盘」准备的。

astrolabe_to_prompt / horoscope_to_prompt

用途　把星盘或运限渲染成结构化文本，供大模型消费。

签名

def astrolabe_to_prompt(self, astrolabe: Astrolabe) -> str
def horoscope_to_prompt(
    self,
    astrolabe: Astrolabe,
    target_date: str,
    target_time_index: TimeIndexType,
) -> str

参数

参数	类型	必填	默认	说明
`astrolabe`	`Astrolabe`	是	—	星盘对象
`target_date`	`str`	是	—	仅运限版本：目标公历日期
`target_time_index`	`int`	是	—	仅运限版本：目标时辰索引

返回值　str——按星盘的排盘语言输出的结构化文本。

示例

astro = Astro()
chart = astro.by_solar("2000-8-16", 2, "female")

print(astro.astrolabe_to_prompt(chart)[:46])

输出

=== 基本信息 ===
性别: 女
阳历: 2000-8-16
农历: 二〇〇〇年七月十七

边界与陷阱

输出语言跟随星盘的 language，不单独设置。要英文 prompt 就用英文排盘。

排盘入口

ChartConfig

按天干、按星整表替换

只收标识，不收译名

六个开关的枚举成员不会被 to_dict 转成字符串

自定义表不回显在 chart.config 上

by_solar

时辰索引为什么是 0–12 而不是 0–11

fix_leap 只在闰月生效

language 不影响判断逻辑

by_lunar

get_horoscope

rearranged

身主星不随重排变化

astrolabe_to_prompt / horoscope_to_prompt

本页目录