x-iztro
x-iztroRustPythonGo

排盘入口

Astro 类的排盘方法、重排与语义化文本投影。

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

from x_iztro import Astro

astro = Astro()

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

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

ChartConfig

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

字段类型默认取值（对应枚举）
year_dividestr"normal"normal 正月初一 / exact 立春（YearDivide）
horoscope_dividestr"normal"normal 初一 / exact 节气（HoroscopeDivide）
age_dividestr"normal"normal 跨年即加 / birthday 过生日才加（AgeDivide）
day_dividestr"forward"forward 晚子时归次日 / current 归当天（DayDivide）
algorithmstr"default"default / zhongzhou（Algorithm）
astro_typestr"heaven"heaven 天盘 / earth 地盘 / human 人盘（AstroType）
mutagensdict[str, list[str]] | NoneNone天干标识 → 四颗星标识（禄、权、科、忌）
brightnessdict[str, list[str]] | NoneNone星耀标识 → 十二项亮度标识，索引 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_datestr是—公历日期，格式 YYYY-M-D，月日不必补零。支持 1583–9999 年
time_indexint是—时辰索引 0–12。0 为早子时（00:00–01:00），12 为晚子时（23:00–24:00）
genderstr是—"male" 或 "female"。决定大限顺逆与长生、博士十二神的排列方向
fix_leapbool否True仅限关键字。是否调整农历闰月。为真时闰月十六日起按下月算（晚子时除外，见下）
languagestr否"zh-CN"输出语言，影响所有译名字段；*_key 标识字段不受影响
configChartConfig | 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_datestr是—农历日期，格式 YYYY-M-D，月份写正数（闰月由下一参数标记）
is_leap_monthbool否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

参数

参数类型必填默认说明
astrolabeAstrolabe是—本命盘
target_datestr | None否None目标公历日期；不传取今天
target_time_indexint | 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_stemstr是—新命宫的天干标识，HeavenlyStem 枚举值域
from_branchstr是—新命宫的地支标识，EarthlyBranch 枚举值域

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

重排返回的盘上，patterns()、运限查询与 to_text 文本投影都按重排后的布局 计算——五行局、命宫与大限随重排起点变化；出生数据（日期与四柱）保持不变。

示例

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 是为「从任意干支起盘」准备的。

语义化文本（to_text）

用途　把星盘或运限投影成语义化文本——盘面事实的自然语言形态， 喂给大模型或直接给人读。与 to_dict/to_json（机器结构）、译文字段（展示） 是同一对象的三种投影。

签名　文本投影是对象自己的方法，不在 Astro 上：

chart.to_text()                       # 本命盘；str(chart) 等价
chart.horoscope("2025-1-1", 0).to_text()   # 运限；str(h) 等价
chart.palace("命宫").to_text()         # 单宫
chart.surrounded_palaces("命宫").to_text() # 三方四正
chart.patterns_to_text()              # 本命格局

返回值　str——按星盘的排盘语言输出的 Markdown 子集（# 标题、- 标签: 值 列表、 十二宫总览窄表）；本命文本带格局节与从命宫起的十二宫详解，运限文本各层带该层视角的 四化、流耀与格局行。每个 to_text 都收 knowledge=（True 或 KnowledgePack）， 给出时释义按盘取材内联在事实之后；也都收 config=（PatternConfig），给格局节与格局释义的判定口径。 格式见语义化文本。

示例

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

print("\n".join(chart.to_text().splitlines()[:5]))

输出

# 命盘 2000-8-16 寅时 女

## 基本信息
- 阳历: 2000-8-16 · 农历: 二〇〇〇年七月十七 · 时辰: 寅时 (03:00~05:00)
- 四柱: 庚辰 甲申 丙午 庚寅 · 生肖: 龙 · 星座: 狮子座

边界与陷阱

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

概览

包结构、类型体系与阅读本参考的方式。

星盘对象

Astrolabe 的字段、定位方法，以及三方四正与夹宫。

本页目录

ChartConfigby_solarby_lunarget_horoscoperearranged语义化文本（to_text）